File: 199.html

package info (click to toggle)
python-casacore 3.7.1-2
links: PTS, VCS
area: main
in suites: forky, sid, trixie
size: 1,488 kB
sloc: python: 4,170; cpp: 1,549; makefile: 67
file content (7800 lines) | stat: -rw-r--r-- 458,796 bytes
parent folder | download | duplicates (4)
<?xml version="1.0" encoding="utf-8" ?> 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0//EN" 
"http://www.w3.org/Math/DTD/mathml2/xhtml-math11-f.dtd" > 
<html xmlns="http://www.w3.org/1999/xhtml"  
> 
<head><title>NOTE 199 – Table Query Language</title> 
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> 
<meta name="generator" content="TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/)" /> 
<meta name="originator" content="TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/)" /> 
<!-- xhtml,mathml,fn-in,css-in,charset=utf-8,html --> 
<meta name="src" content="199.tex" /> 
<meta name="date" content="2016-04-13 09:59:00" /> 
 
<style type="text/css"> 
<!--  
 
/* start css.sty */  
.cmex-10{font-size:90%;}  
.cmr-10{font-size:90%;}  
.cmr-10x-x-109{}  
.cmbx-10x-x-109{ font-weight: bold;}  
.cmbx-10x-x-109{ font-weight: bold;}  
.cmbx-10x-x-109{ font-weight: bold;}  
.cmbsy-10x-x-109{font-weight: bold;}  
.cmbsy-10x-x-109{font-weight: bold;}  
.cmbsy-10x-x-109{font-weight: bold;}  
.cmbsy-8{font-size:72%;font-weight: bold;}  
.cmbsy-8{font-weight: bold;}  
.cmbsy-8{font-weight: bold;}  
.cmbsy-6{font-size:54%;font-weight: bold;}  
.cmbsy-6{font-weight: bold;}  
.cmbsy-6{font-weight: bold;}  
.cmr-8{font-size:72%;}  
.cmr-6{font-size:54%;}  
.cmmi-10x-x-109{font-style: italic;}  
.cmmi-8{font-size:72%;font-style: italic;}  
.cmmi-6{font-size:54%;font-style: italic;}  
.cmsy-10x-x-109{}  
.cmsy-8{font-size:72%;}  
.cmsy-6{font-size:54%;}  
.cmr-17{font-size:154%;}  
.cmr-12{font-size:109%;}  
.cmbx-10{font-size:90%; font-weight: bold;}  
.cmbx-10{ font-weight: bold;}  
.cmbx-10{ font-weight: bold;}  
.cmtt-10x-x-109{font-family: monospace;}  
.cmbx-12{font-size:109%; font-weight: bold;}  
.cmbx-12{ font-weight: bold;}  
.cmbx-12{ font-weight: bold;}  
.cmti-10x-x-109{ font-style: italic;}  
p.noindent { text-indent: 0em }  
td p.noindent { text-indent: 0em; margin-top:0em; }  
p.nopar { text-indent: 0em; }  
p.indent{ text-indent: 1.5em }  
@media print {div.crosslinks {visibility:hidden;}}  
a img { border-top: 0; border-left: 0; border-right: 0; }  
center { margin-top:1em; margin-bottom:1em; }  
td center { margin-top:0em; margin-bottom:0em; }  
.Canvas { position:relative; }  
math { text-indent: 0em; }  
li p.indent { text-indent: 0em }  
li p:first-child{ margin-top:0em; }  
li p:last-child, li div:last-child { margin-bottom:0.5em; }  
li p~ul:last-child, li p~ol:last-child{ margin-bottom:0.5em; }  
.enumerate1 {list-style-type:decimal;}  
.enumerate2 {list-style-type:lower-alpha;}  
.enumerate3 {list-style-type:lower-roman;}  
.enumerate4 {list-style-type:upper-alpha;}  
div.newtheorem { margin-bottom: 2em; margin-top: 2em;}  
.obeylines-h,.obeylines-v {white-space: nowrap; }  
div.obeylines-v p { margin-top:0; margin-bottom:0; }  
.overline{ text-decoration:overline; }  
.overline img{ border-top: 1px solid black; }  
td.displaylines {text-align:center; white-space:nowrap;}  
.centerline {text-align:center;}  
.rightline {text-align:right;}  
div.verbatim {font-family: monospace; white-space: nowrap; text-align:left; clear:both; }  
.fbox {padding-left:3.0pt; padding-right:3.0pt; text-indent:0pt; border:solid black 0.4pt; }  
div.fbox {display:table}  
div.center div.fbox {text-align:center; clear:both; padding-left:3.0pt; padding-right:3.0pt; text-indent:0pt; border:solid black 0.4pt; }  
div.minipage{width:100%;}  
div.center, div.center div.center {text-align: center; margin-left:1em; margin-right:1em;}  
div.center div {text-align: left;}  
div.flushright, div.flushright div.flushright {text-align: right;}  
div.flushright div {text-align: left;}  
div.flushleft {text-align: left;}  
.underline{ text-decoration:underline; }  
.underline img{ border-bottom: 1px solid black; margin-bottom:1pt; }  
.framebox-c, .framebox-l, .framebox-r { padding-left:3.0pt; padding-right:3.0pt; text-indent:0pt; border:solid black 0.4pt; }  
.framebox-c {text-align:center;}  
.framebox-l {text-align:left;}  
.framebox-r {text-align:right;}  
span.thank-mark{ vertical-align: super }  
span.footnote-mark sup.textsuperscript, span.footnote-mark a sup.textsuperscript{ font-size:80%; }  
div.footnotes{border-top:solid 1px black; border-bottom:solid 1px black; padding-bottom:1ex; padding-top:0.5ex; margin-right:15%; margin-top:2ex; font-style:italic; font-size:85%;}  
div.footnotes p{margin-top:0; margin-bottom:0; text-indent:0;}  
div.tabular, div.center div.tabular {text-align: center; margin-top:0.5em; margin-bottom:0.5em; }  
table.tabular td p{margin-top:0em;}  
table.tabular {margin-left: auto; margin-right: auto;}  
td p:first-child{ margin-top:0em; }  
td p:last-child{ margin-bottom:0em; }  
div.td00{ margin-left:0pt; margin-right:0pt; }  
div.td01{ margin-left:0pt; margin-right:5pt; }  
div.td10{ margin-left:5pt; margin-right:0pt; }  
div.td11{ margin-left:5pt; margin-right:5pt; }  
table[rules] {border-left:solid black 0.4pt; border-right:solid black 0.4pt; }  
td.td00{ padding-left:0pt; padding-right:0pt; }  
td.td01{ padding-left:0pt; padding-right:5pt; }  
td.td10{ padding-left:5pt; padding-right:0pt; }  
td.td11{ padding-left:5pt; padding-right:5pt; }  
table[rules] {border-left:solid black 0.4pt; border-right:solid black 0.4pt; }  
.hline hr, .cline hr{ height : 1px; margin:0px; }  
.tabbing-right {text-align:right;}  
span.TEX {letter-spacing: -0.125em; }  
span.TEX span.E{ position:relative;top:0.5ex;left:-0.0417em;}  
a span.TEX span.E {text-decoration: none; }  
span.LATEX span.A{ position:relative; top:-0.5ex; left:-0.4em; font-size:85%;}  
span.LATEX span.TEX{ position:relative; left: -0.4em; }  
div.float, div.figure {margin-left: auto; margin-right: auto;}  
div.float img {text-align:center;}  
div.figure img {text-align:center;}  
.marginpar {width:20%; float:right; text-align:left; margin-left:auto; margin-top:0.5em; font-size:85%; text-decoration:underline;}  
.marginpar p{margin-top:0.4em; margin-bottom:0.4em;}  
.equation td{text-align:center; vertical-align:middle; }  
td.eq-no{ width:5%; }  
table.equation { width:100%; }  
div.math-display, div.par-math-display{text-align:center;}  
mtr.hline mtd{ border-bottom:black solid 1px; padding-top:2px; padding-bottom:0em; }  
mtr.hline mtd mo{ display:none }  
math .texttt { font-family: monospace; }  
math .textit { font-style: italic; }  
math .textsl { font-style: oblique; }  
math .textsf { font-family: sans-serif; }  
math .textbf { font-weight: bold; }  
mo.MathClass-op + mi{margin-left:0.3em}  
mi + mo.MathClass-op{margin-left:0.3em}  
math mstyle[mathvariant="bold"] mi { font-weight: bold; font-style: normal; }  
math mstyle[mathvariant="normal"] mi { font-weight: normal; font-style: normal; }  
.partToc a, .partToc, .likepartToc a, .likepartToc {line-height: 200%; font-weight:bold; font-size:110%;}  
.index-item, .index-subitem, .index-subsubitem {display:block}  
div.caption {text-indent:-2em; margin-left:3em; margin-right:1em; text-align:left;}  
div.caption span.id{font-weight: bold; white-space: nowrap; }  
h1.partHead{text-align: center}  
p.bibitem { text-indent: -2em; margin-left: 2em; margin-top:0.6em; margin-bottom:0.6em; }  
p.bibitem-p { text-indent: 0em; margin-left: 2em; margin-top:0.6em; margin-bottom:0.6em; }  
.paragraphHead, .likeparagraphHead { margin-top:2em; font-weight: bold;}  
.subparagraphHead, .likesubparagraphHead { font-weight: bold;}  
.quote {margin-bottom:0.25em; margin-top:0.25em; margin-left:1em; margin-right:1em; text-align:justify;}  
.verse{white-space:nowrap; margin-left:2em}  
div.maketitle {text-align:center;}  
h2.titleHead{text-align:center;}  
div.maketitle{ margin-bottom: 2em; }  
div.author, div.date {text-align:center;}  
div.thanks{text-align:left; margin-left:10%; font-size:85%; font-style:italic; }  
.quotation {margin-bottom:0.25em; margin-top:0.25em; margin-left:1em; }  
.abstract p {margin-left:5%; margin-right:5%;}  
div.abstract {width:100%;}  
/* end css.sty */  
 
 
--> 
</style> 
</head><body 
>
   <div class="maketitle">
                                                                                            
                                                                                            
                                                                                            
                                                                                            

<h2 class="titleHead">NOTE 199 – Table Query Language</h2>
<div class="author" ><span 
class="cmr-12">Ger van Diepen, ASTRON Dwingeloo</span></div><br />
<div class="date" ><span 
class="cmr-12">2016 Apr 4</span></div>
   </div><div 
class="abstract" 
>
<div class="center" 
>
<!--l. 22--><p class="noindent" >
</p><!--l. 22--><p class="noindent" ><span 
class="cmbx-10">Abstract</span></p></div>
     <!--l. 23--><p class="indent" >    <span 
class="cmr-10">The Table Query Language (TaQL) is an SQL-like high level language to do operations like</span>
     <span 
class="cmr-10">selection, sort, and update on a casacore table. It is a very versatile language with full support</span>
     <span 
class="cmr-10">for table columns containing array data. It has inherent support for masked arrays, units, and</span>
     <span 
class="cmr-10">astronomical coordinates. It has a very rich set of functions (like cone search and array reduction)</span>
     <span 
class="cmr-10">making it very suitable for astronomical applications. User deﬁned functions can be added easily.</span>
     <span 
class="cmr-10">It also has full support of grouping/aggregation and nested queries. An operation that can be</span>
     <span 
class="cmr-10">expressed in a single function is the matching of two sky catalogues. </span><br 
class="newline" /><span 
class="cmr-10">It can be used from C++, Python, and any shell.</span>
</p>
</div>
   <div class="tabular"> <table id="TBL-2" class="tabular" 
cellspacing="0" cellpadding="0"  
><colgroup id="TBL-2-1g"><col 
id="TBL-2-1" /><col 
id="TBL-2-2" /><col 
id="TBL-2-3" /></colgroup><tr  
 style="vertical-align:baseline;" id="TBL-2-1-"><td  style="text-align:left; white-space:nowrap;" id="TBL-2-1-1"  
class="td11">1.0</td><td  style="text-align:left; white-space:nowrap;" id="TBL-2-1-2"  
class="td11">1997 Feb 9 </td><td  style="text-align:left; white-space:nowrap;" id="TBL-2-1-3"  
class="td11">Original version                                                    </td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-2-2-"><td  style="text-align:left; white-space:nowrap;" id="TBL-2-2-1"  
class="td11">2.0 </td><td  style="text-align:left; white-space:nowrap;" id="TBL-2-2-2"  
class="td11">2010 Nov 5</td><td  style="text-align:left; white-space:nowrap;" id="TBL-2-2-3"  
class="td11">UPDATE, INSERT, DELETE and COUNT commands</td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-2-3-"><td  style="text-align:left; white-space:nowrap;" id="TBL-2-3-1"  
class="td11">3.0 </td><td  style="text-align:left; white-space:nowrap;" id="TBL-2-3-2"  
class="td11">2015 Jul 29</td><td  style="text-align:left; white-space:nowrap;" id="TBL-2-3-3"  
class="td11">GROUPBY and HAVING clause                              </td></tr><tr  
 style="vertical-align:baseline;" id="TBL-2-4-"><td  style="text-align:left; white-space:nowrap;" id="TBL-2-4-1"  
class="td11">3.1 </td> <td  style="text-align:left; white-space:nowrap;" id="TBL-2-4-2"  
class="td11">2016 Apr 4 </td> <td  style="text-align:left; white-space:nowrap;" id="TBL-2-4-3"  
class="td11">Masked arrays; ALTER TABLE and SHOW commands</td> 
</tr></table></div>
<!--l. 47--><p class="indent" >   <a 
href="199.pdf" >A pdf version of this note is available.</a>
</p>
   <h3 class="likesectionHead"><a 
 id="x1-1000"></a>Contents</h3>
   <div class="tableofcontents">
   <span class="sectionToc" >1 <a 
href="#x1-20001" id="QQ2-1-2">Introduction</a></span>
<br />    <span class="subsectionToc" >1.1 <a 
href="#x1-30001.1" id="QQ2-1-3">TaQL vs SQL</a></span>
<br />   <span class="sectionToc" >2 <a 
href="#x1-40002" id="QQ2-1-4">TaQL Commands</a></span>
<br />    <span class="subsectionToc" >2.1 <a 
href="#x1-50002.1" id="QQ2-1-5">Command summary</a></span>
<br />    <span class="subsectionToc" >2.2 <a 
href="#x1-60002.2" id="QQ2-1-6">Using a style</a></span>
<br />     <span class="subsubsectionToc" >2.2.1 <a 
href="#x1-70002.2.1" id="QQ2-1-7">UDF library synonyms</a></span>
<br />     <span class="subsubsectionToc" >2.2.2 <a 
href="#x1-80002.2.2" id="QQ2-1-8">Tracing</a></span>
                                                                                            
                                                                                            
<br />     <span class="subsubsectionToc" >2.2.3 <a 
href="#x1-90002.2.3" id="QQ2-1-9">Timing</a></span>
<br />    <span class="subsectionToc" >2.3 <a 
href="#x1-100002.3" id="QQ2-1-10">Reserved words</a></span>
<br />   <span class="sectionToc" >3 <a 
href="#x1-110003" id="QQ2-1-11">Selection from a table</a></span>
<br />    <span class="subsectionToc" >3.1 <a 
href="#x1-120003.1" id="QQ2-1-12">SELECT command overview</a></span>
<br />     <span class="subsubsectionToc" >3.1.1 <a 
href="#x1-130003.1.1" id="QQ2-1-13">Column/keyword lookup</a></span>
<br />    <span class="subsectionToc" >3.2 <a 
href="#x1-150003.2" id="QQ2-1-15">SELECT column_list</a></span>
<br />     <span class="subsubsectionToc" >3.2.1 <a 
href="#x1-170003.2.1" id="QQ2-1-17">Masked array in column_list</a></span>
<br />    <span class="subsectionToc" >3.3 <a 
href="#x1-180003.3" id="QQ2-1-18">INTO [table] [AS options]</a></span>
<br />    <span class="subsectionToc" >3.4 <a 
href="#x1-190003.4" id="QQ2-1-19">FROM table_list</a></span>
<br />    <span class="subsectionToc" >3.5 <a 
href="#x1-220003.5" id="QQ2-1-22">WHERE expression</a></span>
<br />    <span class="subsectionToc" >3.6 <a 
href="#x1-230003.6" id="QQ2-1-23">GROUPBY group_list</a></span>
<br />    <span class="subsectionToc" >3.7 <a 
href="#x1-240003.7" id="QQ2-1-24">HAVING expression</a></span>
<br />    <span class="subsectionToc" >3.8 <a 
href="#x1-250003.8" id="QQ2-1-25">ORDERBY sort_list</a></span>
<br />    <span class="subsectionToc" >3.9 <a 
href="#x1-260003.9" id="QQ2-1-26">LIMIT/OFFSET expression</a></span>
<br />    <span class="subsectionToc" >3.10 <a 
href="#x1-270003.10" id="QQ2-1-27">GIVING [table] [AS options] — set</a></span>
<br />   <span class="sectionToc" >4 <a 
href="#x1-280004" id="QQ2-1-28">Expressions</a></span>
<br />    <span class="subsectionToc" >4.1 <a 
href="#x1-290004.1" id="QQ2-1-29">Data Types</a></span>
<br />    <span class="subsectionToc" >4.2 <a 
href="#x1-300004.2" id="QQ2-1-30">Regular Expressions and String Distances</a></span>
<br />    <span class="subsectionToc" >4.3 <a 
href="#x1-310004.3" id="QQ2-1-31">Constants</a></span>
<br />     <span class="subsubsectionToc" >4.3.1 <a 
href="#x1-320004.3.1" id="QQ2-1-32">Bool</a></span>
<br />     <span class="subsubsectionToc" >4.3.2 <a 
href="#x1-330004.3.2" id="QQ2-1-33">Integer</a></span>
<br />     <span class="subsubsectionToc" >4.3.3 <a 
href="#x1-340004.3.3" id="QQ2-1-34">Double (and time/position)</a></span>
<br />     <span class="subsubsectionToc" >4.3.4 <a 
href="#x1-350004.3.4" id="QQ2-1-35">Complex</a></span>
<br />     <span class="subsubsectionToc" >4.3.5 <a 
href="#x1-360004.3.5" id="QQ2-1-36">String</a></span>
<br />     <span class="subsubsectionToc" >4.3.6 <a 
href="#x1-370004.3.6" id="QQ2-1-37">Regular expression and String distance</a></span>
<br />     <span class="subsubsectionToc" >4.3.7 <a 
href="#x1-380004.3.7" id="QQ2-1-38">Date/time</a></span>
<br />     <span class="subsubsectionToc" >4.3.8 <a 
href="#x1-390004.3.8" id="QQ2-1-39">Arrays</a></span>
<br />     <span class="subsubsectionToc" >4.3.9 <a 
href="#x1-400004.3.9" id="QQ2-1-40">Masked Arrays</a></span>
<br />     <span class="subsubsectionToc" >4.3.10 <a 
href="#x1-410004.3.10" id="QQ2-1-41">Null Arrays</a></span>
<br />    <span class="subsectionToc" >4.4 <a 
href="#x1-420004.4" id="QQ2-1-42">Table Columns</a></span>
<br />     <span class="subsubsectionToc" >4.4.1 <a 
href="#x1-430004.4.1" id="QQ2-1-43">Referring to SELECT columns</a></span>
<br />    <span class="subsectionToc" >4.5 <a 
href="#x1-440004.5" id="QQ2-1-44">Table Keywords</a></span>
<br />    <span class="subsectionToc" >4.6 <a 
href="#x1-450004.6" id="QQ2-1-45">Operators</a></span>
<br />    <span class="subsectionToc" >4.7 <a 
href="#x1-460004.7" id="QQ2-1-46">Sets and intervals</a></span>
<br />    <span class="subsectionToc" >4.8 <a 
href="#x1-470004.8" id="QQ2-1-47">Array Index Operator</a></span>
<br />    <span class="subsectionToc" >4.9 <a 
href="#x1-480004.9" id="QQ2-1-48">Units</a></span>
<br />    <span class="subsectionToc" >4.10 <a 
href="#x1-490004.10" id="QQ2-1-49">Functions</a></span>
<br />     <span class="subsubsectionToc" >4.10.1 <a 
href="#x1-500004.10.1" id="QQ2-1-50">String functions</a></span>
<br />     <span class="subsubsectionToc" >4.10.2 <a 
href="#x1-510004.10.2" id="QQ2-1-51">Regex functions</a></span>
<br />     <span class="subsubsectionToc" >4.10.3 <a 
href="#x1-520004.10.3" id="QQ2-1-52">Date/time functions</a></span>
<br />     <span class="subsubsectionToc" >4.10.4 <a 
href="#x1-530004.10.4" id="QQ2-1-53">Pretty printing functions</a></span>
<br />     <span class="subsubsectionToc" >4.10.5 <a 
href="#x1-540004.10.5" id="QQ2-1-54">Comparison functions</a></span>
<br />     <span class="subsubsectionToc" >4.10.6 <a 
href="#x1-550004.10.6" id="QQ2-1-55">Mathematical functions</a></span>
<br />     <span class="subsubsectionToc" >4.10.7 <a 
href="#x1-560004.10.7" id="QQ2-1-56">Array to scalar reduce functions</a></span>
<br />     <span class="subsubsectionToc" >4.10.8 <a 
href="#x1-570004.10.8" id="QQ2-1-57">Array to array reduce functions</a></span>
<br />     <span class="subsubsectionToc" >4.10.9 <a 
href="#x1-580004.10.9" id="QQ2-1-58">Array downsampling functions</a></span>
<br />     <span class="subsubsectionToc" >4.10.10 <a 
href="#x1-590004.10.10" id="QQ2-1-59">Array functions operating in running windows</a></span>
<br />     <span class="subsubsectionToc" >4.10.11 <a 
href="#x1-600004.10.11" id="QQ2-1-60">Type conversion functions</a></span>
                                                                                            
                                                                                            
<br />     <span class="subsubsectionToc" >4.10.12 <a 
href="#x1-610004.10.12" id="QQ2-1-61">Array creation functions</a></span>
<br />     <span class="subsubsectionToc" >4.10.13 <a 
href="#x1-620004.10.13" id="QQ2-1-62">Aggregate functions</a></span>
<br />     <span class="subsubsectionToc" >4.10.14 <a 
href="#x1-630004.10.14" id="QQ2-1-63">Miscellaneous functions</a></span>
<br />     <span class="subsubsectionToc" >4.10.15 <a 
href="#x1-640004.10.15" id="QQ2-1-64">Cone search functions</a></span>
<br />     <span class="subsubsectionToc" >4.10.16 <a 
href="#x1-650004.10.16" id="QQ2-1-65">User deﬁned functions</a></span>
<br />     <span class="subsubsectionToc" >4.10.17 <a 
href="#x1-660004.10.17" id="QQ2-1-66">Special MeasurementSet functions</a></span>
<br />     <span class="subsubsectionToc" >4.10.18 <a 
href="#x1-710004.10.18" id="QQ2-1-71">Special Measures functions</a></span>
<br />    <span class="subsectionToc" >4.11 <a 
href="#x1-740004.11" id="QQ2-1-74">Subqueries</a></span>
<br />   <span class="sectionToc" >5 <a 
href="#x1-750005" id="QQ2-1-75">Aggregation, GROUPBY, HAVING</a></span>
<br />    <span class="subsectionToc" >5.1 <a 
href="#x1-760005.1" id="QQ2-1-76">Aggregation and GROUPBY</a></span>
<br />    <span class="subsectionToc" >5.2 <a 
href="#x1-770005.2" id="QQ2-1-77">HAVING</a></span>
<br />   <span class="sectionToc" >6 <a 
href="#x1-780006" id="QQ2-1-78">Some further remarks</a></span>
<br />    <span class="subsectionToc" >6.1 <a 
href="#x1-790006.1" id="QQ2-1-79">Joining tables</a></span>
<br />     <span class="subsubsectionToc" >6.1.1 <a 
href="#x1-800006.1.1" id="QQ2-1-80">Join on row number</a></span>
<br />     <span class="subsubsectionToc" >6.1.2 <a 
href="#x1-810006.1.2" id="QQ2-1-81">Join using an indexed subquery</a></span>
<br />     <span class="subsubsectionToc" >6.1.3 <a 
href="#x1-820006.1.3" id="QQ2-1-82">Join using a subquery set</a></span>
<br />     <span class="subsubsectionToc" >6.1.4 <a 
href="#x1-830006.1.4" id="QQ2-1-83">Join using derivedmscal</a></span>
<br />    <span class="subsectionToc" >6.2 <a 
href="#x1-840006.2" id="QQ2-1-84">Optimization</a></span>
<br />   <span class="sectionToc" >7 <a 
href="#x1-850007" id="QQ2-1-85">Modifying a table</a></span>
<br />    <span class="subsectionToc" >7.1 <a 
href="#x1-860007.1" id="QQ2-1-86">UPDATE</a></span>
<br />     <span class="subsubsectionToc" >7.1.1 <a 
href="#x1-870007.1.1" id="QQ2-1-87">Partial Array Update</a></span>
<br />     <span class="subsubsectionToc" >7.1.2 <a 
href="#x1-880007.1.2" id="QQ2-1-88">Update columns from a masked array</a></span>
<br />    <span class="subsectionToc" >7.2 <a 
href="#x1-890007.2" id="QQ2-1-89">INSERT</a></span>
<br />    <span class="subsectionToc" >7.3 <a 
href="#x1-920007.3" id="QQ2-1-92">DELETE</a></span>
<br />   <span class="sectionToc" >8 <a 
href="#x1-930008" id="QQ2-1-93">Creating a new table</a></span>
<br />    <span class="subsectionToc" >8.1 <a 
href="#x1-940008.1" id="QQ2-1-94">Column speciﬁcation</a></span>
<br />    <span class="subsectionToc" >8.2 <a 
href="#x1-950008.2" id="QQ2-1-95">Data manager speciﬁcation</a></span>
<br />   <span class="sectionToc" >9 <a 
href="#x1-960009" id="QQ2-1-96">Modifying the table structure</a></span>
<br />    <span class="subsectionToc" >9.1 <a 
href="#x1-970009.1" id="QQ2-1-97">ADD COLUMN</a></span>
<br />    <span class="subsectionToc" >9.2 <a 
href="#x1-980009.2" id="QQ2-1-98">RENAME COLUMN</a></span>
<br />    <span class="subsectionToc" >9.3 <a 
href="#x1-990009.3" id="QQ2-1-99">DELETE COLUMN</a></span>
<br />    <span class="subsectionToc" >9.4 <a 
href="#x1-1000009.4" id="QQ2-1-100">SET KEYWORD</a></span>
<br />    <span class="subsectionToc" >9.5 <a 
href="#x1-1020009.5" id="QQ2-1-102">COPY KEYWORD</a></span>
<br />    <span class="subsectionToc" >9.6 <a 
href="#x1-1030009.6" id="QQ2-1-103">RENAME KEYWORD</a></span>
<br />    <span class="subsectionToc" >9.7 <a 
href="#x1-1040009.7" id="QQ2-1-104">DELETE KEYWORD</a></span>
<br />    <span class="subsectionToc" >9.8 <a 
href="#x1-1050009.8" id="QQ2-1-105">ADD ROW</a></span>
<br />   <span class="sectionToc" >10 <a 
href="#x1-10600010" id="QQ2-1-106">Counting in a table</a></span>
<br />   <span class="sectionToc" >11 <a 
href="#x1-10700011" id="QQ2-1-107">Calculations on a table</a></span>
<br />   <span class="sectionToc" >12 <a 
href="#x1-10800012" id="QQ2-1-108">Examples</a></span>
<br />    <span class="subsectionToc" >12.1 <a 
href="#x1-10900012.1" id="QQ2-1-109">Selection examples</a></span>
<br />     <span class="subsubsectionToc" >12.1.1 <a 
href="#x1-11000012.1.1" id="QQ2-1-110">Reference table results</a></span>
<br />     <span class="subsubsectionToc" >12.1.2 <a 
href="#x1-11100012.1.2" id="QQ2-1-111">Plain table results</a></span>
<br />    <span class="subsectionToc" >12.2 <a 
href="#x1-11200012.2" id="QQ2-1-112">Modiﬁcation examples</a></span>
<br />     <span class="subsubsectionToc" >12.2.1 <a 
href="#x1-11300012.2.1" id="QQ2-1-113">Applying running median to an image</a></span>
<br />    <span class="subsectionToc" >12.3 <a 
href="#x1-11400012.3" id="QQ2-1-114">Table creation examples</a></span>
<br />    <span class="subsectionToc" >12.4 <a 
href="#x1-11500012.4" id="QQ2-1-115">Calculation examples</a></span>
<br />    <span class="subsectionToc" >12.5 <a 
href="#x1-11600012.5" id="QQ2-1-116">Aggregation/groupby examples</a></span>
<br />     <span class="subsubsectionToc" >12.5.1 <a 
href="#x1-11700012.5.1" id="QQ2-1-117">Obtaining the ﬂux density from visibility data</a></span>
                                                                                            
                                                                                            
<br />     <span class="subsubsectionToc" >12.5.2 <a 
href="#x1-11800012.5.2" id="QQ2-1-118">Number of fully ﬂagged baselines per antenna</a></span>
<br />   <span class="sectionToc" >13 <a 
href="#x1-11900013" id="QQ2-1-119">Interface to TaQL</a></span>
<br />    <span class="subsectionToc" >13.1 <a 
href="#x1-12000013.1" id="QQ2-1-120">Python interface <span 
class="cmtt-10x-x-109">python-casacore</span></a></span>
<br />    <span class="subsectionToc" >13.2 <a 
href="#x1-12100013.2" id="QQ2-1-121">Interface to Glish</a></span>
<br />    <span class="subsectionToc" >13.3 <a 
href="#x1-12200013.3" id="QQ2-1-122">Program <span 
class="cmtt-10x-x-109">taql</span></a></span>
<br />    <span class="subsectionToc" >13.4 <a 
href="#x1-12300013.4" id="QQ2-1-123">C++ interface</a></span>
<br />     <span class="subsubsectionToc" >13.4.1 <a 
href="#x1-12400013.4.1" id="QQ2-1-124">TaQL query string</a></span>
<br />     <span class="subsubsectionToc" >13.4.2 <a 
href="#x1-12500013.4.2" id="QQ2-1-125">Expression string</a></span>
<br />     <span class="subsubsectionToc" >13.4.3 <a 
href="#x1-12600013.4.3" id="QQ2-1-126">Expression classes</a></span>
<br />   <span class="sectionToc" >14 <a 
href="#x1-12700014" id="QQ2-1-127">Writing user deﬁned functions</a></span>
<br />    <span class="subsectionToc" >14.1 <a 
href="#x1-12800014.1" id="QQ2-1-128">UDFs in Python</a></span>
<br />   <span class="sectionToc" >15 <a 
href="#x1-12900015" id="QQ2-1-129">Possible future developments</a></span>
   </div>
                                                                                            
                                                                                            
   <h3 class="sectionHead"><span class="titlemark">1   </span> <a 
 id="x1-20001"></a>Introduction</h3>
<!--l. 5--><p class="noindent" >The Table Query Language (TaQL, rhymes with bagel (though some people pronounce it as tackle)) is a
language for querying and manipulating data in Casacore tables. It makes it possible to get results or select
rows from an arbitrary table based on the contents of its columns and keywords. It supports arbitrary
complex expressions including units, extended regular expressions, and many functions. User deﬁned
functions written in C++ or Python are supported. TaQL also makes sorting and column selection possible.
Furthermore TaQL has commands to update, add or delete rows and columns in a table and to create a new
table.
</p><!--l. 16--><p class="indent" >   The ﬁrst sections of this document explain the syntax and show the options. The last sections give several
examples and show the interface to TaQL using Python or C++. The Python interface makes it possible to
embed Python variables and expressions in a TaQL command.
</p><!--l. 22--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">1.1   </span> <a 
 id="x1-30001.1"></a>TaQL vs SQL</h4>
<!--l. 23--><p class="noindent" >TaQL is modeled after SQL and contains a subset of SQL&#x2019;s functionality. Some familiarity with SQL makes it
easier to understand the TaQL syntax. The most important features of TaQL diﬀerent from SQL are:
</p>
     <ul class="itemize1">
     <li class="itemize">The result of a SELECT is another table (either temporary or persistent). Usually this is a
     so-called reference table, but it is also possible to make a deep copy and create a plain table. <br 
class="newline" />A reference table is a table that can be used as any other table, but does not contain data.
     Instead it contains references to the rows and columns in the original table. Thus modifying data
     in a reference table means that eﬀectively the data in the original table are modiﬁed.
     </li>
     <li class="itemize">A very rich set of mathematical and other functions.
     </li>
     <li class="itemize">Any operand can be a scalar or an N-dimensional array. Many reduce functions can be applied
     to arrays.
     </li>
     <li class="itemize">Arrays can optionally be masked.
     </li>
     <li class="itemize">Full support of units and automatic conversion of units.
     </li>
     <li class="itemize">Support of various types of patterns/regular expressions and support of maximum string distance
     (Levensthein (aka Edit) distance).
     </li>
     <li class="itemize">Speciﬁc operators and functions for cone searching (i.e., spatial searching with a search radius).
     </li>
     <li class="itemize">An advanced way of specifying intervals.
                                                                                            
                                                                                            
     </li>
     <li class="itemize">No support of indices, thus a linear table search is done. Because data are stored column-wise,
     a linear search is usually very fast, even for very large tables.
     </li>
     <li class="itemize">Limited support for joins (only implicit joins on row number).
     </li>
     <li class="itemize">Many aggregate functions.
     </li>
     <li class="itemize">The COUNT command exists to count the occurrences of column values. Although it can still
     be used, this command is obsolete now GROUPBY is fully supported.
     </li>
     <li class="itemize">The CALC command exists to calculate an arbitrary expression (including subqueries) on a table.
     This can be useful to derive values from a table (e.g., the number of ﬂags set in a measurement
     set). It can even be used as a desk calculator.
     </li>
     <li class="itemize">TaQL can be used from languages with diﬀerent conventions, for example the order of array
     axes. Therefore it is possible to set the language style to be used.
     </li>
     <li class="itemize">The language can be extended by means of User Deﬁned Functions, possibly implemented in
     Python. Some standard UDFs exist to deal with MeasurementSets and to do measure conversions
     (for directions, epochs, positions, and stokes).</li></ul>
<!--l. 68--><p class="noindent" >TaQL has a keyword that makes it possible to time the various parts of a TaQL command.
</p><!--l. 72--><p class="noindent" >
</p>
   <h3 class="sectionHead"><span class="titlemark">2   </span> <a 
 id="x1-40002"></a>TaQL Commands</h3>
<!--l. 73--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">2.1   </span> <a 
 id="x1-50002.1"></a>Command summary</h4>
<!--l. 74--><p class="noindent" >TaQL contains several commands. In the commands shown below the square brackets are not part of the
syntax, but indicate the optional parts of the commands.
</p>
     <ul class="itemize1">
     <li class="itemize">show (or help)
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-1">
       SHOW [type ...]
</div>
     <!--l. 82--><p class="nopar" > can be used to give some TaQL explanation or to show table information. A sole <span 
class="cmtt-10x-x-109">show </span>command shows
     the possible options. HELP is a synonym for SHOW.
     </p></li>
     <li class="itemize">selection
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-2">
       SELECT [[DISTINCT] expression_list]
      <br />    [INTO table [AS options]]
      <br />    [FROM table_list]
      <br />    [WHERE expression]
      <br />    [GROUPBY expression_list]
      <br />    [HAVING expression]
      <br />    [ORDERBY [DISTINCT] sort_list]
      <br />    [LIMIT expression] [OFFSET expression]
      <br />    [GIVING table [AS options] | set]
      <br />    [DMINFO datamanagers]
</div>
     <!--l. 99--><p class="nopar" > It can be used to get an optionally sorted subset from a table. It can also be used to do a subquery
     (see <a 
href="#x1-740004.11">section 4.11</a> for more information on subqueries).
     </p></li>
     <li class="itemize">updating
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-3">
       UPDATE table_list SET update_list [FROM table_list]
      <br />    [WHERE ...] [ORDERBY ...] [LIMIT ...] [OFFSET ...]
</div>
     <!--l. 109--><p class="nopar" > It can be used to update data in (a subset of) the ﬁrst table in the ﬁrst table list.
     </p></li>
     <li class="itemize">addition
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-4">
       INSERT INTO table_list SET column=expr, column=expr, ...
      <br />or
      <br />  INSERT INTO table_list [(column_list)] VALUES (expr_list)
      <br />or
      <br />  INSERT INTO table_list [(column_list)] SELECT_command
</div>
     <!--l. 120--><p class="nopar" > It can be used to add and ﬁll new rows in the ﬁrst table in the table list.
     </p></li>
     <li class="itemize">deletion
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-5">
       DELETE FROM table_list
      <br />    [WHERE ...] [ORDERBY ...] [LIMIT ...] [OFFSET ...]
</div>
     <!--l. 128--><p class="nopar" > It can be used to delete some or all rows from the ﬁrst table in the table list.
     </p></li>
     <li class="itemize">counting
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-6">
       COUNT [column_list] FROM table_list [WHERE ...]
</div>
     <!--l. 135--><p class="nopar" > It can be used to count occurrences of column values. Although the command can still be used, it is
     basically obsolete because the same (and more) can be achieved with the GROUPBY clause and
     aggregate functions in the SELECT command. <br 
class="newline" />Furthermore, usually GROUPBY is faster.
     </p></li>
     <li class="itemize">calculation
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-7">
       CALC expression [FROM table_list]
</div>
     <!--l. 145--><p class="nopar" > It can be used to calculate an expression, in which columns in a table can be used.
     </p></li>
     <li class="itemize">table creation
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-8">
       CREATE TABLE table [AS options]
      <br />    [column_spec]
      <br />    [LIMIT ...]
      <br />    [DMINFO datamanagers]
</div>
     <!--l. 155--><p class="nopar" > It can be used to create a new table with the given columns and number of rows. Optionally speciﬁc
     table and data manager info can be given.
     </p></li>
     <li class="itemize">table structure modiﬁcation
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-9">
       ALTER TABLE table
      <br />    [ADD COLUMN [column_spec] [DMINFO datamanagers]
      <br />    [RENAME COLUMN column_pair_list]
      <br />    [DROP COLUMN column_list]
      <br />    [SET KEYWORD key=value, key=value, ...]
      <br />    [COPY KEYWORD key=other, key=other, ...]
      <br />    [RENAME KEYWORD keyword_pair_list]
      <br />    [DROP KEYWORD keyword_list]
      <br />    [ADD ROW nrow]
</div>
     <!--l. 171--><p class="nopar" > It can be used to add, rename, and remove columns and keywords and to add rows. Multiple such
     subcommands can be given, separated by white space.
</p>
     </li></ul>
<!--l. 177--><p class="noindent" >The commands and verbs in the commands are case-insensitive, but case is important in string
values and in names of columns and keywords. Whitespace (blanks and tabs) can be used at will.
<br 
class="newline" /><a 
href="#x1-850007">Section 7 (Modifying a table)</a> explains the UPDATE, INSERT, and DELETE commands in more detail. The
CREATE TABLE command is explained in <a 
href="#x1-930008">section 8 (Creating a table)</a>. The ALTER TABLE command is
explained in <a 
href="#x1-960009">section 9 (Modifying the table structure)</a>. <br 
class="newline" /><a 
href="#x1-10600010">Section 10 (Counting in a table)</a> explains the COUNT command in more detail. <br 
class="newline" /><a 
href="#x1-10700011">Section 11 (Calculations on a table)</a> explains the CALC command in more detail.
</p><!--l. 193--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">2.2   </span> <a 
 id="x1-60002.2"></a>Using a style</h4>
<!--l. 194--><p class="noindent" >TaQL can be used from diﬀerent languages, in particular Python and Glish. Each has its own conventions
breaking down into three important categories: </p>
     <ul class="itemize1">
     <li class="itemize">0-based or 1-based indexing.
     </li>
     <li class="itemize">Fortran-order or C-order of arrays.
     </li>
     <li class="itemize">Inclusive or exclusive end in <span 
class="cmtt-10x-x-109">start:end </span>ranges.</li></ul>
<!--l. 202--><p class="noindent" >The user can set the style (convention) to be used by preceding a TaQL statement with
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-10">
  USING STYLE value, value, ...
</div>
<!--l. 206--><p class="nopar" > The possible (case-independent) values are: </p>
     <ul class="itemize1">
     <li class="itemize"><span 
class="cmtt-10x-x-109">BASE0 </span>or <span 
class="cmtt-10x-x-109">BASE1 </span>telling the indexing style.
     </li>
     <li class="itemize"><span 
class="cmtt-10x-x-109">ENDEXCL </span>or <span 
class="cmtt-10x-x-109">ENDINCL </span>telling the range style.
     </li>
     <li class="itemize"><span 
class="cmtt-10x-x-109">CORDER </span>or <span 
class="cmtt-10x-x-109">FORTRANORDER </span>telling the array style.
     </li>
     <li class="itemize"><span 
class="cmtt-10x-x-109">PYTHON </span>which is equivalent to <span 
class="cmtt-10x-x-109">BASE0,ENDEXCL,CORDER</span>
     </li>
     <li class="itemize"><span 
class="cmtt-10x-x-109">GLISH </span>which is equivalent to <span 
class="cmtt-10x-x-109">BASE1,ENDINCL,FORTRANORDER</span></li></ul>
<!--l. 215--><p class="noindent" >The following values are also possible and are described in the next subsections. </p>
     <ul class="itemize1">
     <li class="itemize"><span 
class="cmtt-10x-x-109">synonym=libname </span>to deﬁne a synonym for a user deﬁned library.
     </li>
     <li class="itemize"><span 
class="cmtt-10x-x-109">TRACE </span>or <span 
class="cmtt-10x-x-109">NOTRACE </span>to (un)set tracing.
     </li>
     <li class="itemize"><span 
class="cmtt-10x-x-109">TIME </span>or <span 
class="cmtt-10x-x-109">NOTIME </span>to (un)set timing.</li></ul>
<!--l. 222--><p class="noindent" >If multiple values are given for a category, the last one will be used. The default style used is <span 
class="cmtt-10x-x-109">GLISH</span>, which is the
way TaQL always worked before this feature was introduced.
</p><!--l. 226--><p class="indent" >   It is important to note that the interpretation of the axes numbers depends on the style being
used. e.g., when using glish style, axes numbers are 1-based and in Fortran order, thus axis 1 is
the most rapidly varying axis. When using python style, axis 0 is the most slowly varying axis.
<br 
class="newline" />Casacore arrays are in Fortran order, but TaQL maps it to the style being used. Thus when using python
style, the axes will be reversed (data will not be transposed). <span 
class="cmbx-10x-x-109">Note: unless said diﬀerently, all examples</span>
<span 
class="cmbx-10x-x-109">in this document are done using the Python style.</span>
</p><!--l. 236--><p class="indent" >   The style feature has to be used with care. A given TaQL statement will behave diﬀerently if used with
another style.
</p><!--l. 239--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">2.2.1   </span> <a 
 id="x1-70002.2.1"></a>UDF library synonyms</h5>
<!--l. 240--><p class="noindent" >The style clause can also be used to deﬁne synonyms for the library names of <a 
href="#x1-650004.10.16">user deﬁned functions</a>. For
example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-11">
  using style mscal=derivedmscal
</div>
<!--l. 244--><p class="nopar" > deﬁnes the synonym <span 
class="cmtt-10x-x-109">mscal</span>. Synonyms make it easier (i.e., less typing) to specify user deﬁned functions.
<br 
class="newline" />Note that the synonym in the example above is automatically deﬁned by TaQL as well as the synonym <span 
class="cmtt-10x-x-109">py </span>for
<span 
class="cmtt-10x-x-109">pytaql</span>.
</p><!--l. 250--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">2.2.2   </span> <a 
 id="x1-80002.2.2"></a>Tracing</h5>
<!--l. 251--><p class="noindent" >It is possible to get tracing output during the execution of a TaQL command by using the case-insensitive
value <span 
class="cmtt-10x-x-109">TRACE </span>in the <span 
class="cmtt-10x-x-109">using style </span>command.
</p><!--l. 255--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">2.2.3   </span> <a 
 id="x1-90002.2.3"></a>Timing</h5>
<!--l. 256--><p class="noindent" >It is possible to time a TaQL command by using the case-insensitive value <span 
class="cmtt-10x-x-109">TIME </span>in the <span 
class="cmtt-10x-x-109">using style</span>
command. For historical reasons it is also possible to use the the case-insensitive keyword <span 
class="cmtt-10x-x-109">TIME </span>before or after
the optional style command.
</p><!--l. 261--><p class="indent" >   Timing shows the total execution time and the times needed for various parts of the TaQL command on
stdout. For example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-12">
time select distinct ANTENNA1,ANTENNA2
 <br />from ~/3C343.MS where any(FLAG)&#x2019;
 <br />
 <br />  Where          2.87 real    2.16 user    0.69 system
 <br />  Projection        0 real       0 user       0 system
 <br />  Distinct       0.18 real    0.16 user    0.03 system
 <br /> Total time      3.07 real    2.33 user    0.72 system
</div>
<!--l. 271--><p class="nopar" > shows the time to do the where part (i.e., row selection on FLAG), projection (selection of columns), and
distinct (unique column values).
</p><!--l. 275--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">2.3   </span> <a 
 id="x1-100002.3"></a>Reserved words</h4>
<!--l. 276--><p class="noindent" >TaQL uses the following words as part of its language.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-13">
  ALL           AND      AS        ASC
 <br />  BETWEEN
 <br />  CALC          CREATETABLE
 <br />  DELETE        DESC     DISTINCT  DMINFO
 <br />  EXCEPT        EXISTS
 <br />  F             FALSE    FROM
 <br />  GIVING        GROUPBY  GROUPBYROLLUP
 <br />  HAVING
 <br />  IN            INCONE   INSERT    INTERSECT  INTO
 <br />  JOIN
 <br />  LIKE          LIMIT
 <br />  MINUS
 <br />  NODUPLICATES  NOT
 <br />  OFFSET        ON       OR        ORDERBY
 <br />  SAVETO        SELECT   SET       SUBTABLES
 <br />  T             TO       TOP       TRUE
 <br />  UNION         UNIQUE   UPDATE    USINGSTYLE
 <br />  VALUES
 <br />  WHERE
 <br />  XOR
</div>
<!--l. 298--><p class="nopar" > These words are reserved. Note that the words in the TaQL vocabulary are case insensitive, thus the
lowercase (or any mixed case) versions are also reserved.
</p><!--l. 303--><p class="indent" >   The reserved words cannot directly be used as <a 
href="#x1-420004.4">column name</a>, <a 
href="#x1-440004.5">keyword name</a>, or <a 
href="#x1-480004.9">unit</a>. However, a reserved
word can be used that way by escaping it with a backslash like <span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">\</span></span></span><span 
class="cmtt-10x-x-109">AS</span>. When reading further, the meaning
of
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-14">
     \IN  \in  IN [3mm,4mm]
 <br />   column unit IN    set
</div>
<!--l. 312--><p class="nopar" > might become clear. It means: use unit <span 
class="cmtt-10x-x-109">in </span>(inch) for column <span 
class="cmtt-10x-x-109">IN </span>and test if it is in the given set.
<br 
class="newline" />Note this is unlike SQL where quotes have to be used to use a reserved word as a column name.
</p><!--l. 318--><p class="noindent" >
</p>
   <h3 class="sectionHead"><span class="titlemark">3   </span> <a 
 id="x1-110003"></a>Selection from a table</h3>
<!--l. 319--><p class="noindent" >The SELECT is the main TaQL command. It can be used to select a subset of rows and/or columns from a
table and to generate new columns based on expressions.
</p><!--l. 323--><p class="indent" >   As explained above, the result of a selection is usually a reference table. This table can be used as any
other table, thus it is possible to do another selection on it or to update it (which updates the underlying
original table). It is, however, not possible to insert rows in a reference table or to delete rows from
it.
</p><!--l. 329--><p class="indent" >   If the select column list contains expressions, it is not possible to generate a reference table. Instead a
normal plain table is generated (which can take some time if it contains large data arrays). It should be clear
that updating such a table does not update the original table.
</p><!--l. 335--><p class="indent" >   The FROM clause can be omitted from the select. In that case no columns can be used in the selection,
but functions like <span 
class="cmtt-10x-x-109">rand </span>and <span 
class="cmtt-10x-x-109">rowid </span>make variable output possible. Clauses like ORDERBY can be given. The
GIVING (or INTO) might be useful to store the result in a table.
</p><!--l. 341--><p class="indent" >   There is no explicit JOIN clause, but it is possible to equi-join tables on row number. Such tables must
have the same number of rows. One can also join , for example, the main table of a MeasurementSet with
a subtable like the ANTENNA table using a <a 
href="#x1-740004.11">subquery</a>. Joins are explained further in <a 
href="#x1-790006.1">section
6.1</a>.
</p><!--l. 350--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">3.1   </span> <a 
 id="x1-120003.1"></a>SELECT command overview</h4>
<!--l. 351--><p class="noindent" >The SELECT command consists of various clauses of which most are optional. The full command looks as
follows where the optional parts are shown in square brackets.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-15">
  SELECT [[DISTINCT] column_list]
 <br />    [INTO table [AS options]]
 <br />    [FROM table_list]
 <br />    [WHERE expression]
 <br />    [GROUPBY expression_list]
 <br />    [HAVING expression]
 <br />    [ORDERBY [DISTINCT] sort_list]
 <br />    [LIMIT expression] [OFFSET expression]
 <br />    [GIVING table [AS options] | set]
 <br />    [DMINFO datamanagers]
</div>
<!--l. 365--><p class="nopar" > The clauses are executed in a somewhat diﬀerent order.
     </p><ol  class="enumerate1" >
     <li 
  class="enumerate" id="x1-12002x1">FROM to deﬁne the tables to be used.
     </li>
     <li 
  class="enumerate" id="x1-12004x2">WHERE to select the rows.
     </li>
     <li 
  class="enumerate" id="x1-12006x3">GROUPBY to group selected rows.
     </li>
     <li 
  class="enumerate" id="x1-12008x4">SELECT to ﬁll select columns used in HAVING or ORDERBY
     </li>
     <li 
  class="enumerate" id="x1-12010x5">HAVING to select groups.
     </li>
     <li 
  class="enumerate" id="x1-12012x6">SELECT to ﬁll the remaining select columns.
     </li>
     <li 
  class="enumerate" id="x1-12014x7">ORDERBY to sort the result.
     </li>
     <li 
  class="enumerate" id="x1-12016x8">LIMIT (or TOP) and OFFSET to ignore entries in the sorted result.
     </li>
     <li 
  class="enumerate" id="x1-12018x9">DMINFO to deﬁne the data managers to be used if the result is
     </li>
     <li 
  class="enumerate" id="x1-12020x10">GIVING/INTO to store the ﬁnal result. stored in a plain table. See <a 
href="#x1-950008.2">section 8.2</a> how to specify
     them.</li></ol>
<!--l. 381--><p class="noindent" >All clauses are explained in full detail in the subsequent sections.
                                                                                            
                                                                                            
</p><!--l. 383--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">3.1.1   </span> <a 
 id="x1-130003.1.1"></a>Column/keyword lookup</h5>
<!--l. 384--><p class="noindent" >Expressions in the various clauses will normally use column names to select, sort, or group a table. It is also
possible to use table keywords or column keywords by giving their names. Furthermore, it is possible to use a
column, created in the SELECT clause, in the HAVING and ORDERBY clauses. This can save time in both
specifying and executing the command, because a possibly complicated expression can be used to
create such a column. If such columns are used, that part of the SELECT is executed before
HAVING.
</p>
<!--l. 393--><p class="noindent" ><span class="likeparagraphHead"><a 
 id="x1-140003.1.1"></a></span>
   TaQL uses the following lookup scheme for column/keyword names.
     </p><ol  class="enumerate1" >
     <li 
  class="enumerate" id="x1-14002x1">If preceded by a shorthand (like in <span 
class="cmtt-10x-x-109">t0.DATA</span>), the name is looked up in the corresponding table.
     </li>
     <li 
  class="enumerate" id="x1-14004x2">If not preceded by a shorthand, a name is ﬁrst looked up in the select columns. If not found, the
     name is looked up in the ﬁrst table given in FROM.
     </li>
     <li 
  class="enumerate" id="x1-14006x3">A name is ﬁrst looked up as a column in a table. If not found, it is looked up as a table keyword.</li></ol>
<!--l. 404--><p class="noindent" >See the discussion of <a 
href="#x1-420004.4">column names</a> and <a 
href="#x1-440004.5">keyword names</a> for more details.
</p><!--l. 408--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">3.2   </span> <a 
 id="x1-150003.2"></a>SELECT column_list</h4>
<!--l. 409--><p class="noindent" >Columns to be selected can be given as a comma-separated list with names of columns that have to be
selected from the tables in the table_list (see below). If no column_list is given, all columns of the
ﬁrst table will be selected. It results in a so-called reference table. Optionally a selected column
can be given another name in the reference table using <span 
class="cmtt-10x-x-109">AS name </span>(where AS is optional). For
example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-16">
  select TIME,ANTENNA1,ANTENNA2,DATA from 3C343.MS
 <br />  select TIME,ANTENNA1,ANTENNA2,MODEL_DATA AS DATA from 3C343.MS
</div>
<!--l. 420--><p class="nopar" > It is possible to precede a column name with a table shorthand indicating with table in the FROM clause
has to be used. If not given, a column will be looked up in the ﬁrst table. Note that if equally named columns
from diﬀerent tables are used, one has to get a new name, otherwise a &#x2019;duplicate name&#x2019; error will occur. For
example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-17">
  select t0.DATA, t1.DATA as DATA1 from 3C343.MS t0, 3C343_1.MS t1
</div>
<!--l. 429--><p class="nopar" >
</p><!--l. 431--><p class="indent" >   Apart from giving exact column names, it is also possible to use wildcards by means of a UNIX
ﬁlename-like pattern (like <span 
class="cmtt-10x-x-109">p/pattern/</span>) or a regular expression (like <span 
class="cmtt-10x-x-109">f/regex/ </span>for a full match or <span 
class="cmtt-10x-x-109">m/regex/</span>
for a partial match). They can be suﬃxed with an <span 
class="cmtt-10x-x-109">i </span>indicating case-insensitive matching. See
<a 
href="#x1-370004.3.6">section 4.3.6</a> for a discussion of these constants. The operator <span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">~</span></span></span> needs to be given before the
pattern or regex to indicate that columns have to be included. Thereafter operator <span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">!~</span></span></span> can be
used with another pattern or regex to remove columns. Such an excluding pattern or regex only
removes columns from the wildcarded columns before it until the latest non-wildcarded column.
<br 
class="newline" />A special pattern is * (which is the same as <span 
class="cmtt-10x-x-109"> p/*/</span>). For example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-18">
  select *, !~p/*_DATA/ from 3C343.MS
</div>
<!--l. 447--><p class="nopar" > selects all columns except the ones ending in <span 
class="cmtt-10x-x-109">_DATA</span>.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-19">
  select ~m/DATA/, !~p/*_DATA/ from 3C343.MS
</div>
<!--l. 451--><p class="nopar" > selects columns with a name containing <span 
class="cmtt-10x-x-109">DATA </span>except the ones ending in <span 
class="cmtt-10x-x-109">_DATA</span>.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-20">
  select CORRECTED_DATA, *, !~p/*_DATA/ from 3C343.MS
 <br />or
 <br />  select *, !~p/*_DATA/, CORRECTED_DATA from 3C343.MS
</div>
<!--l. 458--><p class="nopar" > does select the <span 
class="cmtt-10x-x-109">CORRECTED</span><span 
class="cmtt-10x-x-109">_DATA </span>column. <br 
class="newline" />Note it is not possible to change the name or data type of wildcarded columns.
</p>
<!--l. 463--><p class="noindent" ><span class="likeparagraphHead"><a 
 id="x1-160003.2"></a></span>
   It is also possible to use expressions in the column list to create new columns based on the contents of
other columns. When doing this, the resulting table is a plain table (because a reference table cannot contain
expressions). The new column can be given a name by giving <span 
class="cmtt-10x-x-109">AS name </span>after the expression (where AS is
optional). If no name is given, a unique name like <span 
class="cmtt-10x-x-109">Col</span><span 
class="cmtt-10x-x-109">_1 </span>is constructed. After the name a <a 
href="#x1-290004.1">data type
string</a> can be given for the new column. If no data type is given, the expression data type is
used.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-21">
  select max(ANTENNA1,ANTENNA2) AS ANTENNA from 3C343
 <br />  select means(DATA,1) from 3C343
</div>
<!--l. 477--><p class="nopar" > Note that unit conversion can be (part of) an expression. For example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-22">
  select TIME d AS TIMEH from my.ms
</div>
<!--l. 481--><p class="nopar" > to store the time in unit <span 
class="cmtt-10x-x-109">d </span>(days). Units are discussed in <a 
href="#x1-480004.9">section 4.9</a>.
</p><!--l. 485--><p class="indent" >   It is possible to change the data type of a column by specifying a data type (see below) after the new
column name. Giving a data type (even if the same as the existing one) counts as an expression, thus results
in the generation of a plain table. For example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-23">
  select MODEL_DATA AS DATA FCOMPLEX from 3C343.MS
</div>
<!--l. 492--><p class="nopar" >
</p><!--l. 494--><p class="indent" >   Note that for subqueries the GIVING clause oﬀers a better (faster) way of specifying a result expression.
It also makes it possible to use intervals.
</p><!--l. 498--><p class="indent" >   Special aggregate functions (e.g., <span 
class="cmtt-10x-x-109">gmin</span>) exist to calculate an aggregated value (minimum in this example)
per group of rows where the grouping is deﬁned by the GROUPBY clause. The entire column
is a single group if no GROUPBY is given. Aggregation is discussed in more detail in <a 
href="#x1-750005">section
5</a>.
</p><!--l. 504--><p class="indent" >   If a column_list is given and if all columns (and/or expressions) are scalars, the column_list can be
preceded by the word DISTINCT. It means that the result is made unique by removing the rows with
duplicate values in the columns of the column_list. Instead of DISTINCT the synonym NODUPLICATES or
UNIQUE can also be used. To ﬁnd duplicate values, some temporary sorting is done, but the original order of
the remaining rows is not changed. <br 
class="newline" />Note that support of this keyword is mainly done for SQL compliance. The same (and more) can be achieved
with the DISTINCT keyword in the <a 
href="#x1-250003.8">ORDERBY</a> clause with the diﬀerence that ORDERBY DISTINCT will
change the order. <br 
class="newline" />For full SQL compliance it is also possible to give the keyword ALL which is the opposite of DISTINCT, thus
all values are returned. This is the default. Because there is an ambiguity between the keyword ALL and
function ALL, the ﬁrst element of the column list cannot be an expression starting with a parenthesis if the
keyword ALL is used.
</p><!--l. 523--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">3.2.1   </span> <a 
 id="x1-170003.2.1"></a>Masked array in column_list</h5>
<!--l. 524--><p class="noindent" >If an expression in the column_list is a masked array, it is possible to create two columns from it: one for the
data, one for the mask. This can be done by combining them in parentheses like <span 
class="cmtt-10x-x-109">(DATA,MASK)</span>. A possible
data type given after the column names only applies to the data column, since the mask column always has
data type Bool. For example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-24">
  select means(DATA[FLAG],0) as (MD,MM) C4 from in.ms giving out.tab
</div>
<!--l. 532--><p class="nopar" > The select results in a masked array containing the means along axis 0. Both column MD and MM are ﬁlled
with the contents of the masked array. MD (with data type C4) contains the means over the ﬁrst axis of the
unmasked elements; MM contains the resulting mask.
</p><!--l. 538--><p class="noindent" ><span 
class="cmbx-12">[</span>
AS options]]</p>
   <h4 class="subsectionHead"><span class="titlemark">3.3   </span> <a 
 id="x1-180003.3"></a>INTO [table] [AS options]</h4>
<!--l. 539--><p class="noindent" >This indicates that the ultimate result of the SELECT command should be written to a table (with the given
name). This table can be a reference table, a plain table, or a memory table.
</p><!--l. 543--><p class="indent" >   The <span 
class="cmti-10x-x-109">table </span>argument gives the name of the resulting table. It can be omitted if a memory table is
created.
</p><!--l. 546--><p class="indent" >   The <span 
class="cmti-10x-x-109">options </span>argument is optional and can be a single value or a list, enclosed in square brackets,
consisting of values and key=value. They can be used to specify the table and storage type. All keys and
values are case-insensitive.
     </p><dl class="description"><dt class="description">
<span 
class="cmbx-10x-x-109">TYPE=&#x2019;value&#x2019;</span>  </dt><dd 
class="description">speciﬁes the table type. <br 
class="newline" />PLAIN = make a persistent table, thus a true copy of all selected rows/columns. <br 
class="newline" />SCRATCH = as plain, but only as a temporary table. <br 
class="newline" />MEMORY = as plain, but keep everything in memory. <br 
class="newline" />If <span 
class="cmti-10x-x-109">TYPE </span>is not given, a reference table is made if no expressions are given in the SELECT clause,
     otherwise a plain table is made.
     </dd><dt class="description">
<span 
class="cmbx-10x-x-109">ENDIAN=&#x2019;value&#x2019;</span>  </dt><dd 
class="description">speciﬁes the endianness <br 
class="newline" />BIG = big endian <br 
class="newline" />LITTLE = little endian <br 
class="newline" />LOCAL = native endianness of the machine being used <br 
class="newline" />AIPSRC = as deﬁned in the .casarc ﬁle (which usually defaults to LOCAL) <br 
class="newline" />If <span 
class="cmti-10x-x-109">ENDIAN </span>is not given, it defaults to AIPSRC.
     </dd><dt class="description">
<span 
class="cmbx-10x-x-109">STORAGE=&#x2019;value&#x2019;</span>  </dt><dd 
class="description">speciﬁes the storage type <br 
class="newline" />SEPFILE = store as separate ﬁles (the old Casacore table format) <br 
class="newline" />MULTIFILE = combine all storage manager ﬁles into a single ﬁle. <br 
class="newline" />MULTIHDF5 = as MULTIFILE, but use an HDF5 ﬁle instead of a regular ﬁle. <br 
class="newline" />DEFAULT = use SEPFILE (but might change in a future Casacore version), <br 
class="newline" />AIPSRC = as deﬁned in the .casarc ﬁle (which usually defaults to DEFAULT) <br 
class="newline" />If <span 
class="cmti-10x-x-109">STORAGE </span>is not given, it defaults to AIPSRC.
     </dd><dt class="description">
<span 
class="cmbx-10x-x-109">BLOCKSIZE=n</span>  </dt><dd 
class="description">speciﬁes the blocksize to use for MULTIFILE or MULTIHDF5.
                                                                                            
                                                                                            
     </dd><dt class="description">
<span 
class="cmbx-10x-x-109">OVERWRITE=F</span>  </dt><dd 
class="description">tells that an existing table with the given name should not be overwritten. By
     default TaQL will overwrite existing tables.</dd></dl>
<!--l. 576--><p class="noindent" >For backward compatibility, it is possible to specify an option directly without having to use &#x2019;key=value&#x2019;.
     </p><dl class="description"><dt class="description">
<span 
class="cmbx-10x-x-109">MEMORY</span>  </dt><dd 
class="description">to store the result in a memory table.
     </dd><dt class="description">
<span 
class="cmbx-10x-x-109">SCRATCH</span>  </dt><dd 
class="description">to store the result in a scratch table, possibly on disk.
     </dd><dt class="description">
<span 
class="cmbx-10x-x-109">PLAIN</span>  </dt><dd 
class="description">to store the result in a plain table.
     </dd><dt class="description">
<span 
class="cmbx-10x-x-109">PLAIN</span><span 
class="cmbx-10x-x-109">_BIG</span>  </dt><dd 
class="description">to store the result in a plain table in big-endian format.
     </dd><dt class="description">
<span 
class="cmbx-10x-x-109">PLAIN</span><span 
class="cmbx-10x-x-109">_LITTLE</span>  </dt><dd 
class="description">to store the result in a plain table in little-endian format.
     </dd><dt class="description">
<span 
class="cmbx-10x-x-109">PLAIN</span><span 
class="cmbx-10x-x-109">_LOCAL</span>  </dt><dd 
class="description">to store the result in a plain table in native endian format.</dd></dl>
<!--l. 587--><p class="noindent" >The standard TaQL way to deﬁne the output table is the <a 
href="#x1-270003.10">GIVING</a> clause. INTO is available for SQL
compliance.
</p><!--l. 591--><p class="indent" >   If the INTO (or GIVING) clause is not given, the query result will be written into a memory table. In
this way queries done in a readonly directory will not fail if a result table cannot created. However, if the
result is expected to not ﬁt in memory (which will seldomly be the case), type SCRATCH should be used to
make it ﬁt.
</p><!--l. 598--><p class="indent" >   If the result is stored in a plain table, it is possible to give detailed data manager info for
the result table using the DMINFO clause. See <a 
href="#x1-950008.2">section 8.2</a> how the data manager info can be
speciﬁed.
</p>
   <h4 class="subsectionHead"><span class="titlemark">3.4   </span> <a 
 id="x1-190003.4"></a>FROM table_list</h4>
<!--l. 605--><p class="noindent" >The FROM part deﬁnes the tables used in the query. It is a comma-separated list of tables, each followed by
an optional shorthand (alias).
</p><!--l. 609--><p class="indent" >   The full syntax is:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-25">
  FROM table1 [shorthand1], table2 [shorthand2], ...
</div>
<!--l. 612--><p class="nopar" > Similar to SQL and OQL the shorthand can also be given using <span 
class="cmtt-10x-x-109">AS </span>or <span 
class="cmtt-10x-x-109">IN</span>. E.g.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-26">
  SELECT FROM mytable AS my, other IN ~user/othertable
</div>
<!--l. 617--><p class="nopar" > Note that if using <span 
class="cmtt-10x-x-109">IN</span>, the shorthand has to precede the table name. It can be seen as an iterator
variable.
</p><!--l. 621--><p class="indent" >   The shorthand can be used in the query to qualify the table to be used for a column, for example
<span 
class="cmtt-10x-x-109">t0.DATA</span>. The ﬁrst table in the list is the primary table which will be used if a column is not qualiﬁed by a
shorthand. Often a query uses a single table in which case a shorthand is not needed. Multiple tables require
a shorthand and are useful when: </p>
     <ul class="itemize1">
     <li class="itemize">A keyword in another table is needed.
     </li>
     <li class="itemize">Columns from multiple tables are used (an implicit <a 
href="#x1-790006.1">join</a>). In such a case the tables must have the same
     number of rows. For example, a regression test could be done like:
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-27">
       SELECT FROM test.MS t1, result.MS t2
      <br />    WHERE not all(near(t1.DATA, t2.DATA))
</div>
     <!--l. 637--><p class="nopar" ></p></li></ul>
<!--l. 639--><p class="noindent" >If the table is normal table with a fully alphanumeric name, the shorthand defaults to that name. In practice a
shorthand is always needed if multiple tables are used.
</p>
<!--l. 643--><p class="noindent" ><span class="likeparagraphHead"><a 
 id="x1-200003.4"></a></span>
   The FROM clause can be omitted, in which case the input is a virtual table with no columns. The
number of rows in it is deﬁned by the LIMIT and OFFSET value; it defaults to 1 row. It makes it possible to
select column-independent expressions in the SELECT command. Note that these expressions do not need to
be constant. For example
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-28">
  SELECT rowid() LIMIT 31
</div>
<!--l. 651--><p class="nopar" > creates a temporary table with column Col_1 and 31 rows containing the values 0..30.
</p>
<!--l. 655--><p class="noindent" ><span class="likeparagraphHead"><a 
 id="x1-210003.4"></a></span>
   A table can be given in a variety of ways.
</p><!--l. 658--><p class="indent" >
     </p><ol  class="enumerate1" >
     <li 
  class="enumerate" id="x1-21002x1">A persistent table can be used by giving its name which can contain path speciﬁcation and
     environment variables or the UNIX <span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">~</span></span></span> notation. If the tablename contains a special character,
     the character can be escaped with a backslash or the table name can be enclosed in single or
     double quotes.
     </li>
     <li 
  class="enumerate" id="x1-21004x2">A table name can be taken from a keyword in a previously speciﬁed table. This can be useful in a
     <a 
href="#x1-740004.11">subquery</a>. The syntax for this is the same as that for specifying <a 
href="#x1-440004.5">keywords</a> in an expression.
     E.g.
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-29">
       SELECT FROM mytable tab
      <br />    WHERE col1 IN [SELECT subcol FROM tab.col2::key]
</div>
     <!--l. 675--><p class="nopar" > In this example <span 
class="cmtt-10x-x-109">key </span>is a table keyword of column <span 
class="cmtt-10x-x-109">col2 </span>in table <span 
class="cmtt-10x-x-109">mytable </span>(note that <span 
class="cmtt-10x-x-109">tab </span>is the
     shorthand for <span 
class="cmtt-10x-x-109">mytable </span>and could be left out). <br 
class="newline" />It can also be used for another table in the main query. E.g.
                                                                                            
                                                                                            
</p>
     <div class="verbatim" id="verbatim-30">
       SELECT FROM mytable, ::key subtab
      <br />    WHERE col1 &#x003E; subtab.key1
</div>
     <!--l. 683--><p class="nopar" > In this example the keyword <span 
class="cmtt-10x-x-109">key1 </span>is taken from the subtable given by the table keyword <span 
class="cmtt-10x-x-109">key </span>in the
     main table. <br 
class="newline" />If a keyword is used as the table name, the keyword is searched in one of the tables previously given.
     The search starts at the current query level and proceeds outwards (i.e., up to the main query level). If
     a shorthand is given, only tables with that shorthand are taken into account. If no shorthand is given,
     only primary tables are taken into account.
     </p></li>
     <li 
  class="enumerate" id="x1-21006x3">Opening a subtable using a path name like <span 
class="cmtt-10x-x-109">my.ms/ANTENNA </span>will fail if <span 
class="cmtt-10x-x-109">my.ms </span>is a reference table instead
     of the original table. Therefore the path of a subtable should be given using colons instead of slashes
     like <span 
class="cmtt-10x-x-109">my.ms::ANTENNA </span>which is a slight extension of specifying table names in the previous bullet.
     <br 
class="newline" />In this way a subtable can always be found.
     </li>
     <li 
  class="enumerate" id="x1-21008x4"><a 
 id="x1-210074"></a> Similar to OQL it is possible to use a <a 
href="#x1-740004.11">nested query</a> command in the FROM clause. This is a normal
     query command enclosed in square brackets or parentheses. Besides the SELECT command the
     COUNT and CREATE TABLE command can also be used. The table created can thereafter be used in
     the rest of the query command by using the shorthand given to that table. It can also be used in the
     remainder of the table_list, thus using it as a backreference. Such backreferencing can be useful to avoid
     multiple equal subqueries. E.g.
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-31">
       select from MS,
      <br />   [select from MS where sumsqr(UVW[1:2]) &#x003C; 625]
      <br />    as TIMESEL
      <br />   where TIME in [select distinct TIME from TIMESEL]
      <br />    &#x0026;&#x0026;  any([ANTENNA1,ANTENNA2] in
      <br />      [select from TIMESEL giving
      <br />        [iif(UVW[3] &#x003C; 0, ANTENNA1, ANTENNA2)]])
</div>
     <!--l. 724--><p class="nopar" > is a command to ﬁnd shadowed antennas for the VLA. Without the query in the FROM command the
     subqueries in the remainder of the command would have been more complex. Furthermore, it would
     have been necessary to execute that select twice. <br 
class="newline" />The command above is quite complex and cannot be fully understood before reading the rest of this
     note. Note, however, that the command uses the shorthand <span 
class="cmtt-10x-x-109">TIMESEL </span>to be able to use the temporary
     table in the subqueries.
     </p></li>
     <li 
  class="enumerate" id="x1-21010x5">Normally only persistent tables (i.e., tables on disk) can be used. However, it is also possible to use
     transient tables in a TaQL command given in <a 
href="#x1-11900013">Python, Glish, or C++</a>. This is done by passing one or
     more table objects to the function executing the TaQL command. In the TaQL command a $-sign
     followed by a sequence number has to be given to indicate the correct object containing the transient
     table. E.g., if two table objects are passed $1 indicates the ﬁrst table, while $2 indicates the second
     one.
     </li>
     <li 
  class="enumerate" id="x1-21012x6"><a 
 id="x1-210116"></a> It is possible to use a concatenation of tables with the same description by giving a list of tables
     enclosed in square brackets. In this way it is, for example, possible to do a query on the
     combined parts of a MeasurementSet partitioned in time. Each table in the list can be
     speciﬁed in one of the ways mentioned in this section, including another table concatenation.
     <br 
class="newline" />For example:
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-32">
       SELECT FROM [ms.part1, ms.part2, ms.part3] WHERE ...
</div>
     <!--l. 760--><p class="nopar" > does a query on the three parts of an MS which are seen as a single table. <br 
class="newline" />It is possible to use glob ﬁlename patterns in such a list. For example
                                                                                            
                                                                                            
</p>
     <div class="verbatim" id="verbatim-33">
       SELECT FROM [ms.part*] WHERE ...
</div>
     <!--l. 766--><p class="nopar" > is the same as the example above if no other ﬁles with such a name exist. An error is given if no table
     is found matching the pattern.
     </p><!--l. 770--><p class="noindent" >Subtables of the concatenated tables can be concatenated as well. Alternatively, they can be assumed
     to be the same for all tables meaning that the subtable of the concatenation is the subtable of the
     ﬁrst table. For example, when partitioning a MeasurementSet in time, the ANTENNA
     subtable is the same for all parts, while the POINTING and SYSCAL subtables depend on
     time, thus have to be concatenated as well. Concatenation of subtables can be achieved
     by giving them as a comma-separated list of names after the SUBTABLES keyword. For
     example:
                                                                                            
                                                                                            
</p>
     <div class="verbatim" id="verbatim-34">
       SELECT FROM [ms.part1, ms.part2 SUBTABLES SYSCAL,POINTING]
</div>
     <!--l. 781--><p class="nopar" >
     </p><!--l. 783--><p class="noindent" >Usually the result of a TaQL query references the table given in the FROM. In this example the
     FROM table is the concatenation, which is only known during the query. In such a case the
     concatenation must be made persistent, which can be done by using a GIVING (or INTO) inside
     the concatenation speciﬁcation. Only the table name can be given, because the persistent
     concatenation only keeps the original table names; it does not make a copy of all data.
     <br 
class="newline" />For example:
                                                                                            
                                                                                            
</p>
     <div class="verbatim" id="verbatim-35">
       SELECT FROM [ms.part1, ms.part2 GIVING ms.conc]
      <br />     WHERE ANTENNA1 != ANTENAA2 GIVING ms.cross
</div>
     <!--l. 794--><p class="nopar" > selects the cross-correlation baselines from the concatenation. Note the two GIVING commands. The
     ﬁrst one makes the concatenation persistent, the second one is the query result of the query <span 
class="cmti-10x-x-109">ms.cross</span>. It
     references the matching rows in the persistent concatenation <span 
class="cmti-10x-x-109">ms.conc </span>which in its turn references the
     original parts.</p></li></ol>
<!--l. 803--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">3.5   </span> <a 
 id="x1-220003.5"></a>WHERE expression</h4>
<!--l. 804--><p class="noindent" >It deﬁnes the selection expression which must have a boolean scalar result. A row in the primary table is
selected if the expression is true for the values in that row. The syntax of the expression is explained in a
<a 
href="#x1-280004">section 4</a>.
</p><!--l. 810--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">3.6   </span> <a 
 id="x1-230003.6"></a>GROUPBY group_list</h4>
<!--l. 811--><p class="noindent" >It deﬁnes how rows have to be grouped. Usually a result per group will be calculated using aggregate
functions. A group consists of all rows for which the columns (or expressions) given in the group_list have the
same value. The (aggregate) expressions in the SELECT clause are calculated for the entire group. In this
way one can get, for example, the mean XX amplitude and the number of time slots per baseline
like:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-36">
  SELECT ANTENNA1,ANTENNA2,GMEAN(AMPLITUDE(DATA[,0])),GCOUNT()
 <br />         FROM my.ms GROUPBY ANTENNA1,ANTENNA2
</div>
<!--l. 821--><p class="nopar" > It results in a table containing <span 
class="cmti-10x-x-109">nbaseline </span>rows with in each row the antenna ids, mean amplitude, and
number of rows. <br 
class="newline" />If no aggregate function is used for a column, the value of the last row in the group is used. Note that in this
example ANTENNA1 and ANTENNA2 are the same for the entire group. However, if TIME was also
selected, only the last time would be part of the result. <br 
class="newline" />Note that each expression in the group_list has to result in a scalar value of type bool, integer, double, date,
or string. <br 
class="newline" />Aggregate functions are discussed in more detail in <a 
href="#x1-750005">section 5</a>.
</p><!--l. 833--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">3.7   </span> <a 
 id="x1-240003.7"></a>HAVING expression</h4>
<!--l. 834--><p class="noindent" >This clause can be used to select speciﬁc groups. Only the groups (deﬁned by GROUPBY) are selected for
which the HAVING expression is true. <br 
class="newline" />Note that HAVING can be given without GROUPBY, although that will hardly ever be useful. If no
GROUPBY is given, but the SELECT statement contains an aggregate function, the result is a single
group. HAVING cannot be used if neither GROUPBY nor SELECT aggregate functions are used.
<br 
class="newline" />It is discussed in more detail in <a 
href="#x1-750005">section 5</a>.
</p><!--l. 846--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">3.8   </span> <a 
 id="x1-250003.8"></a>ORDERBY sort_list</h4>
<!--l. 847--><p class="noindent" >It deﬁnes the order in which the result of the selection has to be sorted. The sort_list is a comma separated
list of expressions. It operates on the output of the SELECT, thus after a possible GROUPBY and HAVING
clause are executed. <br 
class="newline" />The sort_list can be preceded by the word <span 
class="cmtt-10x-x-109">ASC </span>or <span 
class="cmtt-10x-x-109">DESC </span>indicating if the given expressions are by default
sorted in ascending or descending order (default is ASC). Each expression in the sort_list can
optionally be followed by <span 
class="cmtt-10x-x-109">ASC </span>or <span 
class="cmtt-10x-x-109">DESC </span>to override the default order for that particular sort key.
<br 
class="newline" />To be compliant with SQL whitespace can be used between the words ORDER and BY.
</p><!--l. 860--><p class="indent" >   The word ORDERBY can optionally be followed by DISTINCT which means that only the ﬁrst row of
multiple rows with equal sort keys is kept in the result. To be compliant with SQL dialects the word
UNIQUE or NODUPLICATES can be used instead of DISTINCT.
</p><!--l. 866--><p class="indent" >   An expression can be a scalar column or a single element from an array column. In these cases some
optimization is performed by reading the entire column directly. <br 
class="newline" />It can also be an arbitrarily complex expression with exactly the same syntax rules as the expressions in
the <a 
href="#x1-280004">WHERE</a> clause. The resulting data type of the expression must be a standard scalar one,
                                                                                            
                                                                                            
thus it cannot be a Regex or DateTime (see <a 
href="#x1-290004.1">below</a> for a discussion of the available data types).
E.g.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-37">
  ORDERBY col1, col2, col3
 <br />  ORDERBY DESC col1, col2 ASC, col3
 <br />  ORDERBY NODUPLICATES uvw[1] DESC
 <br />  ORDERBY square(uvw[1]) + square(uvw[2])
 <br />  ORDERBY datetime(col)       # incorrect data type
 <br />  ORDERBY mjd(datetime(col))  # is correct
</div>
<!--l. 884--><p class="nopar" >
</p><!--l. 886--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">3.9   </span> <a 
 id="x1-260003.9"></a>LIMIT/OFFSET expression</h4>
<!--l. 887--><p class="noindent" >It indicates which of the matching and sorted rows should be selected. If not given, all of them are selected.
The word <span 
class="cmtt-10x-x-109">TOP </span>can also be used instead of <span 
class="cmtt-10x-x-109">LIMIT</span>. <br 
class="newline" /><span 
class="cmtt-10x-x-109">LIMIT </span>and <span 
class="cmtt-10x-x-109">OFFSET </span>are applied after <span 
class="cmtt-10x-x-109">ORDERBY </span>and <span 
class="cmtt-10x-x-109">SELECT DISTINCT</span>, so they are particularly useful in
combination with those clauses to select, for example, the highest 10 values.
</p><!--l. 895--><p class="indent" >   It can be given in two ways: </p>
     <ul class="itemize1">
     <li class="itemize">In the semi-standard SQL way using <span 
class="cmtt-10x-x-109">LIMIT N </span>to select N rows and/or <span 
class="cmtt-10x-x-109">OFFSET M </span>to skip the ﬁrst
     M rows. Similar to Python, N and M can be negative meaning they are counted from the end.
     E.g., <span 
class="cmtt-10x-x-109">LIMIT -1 </span>means all rows but the last.
     </li>
     <li class="itemize">As a Python-style range using <span 
class="cmtt-10x-x-109">LIMIT start:end:incr</span>, where the end is exclusive. Start defaults
     to 0, end to the number of rows, and incr to 1. As above, start and end can be negative to count
     from the end. The increment must be positive.</li></ul>
<!--l. 906--><p class="noindent" >For example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-38">
  SELECT FROM my.tab ORDERBY DISTINCT TIME LIMIT 2 OFFSET 10
 <br />  SELECT FROM my.tab ORDERBY DISTINCT TIME LIMIT 10:12
</div>
<!--l. 910--><p class="nopar" > sorts uniquely by time, skips the ﬁrst 10 rows, and selects the next two rows.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-39">
  SELECT FROM my.tab LIMIT ::100
</div>
<!--l. 915--><p class="nopar" > selects every 100-th row.
</p><!--l. 918--><p class="noindent" ><span 
class="cmbx-12">[</span>
AS options] — set]</p>
   <h4 class="subsectionHead"><span class="titlemark">3.10   </span> <a 
 id="x1-270003.10"></a>GIVING [table] [AS options] — set</h4>
<!--l. 919--><p class="noindent" >It indicates that the ultimate result of the SELECT command should be written to a table (with the given
name). <br 
class="newline" />Another (more SQL compliant) way to deﬁne the output table is the <a 
href="#x1-180003.3">INTO</a> clause. See <a 
href="#x1-180003.3">INTO</a> for a more
detailed description including the possible types.
</p><!--l. 925--><p class="indent" >   It is also possible to specify a set in the GIVING clause instead of a table name. This is very useful if the
result of a <a 
href="#x1-740004.11">subquery</a> is used in the main query. Such a <a 
href="#x1-460004.7">set</a> can contain multiple elements Each element can be
a single value, range and/or interval as long as all elements have the same data type. The parts of each
element have to be expressions resulting in a scalar.
</p><!--l. 933--><p class="indent" >   In the main query and in a query in the FROM command the GIVING clause can only result in a table
and not in a set. <br 
class="newline" />To be compliant with SQL dialects, the word SAVETO can be used instead of GIVING. Whitespace can be
given between SAVE and TO.
</p>
   <h3 class="sectionHead"><span class="titlemark">4   </span> <a 
 id="x1-280004"></a>Expressions</h3>
<!--l. 940--><p class="noindent" >An expression is the basic building block of TaQL. They are similar to expressions in other languages. An
expression is formed by applying an operator or a function to operands which can be a table column or
keyword, a constant, or a subexpression. An operand can be a scalar value or an array or set. The next
subsections discuss them in detail.
</p><!--l. 947--><p class="indent" >   An expression can be used in several places: </p>
     <ul class="itemize1">
     <li class="itemize">In the WHERE and HAVING clause where the result must be a boolean scalar value. It tells if
     a table row or group will be selected.
     </li>
     <li class="itemize">As a key in the GROUPBY clause where the result must be a scalar value (numeric, bool, or
     string).
     </li>
     <li class="itemize">As a sort key in the ORDERBY clause where the result must be a scalar value (numeric, bool,
     or string)
     </li>
     <li class="itemize">As an element in the set in the GIVING clause. It must be a scalar value of any type except
     regex.
                                                                                            
                                                                                            
     </li>
     <li class="itemize">As a scalar or array value in the INSERT and UPDATE command.
     </li>
     <li class="itemize">As a column expression in the column-list part of the SELECT command. The result can be a
     scalar or array value.
     </li>
     <li class="itemize">As a scalar or array value in the CALC command.
     </li>
     <li class="itemize">As a scalar or array value in various ALTER TABLE subcommands</li></ul>
<!--l. 965--><p class="indent" >   The expression in the clause can be as complex as one likes using arithmetic, comparison, and logical
<a 
href="#x1-450004.6">operators</a>. Parentheses can be used to group subexpressions. <br 
class="newline" />The operands in an expression can be <a 
href="#x1-420004.4">table columns</a>, <a 
href="#x1-440004.5">table keywords</a>, <a 
href="#x1-310004.3">constants</a>, <a 
href="#x1-480004.9">units</a>, <a 
href="#x1-490004.10">functions</a>, <a 
href="#x1-460004.7">sets and
intervals</a>, and <a 
href="#x1-740004.11">subqueries</a>. <br 
class="newline" />The <a 
href="#x1-470004.8">index operator</a> can be used to take a single element or a subsection from an array expression.
<br 
class="newline" />For example,
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-40">
  column1 &#x003E; 10
 <br />  column1 + arraycolumn[index] &#x003E;= min (column2, column3)
 <br />  column1 IN [expr1 =:&#x003C; expr2]
</div>
<!--l. 983--><p class="nopar" > The last example shows a <a 
href="#x1-460004.7">set</a> with a continuous interval.
</p><!--l. 986--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">4.1   </span> <a 
 id="x1-290004.1"></a>Data Types</h4>
<!--l. 987--><p class="noindent" >Internally TaQL uses the following data types:
     </p><dl class="description"><dt class="description">
<span 
class="cmbx-10x-x-109">Bool</span>  </dt><dd 
class="description">logical values (true/false (case-insensitive) or T/F)
     </dd><dt class="description">
<span 
class="cmbx-10x-x-109">Integer</span>  </dt><dd 
class="description">integer numbers up to 64 bits
     </dd><dt class="description">
<span 
class="cmbx-10x-x-109">Double</span>  </dt><dd 
class="description">64 bit ﬂoating point numbers including times/positions
     </dd><dt class="description">
<span 
class="cmbx-10x-x-109">Complex</span>  </dt><dd 
class="description">128 bit complex numbers
     </dd><dt class="description">
<span 
class="cmbx-10x-x-109">String</span>  </dt><dd 
class="description">string values on which operator + can be used (concatenation).
     </dd><dt class="description">
<span 
class="cmbx-10x-x-109">Regex</span>  </dt><dd 
class="description">regular  expressions  can  be  used  for  string  matching  (see  <a 
href="#x1-300004.2">section  4.2</a>).  Maximum  string
     distances can also be used in a way similar to regular expressions.
     </dd><dt class="description">
<span 
class="cmbx-10x-x-109">DateTime</span>  </dt><dd 
class="description">representing a date/time. There are several functions acting on a date/time. Operator
     + and - can be used on them.</dd></dl>
<!--l. 1001--><p class="noindent" >Scalars and arbitrarily shaped arrays of these data types can be used. However, arrays of Regex are not possible.
<br 
class="newline" />If an operand or function argument with a non-matching data type is used, TaQL will do the following
automatic conversions: <br 
class="newline" />- from Integer to Double or Complex. <br 
class="newline" />- from Double to Complex. <br 
class="newline" />- from String or Double to DateTime.
</p><!--l. 1009--><p class="indent" >   In this document some special data types are used when describing the functions. <br 
class="newline" />- <span 
class="cmbx-10x-x-109">Real </span>means Integer or Double. <br 
class="newline" />- <span 
class="cmbx-10x-x-109">Numeric </span>means Integer, Double, or Complex. <br 
class="newline" />- <span 
class="cmbx-10x-x-109">DNumeric </span>means Double or Complex.
                                                                                            
                                                                                            
</p><!--l. 1015--><p class="indent" >   TaQL supports any possible data type of a table column or keyword. In some commands (<a 
href="#x1-150003.2">column list</a> and
<a 
href="#x1-930008">CREATE TABLE</a>) columns are created where it is possible to specify the data type of a column. The
following case-insensitive values can be used to specify a type:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-41">
  B          BOOL       BOOLEAN
 <br />  U1         UCHAR      BYTE
 <br />  I2         SHORT      SMALLINT
 <br />  U2   UI2   USHORT     USMALLINT
 <br />  I4         INT        INTEGER
 <br />  U4   UI4   UINT       UINTEGER
 <br />  R4   FLT   FLOAT
 <br />  R8   DBL   DOUBLE
 <br />  C4   FC    FCOMPLEX   COMPLEX
 <br />  C8   DC    DCOMPLEX
 <br />  S          STRING
 <br />  TIME       DATE       EPOCH
</div>
<!--l. 1033--><p class="nopar" > The <span 
class="cmtt-10x-x-109">TIME </span>type is a special data type. It means that the column gets data type <span 
class="cmtt-10x-x-109">DOUBLE </span>and that
a MEASINFO record will be deﬁned in the column keywords to designate the column as an
epoch.
</p><!--l. 1038--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">4.2   </span> <a 
 id="x1-300004.2"></a>Regular Expressions and String Distances</h4>
<!--l. 1039--><p class="noindent" >TaQL supports the use of extended regular expressions and string distances. They can be speciﬁed in
various ways as discussed in <a 
href="#x1-370004.3.6">section 4.3.6</a>. There are three basic types of regular expressions.
</p>
     <ul class="itemize1">
     <li class="itemize">An SQL-style pattern is quite simple. It has 2 special characters. The underscore (_) means a
     single arbitrary character and the percent (%) means zero or more arbitrary characters.
     Special characters can be escaped with a backslash to retain their normal meaning. For
     example:
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-42">
       3c\_%
</div>
     <!--l. 1052--><p class="nopar" > matches <span 
class="cmtt-10x-x-109">3c</span><span 
class="cmtt-10x-x-109">_ </span>and <span 
class="cmtt-10x-x-109">3c</span><span 
class="cmtt-10x-x-109">_xx</span>, but not <span 
class="cmtt-10x-x-109">3caxx</span>.
     </p></li>
     <li class="itemize">A UNIX-style pattern, as often used for wildcarded ﬁle names, is more powerful than the SQL-style
     pattern. It has a few special characters that can be escaped with a backslash.
          <ul class="itemize2">
          <li class="itemize">The question mark (?) means a single arbitrary character.
          </li>
          <li class="itemize">The asterisk (*) means zero or more arbitrary characters. For example: <span 
class="cmtt-10x-x-109">3c</span><span 
class="cmtt-10x-x-109">_* </span>does the same
          as the SQL-style pattern above.
          </li>
          <li class="itemize">Square brackets indicate a bracket expression (character choice). For example: <span 
class="cmtt-10x-x-109">[ab] </span>matches <span 
class="cmtt-10x-x-109">a </span>and
          <span 
class="cmtt-10x-x-109">b</span>, but not <span 
class="cmtt-10x-x-109">c</span>. A few special characters can be used in a bracket expression:
              <ul class="itemize3">
              <li class="itemize">A leading <span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">^</span></span></span> or ! means negation. Thus <span 
class="cmtt-10x-x-109">[!ab] </span>matches every character except a and b.
              </li>
              <li class="itemize">A minus sign indicates a range. For example <span 
class="cmtt-10x-x-109">[0-9] </span>matches a digit or <span 
class="cmtt-10x-x-109">[a-z] </span>matches
              a lowercase letter. If a minus sign cannot be interpreted as a range, it is a literal minus
              sign like in <span 
class="cmtt-10x-x-109">[-ab] </span>or the second minus sign in <span 
class="cmtt-10x-x-109">[a-z-A]</span>.
              </li>
              <li class="itemize">Posix character classes <span 
class="cmtt-10x-x-109">[:xx:] </span>where xx can be: <br 
class="newline" />- <span 
class="cmbx-10x-x-109">alpha </span>matching any letter <br 
class="newline" />- <span 
class="cmbx-10x-x-109">lower </span>matching any lowercase letter <br 
class="newline" />- <span 
class="cmbx-10x-x-109">upper </span>matching any uppercase letter <br 
class="newline" />- <span 
class="cmbx-10x-x-109">alnum </span>matching any digit or letter <br 
class="newline" />- <span 
class="cmbx-10x-x-109">digit </span>matching any digit <br 
class="newline" />- <span 
class="cmbx-10x-x-109">xdigit </span>matching any hexadecimal digit (0-9a-fA-F) <br 
class="newline" />- <span 
class="cmbx-10x-x-109">space </span>matching any whitespace character <br 
class="newline" />- <span 
class="cmbx-10x-x-109">print </span>matching any printable character (alnum, punct, space) <br 
class="newline" />- <span 
class="cmbx-10x-x-109">punct </span>matching any non-alnum visible character (.,!? etc.) <br 
class="newline" />- <span 
class="cmbx-10x-x-109">graph </span>matching any visible printable character (alnum, punct) <br 
class="newline" />- <span 
class="cmbx-10x-x-109">cntrl </span>matching any control character. <br 
class="newline" />For example <span 
class="cmtt-10x-x-109">[</span><span 
class="cmtt-10x-x-109">_[:isalpha:]][</span><span 
class="cmtt-10x-x-109">_[:isalnum:]]* </span>to match variable names.
              </li>
              <li class="itemize">A bracket expression cannot be empty, thus if ] is the ﬁrst character in the bracket
              expression, it is interpreted literally. Note that is also true if it is the ﬁrst character
              after the negation character.
              </li>
              <li class="itemize">A backslash in a character class is always interpreted literally, thus special characters
              cannot be escaped. However, as shown above they can always be placed such that they
              are interpreted literally.</li></ul>
                                                                                            
                                                                                            
          </li>
          <li class="itemize">Braces can be used for a choice between (possible empty) multi-character strings separated by
          commas. Escape a comma or brace with a backslash to treat it literally. For example:
          <br 
class="newline" /><span 
class="cmtt-10x-x-109">*.</span><span 
class="cmsy-10x-x-109">{</span><span 
class="cmtt-10x-x-109">h,hpp,c,cc,cpp</span><span 
class="cmsy-10x-x-109">}</span><br 
class="newline" />It is fully nestable, thus choice strings can be patterns. For example: <br 
class="newline" /><span 
class="cmtt-10x-x-109">*.</span><span 
class="cmsy-10x-x-109">{</span><span 
class="cmtt-10x-x-109">[hc]</span><span 
class="cmsy-10x-x-109">{</span><span 
class="cmtt-10x-x-109">,pp</span><span 
class="cmsy-10x-x-109">}</span><span 
class="cmtt-10x-x-109">,c</span><span 
class="cmsy-10x-x-109">}</span><br 
class="newline" />does the same as the example above. Note that the inner choice is between an empty string and
          <span 
class="cmtt-10x-x-109">pp</span>.</li></ul>
     </li>
     <li class="itemize">An awk/egrep-like extended regular expression is most powerful. A full explanation can be found on
     Wikipedia. Here only a summary of its special characters is given. They can be escaped using
     backslashes.
          <ul class="itemize2">
          <li class="itemize"><span 
class="cmtt-10x-x-109">. </span>matches any character.
          </li>
          <li class="itemize"><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">^</span></span></span> matches beginning of string.
          </li>
          <li class="itemize">$ matches end of string.
          </li>
          <li class="itemize">Square  brackets  for  a  bracket  expression.  It  is  the  same  as  described  above  with  the
          exception that ! cannot be used as negation character.
          </li>
          <li class="itemize">* matches zero or more occurrences of previous character or subexpression.
          </li>
          <li class="itemize">+ matches one or more occurrences.
          </li>
          <li class="itemize">? matches zero or one occurrence.
          </li>
          <li class="itemize"><span 
class="cmsy-10x-x-109">{ </span>and <span 
class="cmsy-10x-x-109">} </span>for an interval giving minimum and maximum number of occurrences. For example:
          <br 
class="newline" /><span 
class="cmtt-10x-x-109">[a-z]</span><span 
class="cmsy-10x-x-109">{</span><span 
class="cmtt-10x-x-109">3,5</span><span 
class="cmsy-10x-x-109">} </span>matches lowercase string with a minimum of 3 and maximum of 5 characters.
          <br 
class="newline" /><span 
class="cmtt-10x-x-109">[a-z]</span><span 
class="cmsy-10x-x-109">{</span><span 
class="cmtt-10x-x-109">3</span><span 
class="cmsy-10x-x-109">} </span>matches exactly 3 characters. <br 
class="newline" /><span 
class="cmtt-10x-x-109">[a-z]</span><span 
class="cmsy-10x-x-109">{</span><span 
class="cmtt-10x-x-109">3,</span><span 
class="cmsy-10x-x-109">} </span>matches at least 3 characters. <br 
class="newline" /><span 
class="cmtt-10x-x-109">[a-z]</span><span 
class="cmsy-10x-x-109">{</span><span 
class="cmtt-10x-x-109">,5</span><span 
class="cmsy-10x-x-109">} </span>matches at most 5 characters.
          </li>
          <li class="itemize"><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">|</span></span></span> matches left or right substring
          </li>
          <li class="itemize">( and ) to form subexpressions for operators like *.
          </li>
          <li class="itemize"><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">\1</span></span></span> till <span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">\9</span></span></span> mean backreference to a subexpression (ﬁrst one is <span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">\1</span></span></span>). A string part matches if
          it is equal to the string part matching that subexpression. e.g., <span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">(a*)x\1</span></span></span> matches x, axa,
          aaxaa, etc., but not axaa nor aaxa.</li></ul>
     <!--l. 1139--><p class="noindent" >For example:
                                                                                            
                                                                                            
</p>
     <div class="verbatim" id="verbatim-43">
       .*\.(h|hpp|c|cc|cpp)
      <br />  .*\.[hc](pp)?|cc
</div>
     <!--l. 1143--><p class="nopar" > do the same as the pattern examples above.</p></li></ul>
<!--l. 1146--><p class="noindent" >Furthermore it is possible to specify maximum string distances (known as Levensthein or Edit distance). It is
explained in <a 
href="#x1-370004.3.6">section 4.3.6</a>.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-44">
  column ~ d/string/ibnn
</div>
<!--l. 1152--><p class="nopar" >
</p><!--l. 1154--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">4.3   </span> <a 
 id="x1-310004.3"></a>Constants</h4>
<!--l. 1155--><p class="noindent" >Scalar constants of the various data types can be formed in a way similar to Python and Glish. Array
constants can be formed from scalar constants.
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">4.3.1   </span> <a 
 id="x1-320004.3.1"></a>Bool</h5>
<!--l. 1159--><p class="noindent" >A Bool constant is the value <span 
class="cmtt-10x-x-109">T </span>or <span 
class="cmtt-10x-x-109">F </span>(both in uppercase) or the value <span 
class="cmtt-10x-x-109">true </span>or <span 
class="cmtt-10x-x-109">false </span>(any case).
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">4.3.2   </span> <a 
 id="x1-330004.3.2"></a>Integer</h5>
<!--l. 1162--><p class="noindent" >An integer constant is a numeric value without decimal point or exponent. It can also be given as a
hexadecimal value like <span 
class="cmtt-10x-x-109">0xffff</span>.
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">4.3.3   </span> <a 
 id="x1-340004.3.3"></a>Double (and time/position)</h5>
<!--l. 1165--><p class="noindent" >A ﬂoating-point constant is given with a decimal point and/or exponent. &#x2019;E&#x2019; or &#x2019;e&#x2019; can be used to
specify the exponent. An integer number followed by a unit is also regarded as a double constant.
<br 
class="newline" />Another way to deﬁne a Double constant is by means of a Time or Position. Such a constant is always
converted to radians. It can be given in several ways: </p>
     <ul class="itemize1">
     <li class="itemize">An  integer  or  ﬂoating-point  number  immediately  followed  by  a  simple  unit  (thus  without
     whitespace). e.g., <span 
class="cmtt-10x-x-109">12.43deg </span><br 
class="newline" />Some valid units are deg, arcmin, arcsec (or as), rad. The units can be scaled by preceding them
     with a letter (e.g., mrad is millirad).
     </li>
     <li class="itemize">A time/position in HMS format. Seconds can be left out. e.g., <span 
class="cmtt-10x-x-109">12h34m34.5 </span>or <span 
class="cmtt-10x-x-109">8h32m</span>
     </li>
     <li class="itemize">A position in DMS format. Seconds can be left out. e.g., <span 
class="cmtt-10x-x-109">12d34m34.5 </span>or <span 
class="cmtt-10x-x-109">8d0m</span>
     </li>
     <li class="itemize">A position as DMS in dot format. Note that all parts must be present. e.g., <span 
class="cmtt-10x-x-109">12.34.34.5 </span>or
     <span 
class="cmtt-10x-x-109">8.0.34.5</span></li></ul>
                                                                                            
                                                                                            
<!--l. 1186--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">4.3.4   </span> <a 
 id="x1-350004.3.4"></a>Complex</h5>
<!--l. 1187--><p class="noindent" >The imaginary part of a Complex constant is formed by an Integer or Double constant immediately followed
by a lowercase <span 
class="cmbx-10x-x-109">i </span>or <span 
class="cmbx-10x-x-109">j</span>. A full Complex constant is formed by adding another Integer or Double constant as the
real part. E.g.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-45">
  1.5 + 2j
 <br />  2i+1.5            is identical
 <br />  
</div>
<!--l. 1195--><p class="nopar" > Note that a full Complex constant has to be enclosed in parentheses if, say, a multiplication is performed on
it. E.g.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-46">
  2 * (1.5+2i)
 <br />  
</div>
<!--l. 1200--><p class="nopar" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">4.3.5   </span> <a 
 id="x1-360004.3.5"></a>String</h5>
<!--l. 1202--><p class="noindent" >A String constant has to be enclosed in ” or &#x2019; and can be concatenated (as in C++). E.g.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-47">
  &#x0022;this is a string constant&#x0022;
 <br />  &#x2019;this is a string constant containing a &#x0022;&#x2019;
 <br />  &#x0022;ab&#x2019;cd&#x0022;&#x2019;ef&#x0022;gh&#x2019;
 <br />      which results in:   ab&#x2019;cdef&#x0022;gh
 <br />  
</div>
<!--l. 1209--><p class="nopar" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">4.3.6   </span> <a 
 id="x1-370004.3.6"></a>Regular expression and String distance</h5>
<!--l. 1211--><p class="noindent" >A <a 
href="#x1-300004.2">regular expression</a> constant can be given directly or using a function. </p>
     <ul class="itemize1">
     <li class="itemize">An SQL-style pattern can be given directly as a string constant preceded by operator LIKE or
     NOT LIKE.
     </li>
     <li class="itemize">A pattern or regular expression can be given like <span 
class="cmtt-10x-x-109">x/expr/q </span>preceded by operator <span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">~</span></span></span> or <span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">!~</span></span></span>. Instead of a
     slash, the characters % and # can also be used as delimiter, as long as the same delimiter is used on
     both sides. The delimiter can not be part of the expression (not even escaped with a backslash).
     <br 
class="newline" />The x denotes the type: <br 
class="newline" />- <span 
class="cmbx-10x-x-109">p </span>means a pattern matching the full string. <br 
class="newline" />- <span 
class="cmbx-10x-x-109">f </span>means a regular expression matching the full string. <br 
class="newline" />- <span 
class="cmbx-10x-x-109">m </span>means a regular expression matching part of the string (a la Perl). <br 
class="newline" />The q denotes optional qualiﬁers. Currently only <span 
class="cmbx-10x-x-109">i </span>is supported meaning a case-insensitive match. For
     example:
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-48">
       name~p/3[cC]*/
      <br />  name ~ p%3c*%i
      <br />  lower(name) ~ p%3c*%
      <br />  name ~ m/^3c/i
      <br />  name ~ f/3c.*/i
      <br />  filename !~ p#/usr/*.{h,cc}#
</div>
     <!--l. 1235--><p class="nopar" > All examples but the last one do the same: matching a name starting with 3c or 3C. <br 
class="newline" />The last example shows a glob-style pattern to ﬁnd ﬁles on <span 
class="cmtt-10x-x-109">/usr </span>not ending in <span 
class="cmtt-10x-x-109">.h </span>or <span 
class="cmtt-10x-x-109">.cc</span>.
     </p></li>
     <li class="itemize">Apart from these Perl-like speciﬁcations, a regular expression can also be formed by applying a function
     to a string constant. The operator = or != has to be applied to it.
          <ul class="itemize2">
          <li class="itemize">Function <span 
class="cmtt-10x-x-109">sqlpattern </span>treats its argument as an SQL-style pattern. For example:
                                                                                            
                                                                                            
          <div class="verbatim" id="verbatim-49">
            lower(name) LIKE &#x2019;3c%&#x2019;
           <br />  lower(name) = sqlpattern(&#x2019;3c%&#x2019;)
</div>
          <!--l. 1249--><p class="nopar" > do the same.
          </p></li>
          <li class="itemize">Function <span 
class="cmtt-10x-x-109">pattern </span>treats its argument as a UNIX-style pattern.
          </li>
          <li class="itemize">Function <span 
class="cmtt-10x-x-109">regex </span>treats its argument as a full regular expression.</li></ul>
     <!--l. 1254--><p class="noindent" >Case-insensitive matching can only be done as shown in the example above by downcasing the string to
     be matched. <br 
class="newline" />Please note that these functions are not limited to constants. They can also be used to form regular
     expressions from variables.</p></li></ul>
<!--l. 1260--><p class="indent" >   A maximum string distance constant can be speciﬁed in a similar way. Such a distance is known as the
Levensthein or Edit distance. It is a measure of the similarity of strings by counting the minimum number of
edits (deletions, insertions, substitutions, and swaps of adjacent characters) that need to be done to make the
strings equal.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-50">
  column ~ d/string/ibnn
</div>
<!--l. 1268--><p class="nopar" > This tests if the strings in the given column are within the maximum distance of the string given in the
constant. The following qualiﬁers can be given (in any order): </p>
     <ul class="itemize1">
     <li class="itemize"><span 
class="cmbx-10x-x-109">i </span>means a case insensitive test.
     </li>
     <li class="itemize"><span 
class="cmbx-10x-x-109">b </span>means that blanks in the strings are ignored.
     </li>
     <li class="itemize"><span 
class="cmbx-10x-x-109">nn </span>is an integer value giving the maximum distance. If not given it defaults to <span 
class="cmtt-10x-x-109">1 + len(string)</span>
     <span 
class="cmtt-10x-x-109">/ 3</span>.</li></ul>
<!--l. 1279--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">4.3.7   </span> <a 
 id="x1-380004.3.7"></a>Date/time</h5>
<!--l. 1280--><p class="noindent" >DateTime constant can be formed in 2 ways:
     </p><ol  class="enumerate1" >
     <li 
  class="enumerate" id="x1-38002x1">From a String constant using the <span 
class="cmtt-10x-x-109">datetime </span>function. In this way all possible formats as explained in
     class <a 
href="../html/classcasa_1_1MVTime.html" >MVTime</a> are supported. E.g.
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-51">
       datetime (&#x0022;11-Dec-1972&#x0022;)
</div>
     <!--l. 1288--><p class="nopar" >
     </p></li>
     <li 
  class="enumerate" id="x1-38004x2">A more convenient way is to specify it directly. Since this makes use of the delimiters space, - or /, it
     conﬂicts with the expression grammar as such. However, possible conﬂicts can be solved by using
     whitespace in an expression and it is believed that in practice the convenience surpasses the possible
     conﬂicts. <br 
class="newline" />A large subset of the MVTime formats is supported. A DateTime has to be speciﬁed as <span 
class="cmtt-10x-x-109">date/time </span>or
     <span 
class="cmtt-10x-x-109">date-time</span>, where the time part (including the space, -, or / delimiter) is optional. The possible date
     formats are: <br 
class="newline" />- YYYY/MM/DD, YYYY-MM-DD, or DD-MM-YYYY where DD and MM must be 2 digits and
     YYYY 4 digits. <br 
class="newline" />- DD-MMMMMMMM-YY where the - is optional and MMMMMMM is the case-insensitive name of
     the month (at least 3 letters). DD can be 1 or 2 digits and YY 1 to 4 digits. 2000 is added if
     YY<!--l. 1304--><math 
 xmlns="http://www.w3.org/1998/Math/MathML"  
display="inline" > <mo 
class="MathClass-rel">&#x003C;</mo></math>50 and 1900 is added if
     50<!--l. 1305--><math 
 xmlns="http://www.w3.org/1998/Math/MathML"  
display="inline" > <mo 
class="MathClass-rel">&#x003C;</mo><mo 
class="MathClass-rel">=</mo></math>YY<!--l. 1305--><math 
 xmlns="http://www.w3.org/1998/Math/MathML"  
display="inline" > <mo 
class="MathClass-rel">&#x003C;</mo></math>100.
     <br 
class="newline" />If MM<!--l. 1306--><math 
 xmlns="http://www.w3.org/1998/Math/MathML"  
display="inline" > <mo 
class="MathClass-rel">&#x003E;</mo></math>12,
     YYYY will be incremented accordingly. <br 
class="newline" />The general time format in a DateTime constant is: <br 
class="newline" />- hh:mm:ss.s <br 
class="newline" />where the delimiter <span 
class="cmbx-10x-x-109">h </span>or <span 
class="cmbx-10x-x-109">H </span>can be used for the ﬁrst colon and <span 
class="cmbx-10x-x-109">m </span>or <span 
class="cmbx-10x-x-109">M </span>for the second. Trailing parts
     can be omitted. E.g.
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-52">
       10-02-1997
      <br />  10-February-97
      <br />  10feb97
      <br />  1997/02/10         are all identical
      <br />
      <br />  1May96/3:          : (or h) is mandatory
      <br />  1May96-3:0
      <br />  1May96 3:0:0
      <br />  1May96-3h          h (or :) is mandatory
      <br />  1May96 3H0
      <br />  1May96/3h0M
      <br />  1May96/3hm0.0
</div>
     <!--l. 1325--><p class="nopar" > A DateTime constant with the current date/time can be made by using the function <span 
class="cmtt-10x-x-109">datetime </span>without
     arguments.</p></li></ol>
<!--l. 1330--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">4.3.8   </span> <a 
 id="x1-390004.3.8"></a>Arrays</h5>
<!--l. 1331--><p class="noindent" >N-dimensional arrays of all data types can be created with the exception of regular expressions.
<br 
class="newline" />It is possible to form a 1-dimensional array from a constant bounded discrete <a 
href="#x1-460004.7">set</a>. When needed such a set is
automatically transformed to an array. E.g.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-53">
  [0:10]
 <br />  [&#x2019;str1&#x2019;, &#x2019;str2&#x2019;, &#x2019;str3&#x2019;]
 <br />  &#x2019;str&#x2019; + [&#x2019;1&#x2019;, &#x2019;2&#x2019;, &#x2019;3&#x2019;]
</div>
<!--l. 1340--><p class="nopar" > The ﬁrst example results in an integer array of 10 elements with values 0..9. The others result in a string
array of 3 elements. The second version already shows that strings can be concatenated (as explained further
on).
</p><!--l. 1345--><p class="indent" >   A multi-dimensional array can be formed by giving a set of arrays. A nested list resembles the <span 
class="cmti-10x-x-109">numpy</span>
way. For example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-54">
  [[1,2,3],[4,5,6]]
</div>
<!--l. 1349--><p class="nopar" > results in a 2-dim array. However, it is also possible to use arrays created in other ways such as arrays in a
column or arrays created with the <span 
class="cmtt-10x-x-109">array </span>function described below. For example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-55">
  [[[1,2,3],[4,5,6]], array([10:13],2,3)]
</div>
<!--l. 1355--><p class="nopar" > results in a 3-dim array.
</p><!--l. 1358--><p class="indent" >   Furthermore it is possible to use the <span 
class="cmtt-10x-x-109">array </span>function to create an array of any shape. The values are given
in the ﬁrst argument as a scalar, set, or another array. The shape is given in the latter arguments as scalars
or as a set. The array is initialized to the values given which are wrapped if the array has more
elements.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-56">
  array([1:11],10,4)
 <br />  array([1:11], [10,4])
 <br />  array(F,shape(DATA))
</div>
<!--l. 1367--><p class="nopar" > The ﬁrst examples create an array with shape [10,4] containing the values 1..10 in each line.
The latter results in a boolean array having the same shape as the DATA array and ﬁlled with
False.
</p><!--l. 1373--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">4.3.9   </span> <a 
 id="x1-400004.3.9"></a>Masked Arrays</h5>
<!--l. 1374--><p class="noindent" >An array can have an optional mask. Similar to numpy&#x2019;s masked array, a mask value True means that the
value is masked oﬀ, thus not taken into account in reduce functions like calculating the mean.
<br 
class="newline" />Note that this deﬁnition is the same as the FLAG column in a MeasurementSet, but is diﬀerent from a mask
in a Casacore Image where True means good and False means bad.
</p><!--l. 1381--><p class="indent" >   All operations on arrays will take the possible mask into account. Reduce functions like <span 
class="cmtt-10x-x-109">median </span>only use
the unmasked array elements. Furthermore, partial reduce functions like <span 
class="cmtt-10x-x-109">medians </span>will set an
output mask element to True if the corresponding input array part has no unmasked elements.
<br 
class="newline" />Operators like + and functions like <span 
class="cmtt-10x-x-109">cos </span>operate on all array elements. The mask in the resulting array is
the logical OR of the input masks. Of course, the result has no mask if no input array has a
mask.
</p><!--l. 1391--><p class="indent" >   A masked array is created by applying a boolean array to an array using the square brackets operator.
Both arrays must have the same shape. For example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-57">
  DATA[FLAG]
 <br />  DATA[DATA &#x003E; 3*median(abs(DATA))]
</div>
<!--l. 1397--><p class="nopar" > The ﬁrst example applies the FLAG column in a MeasurementSet to the DATA column. The second
example masks oﬀ high DATA values.
</p><!--l. 1402--><p class="indent" >   The functions <span 
class="cmtt-10x-x-109">arraydata</span>, <span 
class="cmtt-10x-x-109">arraymask</span>, and <span 
class="cmtt-10x-x-109">flatten </span>can be used to get the array data or mask. The last
one ﬂattens the array to a vector while removing all masked elements.
</p><!--l. 1406--><p class="indent" >   The TaQL commands putting values into a table accept two columns (in parentheses) for a masked array.
This is described in more detail in the appropriate sections. For example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-58">
  select means(DATA[FLAG],0) as (MD,MM) from in.ms giving out.tab
</div>
<!--l. 1411--><p class="nopar" > to write the data averaged over the ﬁrst axis (frequency channel)into column MD. Only the unﬂagged data
points are taken into account. The output contains the resulting ﬂags in column MM; a ﬂag is set to True if
all channels were ﬂagged.
</p><!--l. 1417--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">4.3.10   </span> <a 
 id="x1-410004.3.10"></a>Null Arrays</h5>
<!--l. 1418--><p class="noindent" >A cell in a table column containing variable shaped arrays, can be empty. Such a cell does not contain an
array and is represented in TaQL as a null array. Note it is diﬀerent from a cell containing an empty array,
which is an array without values.
</p><!--l. 1424--><p class="indent" >   Null arrays can be used with any operator and in any function. If one of the operands or function
arguments is a null array, the result will be a null array; only array functions reducing to a scalar (such as
<span 
class="cmtt-10x-x-109">sum </span>and <span 
class="cmtt-10x-x-109">mean</span>) give a valid value (usually 0).
</p><!--l. 1429--><p class="indent" >   The UPDATE and INSERT commands will ignore a null array result; no value is written in that
row.
</p><!--l. 1433--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">4.4   </span> <a 
 id="x1-420004.4"></a>Table Columns</h4>
<!--l. 1434--><p class="noindent" >A table column can be used in a query by giving its name in the expression, possibly qualiﬁed with a table
shorthand name. A column can contain a scalar or an array value of any data type supported by the table
system. It will be mapped to the available TaQL <a 
href="#x1-290004.1">data types</a>. If the column keywords deﬁne a <a 
href="#x1-480004.9">unit</a> for the
column, the unit will be used by TaQL.
</p><!--l. 1442--><p class="indent" >   The name of a column can contain alphanumeric characters and underscores. It should start with an
alphabetic character or underscore. A column name is case-sensitive. <br 
class="newline" />It is possible to use other characters in the name by escaping them with a backslash. e.g., <span 
class="cmtt-10x-x-109">DATE</span><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">\</span></span></span><span 
class="cmtt-10x-x-109">-OBS</span>.
<br 
class="newline" />In the same way a numeric character can be used as the ﬁrst character of the column name. e.g., <span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">\</span></span></span><span 
class="cmtt-10x-x-109">1stDay</span>.
<br 
class="newline" />A <a 
href="#x1-100002.3">reserved word</a> cannot be used directly as a column name. It can, however, be used by escaping it with a
backslash. e.g., <span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">\</span></span></span><span 
class="cmtt-10x-x-109">IN</span>. <br 
class="newline" />Note that in programming languages like C++ and Python a backslash itself has to be escaped by another backslash. e.g., in Python:
<span 
class="cmtt-10x-x-109">tab.query(&#x2019;DATE</span><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">\\</span></span></span><span 
class="cmtt-10x-x-109">-OBS</span><!--l. 1456--><math 
 xmlns="http://www.w3.org/1998/Math/MathML"  
display="inline" > <mo 
class="MathClass-rel">&#x003E;</mo></math><span 
class="cmtt-10x-x-109">10MAR1996&#x2019;)</span>.
</p><!--l. 1458--><p class="indent" >   If a column contains a record, one has to specify a ﬁeld in it using the dot operator; e.g., <span 
class="cmtt-10x-x-109">col.fld </span>means
use ﬁeld <span 
class="cmtt-10x-x-109">fld </span>in the column. It is fully recursive, so <span 
class="cmtt-10x-x-109">col.fld.subfld </span>can be used if ﬁeld <span 
class="cmtt-10x-x-109">fld </span>is a record in
itself. <br 
class="newline" />Alas records in columns are not really supported yet. One can specify ﬁelds, but thereafter an error message
will be given.
                                                                                            
                                                                                            
</p><!--l. 1466--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">4.4.1   </span> <a 
 id="x1-430004.4.1"></a>Referring to SELECT columns</h5>
<!--l. 1467--><p class="noindent" >Usually a column used in an expression will be a column in one of the tables speciﬁed in the FROM clause.
However, it is possible to use a column created in the SELECT clause, in expressions given in the HAVING
or ORDERBY clause. In fact, a column name not preceded by a table shorthand, is ﬁrst looked up in the
SELECT columns and thereafter in the ﬁrst FROM table.
</p><!--l. 1474--><p class="indent" >   It can be advantageous to use a SELECT column if that column is an expression; it saves both typing and
execution time. because that expression is executed only once.
</p><!--l. 1479--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">4.5   </span> <a 
 id="x1-440004.5"></a>Table Keywords</h4>
<!--l. 1480--><p class="noindent" >It is possible to use table or column keywords, which can have a scalar or an array value or a record, possibly
nested. A table keyword has to be speciﬁed as <span 
class="cmtt-10x-x-109">::key</span>. In an expression the <span 
class="cmtt-10x-x-109">:: </span>part can be omitted if
there is no column with the same name. A column keyword has to be speciﬁed as <span 
class="cmtt-10x-x-109">column::key</span>.
<br 
class="newline" />Note that the <span 
class="cmtt-10x-x-109">:: </span>syntax is chosen, because it is similar to the scope operator in C++. <br 
class="newline" />As explained in the <a 
href="#x1-190003.4">FROM clause</a>, keywords in the primary table and in other tables can be used. If
used from another table, it has to be qualiﬁed with the (shorthand) name of the table. E.g.,
<br 
class="newline" /><span 
class="cmtt-10x-x-109">sh.key </span>or <span 
class="cmtt-10x-x-109">sh.::key </span><br 
class="newline" />takes table keyword <span 
class="cmtt-10x-x-109">key </span>from the table with the shorthand name <span 
class="cmtt-10x-x-109">sh</span>.
</p><!--l. 1497--><p class="indent" >   If a keyword value is a record, it is possible to use a ﬁeld in it using the dot operator. e.g., <span 
class="cmtt-10x-x-109">::key.fld </span>to
use ﬁeld <span 
class="cmtt-10x-x-109">fld</span>. It is fully recursive, so if the ﬁeld is a record in itself, a subﬁeld can be used like
<span 
class="cmtt-10x-x-109">col::key.fld.subfld</span>
</p><!--l. 1503--><p class="indent" >   A keyword can be used in any expression. It is evaluated immediately and transformed to a constant
value.
</p><!--l. 1506--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">4.6   </span> <a 
 id="x1-450004.6"></a>Operators</h4>
<!--l. 1507--><p class="noindent" >TaQL has a fair amount of operators which have the same meaning as their C and Python counterparts. The
operator precedence order is:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-59">
  **
 <br />  !  ~  +  -       (unary operators)
 <br />  *  /  // %
 <br />  +  -
 <br />  &#x0026;
 <br />  ^
 <br />  |
 <br />  == != &#x003E;  &#x003E;= &#x003C;  &#x003C;=  ~= !~= IN INCONE BETWEEN EXISTS LIKE  ~  !~
 <br />  &#x0026;&#x0026;
 <br />  ||
</div>
<!--l. 1521--><p class="nopar" > Operator names are case-insensitive. For SQL compliancy some operators have a synonym.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-60">
  ==     =
 <br />  !=     &#x003C;&#x003E;
 <br />  &#x0026;&#x0026;     AND
 <br />  ||     OR
 <br />  !      NOT
 <br />  ^      XOR
</div>
<!--l. 1531--><p class="nopar" > All operators can be used for scalars and arrays and a mix of them. Note that arrays of regular expressions
cannot be used.
</p><!--l. 1535--><p class="indent" >   The following table shows all available operators and the data types that can be used with
them.
</p>
                                                                                            
                                                                                            
   <div class="tabular"> <table id="TBL-3" class="tabular" 
cellspacing="0" cellpadding="0"  
><colgroup id="TBL-3-1g"><col 
id="TBL-3-1" /><col 
id="TBL-3-2" /><col 
id="TBL-3-3" /></colgroup><tr  
 style="vertical-align:baseline;" id="TBL-3-1-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-1-1"  
class="td11">Operator                                                                                                                                                                                                                                                              </td><td  style="text-align:left;" id="TBL-3-1-2"  
class="td11"><!--l. 1539--><p class="noindent" >Data Type </p></td><td  style="text-align:left;" id="TBL-3-1-3"  
class="td11"><!--l. 1539--><p class="noindent" >Description                                                               </p></td>
</tr><tr 
class="hline"><td><hr /></td><td><hr /></td><td><hr /></td></tr><tr  
 style="vertical-align:baseline;" id="TBL-3-2-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-2-1"  
class="td11"><span 
class="cmtt-10x-x-109">**                                                                                                                                                                       </span></td><td  style="text-align:left;" id="TBL-3-2-2"  
class="td11"><!--l. 1540--><p class="noindent" >numeric     </p></td><td  style="text-align:left;" id="TBL-3-2-3"  
class="td11"><!--l. 1540--><p class="noindent" >power. It is right associative, thus <span 
class="cmtt-10x-x-109">2**1**2 </span>results in <span 
class="cmtt-10x-x-109">2</span>.     </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-3-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-3-1"  
class="td11"><span 
class="cmtt-10x-x-109">*                                                                                                                                                                        </span></td><td  style="text-align:left;" id="TBL-3-3-2"  
class="td11"><!--l. 1542--><p class="noindent" >numeric     </p></td><td  style="text-align:left;" id="TBL-3-3-3"  
class="td11"><!--l. 1542--><p class="noindent" >multiplication                                                            </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-4-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-4-1"  
class="td11"><span 
class="cmtt-10x-x-109">/                                                                                                                                                                        </span></td><td  style="text-align:left;" id="TBL-3-4-2"  
class="td11"><!--l. 1543--><p class="noindent" >numeric     </p></td><td  style="text-align:left;" id="TBL-3-4-3"  
class="td11"><!--l. 1543--><p class="noindent" >non-truncated division, thus <span 
class="cmtt-10x-x-109">1/2 </span>results in <span 
class="cmtt-10x-x-109">0.5</span>          </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-5-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-5-1"  
class="td11"><span 
class="cmtt-10x-x-109">//                                                                                                                                                                       </span></td><td  style="text-align:left;" id="TBL-3-5-2"  
class="td11"><!--l. 1545--><p class="noindent" >real           </p></td><td  style="text-align:left;" id="TBL-3-5-3"  
class="td11"><!--l. 1545--><p class="noindent" >truncated division (a la Python) resulting in an integer, thus
<span 
class="cmtt-10x-x-109">1./2. </span>results in <span 
class="cmtt-10x-x-109">0</span>                                   </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-6-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-6-1"  
class="td11"><span 
class="cmtt-10x-x-109">%                                                                                                                                                                        </span></td><td  style="text-align:left;" id="TBL-3-6-2"  
class="td11"><!--l. 1547--><p class="noindent" >real           </p></td><td  style="text-align:left;" id="TBL-3-6-3"  
class="td11"><!--l. 1547--><p class="noindent" >modulo; <span 
class="cmtt-10x-x-109">3.5%1.2 </span>results in <span 
class="cmtt-10x-x-109">1.1</span>; <span 
class="cmtt-10x-x-109">-5%3 </span>results in <span 
class="cmtt-10x-x-109">-2</span>       </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-7-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-7-1"  
class="td11"><span 
class="cmtt-10x-x-109">+                                                                                                                                                                        </span></td><td  style="text-align:left;" id="TBL-3-7-2"  
class="td11"><!--l. 1549--><p class="noindent" >no bool      </p></td><td  style="text-align:left;" id="TBL-3-7-3"  
class="td11"><!--l. 1549--><p class="noindent" >addition. If a date is used, only a real (converted to unit day)
can be added to it. String addition means concatenation.   </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-8-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-8-1"  
class="td11"><span 
class="cmtt-10x-x-109">-                                                                                                                                                                        </span></td><td  style="text-align:left;" id="TBL-3-8-2"  
class="td11"><!--l. 1552--><p class="noindent" >numeric,date </p> </td> <td  style="text-align:left;" id="TBL-3-8-3"  
class="td11"><!--l. 1552--><p class="noindent" >subtraction. Substracting a date from a date results in a real
(with unit day). Subtracting a real (converted to unit day)
from a date results in a date.                                        </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-9-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-9-1"  
class="td11"><span 
class="cmtt-10x-x-109">&#x0026;                                                                                                                                                                        </span></td><td  style="text-align:left;" id="TBL-3-9-2"  
class="td11"><!--l. 1555--><p class="noindent" >integer       </p></td><td  style="text-align:left;" id="TBL-3-9-3"  
class="td11"><!--l. 1555--><p class="noindent" >bitwise and                                                               </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-10-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-10-1"  
class="td11"><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">|</span></span></span>                                                                                                                                                                        </td><td  style="text-align:left;" id="TBL-3-10-2"  
class="td11"><!--l. 1556--><p class="noindent" >integer       </p></td><td  style="text-align:left;" id="TBL-3-10-3"  
class="td11"><!--l. 1556--><p class="noindent" >bitwise or                                                                 </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-11-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-11-1"  
class="td11"><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">^</span></span></span>, XOR                                                                                                                                                                                                                                                                 </td><td  style="text-align:left;" id="TBL-3-11-2"  
class="td11"><!--l. 1557--><p class="noindent" >integer       </p></td><td  style="text-align:left;" id="TBL-3-11-3"  
class="td11"><!--l. 1557--><p class="noindent" >bitwise xor                                                                </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-12-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-12-1"  
class="td11"><!--l. 1558--><math 
 xmlns="http://www.w3.org/1998/Math/MathML"  
display="inline" > <mo 
class="MathClass-rel">=</mo><mo 
class="MathClass-rel">=</mo></math>, <!--l. 1558--><math 
 xmlns="http://www.w3.org/1998/Math/MathML"  
display="inline" > <mo 
class="MathClass-rel">=</mo></math></td><td  style="text-align:left;" id="TBL-3-12-2"  
class="td11"><!--l. 1558--><p class="noindent" >all            </p></td><td  style="text-align:left;" id="TBL-3-12-3"  
class="td11"><!--l. 1558--><p class="noindent" >comparison for equal. The norm is used when comparing
complex numbers.                                                      </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-13-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-13-1"  
class="td11"><!--l. 1560--><math 
 xmlns="http://www.w3.org/1998/Math/MathML"  
display="inline" > <mo 
class="MathClass-rel">&#x003E;</mo></math>                                                                                                                  </td><td  style="text-align:left;" id="TBL-3-13-2"  
class="td11"><!--l. 1560--><p class="noindent" >no bool      </p></td><td  style="text-align:left;" id="TBL-3-13-3"  
class="td11"><!--l. 1560--><p class="noindent" >comparison for greater                                                </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-14-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-14-1"  
class="td11"><!--l. 1561--><math 
 xmlns="http://www.w3.org/1998/Math/MathML"  
display="inline" > <mo 
class="MathClass-rel">&#x003E;</mo><mo 
class="MathClass-rel">=</mo></math>                                                                                                                                      </td><td  style="text-align:left;" id="TBL-3-14-2"  
class="td11"><!--l. 1561--><p class="noindent" >no bool      </p></td><td  style="text-align:left;" id="TBL-3-14-3"  
class="td11"><!--l. 1561--><p class="noindent" >comparison for greater or equal                                     </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-15-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-15-1"  
class="td11"><!--l. 1562--><math 
 xmlns="http://www.w3.org/1998/Math/MathML"  
display="inline" > <mo 
class="MathClass-rel">&#x003C;</mo></math>                                                                                                                  </td><td  style="text-align:left;" id="TBL-3-15-2"  
class="td11"><!--l. 1562--><p class="noindent" >no bool      </p></td><td  style="text-align:left;" id="TBL-3-15-3"  
class="td11"><!--l. 1562--><p class="noindent" >comparison for less                                                     </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-16-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-16-1"  
class="td11"><!--l. 1563--><math 
 xmlns="http://www.w3.org/1998/Math/MathML"  
display="inline" > <mo 
class="MathClass-rel">&#x003C;</mo><mo 
class="MathClass-rel">=</mo></math>                                                                                                                                      </td><td  style="text-align:left;" id="TBL-3-16-2"  
class="td11"><!--l. 1563--><p class="noindent" >no bool      </p></td><td  style="text-align:left;" id="TBL-3-16-3"  
class="td11"><!--l. 1563--><p class="noindent" >comparison for less or equal                                         </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-17-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-17-1"  
class="td11"><!--l. 1564--><math 
 xmlns="http://www.w3.org/1998/Math/MathML"  
display="inline" ><mo 
class="MathClass-punc">!</mo> <mo 
class="MathClass-rel">=</mo></math>, <!--l. 1564--><math 
 xmlns="http://www.w3.org/1998/Math/MathML"  
display="inline" > <mo 
class="MathClass-rel">&#x003C;</mo><mo 
class="MathClass-rel">&#x003E;</mo></math></td><td  style="text-align:left;" id="TBL-3-17-2"  
class="td11"><!--l. 1564--><p class="noindent" >all            </p></td><td  style="text-align:left;" id="TBL-3-17-3"  
class="td11"><!--l. 1564--><p class="noindent" >comparison for not equal                                             </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-18-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-18-1"  
class="td11"><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">~=</span></span></span>                                                                                                                                                                       </td><td  style="text-align:left;" id="TBL-3-18-2"  
class="td11"><!--l. 1565--><p class="noindent" >numeric     </p></td><td  style="text-align:left;" id="TBL-3-18-3"  
class="td11"><!--l. 1565--><p class="noindent" >shorthand for the <a 
href="#x1-540004.10.5">NEAR function</a> with a tolerance of 1e-5  </p></td></tr><tr  
 style="vertical-align:baseline;" id="TBL-3-19-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-19-1"  
class="td11"><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">!~=</span></span></span> </td> <td  style="text-align:left;" id="TBL-3-19-2"  
class="td11"><!--l. 1568--><p class="noindent" >numeric </p> </td> <td  style="text-align:left;" id="TBL-3-19-3"  
class="td11"><!--l. 1568--><p class="noindent" >shorthand for NOT <a 
href="#x1-540004.10.5">NEAR</a> with a tolerance of 1e-5</p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-20-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-20-1"  
class="td11"><span 
class="cmtt-10x-x-109">&#x0026;&#x0026;</span>, AND                                                                                                                                                                                                                                                               </td><td  style="text-align:left;" id="TBL-3-20-2"  
class="td11"><!--l. 1571--><p class="noindent" >bool          </p></td><td  style="text-align:left;" id="TBL-3-20-3"  
class="td11"><!--l. 1571--><p class="noindent" >logical and                                                                </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-21-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-21-1"  
class="td11"><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">||</span></span></span>, OR                                                                                                                                                                                                                                                                 </td><td  style="text-align:left;" id="TBL-3-21-2"  
class="td11"><!--l. 1572--><p class="noindent" >bool          </p></td><td  style="text-align:left;" id="TBL-3-21-3"  
class="td11"><!--l. 1572--><p class="noindent" >logical or                                                                  </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-22-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-22-1"  
class="td11"><span 
class="cmtt-10x-x-109">!</span>, NOT                                                                                                                                                                                                                                                                 </td><td  style="text-align:left;" id="TBL-3-22-2"  
class="td11"><!--l. 1573--><p class="noindent" >bool          </p></td><td  style="text-align:left;" id="TBL-3-22-3"  
class="td11"><!--l. 1573--><p class="noindent" >logical not                                                                </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-23-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-23-1"  
class="td11"><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">~</span></span></span>                                                                                                                                                                        </td><td  style="text-align:left;" id="TBL-3-23-2"  
class="td11"><!--l. 1574--><p class="noindent" >integer       </p></td><td  style="text-align:left;" id="TBL-3-23-3"  
class="td11"><!--l. 1574--><p class="noindent" >bitwise negation                                                         </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-24-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-24-1"  
class="td11"><span 
class="cmtt-10x-x-109">+                                                                                                                                                                        </span></td><td  style="text-align:left;" id="TBL-3-24-2"  
class="td11"><!--l. 1575--><p class="noindent" >numeric     </p></td><td  style="text-align:left;" id="TBL-3-24-3"  
class="td11"><!--l. 1575--><p class="noindent" >unary plus                                                                </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-25-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-25-1"  
class="td11"><span 
class="cmtt-10x-x-109">-                                                                                                                                                                        </span></td><td  style="text-align:left;" id="TBL-3-25-2"  
class="td11"><!--l. 1576--><p class="noindent" >numeric     </p></td><td  style="text-align:left;" id="TBL-3-25-3"  
class="td11"><!--l. 1576--><p class="noindent" >unary minus                                                              </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-26-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-26-1"  
class="td11"><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">~</span></span></span>                                                                                                                                                                        </td><td  style="text-align:left;" id="TBL-3-26-2"  
class="td11"><!--l. 1577--><p class="noindent" >string        </p></td><td  style="text-align:left;" id="TBL-3-26-3"  
class="td11"><!--l. 1577--><p class="noindent" >test if string matches a regular expression <a 
href="#x1-310004.3">constant</a>.          </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-27-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-27-1"  
class="td11"><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">!~</span></span></span>                                                                                                                                                                       </td><td  style="text-align:left;" id="TBL-3-27-2"  
class="td11"><!--l. 1579--><p class="noindent" >string        </p></td><td  style="text-align:left;" id="TBL-3-27-3"  
class="td11"><!--l. 1579--><p class="noindent" >test if string does not match a regular expression constant. </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-28-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-28-1"  
class="td11">LIKE                                                                                                                                                                                                                                                                    </td><td  style="text-align:left;" id="TBL-3-28-2"  
class="td11"><!--l. 1581--><p class="noindent" >string        </p></td><td  style="text-align:left;" id="TBL-3-28-3"  
class="td11"><!--l. 1581--><p class="noindent" >test if a string matches an SQL pattern.                         </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-29-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-29-1"  
class="td11">NOT LIKE                                                                                                                                                                                                                                                            </td><td  style="text-align:left;" id="TBL-3-29-2"  
class="td11"><!--l. 1582--><p class="noindent" >string        </p></td><td  style="text-align:left;" id="TBL-3-29-3"  
class="td11"><!--l. 1582--><p class="noindent" >test if string does not match an SQL pattern.                  </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-30-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-30-1"  
class="td11">IN                                                                                                                                                                                                                                                                        </td><td  style="text-align:left;" id="TBL-3-30-2"  
class="td11"><!--l. 1583--><p class="noindent" >all            </p></td><td  style="text-align:left;" id="TBL-3-30-3"  
class="td11"><!--l. 1583--><p class="noindent" >test if a value is present in a set of values, ranges, and/or
intervals. (See the discussion of <a 
href="#x1-460004.7">sets</a>).                             </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-31-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-31-1"  
class="td11">NOT IN                                                                                                                                                                                                                                                                </td><td  style="text-align:left;" id="TBL-3-31-2"  
class="td11"><!--l. 1586--><p class="noindent" >all            </p></td><td  style="text-align:left;" id="TBL-3-31-3"  
class="td11"><!--l. 1586--><p class="noindent" >negation of IN                                                           </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-32-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-32-1"  
class="td11">BETWEEN                                                                                                                                                                                                                                                           </td><td  style="text-align:left;" id="TBL-3-32-2"  
class="td11"><!--l. 1587--><p class="noindent" >no bool      </p></td><td  style="text-align:left;" id="TBL-3-32-3"  
class="td11"><!--l. 1587--><p class="noindent" ><span 
class="cmtt-10x-x-109">x BETWEEN b AND c </span>is similar to <span 
class="cmtt-10x-x-109">x&#x003E;=b AND x&#x003C;=c </span>and <span 
class="cmtt-10x-x-109">x IN</span>
<span 
class="cmtt-10x-x-109">[b=:=c]</span>                                          </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-33-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-33-1"  
class="td11">NOT BETWEEN                                                                                                                                                                                                                                                   </td><td  style="text-align:left;" id="TBL-3-33-2"  
class="td11"><!--l. 1589--><p class="noindent" >no bool      </p></td><td  style="text-align:left;" id="TBL-3-33-3"  
class="td11"><!--l. 1589--><p class="noindent" ><span 
class="cmtt-10x-x-109">a NOT BETWEEN b AND c </span>is negation of above.                 </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-34-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-34-1"  
class="td11">INCONE                                                                                                                                                                                                                                                               </td><td  style="text-align:left;" id="TBL-3-34-2"  
class="td11"><!--l. 1591--><p class="noindent" >          </p></td><td  style="text-align:left;" id="TBL-3-34-3"  
class="td11"><!--l. 1591--><p class="noindent" >cone search. (See the discussion of <a 
href="#x1-640004.10.15">cone search functions</a>).  </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-35-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-35-1"  
class="td11">NOT INCONE                                                                                                                                                                                                                                                       </td><td  style="text-align:left;" id="TBL-3-35-2"  
class="td11"><!--l. 1593--><p class="noindent" >          </p></td><td  style="text-align:left;" id="TBL-3-35-3"  
class="td11"><!--l. 1593--><p class="noindent" >negation of INCONE                                                  </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-36-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-36-1"  
class="td11">EXISTS                                                                                                                                                                                                                                                                </td><td  style="text-align:left;" id="TBL-3-36-2"  
class="td11"><!--l. 1594--><p class="noindent" >          </p></td><td  style="text-align:left;" id="TBL-3-36-3"  
class="td11"><!--l. 1594--><p class="noindent" >test if a subquery ﬁnds at least N matching rows. The value
for N is taken from its LIMIT clause; if LIMIT is not given it
defaults to 1. The subquery loop stops as soon as N matching
rows   are   found.   E.g.   <span 
class="cmtt-10x-x-109">EXISTS(select from ::ANTENNA</span>
<span 
class="cmtt-10x-x-109">where NAME=&#x2019;&#x2019;somename&#x2019;&#x2019; LIMIT 2) </span>results in true if at
least 2 matching rows in the ANTENNA table were found. </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-37-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-37-1"  
class="td11">NOT EXISTS                                                                                                                                                                                                                                                        </td><td  style="text-align:left;" id="TBL-3-37-2"  
class="td11"><!--l. 1602--><p class="noindent" >          </p></td><td  style="text-align:left;" id="TBL-3-37-3"  
class="td11"><!--l. 1602--><p class="noindent" >negation of EXISTS                                                   </p></td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-3-38-"><td  style="text-align:left; white-space:nowrap;" id="TBL-3-38-1"  
class="td11">                                                                                                                                                                         </td> </tr></table>
</div>
<!--l. 1605--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">4.7   </span> <a 
 id="x1-460004.7"></a>Sets and intervals</h4>
<!--l. 1606--><p class="noindent" >As in SQL the operator <span 
class="cmtt-10x-x-109">IN </span>can be used to do a selection based on a set. E.g.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-61">
  SELECT FROM table WHERE column IN [1,2,3]
</div>
<!--l. 1610--><p class="nopar" > The result of operator <span 
class="cmtt-10x-x-109">IN </span>is true if the column value matches one of the values in the set. A set can contain
any data type except a regex.
</p><!--l. 1616--><p class="indent" >   This example shows that (in its simplest form) a set consists of one or more values (which can be
arbitrary expressions) separated by commas and enclosed in square brackets. The elements in a set have to be
scalars and their data types have to be the same or convertible to a common data type. The square brackets
can be left out if the set consists of only one element. For SQL compliance parentheses can be used instead of
square brackets.
</p><!--l. 1625--><p class="indent" >   An array is also a set, so <span 
class="cmtt-10x-x-109">IN </span>can also be used on an array like:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-62">
  SELECT FROM table WHERE column IN expr1
</div>
<!--l. 1629--><p class="nopar" > where <span 
class="cmtt-10x-x-109">expr1 </span>is the array result of some expression. It is also possible to use a scalar as the
righthand of operator <span 
class="cmtt-10x-x-109">IN</span>. So if <span 
class="cmtt-10x-x-109">expr1 </span>is a scalar, operator <span 
class="cmtt-10x-x-109">IN </span>gives the same result as operator
<span 
class="cmtt-10x-x-109">==</span>.
</p><!--l. 1636--><p class="indent" >   The lefthand operand of the <span 
class="cmtt-10x-x-109">IN </span>operator can also be an array or set. In that case the result is a
boolean array telling for each element in the lefthand operand if it is found in the righthand
operand.
</p><!--l. 1641--><p class="indent" >   An element in a set can be more complicated than a single value. It can deﬁne multiple values and
intervals. The possible forms of a set element are:
     </p><ol  class="enumerate1" >
     <li 
  class="enumerate" id="x1-46002x1">A single value as shown in the example above.
     </li>
     <li 
  class="enumerate" id="x1-46004x2"><span 
class="cmtt-10x-x-109">start:end:incr</span>. This is similar to the way an array index is speciﬁed. Incr defaults to 1. End defaults
     to an open end (i.e., no upper bound) and results in an unbounded set. Start and end can be a real or a
     datetime. Incr has to be a real. Some examples:
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-63">
       1:10         means 1,2,...,9  (also 10 when using glish style)
      <br />  1:10:2       means 1,3,5,7,9
      <br />  1::2         means all odd numbers
      <br />  1:           means all positive integer numbers
      <br />  18Aug97::2   means every other day from 18Aug97 on
</div>
     <!--l. 1657--><p class="nopar" > These examples show constants only, but <span 
class="cmtt-10x-x-109">start</span>, <span 
class="cmtt-10x-x-109">end</span>, and <span 
class="cmtt-10x-x-109">incr </span>can be any expression.
     <br 
class="newline" />Note that :: used here can conﬂict with the :: in the <a 
href="#x1-440004.5">keywords</a>. e.g., <span 
class="cmtt-10x-x-109">a::b </span>is scanned as a keyword
     speciﬁcation. If the intention is <span 
class="cmtt-10x-x-109">start::incr</span>, whitespace should be used as in <span 
class="cmtt-10x-x-109">a: :b</span>. In practice this
     conﬂict will hardly ever occur.
     </p></li>
     <li 
  class="enumerate" id="x1-46006x3">Continuous intervals can be speciﬁed for data type real, string, and datetime. The speciﬁcation of an
     interval resembles the mathematical notation <span 
class="cmtt-10x-x-109">1&#x003C;x&#x003C;5</span>, where x is replaced by :. An open interval side is
     indicated by <span 
class="cmtt-10x-x-109">&#x003C;</span>, while a closed interval side is indicated by <span 
class="cmtt-10x-x-109">=</span>. <br 
class="newline" />Another way to specify intervals is using curly and/or angle brackets. A curly bracket is a closed side,
     the angle bracket is an open side. The following examples show how bounded and half-bounded,
     (half-)open and closed intervals can be speciﬁed.
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-64">
       1=:=5   {1,5}     means 1&#x003C;=x&#x003C;=5   bounded closed
      <br />  1&#x003C;:&#x003C;5   &#x003C;1,5&#x003E;     means 1&#x003C;x&#x003C;5     bounded open
      <br />  1=:&#x003C;5   {1,5&#x003E;     means 1&#x003C;=x&#x003C;5    bounded right-open
      <br />  1&#x003C;:=5   &#x003C;1,5}     means 1&#x003C;x&#x003C;=5    bounded left-open
      <br />  1=:  {1,}  {1,&#x003E;   means 1&#x003C;=x      left-bounded closed
      <br />  1&#x003C;:  &#x003C;1,}  &#x003C;1,&#x003E;   means 1&#x003C;x       left-bounded open
      <br />  :=5  {,5}  &#x003C;,5}   means x&#x003C;=5      right-bounded closed
      <br />  :&#x003C;5  {,5&#x003E;  &#x003C;,5&#x003E;   means x&#x003C;5       right-bounded open
</div>
     <!--l. 1683--><p class="nopar" ></p></li></ol>
<!--l. 1685--><p class="noindent" >It is very important to note that the 2nd form of set speciﬁcation results in discrete values, while the 3rd form
results in a continuous interval.
</p><!--l. 1688--><p class="indent" >   Each element in a set can have its own form, i.e., one element can be a single value while another can be
an interval. If a set consists of single or bounded discrete <span 
class="cmtt-10x-x-109">start:end:incr </span>values only, the set will be
expanded to an array. This makes it possible for array operators and functions (like <span 
class="cmtt-10x-x-109">mean</span>) to be applied to
such sets. E.g.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-65">
  WHERE column &#x003E; mean([10,30:100:5])
</div>
<!--l. 1697--><p class="nopar" >
</p><!--l. 1699--><p class="indent" >   Another form of constructing a set is using a <a 
href="#x1-740004.11">subquery</a> as described in section 4.11.
</p><!--l. 1702--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">4.8   </span> <a 
 id="x1-470004.8"></a>Array Index Operator</h4>
<!--l. 1703--><p class="noindent" >It is possible to take a subsection or a single element from an array column, keyword or expression using the
index operator <span 
class="cmtt-10x-x-109">[index1,index2,...]</span>. This syntax is similar to that used in Python or Glish. Similar to
Python a negative value can be given meaning counting from the end. However, a negative stride cannot be
given. Taking a single element can be done as:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-66">
  array[1, 2]
 <br />  array[-1, -1]                  last element
 <br />  array[1, some_expression]
</div>
<!--l. 1715--><p class="nopar" > Taking a subsection can be done as:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-67">
  array[start1:end1:incr1, start2:end2:incr2, ...]
</div>
<!--l. 1719--><p class="nopar" > If a start value is left out it defaults to the beginning of that axis. An end value defaults to the end of the
axis and an increment defaults to one. If an entire axis is left out, it defaults to the entire axis.
<br 
class="newline" />E.g., an array with shape [10,15,20] can be subsectioned as:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-68">
  [,,3]               resulting in an array of shape [10,15,1]
 <br />  [2:4, ::3, 2:15:2]  resulting in an array of shape [3,5,7]
 <br />                      (NB. shape is [2,5,7] for python style)
 <br />  [-1:-1,,]           last element of first axis, all elements other axes
</div>
<!--l. 1730--><p class="nopar" > The examples show that an index can be a simple constant (as it will usually be). It can also be an
expression which can be as complex as one likes. The expression has to result in a real value which will be
truncated to an integer. <br 
class="newline" />For ﬁxed shaped arrays checking if array bounds are exceeded is done at parse time. For variable shaped
arrays it can only be done per row. If array bounds are exceeded, an exception is thrown. In the future a
special undeﬁned value will be assigned if bounds of variable shaped arrays are exceeded to prevent the
selection process from aborting due to the exception.
</p><!--l. 1743--><p class="indent" >   Note that the index operator will be applied directly to a column. This results in reading only the
required part of the array from the table column on disk. It is, however, also possible to apply it to a
subexpression (enclosed in parentheses) resulting in an array. E.g.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-69">
  arraycolumn[2,3,4] + 1
 <br />  (arraycolumn + 1)[2,3,4]
</div>
<!--l. 1752--><p class="nopar" > can both be used and have the same result. However, the ﬁrst form is faster, because only a
single element is read (resulting in a scalar) and 1 is added to it. The second form results in
reading the entire array. 1 is added to all elements and only then the requested element is taken.
<br 
class="newline" />From this example it should be clear that indexing an array expression has to be done with
care.
</p><!--l. 1761--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">4.9   </span> <a 
 id="x1-480004.9"></a>Units</h4>
<!--l. 1762--><p class="noindent" >Units can be given at many places in an expression; in fact, each subexpression can be ended with a unit
meaning that the subexpression result gets that unit or will be converted to that unit. A simple unit (only
letters) can always be given literally. A non-simple unit can be given literally if only containing digits,
underscores and/or dots (e.g., <span 
class="cmtt-10x-x-109">m2</span>, <span 
class="cmtt-10x-x-109">fl</span><span 
class="cmtt-10x-x-109">_oz</span>. or <span 
class="cmtt-10x-x-109">m.m</span>). Otherwise the unit has to be enclosed in single or double
quotes (e.g., <span 
class="cmtt-10x-x-109">&#x2019;m/s&#x2019;</span>) or the backslash has to be used as escape character (e.g., <span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">\</span></span></span><span 
class="cmtt-10x-x-109">in </span>or <span 
class="cmtt-10x-x-109">m</span><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">\</span></span></span><span 
class="cmtt-10x-x-109">/s</span>).
<br 
class="newline" />Arguments to functions like <span 
class="cmtt-10x-x-109">sin </span>will be converted to the appropriate unit (radians) as needed. In a similar
way, the units of operands to operators like addition, will be converted as needed. An exception is thrown if a
unit conversion is not possible.
</p><!--l. 1776--><p class="indent" >   All units supported by module <a 
href="../html/group__Quanta__module.html" >Quanta</a> can be used. Note that the units are case sensitive. Most common
units use lowercase characters. A unit can be preceded by a scaling preﬁx (like <span 
class="cmtt-10x-x-109">k </span>for kilo). Compound units
are created when multiplying or dividing values with units. The available units can be shown using the <span 
class="cmtt-10x-x-109">show</span>
<span 
class="cmtt-10x-x-109">units </span>command of the program <span 
class="cmti-10x-x-109">taql</span>.
</p><!--l. 1785--><p class="indent" >   Units can be given as follows: </p>
     <ul class="itemize1">
     <li class="itemize">If a column has a unit deﬁned in column keyword <span 
class="cmtt-10x-x-109">QuantumUnits </span>or <span 
class="cmtt-10x-x-109">UNIT</span>, it automatically gets
     that unit.
     </li>
     <li class="itemize">A constant can immediately be followed by a simple unit. e.g., <span 
class="cmtt-10x-x-109">2deg</span>.
     </li>
     <li class="itemize">The result of several expressions have an implicit unit. <br 
class="newline" />Constants given as positions are in radians (rad). <br 
class="newline" />Diﬀerence of 2 dates is in days (d). <br 
class="newline" />Inverse trigonometric functions like <span 
class="cmtt-10x-x-109">asin </span>give radians.
     </li>
     <li class="itemize">When combining values with diﬀerent units in e.g., an interval, a set, an addition, or a function like
     <span 
class="cmtt-10x-x-109">min</span>, the values are converted to the unit of the ﬁrst operand or argument with a unit.
                                                                                            
                                                                                            
     Values without a unit have by default the unit of the ﬁrst operand or argument with a
     unit.
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-70">
       3mm-7cm          result is -67 mm
      <br />  3+3mm            result is 6 mm
      <br />  3mm&#x003C;:&#x003C;3cm        result is interval &#x003C;3mm,30mm&#x003E;
      <br />  [3,4cm,5]        result is [3cm, 4cm, 5cm]
      <br />  [5, 7cm, 8mm]    result is [5cm, 7cm, 0.8cm]
      <br />  [5, 7mm, 8cm]    result is [5mm, 7mm, 80mm]
      <br />  max(3mm,2cm)     result is 20 mm
      <br />  5 &#x2019;km/h&#x2019; + 1 &#x2019;m/s&#x2019;      is 8.6 km/h
      <br />  iif(F,3min,30sec)       is 0.5 min
</div>
     <!--l. 1811--><p class="nopar" >
     </p></li>
     <li class="itemize">Similarly, operands of comparison operators and arguments of comparison functions (like <span 
class="cmtt-10x-x-109">near</span>) are
     converted to the unit of the ﬁrst operand or argument with a unit.
     </li>
     <li class="itemize">The result of a multiplication and division is a compound unit if both operands have a unit. Otherwise
     it is the unit of the argument with a unit. <br 
class="newline" />Before TaQL supported units, it was needed to divide the TIME column in a MeasurementSet
     by 86400 to convert it to days, so it could be compared with a given date/time. So, for
     backward compatibility, a division of a value with unit <span 
class="cmtt-10x-x-109">s </span>by a constant 86400 results in unit
     <span 
class="cmtt-10x-x-109">d</span>.
     </li>
     <li class="itemize">Division of units of an equal kind (e.g., km by m) results in a unitless value.
     </li>
     <li class="itemize">Division of a unitless value by a value with unit, results in the reciproke unit.
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-71">
       1km/10m          result is 100
      <br />  1/2s             result is 0.5 &#x2019;(s)-1&#x2019;
      <br />  1Hz + 1/2s       result is 1.5Hz
</div>
     <!--l. 1831--><p class="nopar" >
     </p></li>
     <li class="itemize">The result of functions like <span 
class="cmtt-10x-x-109">SUMSQR </span>and <span 
class="cmtt-10x-x-109">SQRT </span>is a compound unit if the argument has a unit. Note that
     <span 
class="cmtt-10x-x-109">sqrt(2m) </span>will fail, because the square root of a meter does not exist.
     </li>
     <li class="itemize">A (sub)expression can be followed by a simple or compound unit. If the subexpression
     has no unit, it gets the given unit. Otherwise the resulting value is converted to the unit.
     <br 
class="newline" />Note that some units can be the same as a <a 
href="#x1-100002.3">reserved word</a> (e.g., <span 
class="cmtt-10x-x-109">as </span>or <span 
class="cmtt-10x-x-109">in</span>). In that case it has to be
     escaped or enclosed in quotes.
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-72">
       COL \in          set/convert column COL to inch
      <br />  3 cm             result is 3 cm
      <br />  3 &#x2019;km/s&#x2019;         result is 3 km/second
      <br />  3mm cm           result is 0.3 cm
      <br />  (3mm cm)m        result is 0.003 m
      <br />  (3+3) cm         result is 6 cm
      <br />  (3+3mm) cm       result is 0.6 cm
      <br />  [3,4,5]mm        result is [3mm, 4mm, 5mm]
      <br />  [3,4cm,5]mm      result is [30mm, 40mm, 50mm]
      <br />      Note: all values in the set first get the same unit cm
      <br />  asin(1)          result is pi/2 radians
      <br />  asin(1) deg      result is 90 degrees
      <br />  (3mm+7cm) m      result is 0.073 m
</div>
     <!--l. 1857--><p class="nopar" >
     </p></li>
     <li class="itemize">If a function argument is expected in a certain unit, values are converted as needed. For example,
     arguments to functions <span 
class="cmtt-10x-x-109">sin </span>and <span 
class="cmtt-10x-x-109">anycone </span>are automatically converted to radians.
     </li>
     <li class="itemize">When adding or subtracting a value from a date, that value is converted to unit <span 
class="cmtt-10x-x-109">d </span>(days).</li></ul>
<!--l. 1865--><p class="noindent" >Units will probably mostly be used in an expression in the WHERE clause or in a CALC command.
However, it is also possible to use a unit in the selection of a column in the SELECT clause. For
example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-73">
  select TIME d as TIMED from my.ms
</div>
<!--l. 1870--><p class="nopar" > In such a case the selection is an expression and the unit is stored in the column keywords. Thus in this
example, TIME is stored in a column <span 
class="cmtt-10x-x-109">TIMED </span>with keyword <span 
class="cmtt-10x-x-109">QuantumUnits=d </span>and the values are converted to
days.
</p><!--l. 1876--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">4.10   </span> <a 
 id="x1-490004.10"></a>Functions</h4>
<!--l. 1877--><p class="noindent" >More than 100 functions exist to operate on scalar and/or array values. Some functions have two names. One
name is the CASA/Glish name, while the other is the name as used in SQL. In the following tables the
function names are shown in uppercase, while the result and argument types are shown in lowercase. Note,
however, that function names are case-insensitive. <br 
class="newline" />Furthermore it is possible to have <a 
href="#x1-650004.10.16">user deﬁned functions</a> that are dynamically loaded from a shared library.
In section <a 
href="#x1-12700014">Writing user deﬁned functions</a> it is explained how to write user deﬁned functions.
<br 
class="newline" />A set of standard UDFs exists dealing with <a 
href="#x1-710004.10.18">Measure conversions</a>, for example to convert J2000 to
apparent. Another set of UDFs deals with values and relations in <a 
href="#x1-660004.10.17">MeasurementSets and Calibration
Tables</a>.
</p><!--l. 1893--><p class="indent" >   <a 
href="#x1-460004.7">Sets</a>, and in particular <a 
href="#x1-740004.11">subqueries</a>, can result in a 1-dim array. This means that the functions accepting an
array argument can also be used on a set or the result of a subquery.
</p><!--l. 1898--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">4.10.1   </span> <a 
 id="x1-500004.10.1"></a>String functions</h5>
<!--l. 1899--><p class="noindent" >These functions can be used on a scalar or an array argument.
     </p><dl class="description"><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">integer STRLENGTH(string), integer LEN(string)</span><br 
class="newline" />Returns the number of characters in a string (trailing whitespace is signiﬁcant).
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">string UPCASE(string), string UPPER(string) </span><br 
class="newline" />Convert to uppercase.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">string DOWNCASE(string), string LOWER(string)</span><br 
class="newline" />Convert to lowercase.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">string CAPITALIZE(string)</span><br 
class="newline" />Capitalize a string (make ﬁrst letter uppercase).
                                                                                            
                                                                                            
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">string LTRIM(string)</span><br 
class="newline" />Removes leading whitespace.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">string RTRIM(string)</span><br 
class="newline" />Removes trailing whitespace.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">string TRIM(string)</span><br 
class="newline" />Removes leading and trailing whitespace.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">string SUBSTR(string, integer ST, integer N)</span><br 
class="newline" />Returns a substring starting at the 0-based position <span 
class="cmtt-10x-x-109">ST </span>with a length of at most <span 
class="cmtt-10x-x-109">N </span>characters. If
     the string argument is an array of strings, an array with the substring of each string is returned.
     The arguments ST and N have to be scalar values. If ST is negative, it counts from the end (a
     la Python). N and the resulting ST will be set to 0 if negative.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">string REPLACE(string SRC, PATTERN, string REPL)</span><br 
class="newline" />Replaces all occurrences of PATTERN in SRC by REPL and returns the result. REPL can
     be omitted and defaults to the empty string. If the ﬁrst argument is an array of strings, each
     element in the array is replaced. The arguments PATTERN and REPL have to be scalar values.
     PATTERN can be a string or a regular expression (see below). For example: <br 
class="newline" /><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">REPLACE(&#x0022;abcdab&#x0022;,</span><span 
class="cmtt-10x-x-109"> &#x0022;ab&#x0022;)</span></span></span> results in <span 
class="cmtt-10x-x-109">cd </span><br 
class="newline" /><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">REPLACE(&#x0022;abcdab&#x0022;,</span><span 
class="cmtt-10x-x-109"> REGEX(&#x0022;^ab&#x0022;),</span><span 
class="cmtt-10x-x-109"> &#x0022;xyz&#x0022;)</span></span></span> results in <span 
class="cmtt-10x-x-109">xyzcdab</span></dd></dl>
<!--l. 1934--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">4.10.2   </span> <a 
 id="x1-510004.10.2"></a>Regex functions</h5>
<!--l. 1935--><p class="noindent" >Apart from using <a 
href="#x1-370004.3.6">regex/pattern constants</a>, it is possible to use functions to form a regex or pattern. These
functions can only be used on a scalar argument.
</p><!--l. 1939--><p class="indent" >
     </p><dl class="description"><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">regex REGEX(string)</span><br 
class="newline" />Handle the given string as a regular expression.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">regex PATTERN(string)</span><br 
class="newline" />Handle the given string as a UNIX ﬁlename-like pattern and convert it to a regular expression.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">regex SQLPATTERN(string)</span><br 
class="newline" />Handle the given string as an SQL-style pattern and convert it to a regular expression.</dd></dl>
<!--l. 1949--><p class="noindent" >A regex formed this way can only be used in a comparison == or !=. E.g. <br 
class="newline" /><span 
class="cmtt-10x-x-109">object == pattern(&#x2019;3C*&#x2019;) </span><br 
class="newline" />to ﬁnd all 3C objects in a catalogue.
                                                                                            
                                                                                            
</p><!--l. 1953--><p class="indent" >   A few remarks:
     </p><ol  class="enumerate1" >
     <li 
  class="enumerate" id="x1-51002x1">The regex/pattern functions and operator LIKE work on any string, thus they can be used with
     any string expression.
     </li>
     <li 
  class="enumerate" id="x1-51004x2">A Regex is case sensitive. One should use function <span 
class="cmtt-10x-x-109">upcase </span>or <span 
class="cmtt-10x-x-109">downcase </span>on the string to test to
     make it case insensitive or use the <span 
class="cmti-10x-x-109">i </span>qualiﬁer on a regex constant.
     </li>
     <li 
  class="enumerate" id="x1-51006x3">Usually a regex/pattern must match the full string, thus not part of it. However, one can use
     the <span 
class="cmtt-10x-x-109">m// </span>regex constant to do partial matching. Thus something like <span 
class="cmtt-10x-x-109">m/xx/ </span>matches all strings
     containing <span 
class="cmtt-10x-x-109">xx</span>. Of course, <span 
class="cmtt-10x-x-109">regex(&#x2019;.*xx.*&#x2019;) </span>can also be used. In this way the <span 
class="cmtt-10x-x-109">m// </span>regex works
     the same as in languages like Perl, Python, and Glish.</li></ol>
<!--l. 1968--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">4.10.3   </span> <a 
 id="x1-520004.10.3"></a>Date/time functions</h5>
<!--l. 1969--><p class="noindent" >These functions make it possible to handle dates/times and can be used on a scalar or an array argument.
The syntax of a date/time string or constant is explained in <a 
href="#x1-380004.3.7">section 4.3.7</a>.
     </p><dl class="description"><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">DateTime DATETIME(string)</span><br 
class="newline" />Parse the string and convert it to a DateTime value.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">DateTime MJDTODATE(real)</span><br 
class="newline" />The real value, which has to be a MJD (ModiﬁedJulianDate), is converted to a DateTime.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double MJD(DateTime)</span><br 
class="newline" />Get the DateTime as MJD (ModiﬁedJulianDate) in days.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">DateTime DATE(DateTime)</span><br 
class="newline" />Get the date (i.e., remove the time part). This function is needed in something like: <br 
class="newline" /><span 
class="cmtt-10x-x-109">DATE(column) == 12Feb1997 </span><br 
class="newline" />if the column contains date/times with times<!--l. 1985--><math 
 xmlns="http://www.w3.org/1998/Math/MathML"  
display="inline" > <mo 
class="MathClass-rel">&#x003E;</mo></math>0.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double TIME(DateTime)</span><br 
class="newline" />Get the time part of the day. It is converted to radians to be compatible with the internal
     representation of times/positions. In that way the function can easily be used as in: <br 
class="newline" /><span 
class="cmtt-10x-x-109">TIME(date) </span><!--l. 1990--><math 
 xmlns="http://www.w3.org/1998/Math/MathML"  
display="inline" > <mo 
class="MathClass-rel">&#x003E;</mo></math>
     <span 
class="cmtt-10x-x-109">12h</span>
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">integer YEAR(DateTime)</span><br 
class="newline" />Get the year (which includes the century).
                                                                                            
                                                                                            
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">integer MONTH(DateTime)</span><br 
class="newline" />Get the month number (1-12).
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">integer DAY(DateTime)</span><br 
class="newline" />Get the day number (1-31).
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">integer WEEK(DateTime)</span><br 
class="newline" />Get the week number in the year (0 ... 53). <br 
class="newline" />Note that week 1 is the week containing Jan 4th.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">integer WEEKDAY(DateTime), integer DOW(DateTime)</span><br 
class="newline" />Get the weekday number (1=Monday, ..., 7=Sunday).
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">string CDATETIME(DateTime), string CTOD(DateTime)</span><br 
class="newline" />Get the DateTime as a string like YYYY/MM/DD/HH:MM:SS.SSS.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">string CDATE(DateTime)</span><br 
class="newline" />Get the date part of a DateTime as a string like DD-MMM-YYYY.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">string CTIME(DateTime)</span><br 
class="newline" />Get the time part of a DateTime as a string like HH:MM:SS.SSS.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">string CMONTH(DateTime)</span><br 
class="newline" />Get the abbreviated name of the month (Jan ... Dec).
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">string CWEEKDAY(DateTime), string CDOW(DateTime)</span><br 
class="newline" />Get the abbreviated name of the weekday (Mon ... Sun).</dd></dl>
<!--l. 2013--><p class="noindent" >All functions can be used without an argument in which case the current date/time is used. e.g., <span 
class="cmtt-10x-x-109">DATE() </span>results
in the current date. <br 
class="newline" />It is possible to give a string argument instead of a date. In this case the string is parsed and converted to a
date (i.e., the function DATETIME is used implicitly). <br 
class="newline" />Note that the function <span 
class="cmtt-10x-x-109">STR </span>discussed in the next section can also be used for pretty-printing a date/time. It
gives more control over the number of decimals and date format.
</p><!--l. 2022--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">4.10.4   </span> <a 
 id="x1-530004.10.4"></a>Pretty printing functions</h5>
<!--l. 2023--><p class="noindent" >Angles (scalar or array) can be returned as strings in HMS and/or DMS format. Currently, they are always
formatted with 3 decimals in the seconds.
                                                                                            
                                                                                            
     </p><dl class="description"><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">string HMS(real)</span><br 
class="newline" />Return angle(s) like 12h34m56.789
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">string DMS(real)</span><br 
class="newline" />Return angle(s) like 12d34m56.789
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">string HDMS(realarray)</span><br 
class="newline" />Return angles like 12h34m56.789 (even elements) and 12d34m56.789 (odd elements). It is useful
     for arrays containing RA,DEC values.</dd></dl>
<!--l. 2034--><p class="noindent" >The functions mentioned above and the date/time functions in the previous subsection can format a value in a
predeﬁned way only. <br 
class="newline" />The <span 
class="cmtt-10x-x-109">STRING </span>(shorthand <span 
class="cmtt-10x-x-109">STR</span>) function makes it possible to convert values to strings using an optional format
string or width.precision value. It also makes it possible to format dates, times, and angles in a variety of
ways.
     </p><dl class="description"><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">string STR(value, [format]), string STRING(value, [format])</span></dd></dl>
<!--l. 2043--><p class="noindent" >The value can be of any type (except Regex) and can be a scalar or array. The optional format must be a
scalar string or numeric value. If no format is given, an appropriate default format will be used.
</p>
     <ul class="itemize1">
     <li class="itemize">A numeric format value deﬁnes the width and/or precision. For example:
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-74">
       8        defines width 8 and default precision
      <br />  20.12    defines width 20 and precision 12
      <br />  .8       defines precision 8 and default width
</div>
     <!--l. 2052--><p class="nopar" > In this way precision represents all digits, not only the ones behind the decimal point. A default width
     or precision is used if not given.
     </p></li>
     <li class="itemize">A string format value can contain a <span 
class="cmtt-10x-x-109">printf</span>-style format string, which must include the %-sign. Note
     that the real and imaginary part of a complex value are formatted separately, so such a format string
     needs to contain a format speciﬁer for both parts. See <a 
href="http://www.cplusplus.com/reference/cstdio/printf" >printf reference</a> for possible format speciﬁers. For
     example:
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-75">
       %10d     decimal with width 10
      <br />  %010d    decimal with width 10 and filled with zeroes
      <br />  %f+%fi   to format a complex value as a+bi
</div>
     <!--l. 2068--><p class="nopar" > Apart from a <span 
class="cmtt-10x-x-109">printf</span>-style format string, it is also possible to deﬁne a string to format
     date/time and angle values (which are automatically converted to radians if containing units).
     <br 
class="newline" />Such a format string contains one or more format values as deﬁned in class <a 
href="../html/classcasa_1_1MVTime.html" >MVTime</a>. A vertical bar
     (with optional whitespace) must be used as separator. A string part can be a numeric value deﬁning the
     precision of the time/angle. Default precision is 6 (thus hh:mm:ss). The optional time/angle formats
     and modiﬁers are:
</p>
     <div class="tabular"> <table id="TBL-4" class="tabular" 
cellspacing="0" cellpadding="0"  
><colgroup id="TBL-4-1g"><col 
id="TBL-4-1" /><col 
id="TBL-4-2" /></colgroup><tr  
 style="vertical-align:baseline;" id="TBL-4-1-"><td  style="text-align:left; white-space:nowrap;" id="TBL-4-1-1"  
class="td11">Format              </td><td  style="text-align:left; white-space:nowrap;" id="TBL-4-1-2"  
class="td11">Description                                                                                                                                                                                        </td>
</tr><tr 
class="hline"><td><hr /></td><td><hr /></td></tr><tr  
 style="vertical-align:baseline;" id="TBL-4-2-"><td  style="text-align:left; white-space:nowrap;" id="TBL-4-2-1"  
class="td11">YMD                 </td><td  style="text-align:left; white-space:nowrap;" id="TBL-4-2-2"  
class="td11">yyyy/mm/dd/hh:mm:ss.sss                                                                                                                                                                   </td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-4-3-"><td  style="text-align:left; white-space:nowrap;" id="TBL-4-3-1"  
class="td11">YMD_ONLY       </td><td  style="text-align:left; white-space:nowrap;" id="TBL-4-3-2"  
class="td11">YMD without the time (same as YMD<!--l. 2082--><math 
 xmlns="http://www.w3.org/1998/Math/MathML"  
display="inline" ><mo 
class="MathClass-rel">|</mo></math>NO_TIME)</td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-4-4-"><td  style="text-align:left; white-space:nowrap;" id="TBL-4-4-1"  
class="td11">DMY                 </td><td  style="text-align:left; white-space:nowrap;" id="TBL-4-4-2"  
class="td11">dd-Mon-yyyy/hh:mm:ss.sss                                                                                                                                                                   </td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-4-5-"><td  style="text-align:left; white-space:nowrap;" id="TBL-4-5-1"  
class="td11">FITS                 </td><td  style="text-align:left; white-space:nowrap;" id="TBL-4-5-2"  
class="td11">yyyy-mm-ddThh:mm:ss.sss                                                                                                                                                                   </td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-4-6-"><td  style="text-align:left; white-space:nowrap;" id="TBL-4-6-1"  
class="td11">BOOST              </td><td  style="text-align:left; white-space:nowrap;" id="TBL-4-6-2"  
class="td11">the same as DMY<!--l. 2085--><math 
 xmlns="http://www.w3.org/1998/Math/MathML"  
display="inline" ><mo 
class="MathClass-rel">|</mo></math>USE_SPACE                         </td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-4-7-"><td  style="text-align:left; white-space:nowrap;" id="TBL-4-7-1"  
class="td11">NO_H, NO_D      </td><td  style="text-align:left; white-space:nowrap;" id="TBL-4-7-2"  
class="td11">suppress the output of hours (or degrees): useful for oﬀsets                                                                                                                          </td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-4-8-"><td  style="text-align:left; white-space:nowrap;" id="TBL-4-8-1"  
class="td11">NO_HM, NO_DM</td><td  style="text-align:left; white-space:nowrap;" id="TBL-4-8-2"  
class="td11">suppress the degrees and minutes                                                                                                                                                           </td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-4-9-"><td  style="text-align:left; white-space:nowrap;" id="TBL-4-9-1"  
class="td11">CLEAN              </td><td  style="text-align:left; white-space:nowrap;" id="TBL-4-9-2"  
class="td11">suppress leading or trailing periods or colons if not all time/angle parts                                                                                                         </td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-4-10-"><td  style="text-align:left; white-space:nowrap;" id="TBL-4-10-1"  
class="td11">               </td><td  style="text-align:left; white-space:nowrap;" id="TBL-4-10-2"  
class="td11">are printed (e.g., when giving NO_H or 4 decimals)                                                                                                                                   </td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-4-11-"><td  style="text-align:left; white-space:nowrap;" id="TBL-4-11-1"  
class="td11">DAY                  </td><td  style="text-align:left; white-space:nowrap;" id="TBL-4-11-2"  
class="td11">precede the output with Day- (e.g., Wed-)                                                                                                                                                </td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-4-12-"><td  style="text-align:left; white-space:nowrap;" id="TBL-4-12-1"  
class="td11">NO_TIME          </td><td  style="text-align:left; white-space:nowrap;" id="TBL-4-12-2"  
class="td11">suppress printing of time                                                                                                                                                                      </td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-4-13-"><td  style="text-align:left; white-space:nowrap;" id="TBL-4-13-1"  
class="td11">ANGLE             </td><td  style="text-align:left; white-space:nowrap;" id="TBL-4-13-2"  
class="td11">+ddd.mm.ss.ttt                                                                                                                                                                                  </td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-4-14-"><td  style="text-align:left; white-space:nowrap;" id="TBL-4-14-1"  
class="td11">TIME                </td><td  style="text-align:left; white-space:nowrap;" id="TBL-4-14-2"  
class="td11">hh:mm:ss.ttt                                                                                                                                                                                      </td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-4-15-"><td  style="text-align:left; white-space:nowrap;" id="TBL-4-15-1"  
class="td11">USE_SPACE       </td><td  style="text-align:left; white-space:nowrap;" id="TBL-4-15-2"  
class="td11">use a space between date and time (and day and date)                                                                                                                               </td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-4-16-"><td  style="text-align:left; white-space:nowrap;" id="TBL-4-16-1"  
class="td11">DIG2                 </td><td  style="text-align:left; white-space:nowrap;" id="TBL-4-16-2"  
class="td11">get angle/time in range -90:+90 or -12:+12                                                                                                                                              </td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-4-17-"><td  style="text-align:left; white-space:nowrap;" id="TBL-4-17-1"  
class="td11">LOCAL              </td><td  style="text-align:left; white-space:nowrap;" id="TBL-4-17-2"  
class="td11">local time; in FITS mode append time zone as +hh:mm                                                                                                                             </td>
</tr><tr  
 style="vertical-align:baseline;" id="TBL-4-18-"><td  style="text-align:left; white-space:nowrap;" id="TBL-4-18-1"  
class="td11">               </td></tr></table>
     </div>
     <!--l. 2104--><p class="noindent" >For example:
                                                                                            
                                                                                            
</p>
     <div class="verbatim" id="verbatim-76">
       YMD             format as YYYY/MM/DD/HH:MM:SS
      <br />  DMY|NO_TIME     format as DD-MMM-YYYY
      <br />  DMY | DAY | 8   format as Thu-DD-MMM-YYY/HH:MM:SS.SS
      <br />  TIME            format a datetime or angle as HH:MM:SS
      <br />  ANGLE|9         format an angle as DD.MM.SS.SSS
</div>
     <!--l. 2111--><p class="nopar" > If such a format string contains an invalid part, it is assumed that the entire string is a <span 
class="cmtt-10x-x-109">printf</span>-style
     format string.</p></li></ul>
<!--l. 2116--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">4.10.5   </span> <a 
 id="x1-540004.10.5"></a>Comparison functions</h5>
<!--l. 2117--><p class="noindent" >The exact comparison of ﬂoating point values is quite tricky. Two functions make it possible to compare 2
double or complex values with a tolerance. They can be used on scalar and array arguments (and a mix of
them). The tolerance must be a scalar though. <br 
class="newline" />Note that operator <span 
class="cmtt-10x-x-109"> = </span>is the same as NEAR with a tolerance of 1e-5.
     </p><dl class="description"><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">bool NEAR(numeric val1, numeric val2, double tol)</span><br 
class="newline" />Tests in a relative way if a value is near another. Relative means that the magnitude of the
     numbers is taken into account. <br 
class="newline" />It returns <span 
class="cmtt-10x-x-109">abs(val2 - val1)/max(abs(val1),abs(val2)) &#x003C; tol</span>. <br 
class="newline" />If <span 
class="cmtt-10x-x-109">tol&#x003C;=0</span>, it returns <span 
class="cmtt-10x-x-109">val1==val2</span>. If either val is 0.0, it takes care of area around the minimum
     number that can be represented. The default tolerance is 1.0e-13.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">bool NEARABS(numeric val1, numeric val2, double tol)</span><br 
class="newline" />Tests in an absolute way if a value is near another. Absolute means that the magnitude of the
     numbers is not taken into account. <br 
class="newline" />It returns <span 
class="cmtt-10x-x-109">abs(val2 - val1) &#x003C; tol</span>. The default tolerance is 1.0e-13.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">bool ISNAN(numeric val)</span><br 
class="newline" />Tests if a numeric value is a NaN (not-a-number).
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">bool ISINF(numeric val)</span><br 
class="newline" />Tests if a numeric value is inﬁnite (positive or negative).
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">bool ISFINITE(numeric val)</span><br 
class="newline" />Tests if a numeric value is a ﬁnite number (not NaN or inﬁnite).</dd></dl>
                                                                                            
                                                                                            
<!--l. 2148--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">4.10.6   </span> <a 
 id="x1-550004.10.6"></a>Mathematical functions</h5>
<!--l. 2149--><p class="noindent" >Standard mathematical can be used on scalar and array arguments (and a mix of them).
     </p><dl class="description"><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double PI()</span><br 
class="newline" />Return the value of <span 
class="cmbx-10x-x-109">pi</span>.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double E()</span><br 
class="newline" />Return the value of <span 
class="cmbx-10x-x-109">e </span>(is equal to <span 
class="cmtt-10x-x-109">EXP(1)</span>).
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double C()</span><br 
class="newline" />Return the value of the speed of light (with unit m/s).
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">dnumeric SIN(numeric)</span>
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">dnumeric SINH(numeric)</span>
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double ASIN(real)</span>
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">dnumeric COS(numeric)</span>
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">dnumeric COSH(numeric)</span>
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double ACOS(real)</span>
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double TAN(real)</span>
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double TANH(real)</span>
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double ATAN(real)</span>
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double ATAN2(real y, real x)</span><br 
class="newline" />Return <span 
class="cmtt-10x-x-109">ATAN(y/x) </span>in correct quadrant.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">dnumeric EXP(numeric)</span>
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">dnumeric LOG(numeric)</span><br 
class="newline" />Natural logarithm.
                                                                                            
                                                                                            
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">dnumeric LOG10(numeric)</span>
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">dnumeric POW(numeric, numeric)</span><br 
class="newline" />The same as operator <span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">**</span></span></span>.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">numeric SQUARE(numeric), numeric SQR(numeric)</span><br 
class="newline" />The same as <span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">**</span></span></span>2, but much faster.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">dnumeric SQRT(numeric)</span>
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">complex COMPLEX(real, real)</span>
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">dnumeric CONJ(numeric)</span>
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double REAL(numeric)</span><br 
class="newline" />Real part of a complex number. Returns argument if real.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double IMAG(numeric)</span><br 
class="newline" />Imaginary part of a complex number. Returns 0 if argument is real.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">real NORM(numeric)</span>
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">real ABS(numeric), real AMPLITUDE(numeric)</span>
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double ARG(numeric), double PHASE(numeric)</span>
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">numeric MIN(numeric, numeric)</span>
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">numeric MAX(numeric, numeric)</span>
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">real SIGN(real)</span><br 
class="newline" />Return -1 for a negative value, 0 for zero, 1 for a positive value.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">real ROUND(real)</span><br 
class="newline" />Return the rounded value of the number. Negative numbers are rounded in an absolute way.
     e.g., <span 
class="cmtt-10x-x-109">ROUND(-1.6) = -2.</span>
                                                                                            
                                                                                            
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">real FLOOR(real)</span><br 
class="newline" />Works towards negative inﬁnity. e.g., <span 
class="cmtt-10x-x-109">FLOOR(-1.2) = -2.</span>
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">real CEIL(real)</span><br 
class="newline" />Works towards positive inﬁnity.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">real FMOD(real, real)</span><br 
class="newline" />The same as operator %.</dd></dl>
<!--l. 2202--><p class="noindent" >Note that the arguments or results of the trigonometric functions are in radians. They are converted
automatically if units are given.
</p><!--l. 2205--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">4.10.7   </span> <a 
 id="x1-560004.10.7"></a>Array to scalar reduce functions</h5>
<!--l. 2206--><p class="noindent" >The following functions reduce an array to a scalar. They are meant for an array, but can also be used for a
scalar.
     </p><dl class="description"><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">bool ANY(bool)</span><br 
class="newline" />Is any element true?
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">bool ALL(bool)</span><br 
class="newline" />Are all elements true?
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">integer NTRUE(bool)</span><br 
class="newline" />Return number of true elements.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">integer NFALSE(bool)</span><br 
class="newline" />Return number of false elements.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">numeric SUM(numeric)</span><br 
class="newline" />Return sum of all elements.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">numeric SUMSQUARE(numeric), numeric SUMSQR(numeric)</span><br 
class="newline" />Return sum of all squared elements.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">numeric PRODUCT(numeric)</span><br 
class="newline" />Return product of all elements.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">real MIN(real)</span><br 
class="newline" />Return minimum of all elements.
                                                                                            
                                                                                            
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">real MAX(real)</span><br 
class="newline" />Return maximum of all elements.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">dnumeric MEAN(numeric), dnumeric AVG(numeric)</span><br 
class="newline" />Return mean of all elements.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double VARIANCE(real)</span><br 
class="newline" />Return variance (the sum of <br 
class="newline" /><span 
class="cmtt-10x-x-109">(a(i) - mean(a))**2/(nelements(a) - 1)</span>.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double STDDEV(real)</span><br 
class="newline" />Return standard deviation (the square root of the variance).
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double AVDEV(real)</span><br 
class="newline" />Return average deviation. (the sum of <br 
class="newline" /><span 
class="cmtt-10x-x-109">abs(a[i] - mean(a))/nelements(a)</span>.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double RMS(real)</span><br 
class="newline" />Return root-mean-squares. (the square root of the sum of <br 
class="newline" /><span 
class="cmtt-10x-x-109">(a(i)**2)/nelements(a)</span>.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double MEDIAN(real)</span><br 
class="newline" />Return median (the middle element). If the array has an even number of elements, the mean of
     the two middle elements is returned.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double FRACTILE(real, doublescalar fraction)</span><br 
class="newline" />Return the value of the element at the given fraction. Fraction 0.5 is the same as the median,
     but no mean of the two middle elements is taken.</dd></dl>
<!--l. 2250--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">4.10.8   </span> <a 
 id="x1-570004.10.8"></a>Array to array reduce functions</h5>
<!--l. 2251--><p class="noindent" >These functions reduce an array to a smaller array by collapsing the given axes using the given function. The
axes are the last argument(s). They can be given in two ways: <br 
class="newline" />- As a single set argument; for example, <span 
class="cmtt-10x-x-109">maxs(ARRAY,[1,2]) </span><br 
class="newline" />- As individual scalar arguments; for example, <span 
class="cmtt-10x-x-109">maxs(ARRAY,1,2) </span><br 
class="newline" />For example, using <span 
class="cmtt-10x-x-109">MINS(array,0,1) </span>for a 3-dim array results in a 1-dim array where each value is the
minimum of each plane in the cube. <br 
class="newline" />It is important to note that the interpretation of the axes numbers depends on the style being
used. e.g., when using glish style, axes numbers are 1-based and in Fortran order, thus axis 1 is
the most rapidly varying axis. When using python style, axis 0 is the most slowly varying axis.
                                                                                            
                                                                                            
<br 
class="newline" />Axes numbers exceeding the dimensionality of the array are ignored. For example, <span 
class="cmtt-10x-x-109">maxs(ARRAY,[1:10])</span>
works for arrays of virtually any dimensionality and results in a 1-dim array. <br 
class="newline" />The function names are the &#x2019;plural&#x2019; forms of the functions in the previous section. They can only be used for
arrays, thus not for scalars.
     </p><dl class="description"><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">bool ANYS(bool)</span><br 
class="newline" />Is any element true?
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">bool ALLS(bool)</span><br 
class="newline" />Are all elements true?
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">integer NTRUES(bool)</span><br 
class="newline" />Return number of true elements.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">integer NFALSES(bool)</span><br 
class="newline" />Return number of false elements.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">numeric SUMS(numeric)</span><br 
class="newline" />Return sum of elements.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">numeric SUMSQUARES(numeric), numeric SUMSQRS(numeric)</span><br 
class="newline" />Return sum of squared elements.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">numeric PRODUCTS(numeric)</span><br 
class="newline" />Return product of elements.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">real MINS(real)</span><br 
class="newline" />Return minimum of elements.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">real MAXS(real)</span><br 
class="newline" />Return maximum of elements.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">dnumeric MEANS(numeric), dnumeric AVGS(numeric)</span><br 
class="newline" />Return mean of elements.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double VARIANCES(real)</span><br 
class="newline" />Return variance (the sum of <br 
class="newline" /><span 
class="cmtt-10x-x-109">(a(i) - mean(a))**2/(nelements(a) - 1)</span>.
                                                                                            
                                                                                            
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double STDDEVS(real)</span><br 
class="newline" />Return standard deviation (the square root of the variance).
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double AVDEVS(real)</span><br 
class="newline" />Return average deviation. (the sum of <br 
class="newline" /><span 
class="cmtt-10x-x-109">abs(a(i) - mean(a))/nelements(a)</span>.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double RMSS(real)</span><br 
class="newline" />Return root-mean-squares. (the square root of the sum of <br 
class="newline" /><span 
class="cmtt-10x-x-109">(a(i)**2)/nelements(a)</span>.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double MEDIANS(real)</span><br 
class="newline" />Return median (the middle element). If the array has an even number of elements, the mean of
     the two middle elements is returned.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double FRACTILES(real, doublescalar fraction)</span><br 
class="newline" />Return the value of the element at the given fraction. Fraction 0.5 is the same as the median.</dd></dl>
<!--l. 2310--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">4.10.9   </span> <a 
 id="x1-580004.10.9"></a>Array downsampling functions</h5>
<!--l. 2311--><p class="noindent" >These functions are a generalization of the functions in the previous section. They downsample an array by
taking, say, the mean of every n*m elements. The functions in the previous section downsample by taking the
mean of a full line or plane, etc. The most useful one is probably calculating the boxed mean, but the other
ones can be used similarly. The width of each window axis has to be given. Missing axes default to 1.
Similarly to the partial reduce functions described above, the axes can be given as scalars or as a set.
<br 
class="newline" />For example, <span 
class="cmtt-10x-x-109">BOXEDMEAN(array,3,3) </span>calculates the mean in each 3x3 box. At the end of an axis the box
used will be smaller if it does not ﬁt integrally. <br 
class="newline" />The functions can only be used for arrays, thus not for scalars.
     </p><dl class="description"><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">bool BOXEDANY(bool)</span><br 
class="newline" />Is any element true?
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">bool BOXEDALL(bool)</span><br 
class="newline" />Are all elements true?
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double BOXEDMIN(real)</span><br 
class="newline" />Return minimum of elements.
                                                                                            
                                                                                            
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double BOXEDMAX(real)</span><br 
class="newline" />Return maximum of elements.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">dnumeric BOXEDMEAN(numeric), dnumeric BOXEDAVG(numeric)</span><br 
class="newline" />Return mean of elements.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double BOXEDVARIANCE(real)</span><br 
class="newline" />Return variance (the sum of <br 
class="newline" /><span 
class="cmtt-10x-x-109">(a(i) - mean(a))**2/(nelements(a) - 1)</span>.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double BOXEDSTDDEV(real)</span><br 
class="newline" />Return standard deviation (the square root of the variance).
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double BOXEDAVDEV(real)</span><br 
class="newline" />Return average deviation. (the sum of <br 
class="newline" /><span 
class="cmtt-10x-x-109">abs(a(i) - mean(a))/nelements(a)</span>.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double BOXEDRMS(real)</span><br 
class="newline" />Return root-mean-squares. (the square root of the sum of <br 
class="newline" /><span 
class="cmtt-10x-x-109">(a(i)**2)/nelements(a)</span>.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double BOXEDMEDIAN(real)</span><br 
class="newline" />Return median (the middle element).</dd></dl>
<!--l. 2351--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">4.10.10   </span> <a 
 id="x1-590004.10.10"></a>Array functions operating in running windows</h5>
<!--l. 2352--><p class="noindent" >These functions transform an array into an array with the same shape by operating on a rectangular
window around each array element. The most useful one is probably calculating the running
median, but the other ones can be used similarly. The half-width of each window axis has to be
given; the full width is <span 
class="cmtt-10x-x-109">2*halfwidth + 1</span>. Missing axes default to a half-width of 0. Similarly
to the partial reduce functions described above, the axes can be given as scalars or as a set.
<br 
class="newline" />For example, <span 
class="cmtt-10x-x-109">RUNNINGMEDIAN(array,1,1) </span>calculates the median in a 3x3 box around each array element. See
the <a 
href="#x1-11300012.2.1">examples</a> how it is applied to an image. <br 
class="newline" />In the result the edge elements (i.e., the elements where no full window can be applied) are set to 0 (or
False). <br 
class="newline" />The functions can only be used for arrays, thus not for scalars.
     </p><dl class="description"><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">bool RUNNINGANY(bool)</span><br 
class="newline" />Is any element true?
                                                                                            
                                                                                            
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">bool RUNNINGALL(bool)</span><br 
class="newline" />Are all elements true?
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double RUNNINGMIN(real)</span><br 
class="newline" />Return minimum of elements.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double RUNNINGMAX(real)</span><br 
class="newline" />Return maximum of elements.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">dnumeric RUNNINGMEAN(numeric), dnumeric RUNNINGAVG(numeric)</span><br 
class="newline" />Return mean of elements.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double RUNNINGVARIANCE(real)</span><br 
class="newline" />Return variance (the sum of <br 
class="newline" /><span 
class="cmtt-10x-x-109">(a(i) - mean(a))**2/(nelements(a) - 1)</span>.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double RUNNINGSTDDEV(real)</span><br 
class="newline" />Return standard deviation (the square root of the variance).
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double RUNNINGAVDEV(real)</span><br 
class="newline" />Return average deviation. (the sum of <br 
class="newline" /><span 
class="cmtt-10x-x-109">abs(a(i) - mean(a))/nelements(a)</span>.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double RUNNINGRMS(real)</span><br 
class="newline" />Return root-mean-squares. (the square root of the sum of <br 
class="newline" /><span 
class="cmtt-10x-x-109">(a(i)**2)/nelements(a)</span>.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double RUNNINGMEDIAN(real)</span><br 
class="newline" />Return median (the middle element).</dd></dl>
<!--l. 2393--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">4.10.11   </span> <a 
 id="x1-600004.10.11"></a>Type conversion functions</h5>
<!--l. 2394--><p class="noindent" >Explicit type conversions can be done using one of the functions below. They can operate on scalars and
arrays.
     </p><dl class="description"><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">integer INT(numeric or bool or string)</span><br 
class="newline" />Convert the argument to an integer. A real number is truncated (-10.9 results in -10). For a
     complex number the truncated real part is taken. A bool is converted to 0 (False) or 1 (True).
     It does not check if a string represents a valid integer. It is interpreted until the ﬁrst non-valid
     character, so a string containing a ﬂoating point value is truncated.
                                                                                            
                                                                                            
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double REAL(numeric or bool or string)</span><br 
class="newline" />Convert the argument to a real number. For a complex number the real part is taken. A bool is
     converted to 0 (False) or 1 (True). It does not check if a string represents a valid ﬂoating point
     value. A string is interpreted until the ﬁrst non-valid character.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">complex COMPLEX(real,real)</span><br 
class="newline" />Form a complex number from the given real and imaginary part.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">complex COMPLEX(string)</span><br 
class="newline" />Convert the string to a complex number. The number can be given like <span 
class="cmtt-10x-x-109">(1,2) </span>or <span 
class="cmtt-10x-x-109">1+2i</span>. In fact,
     any separator (except whitespace) between real and imaginary part is possible. It does not check
     if a string represents a valid complex value. The string is interpreted until the ﬁrst non-valid
     character, so the last character can be any character (e.g., also <span 
class="cmtt-10x-x-109">j</span>).
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">bool BOOL(anytype)</span><br 
class="newline" />Convert the value to a bool. A numeric type (or date) results in False if the value is 0, otherwise
     True. A string is case-insensitive. False, F, No, N, -, or 0 results in False, otherwise True.</dd></dl>
<!--l. 2424--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">4.10.12   </span> <a 
 id="x1-610004.10.12"></a>Array creation functions</h5>
<!--l. 2425--><p class="noindent" >
     </p><dl class="description"><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">anytypearray ARRAY(anytype,shape)</span><br 
class="newline" />This function creates an unmasked array of the given type and shape. The shape is given in the
     last argument(s). It can be given in two ways: <br 
class="newline" />- As a single set argument; for example, <span 
class="cmtt-10x-x-109">array(0,[3,4]) </span><br 
class="newline" />- As individual scalar arguments; for example, <span 
class="cmtt-10x-x-109">array(0,3,4) </span><br 
class="newline" />The ﬁrst argument gives the values the array is ﬁlled with. It can be a scalar or an array of any
     shape. To initialize the created array, the value array is ﬂattened to a 1D array. Its successive
     values are stored in the created array. If the new array has more values than the value array, the
     value array is reset to its beginning and the process continues. <br 
class="newline" />Note that a masked array can be created from an (unmasked) array and a mask using the
     brackets operator like <span 
class="cmtt-10x-x-109">ARRAY[MASK]</span>.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">anytypearray MARRAY(anytypearray,boolarray)</span><br 
class="newline" />This function oﬀers another way to create a masked array. The mask must be given in the second
     argument; its shape must be the same as the shape of the data array.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">anytypearray NULLARRAY(anytype)</span><br 
class="newline" />This function creates a null array. Its data type is determined by the data type of the argument.
     The argument value itself is not used. It is mainly meant for test purposes.
                                                                                            
                                                                                            
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">anytypearray RESIZE(anytypearray,shape[,mode])</span><br 
class="newline" />This function resizes an array to the given shape and copies the values. The optional <span 
class="cmtt-10x-x-109">mode</span>
     argument determines how the values are copied. If the argument is not given, the new shape is
     arbitrary and the dimensionality can change. The values are copied to the same index in the
     new array. If an axis gets larger, the new values are set to 0 (or an empty string). <br 
class="newline" />If mode is given, the new shape is much more restricted. The dimensionality cannot change
     and each axis has to be a multiple of the old one. If <span 
class="cmtt-10x-x-109">mode=0</span>, copying the values is done in an
     upsampling way. E.g., if a new axis is twice the length of the old one, values 1,2,3 are copied as
     1,1,2,2,3,3. A good use case is applying the ﬂags of averaged data to the original data. If <span 
class="cmtt-10x-x-109">mode=1</span>,
     the values in the example above are copied repeatedly as 1,2,3,1,2,3. By giving the mode as a
     set, it is possible to specify the mode per axis, but that is quite esoteric.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">anytypearray TRANSPOSE(anytypearray[,axes])</span><br 
class="newline" />This function transposes an N-dim array. If no axes are given, the array is fully transposed (thus
     all axes are reversed). Axes can be speciﬁed meaning that those axes will become the ﬁrst axes
     in the output array. Non-given axes follow thereafter in their natural order. <br 
class="newline" />A possible mask is transposed as well.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">anytypearray DIAGONAL(anytypearray[,firstaxis[,diag]])</span><br 
class="newline" />This function takes the diagonal of 2-dim subarrays in an N-dim array resulting in an array
     with 1 dimension less. For a 2-dim array, it is simply the diagonal of the matrix. For a higher
     dimensional array, it takes the diagonal of each matrix deﬁned by <span 
class="cmtt-10x-x-109">firstaxis </span>and <span 
class="cmtt-10x-x-109">firstaxis+1</span>.
     e.g., in a 3-dim array the diagonals of each XY-plane can be taken. The default for ﬁrstaxis is
     0. <br 
class="newline" />The <span 
class="cmtt-10x-x-109">diag </span>argument tells which diagonal has to be taken. The default 0 means the main diagonal.
     A negative value means below the main diagonal, while positive means above the main diagonal.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">anytypearray ARRAYDATA(anytype)</span><br 
class="newline" />This function returns the array without a mask, thus removes the mask. If the operand is a
     scalar, it returns a 1-dim array with one element.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">anytypearray NEGATEMASK(anytype)</span><br 
class="newline" />This function returns the array with the negated mask. If the array has no mask, it returns the
     array with a mask of all Trues. If the operand is a scalar, it returns a 1-dim array with one
     element.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">anytypearray REPLACEMASKED(anytype, anytype)</span><br 
class="newline" />This function replaces the masked elements in the ﬁrst argument by the corresponding value
     in the second argument (which can be a scalar value). If the ﬁrst argument has no mask, the
     function is a no-op.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">anytypearray REPLACEUNMASKED(anytype, anytype)</span><br 
class="newline" />This function replaces the unmasked elements in the ﬁrst argument by the corresponding value
                                                                                            
                                                                                            
     in the second argument (which can be a scalar value). If the ﬁrst argument has no mask, the
     function is a no-op.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">boolarray ARRAYMASK(anytype), boolarray MASK(anytype)</span><br 
class="newline" />This function returns the mask of an array. If the array has no mask, it returns a boolean array
     of the same shape with all values set to False. If the operand is a scalar, it returns an 1-dim
     array with one False element.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">anytypearray FLATTEN(anytype)</span><br 
class="newline" />This function ﬂattens an N-dim array to a 1-dim array keeping the unmasked elements only. If
     the operand is a scalar, it returns a 1-dim array with one element.</dd></dl>
<!--l. 2513--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">4.10.13   </span> <a 
 id="x1-620004.10.13"></a>Aggregate functions</h5>
<!--l. 2514--><p class="noindent" >The <span 
class="cmtt-10x-x-109">GXXX </span>aggregate functions calculate an aggregated value for all rows in a group, usually deﬁned with a
GROUPBY clause. For example, when grouping in TIME, an aggregate function like <span 
class="cmtt-10x-x-109">GNTRUE(FLAG) </span>counts
per time slot the number of ﬂagged data points. Aggregate functions can only be used in the SELECT and
the HAVING clause. <br 
class="newline" />Most functions listed below reduce the values in a group to a scalar value, also if the value in a
row is an array (as in the GNTRUE example above). The arrays in a group can have diﬀerent
shapes.
</p><!--l. 2524--><p class="indent" >   However, there are several aggregate functions returning an array as done by the last three
functions (GHIST, GAGGR, and GROWID) shown below. Furthermore, most scalar functions
have a plural form (e.g., GNTRUES) returning an array. They are described at the end of this
section.
</p><!--l. 2529--><p class="indent" >   Note that the aggregate function names diﬀer from their SQL counterparts; they all have the preﬁx <span 
class="cmtt-10x-x-109">G</span>,
because TaQL functions like <span 
class="cmtt-10x-x-109">MAX </span>already exist for array operations. This naming scheme also makes it more
clear which TaQL functions are aggregate functions.
</p><!--l. 2534--><p class="indent" >   A technical detail is how aggregate functions are implemented. TaQL walks sequentially through a
table. Non-lazy functions operate directly on the value in a row making the table access purely
sequential. It requires that the results of all groups are held in memory. For some functions, in
particular GAGGR, this could lead to a very high memory usage. Therefore, some functions are
implemented in a lazy way. They keep the row numbers of a group and access the data when the
aggregated result of a group is needed. In this way only the data of a single group needs to be held
in memory, but the access to the table might be non-sequential making it somewhat slower.
Currently, only GAGGR and the User Deﬁned aggregate functions are implemented in a lazy
way.
</p><!--l. 2548--><p class="indent" >
     </p><dl class="description"><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">integer GCOUNT(), integer GCOUNT(*)</span><br 
class="newline" />Return the number of rows per group.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">integer GCOUNT(columnname)</span><br 
class="newline" />Return the number of rows per group for which the column has a value. Note that only a column
     containing variable sized arrays can contain empty cells.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">anytype GFIRST(anytype)</span><br 
class="newline" />Return the ﬁrst value of an expression in the group. The values of a column not mentioned in
     the GROUPBY clause, might diﬀer. This function can be used to return the value of the ﬁrst
     row in the group.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">anytype GLAST(anytype)</span><br 
class="newline" />Return the last value of the group (is similar to GFIRST). <br 
class="newline" />Note this function is implicitly used if an expression without aggregate function is used in a
     group.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">bool GANY(bool)</span><br 
class="newline" />Is any element true?
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">bool GALL(bool)</span><br 
class="newline" />Are all elements true?
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">integer GNTRUE(bool)</span><br 
class="newline" />Return number of true elements.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">integer GNFALSE(bool)</span><br 
class="newline" />Return number of false elements.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">numeric GSUM(numeric)</span><br 
class="newline" />Return sum of all elements.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">numeric GSUMSQUARE(numeric), numeric GSUMSQR(numeric)</span><br 
class="newline" />Return sum of all squared elements.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">numeric GPRODUCT(numeric)</span><br 
class="newline" />Return product of all elements.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">real GMIN(real)</span><br 
class="newline" />Return minimum of all elements.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">real GMAX(real)</span><br 
class="newline" />Return maximum of all elements.
                                                                                            
                                                                                            
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">dnumeric GMEAN(numeric), dnumeric GAVG(numeric)</span><br 
class="newline" />Return mean of all elements.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double GVARIANCE(real)</span><br 
class="newline" />Return variance (the sum of <br 
class="newline" /><span 
class="cmtt-10x-x-109">(a(i) - mean(a))**2/(nelements(a) - 1)</span>.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double GSTDDEV(real)</span><br 
class="newline" />Return standard deviation (the square root of the variance).
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double GAVDEV(real)</span><br 
class="newline" />Return average deviation. (the sum of <br 
class="newline" /><span 
class="cmtt-10x-x-109">abs(a[i] - mean(a))/nelements(a)</span>.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double GRMS(real)</span><br 
class="newline" />Return root-mean-squares. (the square root of the sum of <br 
class="newline" /><span 
class="cmtt-10x-x-109">(a(i)**2)/nelements(a)</span>.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double GMEDIAN(real)</span><br 
class="newline" />Return median (the middle element). If the array has an even number of elements, the mean of
     the two middle elements is returned.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double GFRACTILE(real, doublescalar fraction)</span><br 
class="newline" />Return the value of the element at the given fraction. Fraction 0.5 is the same as the median.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double GHIST(real, intscalar nbin, realscalar start, realscalar end)</span><br 
class="newline" />Return the histogram of the data using the given number of bins. The histogram contains an
     extra bin at the beginning and the end for the outliers. If the rows in the group contain arrays,
     they can have variable shapes.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">anytypearray GAGGR(anytype), anytypearray GSTACK(anytype)</span><br 
class="newline" />Stack the row values in a group to form an array where the row is the slowest varying axis
     (similar to numpy&#x2019;s dstack). Thus if the column contains scalar values, the result is a vector.
     Otherwise it is an array whose dimensionality is one higher. It requires that all arrays in a group
     have the same shape. <br 
class="newline" />Note that this function can be very useful for arrays, because it makes it possible to use partial
     reduce functions like <span 
class="cmtt-10x-x-109">medians </span>to calculate the medians along arbitrary axes.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">integerarray GROWID()</span><br 
class="newline" />Return the row numbers of the rows in the group.</dd></dl>
                                                                                            
                                                                                            
<!--l. 2620--><p class="noindent" >Most functions above have a plural counterpart. They calculate the aggregated value per array index, thus the
result has the same shape as the arrays in the group. Similar to function GAGGR, they require that all
arrays in a group have the same shape. <br 
class="newline" />For instance, for a MeasurementSet the expression <span 
class="cmtt-10x-x-109">GMEANS(DATA) </span>calculates the mean in a group per
channel/polarization. Not only it is a shorthand for <span 
class="cmtt-10x-x-109">MEANS(GAGGR(DATA), 0)</span>, but it usually works faster
because, unlike GAGGR, it is non-lazy. <br 
class="newline" />The functions available are:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-77">
  GANYS   GALLS      GNTRUES     GNFALSES
 <br />  GMINS   GMAXS
 <br />  GSUMS   GPRODUCTS  GSUMSQRS    GSUMSQUARES
 <br />  GMEANS  GAVGS      GVARIANCES  GSTDDEVS  GRMSS
</div>
<!--l. 2634--><p class="nopar" >
</p><!--l. 2637--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">4.10.14   </span> <a 
 id="x1-630004.10.14"></a>Miscellaneous functions</h5>
<!--l. 2638--><p class="noindent" >
     </p><dl class="description"><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">bool ISNULL(anytype)</span><br 
class="newline" />Return True if the argument value is a null array.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">bool ISDEFINED(anytype)</span><br 
class="newline" />Return False if the array value in the current row is undeﬁned (is null). It makes it possible to
     test if a cell in a column with variable shaped arrays contains an array. Furthermore, it can be
     used to test if a ﬁeld in a record is deﬁned.<br 
class="newline" />Note that function <span 
class="cmtt-10x-x-109">ISNULL </span>can also be used to test for an undeﬁned array in a row.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">bool sh.ISCOLUMN(string)</span><br 
class="newline" />Return False if no column with the given name exists in the table with the shorthand given
     before the function name. If no table is given, the ﬁrst one will be used.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">bool sh.ISKEYWORD(string)</span><br 
class="newline" />Return False if no keyword with the given name exists in the table with the shorthand given
     before the function name. If no table is given, the ﬁrst one will be used. The keyword name can
     be given as described in <a 
href="#x1-440004.5">section 4.5</a>, thus the name of a table keyword or column keyword or a
     nested ﬁeld can be speciﬁed.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">integer NELEMENTS(anytype), integer COUNT(anytype)</span><br 
class="newline" />Return number of elements in an array (1 for a scalar).
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">integer NDIM(anytype)</span><br 
class="newline" />Return dimensionality of an array (0 for a scalar).
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">integerarray SHAPE(anytype)</span><br 
class="newline" />Return shape of an array (returns an empty array for a scalar).
                                                                                            
                                                                                            
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">integer ROWNUMBER(), integer ROWNR()</span><br 
class="newline" />Return the row number being tested (ﬁrst row is row number 0 or 1 depending on the style
     used). <br 
class="newline" />In combination with function RAND it can, for instance, be used to select arbitrary rows from
     a table.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">integer ROWID()</span><br 
class="newline" />Return the row number in the original table. This is especially useful for returning the result of a
     selection of a subtable of a Casacore measurement set (see also <a 
href="#x1-740004.11">subqueries in 4.11</a> and <a 
href="#x1-10900012.1">examples
     in section 12.1</a>).
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double RAND()</span><br 
class="newline" />Return  (per  table  row)  a  uniformly  distributed  random  number  between  0  and  1  using  a
     Multiplicative Linear Congruential Generator. The seeds for the generator are deduced from the
     current date and time, so the results are diﬀerent from run to run. <br 
class="newline" />The function can, for instance, be used to select a random subset from a table.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double ANGDIST(arg1,arg2)</span>, <span 
class="cmtt-10x-x-109">double ANGULARDISTANCE(arg1,arg2)</span><br 
class="newline" />Return the angular distance (in radians) between the positions in <span 
class="cmtt-10x-x-109">arg1 </span>and <span 
class="cmtt-10x-x-109">arg2</span>. Both arguments
     have to be numeric arrays containing an even number of values. Two subsequent values give
     the RA and DEC (or longitude and latitude) of positions on a sphere. The result is a 1-dim
     array containing the angular distance between corresponding positions in <span 
class="cmtt-10x-x-109">arg1 </span>and <span 
class="cmtt-10x-x-109">arg2</span>. If
     either array contains only one position, the result is the distance between that position and each
     position in the other array. If both arguments contain only 2 values, the result is a scalar. For
     example: <br 
class="newline" /><span 
class="cmtt-10x-x-109">angdist(PHASE</span><span 
class="cmtt-10x-x-109">_DIR[0,], [12h13m45,4d21m39.4, 12h13m49,10d8m4]) </span><br 
class="newline" />returns an array with shape [2] containing the angular distance between the phase center of the
     ﬁeld and the two positions given.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double ANGDISTX(arg1,arg2)</span>, <span 
class="cmtt-10x-x-109">double ANGULARDISTANCEX(arg1,arg2)</span><br 
class="newline" />Same as above, but the result is a 2-dim array giving the distance between each position in
     the ﬁrst argument and each position in the second argument. Only if both arguments contain a
     single position, the result is a scalar.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">anytype IIF(cond,arg1,arg2)</span><br 
class="newline" />This is a special funtion which operates like the ternary <span 
class="cmtt-10x-x-109">?: </span>operator in C++. If all arguments
     are scalars, the result is a scalar, otherwise an array. In the latter case possible scalar arguments
     are virtually expanded to arrays. IIF evaluates the condition for each element. If True, it takes
     the corresponding element of <span 
class="cmtt-10x-x-109">arg1</span>, otherwise of <span 
class="cmtt-10x-x-109">arg2</span>. <br 
class="newline" />If one of the input arrays has a mask, the output array will also have a mask. Each output mask
     element value is the logical OR of the condition mask element value and the mask value of the
     element taken from arg1 or arg2.</dd></dl>
                                                                                            
                                                                                            
<!--l. 2721--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">4.10.15   </span> <a 
 id="x1-640004.10.15"></a>Cone search functions</h5>
<!--l. 2722--><p class="noindent" >Cone search functions make it possible to test if a source is within a given distance of a given sky position.
The expression
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-78">
  cos(0d1m) &#x003C; sin(52deg) * sin(DEC) +
 <br />              cos(52deg) * cos(DEC) * cos(3h30m - RA)
</div>
<!--l. 2727--><p class="nopar" > could be used to test if sources with their sky position deﬁned in columns <span 
class="cmtt-10x-x-109">RA </span>and <span 
class="cmtt-10x-x-109">DEC </span>are within 1 arcmin of
the given sky position. <br 
class="newline" />The cone search functions implement this expression making life much easier for the user. Because they can
also operate on arrays of positions, searching in multiple cones can be done simultaneously. That makes it
possible to ﬁnd matching source positions in two catalogues as shown in an example at the end of this
section.
</p><!--l. 2738--><p class="indent" >   The arguments of all functions are described below. All of them have to be given in radians. However,
usually one does not need to bother because TaQL makes it possible to specify positions in many formats
automatically converted to radians.
     </p><dl class="description"><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">SOURCES</span><br 
class="newline" />is a set or array giving the positions of one or more sources (e.g., in equatorial coordinates) to
     be tested. Normally these are columns in a table. Where argument name <span 
class="cmtt-10x-x-109">SOURCE </span>is mentioned
     below, only a single source can be used, otherwise multiple sources. <br 
class="newline" />For example: <br 
class="newline" /><span 
class="cmtt-10x-x-109">[RA,DEC] </span>for scalar columns RA and DEC. <br 
class="newline" /><span 
class="cmtt-10x-x-109">SKYPOS </span>for a column SKYPOS containing 2-element vectors with RA and DEC.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">CONES</span><br 
class="newline" />is  a  set  or  array  giving  the  center  positions  and  radii  of  one  or  more  cones  (e.g.,  as
     RA,DEC,radius). Usually the user will specify it as constants. <br 
class="newline" />For example: <br 
class="newline" /><span 
class="cmtt-10x-x-109">[12h13m54, -5.3.34, 0d1m] </span>for a single cone. <br 
class="newline" /><span 
class="cmtt-10x-x-109">[12h13m54, -5.3.34, 0d1m, 1h2m3, 4.5.6, 0d1m] </span>for two cones.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">CONEPOS</span><br 
class="newline" />is a set or array giving the positions of one or more cone centers (e.g., as RA,DEC).
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">RADII</span><br 
class="newline" />is a scalar, set or array giving one or more radii. Each radius is applied to all positions in
     <span 
class="cmtt-10x-x-109">CONEPOS</span>. Specifying a cone as <span 
class="cmtt-10x-x-109">CONEPOS,RADIUS </span>is easier than specifying it as <span 
class="cmtt-10x-x-109">CONES </span>if the same
     radius has to be used for multiple cones. <br 
class="newline" />For example: <br 
class="newline" /><span 
class="cmtt-10x-x-109">[12h13m54, -5.3.34, 1h2m3, 4.5.6], 0d1m </span>is the same as the second <span 
class="cmtt-10x-x-109">CONES </span>example above.</dd></dl>
<!--l. 2774--><p class="noindent" >The following cone search functions are available.
     </p><dl class="description"><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">bool ANYCONE(SOURCE,CONES)</span><br 
class="newline" />Return <span 
class="cmtt-10x-x-109">T </span>if the source is contained in at least one of the cones. Operator <span 
class="cmtt-10x-x-109">INCONE </span>is a synonym.
     So <span 
class="cmtt-10x-x-109">ANYCONE(SOURCE,CONES) </span>is the same as <span 
class="cmtt-10x-x-109">SOURCE INCONE CONES</span>.
                                                                                            
                                                                                            
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">bool ANYCONE(SOURCE,CONEPOS,RADII)</span><br 
class="newline" />It does the same as above.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">integer FINDCONE(SOURCES,CONES)</span><br 
class="newline" />Return the index of the ﬁrst cone containing the source. If a single source is given, the result is
     a scalar. If multiple sources are given, the result is an array with the same shape as the source
     array.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">integer FINDCONE(SOURCES,CONEPOS,RADII)</span><br 
class="newline" />It does the same as above. Note that in this case each radius is applied to each cone, so the
     resulting index array is a combination of the two input arrays (with the radius as the most
     rapidly varying axis).
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">bool CONES(SOURCES,CONES)</span><br 
class="newline" />Return a 2-dim bool array. The length of the most rapidly varying axis is the number of cones.
     The length of the other axis is the number of sources. When using python style, element <span 
class="cmtt-10x-x-109">(i,j)</span>
     in the resulting array is <span 
class="cmtt-10x-x-109">T </span>if source <span 
class="cmtt-10x-x-109">i </span>is contained in cone <span 
class="cmtt-10x-x-109">j</span>.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">bool CONES(SOURCES,CONEPOS,RADII)</span><br 
class="newline" />It does the same as above. However, the result is a 3-dim array with the radii as the most rapidly
     varying axis, cones as the next axis, and sources as the slowest axis.</dd></dl>
<!--l. 2805--><p class="noindent" >Please note that <span 
class="cmtt-10x-x-109">ANYCONE(SOURCE,CONES) </span>does the same as <span 
class="cmtt-10x-x-109">any(CONES(SOURCE,CONES))</span>, but is faster because it
stops as soon as a cone is found. <br 
class="newline" />Function <span 
class="cmtt-10x-x-109">CONES </span>makes it possible to do catalogue matching. For example, to ﬁnd sources matching other
sources in the same catalogue (within a radius of 10 arcseconds):
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-79">
  CALC CONES([RA,DEC],
 <br />             [SELECT FROM table.cat GIVING [RA,DEC]], 0d0m10)
 <br />     FROM table.cat
</div>
<!--l. 2815--><p class="nopar" > Note that in this example the SELECT clause returns an array with positions which are used as the cone
centers. So each source in the catalogue is tested against every source. It makes it an N-square operation,
thus potentially very expensive. The result is a 4-dim boolean array with shape (in glish style)
<span 
class="cmtt-10x-x-109">[1,nrow,1,nrow] </span>which can be processed in Glish. Please note that the <span 
class="cmtt-10x-x-109">CONES </span>function results for each row
in a array with shape <span 
class="cmtt-10x-x-109">[1,nrow,1]</span>. <br 
class="newline" />The query can be done with multiple radii, for example also with 1 arcsecond and 1 arcminute.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-80">
  CALC CONES([RA,DEC],
 <br />       [SELECT FROM table.cat GIVING [RA,DEC]], [0d0m1, 0d0m10, 0d1m])
 <br />     FROM table.cat
</div>
<!--l. 2830--><p class="nopar" > resulting in an array with glish shape <span 
class="cmtt-10x-x-109">[3,nrow,1,nrow]</span>. In this way one can get a better indication how
close sources are to the cone centers.
</p><!--l. 2835--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">4.10.16   </span> <a 
 id="x1-650004.10.16"></a>User deﬁned functions</h5>
<!--l. 2836--><p class="noindent" >TaQL can be extended with so-called User Deﬁned Functions (UDF). These are dynamically loaded
functions, either written in C++ or in Python. In TaQL the name of a UDF written in C++ consists of the
name of the library (without lib preﬁx and extension) followed by a dot and the function name. For
example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-81">
  meas.hadec(...)
</div>
<!--l. 2843--><p class="nopar" > denotes function <span 
class="cmtt-10x-x-109">hadec </span>in shared library <span 
class="cmtt-10x-x-109">libmeas.so </span>or <span 
class="cmtt-10x-x-109">libcasa</span><span 
class="cmtt-10x-x-109">_meas.so</span>. For OS-X the extension <span 
class="cmtt-10x-x-109">.dylib</span>
will be used. <br 
class="newline" />The physical shared library name must be fully lowercase, but the UDF name used in TaQL is
case-insensitive. The name of a UDF written in Python is like <span 
class="cmtt-10x-x-109">py.module.func </span>where the module part
is optional. In the <a 
href="#x1-60002.2"><span 
class="cmtt-10x-x-109">USING STYLE</span></a> clause it is possible to deﬁne synonyms for the UDF library
names. By default, <span 
class="cmtt-10x-x-109">mscal </span>is deﬁned as a synonym for <span 
class="cmtt-10x-x-109">derivedmscal </span>and <span 
class="cmtt-10x-x-109">py </span>as a synonym for
<span 
class="cmtt-10x-x-109">pytaql</span>.
</p><!--l. 2856--><p class="indent" >   Usually a UDF will operate on the arguments given to the function and will not itself operate on a table
given in a query command. However, some UDFs (most notably the <span 
class="cmtt-10x-x-109">mscal </span>ones) do not have arguments, but
operate directly in a speciﬁc way on a table. Normally they use the ﬁrst table given in the FROM
clause, but the UDF name can be preceded by a <a 
href="#x1-190003.4">table shorthand</a> to specify another table. For
example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-82">
  select t1.mscal.ha1(), t2.mscal.ha1() from my1.ms t1, my2.ms t2
</div>
<!--l. 2865--><p class="nopar" > to get the hourangle from two diﬀerent tables. Of course, both tables need to have the same number of rows.
<br 
class="newline" />Note that UDFs not directly operating on a table, will ignore a shorthand.
</p><!--l. 2870--><p class="indent" >   In section <a 
href="#x1-12700014">Writing user deﬁned functions</a> it is explained how to write user deﬁned functions.
</p><!--l. 2874--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">4.10.17   </span> <a 
 id="x1-660004.10.17"></a>Special MeasurementSet functions</h5>
<!--l. 2875--><p class="noindent" >The Casacore package comes with several predeﬁned UDFs in library <span 
class="cmtt-10x-x-109">libcasa</span><span 
class="cmtt-10x-x-109">_derivedmscal</span>. It contains
four groups of UDFs, all operating on a MeasurementSet and several on a CASA calibration table (both old
and new format). <br 
class="newline" />Although the library is called <span 
class="cmtt-10x-x-109">derivedmscal</span>, for ease of use it is possible to use the synonym
<span 
class="cmtt-10x-x-109">mscal</span>.
</p>
<!--l. 2882--><p class="noindent" ><span class="likeparagraphHead"><a 
 id="x1-670004.10.17"></a></span>
   <span 
class="cmbx-10x-x-109">Get derived values </span><br 
class="newline" />The ﬁrst group calculates derived values like hourangle and azimuth for the ﬁrst or second antenna of a
baseline. For calibration tables, where a row contains a single antenna, functions like PA1 are the same as
PA2. All angles are returned in radians.
     </p><dl class="description"><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double MSCAL.HA()</span><br 
class="newline" />gives the hourangle of the array center (observatory position).
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double MSCAL.HA1()</span><br 
class="newline" />gives the hourangle of ANTENNA1.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double MSCAL.HA2()</span><br 
class="newline" />gives the hourangle of ANTENNA2.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double MSCAL.HADEC()</span><br 
class="newline" />gives the topocentric hourangle/declination of the array center (observatory position).
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double MSCAL.HADEC1()</span><br 
class="newline" />gives the topocentric hourangle/declination of ANTENNA1.
                                                                                            
                                                                                            
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double MSCAL.HADEC2()</span><br 
class="newline" />gives the topocentric hourangle/declination of ANTENNA2.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">doublearray MSCAL.AZEL()</span><br 
class="newline" />gives the topocentric azimuth/elevation of the array center (observatory position).
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">doublearray MSCAL.AZEL1()</span><br 
class="newline" />gives the topocentric azimuth/elevation of ANTENNA1.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">doublearray MSCAL.AZEL2()</span><br 
class="newline" />gives the topocentric azimuth/elevation of ANTENNA2.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double MSCAL.LAST()</span><br 
class="newline" />gives the local sidereal time of the array center.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double MSCAL.LAST1()</span><br 
class="newline" />gives the local sidereal time of ANTENNA1.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double MSCAL.LAST2()</span><br 
class="newline" />gives the local sidereal time of ANTENNA2.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double MSCAL.PA1()</span><br 
class="newline" />gives the parallactic angle of ANTENNA1.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">double MSCAL.PA2()</span><br 
class="newline" />gives the parallactic angle of ANTENNA2.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">doublearray MSCAL.NEWUVW()</span><br 
class="newline" />gives the 3-vector of UVW coordinates in J2000 in meters. It recalculates them, thus does not
     return the UVW coordinates stored in the MeasurementSet.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">doublearray MSCAL.NEWUVWWVL()</span><br 
class="newline" />gives the 3-vector of calculated UVW coordinates in J2000 in wavelengths for the reference
     frequency of the appropriate spectral window.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">doublearray MSCAL.NEWUVWWVLS()</span><br 
class="newline" />gives the nfreq*3-matrix of calculated UVW coordinates in J2000 in wavelengths for all channel
     frequencies of the appropriate spectral window.
                                                                                            
                                                                                            
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">doublearray MSCAL.UVWWVL()</span><br 
class="newline" />gives the 3-vector of stored UVW coordinates in wavelengths for the reference frequency of the
     appropriate spectral window.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">doublearray MSCAL.UVWWVLS()</span><br 
class="newline" />gives the nfreq*3-matrix of stored UVW coordinates in wavelengths for all channel frequencies
     of the appropriate spectral window.</dd></dl>
<!--l. 2934--><p class="noindent" >By default all these functions will use the direction given in column PHASE_DIR of the FIELD subtable. It is
possible to use another column by giving its name as a string argument (e.g., HA(&#x2019;DELAY_DIR&#x2019;)).
<br 
class="newline" />Except for the last 2 functions, it is possible to use an explicit direction which must be given as [RA,DEC] in
J2000 or as a case-insensitive name of a planetary object (as deﬁned by the Casacore Measures). For
example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-83">
   derivedmscal.azel1([5h23m32.76, 10d15m56.49])
 <br />   derivedmscal.azel1(&#x2019;MOON&#x2019;)
</div>
<!--l. 2944--><p class="nopar" > The examples above give the azimuth and elevation of the given directions for each selected row in the
MeasurementSet, using the position of ANTENNA1 and the times in these rows.
</p><!--l. 2949--><p class="indent" >   If a string value is given, it is ﬁrst tried as a planetary object. Theoretically it is possible that a column
has the same name as a planetary object. In such a case the name can be escaped by a backslash to indicate
that a column name is meant. For example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-84">
   derivedmscal.azel1(&#x2019;\SUN&#x2019;)
</div>
<!--l. 2956--><p class="nopar" > means that column SUN in the FIELD table has to be used.
</p>
<!--l. 2959--><p class="noindent" ><span class="likeparagraphHead"><a 
 id="x1-680004.10.17"></a></span>
   <span 
class="cmbx-10x-x-109">Stokes conversion </span><br 
class="newline" />The <span 
class="cmtt-10x-x-109">STOKES </span>function makes it possible to convert the Stokes parameters of a DATA column in a
MeasurementSet, for instance from linear or circular to iquv. It is also possible to convert the weights or
ﬂags, i.e., to combine them in the same way as the data would be combined.
     </p><dl class="description"><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">complexarray MSCAL.STOKES(complexarray, string)</span><br 
class="newline" />converts the data.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">doublearray MSCAL.STOKES(doublearray, string)</span><br 
class="newline" />combines the weights.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">boolarray MSCAL.STOKES(boolarray, string)</span><br 
class="newline" />combines the ﬂags.</dd></dl>
<!--l. 2973--><p class="noindent" >In all cases the case-insensitive string argument deﬁnes the output Stokes axes. It must be a comma separated
list of Stokes names. All values deﬁned in the Casacore class <span 
class="cmtt-10x-x-109">Stokes </span>are possible. Most important are:
</p>
     <ul class="itemize1">
     <li class="itemize">XX, XY, YX, and/or YY. <br 
class="newline" />LINEAR or LIN means XX,XY,YX,YY.
     </li>
     <li class="itemize">RR, RL, LR, and/or LL. <br 
class="newline" />CIRCULAR or CIRC means RR,RL,LR,LL.
     </li>
     <li class="itemize">I, Q, U, and/or V. <br 
class="newline" />IQUV or STOKES means I,Q,U,V.
     </li>
     <li class="itemize">PTOTAL is the polarized intensity (sqrt(Q**2+U**2+V**2))
     </li>
     <li class="itemize">PLINEAR is the linearly polarized intensity (sqrt(Q**2+U**2))
     </li>
     <li class="itemize">PFTOTAL is the polarization fraction (Ptotal/I)
                                                                                            
                                                                                            
     </li>
     <li class="itemize">PFLINEAR is the linear polarization fraction (Plinear/I)
     </li>
     <li class="itemize">PANGLE is the linear polarization angle (0.5*arctan(U/Q)) (in radians)</li></ul>
<!--l. 2987--><p class="noindent" >If not given, the string argument defaults to &#x2019;IQUV&#x2019;. For example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-85">
  select mscal.stokes(DATA,&#x2019;circ&#x2019;) as CIRCDATA from my.ms
</div>
<!--l. 2991--><p class="nopar" > creates a table with column CIRCDATA containing the circular polarization data.
</p>
<!--l. 2995--><p class="noindent" ><span class="likeparagraphHead"><a 
 id="x1-690004.10.17"></a></span>
   <span 
class="cmbx-10x-x-109">CASA style selection </span><br 
class="newline" />The <span 
class="cmtt-10x-x-109">BASELINE </span>function makes it possible to do selection on baselines in a MeasurementSet or CalTable using
the special CASA selection syntax described in <a 
href="263.html" >note 263</a>. Similar functions <span 
class="cmtt-10x-x-109">CORR, TIME, FIELD, FEED,</span>
<span 
class="cmtt-10x-x-109">SCAN, SPW, UVDIST, STATE, OBS</span>, and <span 
class="cmtt-10x-x-109">ARRAY </span>can be used to do selection based on other meta data. The
functions accept a string containing a selection string and return a Bool value telling if a row matches the
selection string. For example,
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-86">
  select from my.ms where mscal.baseline(&#x2019;RT[2-4]&#x2019;)
</div>
<!--l. 3007--><p class="nopar" > selects the cross-correlation baselines containing an antenna whose name matches the pattern in the function
argument. <br 
class="newline" />Note there is a diﬀerence how CASA and TaQL handle unknown antennas given in the baseline
selection string. CASA tasks give an error, while TaQL will not complain and not even report it,
because doing a selection this way should not behave diﬀerently from doing it like <span 
class="cmtt-10x-x-109">NAME=&#x2019;RTX&#x2019;</span>.
<br 
class="newline" />Also note that in CASA tasks only one selection string per type can be given and the ﬁnal selection is the
AND of them. TaQL has the AND and OR operators making it possible to combine the selections in all kind
of ways, possibly using multiple selection strings of the same type.
</p>
<!--l. 3020--><p class="noindent" ><span class="likeparagraphHead"><a 
 id="x1-700004.10.17"></a></span>
   <span 
class="cmbx-10x-x-109">Get values from a subtable </span><br 
class="newline" />Several functions exist to get information like the name of an antenna from the subtable for each row in the
main table. Basically they do a join of the main table and a subtable. For example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-87">
  select mscal.ant1name(), mscal.ant2name() from my.ms
</div>
<!--l. 3027--><p class="nopar" > gets the names of the antennae used in each baseline.
</p><!--l. 3030--><p class="indent" >   The following functions can be used:
     </p><dl class="description"><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">string MSCAL.ANT1NAME()</span><br 
class="newline" />gives the name of ANTENNA1.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">string MSCAL.ANT2NAME()</span><br 
class="newline" />gives the name of ANTENNA2.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">anytype MSCAL.ANT1COL(ColumnName)</span><br 
class="newline" />gives for ANTENNA1 the value in the given column (in quotes) in the ANTENNA subtable.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">anytype MSCAL.ANT2COL(ColumnName)</span><br 
class="newline" />gives for ANTENNA2 the value in the given column (in quotes) in the ANTENNA subtable.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">anytype MSCAL.STATECOL(ColumnName)</span><br 
class="newline" />gives for STATE_ID the value in the given column (in quotes) in the STATE subtable.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">anytype MSCAL.OBSCOL(ColumnName)</span><br 
class="newline" />gives for OBSERVATION_ID the value in the given column (in quotes) in the OBSERVATION
     subtable.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">anytype MSCAL.SPWCOL(ColumnName)</span><br 
class="newline" />gives
     for DATA_DESC_ID the value in the given column (in quotes) in the SPECTRAL_WINDOW
     subtable.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">anytype MSCAL.POLCOL(ColumnName)</span><br 
class="newline" />gives for DATA_DESC_ID the value in the given column (in quotes) in the POLARIZATION
     subtable.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">anytype MSCAL.FIELDCOL(ColumnName)</span><br 
class="newline" />gives for FIELD_ID the value in the given column (in quotes) in the FIELD subtable.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">anytype MSCAL.PROCCOL(ColumnName)</span><br 
class="newline" />gives for PROCESSOR_ID the value in the given column (in quotes) in the PROCESSOR
     subtable.
                                                                                            
                                                                                            
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">anytype MSCAL.SUBCOL(SubtableName, ColumnName, idcolumn)</span><br 
class="newline" />gives for the (integer) id-column the value in the given column in the given subtable. This is the
     most common form and can be used to join any table with a subtable.</dd></dl>
<!--l. 3065--><p class="noindent" >Note that the following are equivalent. The ﬁrst versions are shorthands for the latter ones.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-88">
 mscal.ant1name()
 <br /> mscal.ant1col(&#x2019;NAME&#x2019;)
 <br /> mscal.subcol(&#x2019;ANTENNA&#x2019;, &#x2019;NAME&#x2019;, ANTENNA1)
</div>
<!--l. 3071--><p class="nopar" > In the last example the id-column must be given as such, thus must not be a string.
</p><!--l. 3076--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">4.10.18   </span> <a 
 id="x1-710004.10.18"></a>Special Measures functions</h5>
<!--l. 3077--><p class="noindent" >These functions make it possible to convert measures like directions, epochs, and positions from one
reference frame to another. All conversions supported by Casacore&#x2019;s <a 
href="../html/group__Measures__module.html" >Measures</a> are possible. For
example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-89">
  meas.galactic (-6h52m36.7, 34d25m56.1, &#x0022;J2000&#x0022;)
 <br />  meas.azel (&#x0022;MOON&#x0022;, datetime(), &#x0022;WSRT&#x0022;)
</div>
<!--l. 3086--><p class="nopar" > The ﬁrst example converts a J2000 position to galactic coordinates. The second example gives the moon&#x2019;s
azimuth/elevation at the WSRT at the current date/time.
</p>
<!--l. 3091--><p class="noindent" ><span class="likeparagraphHead"><a 
 id="x1-720004.10.18"></a></span>
   The following basic functions are available. Most functions return double angle values with unit rad. Only
the RISESET function returns date/time values. <br 
class="newline" />Note that all names used below are case-insensitive.
     </p><dl class="description"><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">doublearray MEAS.DIR(toref, direction, epoch, position)</span><br 
class="newline" />converts a direction to the reference type given by the &#x2019;toref&#x2019; string. The epoch and position
     arguments only need to be given if the conversion needs frame information (e.g., when converting
     J2000 to apparent).<br 
class="newline" />Function name MEAS.DIRECTION can be used as well.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">doublearray MEAS.DIRCOS(toref, direction, epoch, position)</span><br 
class="newline" />Same as function DIR, but returning 3 direction cosines instead of 2 angles.<br 
class="newline" />Function name MEAS.DIRECTIONCOSINE can be used as well.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">DateTimearray MEAS.RISESET(direction, epoch, position)</span><br 
class="newline" />returns the rise and set date/times (UTC) of the sources given in the direction argument for the given dates and
     positions. Function name MEAS.RISET can be used as well. Note that the source can be invisible all day (results
     in set<!--l. 3110--><math 
 xmlns="http://www.w3.org/1998/Math/MathML"  
display="inline" > <mo 
class="MathClass-rel">&#x003C;</mo></math>rise).
     If visible all day, rise time is 0h0m and set time is 24 hours later. <br 
class="newline" />The TIME or CTIME function can be used on the result to get the time part only (as double or string).
     <br 
class="newline" />If the sun is used as a source name (case-insensitive), it can be followed by a hyphen and one of the
     following case-insensitive suﬃces indicating what to use. The default is CR which is used in most
     almanacs.
          <ul class="itemize1">
          <li class="itemize"><span 
class="cmtt-10x-x-109">CR</span>: use the center of the sun with refraction correction.
          </li>
          <li class="itemize"><span 
class="cmtt-10x-x-109">UR</span>: use the upper brim of the sun with refraction correction, thus show when part of the
          sun is visible.
          </li>
          <li class="itemize"><span 
class="cmtt-10x-x-109">LR</span>: use the lower brim of the sun with refraction correction, thus show when the full sun is
          visible.
                                                                                            
                                                                                            
          </li>
          <li class="itemize"><span 
class="cmtt-10x-x-109">C</span>: use the center of the sun without refraction correction.
          </li>
          <li class="itemize"><span 
class="cmtt-10x-x-109">U</span>: use the upper brim of the sun without refraction correction.
          </li>
          <li class="itemize"><span 
class="cmtt-10x-x-109">L</span>: use the lower brim of the sun without refraction correction.
          </li>
          <li class="itemize"><span 
class="cmtt-10x-x-109">CT</span>: use the civil twilight (6 deg). without artiﬁcal light.
          </li>
          <li class="itemize"><span 
class="cmtt-10x-x-109">NT</span>: use the nautical twilight (12 deg). visible for navigating.
          </li>
          <li class="itemize"><span 
class="cmtt-10x-x-109">AT</span>: use the amateur astronomical twilight (15 deg).
          </li>
          <li class="itemize"><span 
class="cmtt-10x-x-109">ST</span>: use the scientiﬁc astronomical twilight (18 deg).</li></ul>
     <!--l. 3134--><p class="noindent" >The ﬁrst six suﬃces can also be used with the Moon. <br 
class="newline" />See <a 
href="http://www.stjarnhimlen.se/comp/riset.html" >stjarnhimlen.se</a> for additional information.
     </p></dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">doublearray MEAS.EPOCH(toref, epoch, position)</span><br 
class="newline" />converts an epoch to the reference type given by the &#x2019;toref&#x2019; string. The position argument only needs to
     be given if the conversion needs frame information. By default conversions to sidereal time (e.g, LAST)
     return the fraction giving the true sidereal time. Only if the <span 
class="cmtt-10x-x-109">toref </span>string starts with &#x2019;F-&#x2019;, &#x2019;F_&#x2019;, &#x2019;f-&#x2019;, or
     &#x2019;f_&#x2019; the full sidereal time is returned which includes the number of sidereal days since the start of
     MJD.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">doublearray MEAS.POS(toref, position)</span><br 
class="newline" />converts a position to the reference type given by the &#x2019;toref&#x2019; string.<br 
class="newline" />Function name MEAS.POSITION can be used as well.</dd></dl>
<!--l. 3151--><p class="noindent" >The available reference types can be shown using the <span 
class="cmtt-10x-x-109">show meastypes </span>command in the program <span 
class="cmti-10x-x-109">taql</span>. For ease of
use several specialized MEAS.DIR and MEAS.POS functions are deﬁned with an implicit &#x2019;toref&#x2019;
argument.
     </p><dl class="description"><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">doublearray MEAS.J2000(direction, epoch, position)</span><br 
class="newline" />converts a direction to J2000.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">doublearray MEAS.B1950(direction, epoch, position)</span><br 
class="newline" />converts a direction to B1950.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">doublearray MEAS.APP(direction, epoch, position)</span><br 
class="newline" />converts a direction to apparent coordinates. <br 
class="newline" />Function name MEAS.APPARENT can be used as well.
                                                                                            
                                                                                            
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">doublearray MEAS.HADEC(direction, epoch, position)</span><br 
class="newline" />converts a direction to hourangle/declination.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">doublearray MEAS.AZEL(direction, epoch, position)</span><br 
class="newline" />converts a direction to azimuth/elevation.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">doublearray MEAS.ECL(direction, epoch, position)</span><br 
class="newline" />converts a direction to ecliptic coordinates. <br 
class="newline" />Function name MEAS.ECLIPTIC can be used as well.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">doublearray MEAS.GAL(direction, epoch, position)</span><br 
class="newline" />converts a direction to galactic coordinates. <br 
class="newline" />Function name MEAS.GALACTIC can be used as well.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">doublearray MEAS.SGAL(direction, epoch, position)</span><br 
class="newline" />converts a direction to supergalactic coordinates. <br 
class="newline" />Function name MEAS.SUPERGAL or MEAS.SUPERGALACTIC can be used as well.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">doublearray MEAS.ITRFD(direction, epoch, position)</span><br 
class="newline" />converts a direction to ITRF coordinates. <br 
class="newline" />Function name MEAS.ITRFDIR or MEAS.ITRFDIRECTION can be used as well.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">doublearray MEAS.LAST(epoch, position)</span><br 
class="newline" />converts an epoch to local sidereal time. <br 
class="newline" />Function name MEAS.LST can be used as well.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">doublearray MEAS.ITRFxxx(position)</span><br 
class="newline" />converts a position to ITRF coordinates.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">doublearray MEAS.WGSxxx(position)</span><br 
class="newline" />converts a position to WGS84 coordinates.</dd></dl>
<!--l. 3187--><p class="noindent" >The names of the last two functions have a suﬃx xxx indicating how positions are returned. <br 
class="newline" />- XYZ means as x,y,z <br 
class="newline" />- LL or LONLAT means as lon,lat <br 
class="newline" />- H or HEIGHT means as height <br 
class="newline" />It defaults to XYZ.
</p>
<!--l. 3194--><p class="noindent" ><span class="likeparagraphHead"><a 
 id="x1-730004.10.18"></a></span>
   The function arguments can be given in a variety of ways. </p>
                                                                                            
                                                                                            
     <ul class="itemize1">
     <li class="itemize">&#x2019;toref&#x2019; is a constant scalar string giving the reference type to convert to. See the Measure classes
     <a 
href="../html/classcasa_1_1MDirection.html" >MDirection</a>, <a 
href="../html/classcasa_1_1MEpoch.html" >MEpoch</a>, and <a 
href="../html/classcasa_1_1MPosition.html" >MPosition</a>, for an overview of the types.
     </li>
     <li class="itemize">&#x2019;direction&#x2019; gives one or more directions to convert. They can be given in several ways.
          <ul class="itemize2">
          <li class="itemize">As a constant scalar or array of strings giving one or more planetary objects like MOON
          or VENUS and/or giving the name of standard sources (CasA, CygA, TauA, VirA, HerA,
          HydA, or PerA). In the future support for comets might be added. <br 
class="newline" />The names are case-insensitive.
          </li>
          <li class="itemize">As 2 constant double scalar arguments giving ra and dec (or longitude and latitude).
          </li>
          <li class="itemize">As a double array with an even number of elements giving ra/dec or longitude/latitude of
          one or more directions. It can be a constant array (expression), but it can also be a column
          or an expression using a column.</li></ul>
     <!--l. 3218--><p class="noindent" >If a column or a column slice is given, the reference type stored in the column keywords will be
     recognized. In other cases the input reference type should be given in the next string argument. If not
     given, it defaults to J2000. <br 
class="newline" />For example:
                                                                                            
                                                                                            
</p>
     <div class="verbatim" id="verbatim-90">
       [&#x2019;MOON&#x2019;,&#x2019;sun&#x2019;, &#x2019;venus&#x2019;]          # 3 planetary objects
      <br />  12h23m17.5, 23d56m43.8, &#x2019;B1950&#x2019;  # ra/dec as scalar constants (as B1950)
      <br />  [12h23m17.5, 23d56m43.8]         # ra/dec as array (default J2000)
      <br />  PHASE_DIR[0,]                    # direction ra/dec in given column
</div>
     <!--l. 3228--><p class="nopar" >
     </p></li>
     <li class="itemize">&#x2019;epoch&#x2019; gives one or more epochs to use. Similar to directions the reference type is taken from the
     column keywords or can be given in the next argument. It defaults to UTC. <br 
class="newline" />Epochs can be given in three ways:
          <ul class="itemize2">
          <li class="itemize">As a scalar or array containing double values. It can be a constant expression or a column
          (expression).
          </li>
          <li class="itemize">As a scalar or array containing DateTime values.
          </li>
          <li class="itemize">As  a  scalar  or  array  containing  String  values  representing  date/time.  They  will
          automatically be converted to DateTime values using function <span 
class="cmtt-10x-x-109">datetime</span>.</li></ul>
     <!--l. 3242--><p class="noindent" >For example:
                                                                                            
                                                                                            
</p>
     <div class="verbatim" id="verbatim-91">
       datetime()                         # current date/time
      <br />  &#x2019;today&#x2019;                            # current date/time
      <br />  [select unique TIME from my.ms]    # all times from some MS
      <br />  9Sep2011/12:00:00, &#x2019;UTC&#x2019;           # given UTC time
</div>
     <!--l. 3248--><p class="nopar" > Note that in the last example &#x2019;UTC&#x2019; is not necessary, because it is the default.
     </p></li>
     <li class="itemize">&#x2019;position&#x2019; gives one or more directions to use. They can be given as x,y,z or as lon,lat with an optional
     height. Usually the unit of the ﬁrst value deﬁnes if x,y,z or lon,lat is used. It is, however, also possible to
     distinguish between LL and XYZ by using suﬃces like XYZ or LL in the reference type given in the
     next argument.
          <ul class="itemize2">
          <li class="itemize">As a scalar or array of observatory names using their positions in the Measures Observatory
          table.
          </li>
          <li class="itemize">As 2 or 3 constant double scalar values giving xyz, lonlat, or lonlat/height.
          </li>
          <li class="itemize">As a double array giving one or more positions in xyz or lonlat. Similar to directions it can
          be a column (expression) where the reference type is taken from the column keywords.
          </li>
          <li class="itemize">As two constant double arrays giving lonlat and height of one or more positions. The array
          sizes have to match (thus the size of the lonlat array must be twice the size of the height
          array).</li></ul>
     <!--l. 3269--><p class="noindent" >If needed, the reference type (with optional suﬃx) can be given in the next argument. The reference
     type defaults to ITRF if xyz coordinates are used, otherwise to WGS. <br 
class="newline" />For example:
                                                                                            
                                                                                            
</p>
     <div class="verbatim" id="verbatim-92">
       &#x2019;WSRT&#x2019;                             # WSRT position
      <br />  5deg, 52deg                        # 2 scalar constants (WGS84 lonlat)
      <br />  (5deg, 52deg]                      # same, but as array
      <br />  5deg, 52deg, 5m                    # WGS84 lonlat with height
      <br />  [5deg, 52deg], [5m]                # same, but as array
      <br />  3.8288e+06m, 442449, 5.0649e+06    # xyz as scalars (ITRF)
      <br />  [41.84m, 4.835, 55.722], &#x2019;WGS&#x2019;     # xyz as array (WGS84)
      <br />  POSITION                           # POSITION column
</div>
     <!--l. 3282--><p class="nopar" ></p></li></ul>
<!--l. 3284--><p class="noindent" >A few more elaborate examples are given below.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-93">
  meas.last (date(&#x2019;15Oct2011/15:34&#x2019;), 5deg, 52deg)
</div>
<!--l. 3287--><p class="nopar" > calculates the local apparent sidereal time for the given date and position.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-94">
  meas.azel (&#x0022;JUPITER&#x0022;, [select unique TIME from ~/GER1.MS],
 <br />            [&#x0022;WSRT&#x0022;,&#x0022;VLA&#x0022;])
</div>
<!--l. 3293--><p class="nopar" > calculates Jupiter&#x2019;s azimuth/elevation for WSRT and VLA for all times returned by the subquery (see next
section for subqueries).
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-95">
  calc meas.b1950(PHASE_DIR[0,]) from ~/GER1.MS/FIELD&#x2019;
</div>
<!--l. 3298--><p class="nopar" > converts the PHASE_DIR directions in the FIELD table to B1950. Note that no frame information is needed
for such a conversion.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-96">
  meas.azel([03h13m10,65d50m12], 24sep2015/12:0:0+[0:24]h, &#x2019;LOFAR&#x2019;) deg
 <br />  meas.azel(03h13m10,65d50m12,&#x2019;B1950&#x2019;, 24sep2015/12:0:0+[0:24]h, &#x2019;LOFAR&#x2019;)deg
</div>
<!--l. 3304--><p class="nopar" > calculates the azimuth/elevation (in degrees) of the given source direction for the LOFAR site for 24 hours.
The result is an array with shape [24,2]. The direction in the second example is given in B1950, the ﬁrst as
the default J2000.
</p><!--l. 3311--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">4.11   </span> <a 
 id="x1-740004.11"></a>Subqueries</h4>
<!--l. 3312--><p class="noindent" >As in SQL it is possible to create a set from a subquery. A subquery has the same syntax as a main query,
but has to be enclosed in square brackets or parentheses. Basically it looks like:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-97">
  SELECT FROM maintable WHERE time IN
 <br />      [SELECT time FROM othertable WHERE windspeed &#x003C; 5]
</div>
<!--l. 3318--><p class="nopar" > The subquery on <span 
class="cmtt-10x-x-109">othertable </span>results in a constant set containing the times for which the windspeed
matches. Subsequently the main query is executed and selects all rows from the main table with times in that
set. Note that like other bounded sets this set is transformed to a constant array, so it is possible to apply
functions to it (e.g., min, mean).
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-98">
  SELECT [SELECT NAME FROM ::ANTENNA][ANTENNA1] FROM ~/GER1.MS
</div>
<!--l. 3330--><p class="nopar" > This example shows how a subquery is used to join the main table of a MeasurementSet and
its ANTENNA subtable. The subquery returns a list with the names of all antennae, which
subsequently is indexed with the antenna number to get the antenna name for each row in the main
table.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-99">
  SELECT mscal.ant1name() from ~/GER1.MS
</div>
<!--l. 3338--><p class="nopar" > is a newer and easier way to obtain the name of ANTENNA1. It makes use of the new user
deﬁned functions in <a 
href="#x1-660004.10.17">derivedmscal</a> which can do an implicit join of a MeasurementSet and its
subtables.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-100">
  SELECT FROM maintable WHERE time IN
 <br />      [SELECT time FROM othertable WHERE windspeed &#x003C;
 <br />           mean([SELECT windspeed FROM othertable])]
</div>
<!--l. 3348--><p class="nopar" > This example contains another subquery to get all windspeeds and to take the mean of them. So
the ﬁrst subquery selects all times where the windspeed is less than the average windspeed.
<br 
class="newline" />A subquery result should contain only one column, otherwise an exception is thrown.
</p><!--l. 3355--><p class="indent" >   It may happen that a subquery has to be executed twice because 2 columns from the other table are
needed. E.g.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-101">
  SELECT FROM maintable WHERE any(time &#x003E;=
 <br />      [SELECT starttime FROM othertable WHERE windspeed &#x003C; 5]
 <br />                               &#x0026;&#x0026; time &#x003C;=
 <br />      [SELECT endtime FROM othertable WHERE windspeed &#x003C; 5])
</div>
<!--l. 3362--><p class="nopar" > In this case the other table contains the time range for each windspeed. For big tables it is expensive to
execute the subquery twice. A better solution is to store the result of the subquery in a temporary table and
reuse it.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-102">
  SELECT FROM othertable WHERE windspeed &#x003C; 5 GIVING tmptab
 <br />  SELECT FROM maintable WHERE any(time &#x003E;=
 <br />      [SELECT starttime FROM tmptab]
 <br />                               &#x0026;&#x0026; time &#x003C;=
 <br />      [SELECT endtime FROM tmptab])
</div>
<!--l. 3373--><p class="nopar" > However, this has the disadvantage that the table <span 
class="cmtt-10x-x-109">tmptab </span>still exists after the query and has to be deleted
explictly by the user. Below a better solution for this problem is shown.
</p><!--l. 3378--><p class="indent" >   TaQL has a few extensions to support tables better, in particular the Casacore MeasurementSets.
     </p><ol  class="enumerate1" >
     <li 
  class="enumerate" id="x1-74002x1">The temporary problem above can be circumvented by using the ability to use a <span 
class="cmtt-10x-x-109">SELECT </span>expression in
     the <span 
class="cmtt-10x-x-109">FROM </span>clause. E.g.
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-103">
       SELECT FROM maintable,
      <br />      [SELECT FROM othertable WHERE windspeed &#x003C; 5] tmptab
      <br />      WHERE any(time &#x003E;= [SELECT starttime FROM tmptab]
      <br />             &#x0026;&#x0026; time &#x003C;= [SELECT endtime FROM tmptab])
</div>
     <!--l. 3390--><p class="nopar" > However, below an even nicer solution is given.
     </p></li>
     <li 
  class="enumerate" id="x1-74004x2">The time range problem above can be solved elegantly by using a set as the result of the subquery.
     Instead of a table name, it is possible to give an expression in the GIVING clause (as mentioned in
     <a 
href="#x1-270003.10">section 3.10</a>). E.g.
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-104">
       select from MY.MS where TIME in
      <br />      [select FROM OTHERTABLE where WINDSPEED &#x003C; 5
      <br />           giving [TIME-INTERVAL/2 =:= TIME+INTERVAL/2]]
</div>
     <!--l. 3402--><p class="nopar" > The set expression in the GIVING clause is ﬁlled with the results from the subquery and used in the
     main query. So if the subquery results in 5 rows, the resulting set contains 5 intervals. Thereafter the
     resulting intervals are sorted and combined where possible. In this way the minimum number of
     intervals have to be examined by the main query.
     </p></li>
     <li 
  class="enumerate" id="x1-74006x3">In Casacore the other table will often be the name of a subtable, which is stored in a table or column
     keyword of the main table. The standard <a 
href="#x1-440004.5">keyword syntax</a> can be used to indicate that the other table is
     the table in the given keyword. Note that for a table keyword the <span 
class="cmtt-10x-x-109">:: </span>part has to be given, otherwise the
     name is treated as an ordinary table name. E.g.
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-105">
       select from MY.MS where TIME in
      <br />      [select TIME from ::WEATHER where WINDSPEED &#x003C; 5]
</div>
     <!--l. 3420--><p class="nopar" > In this example the other table is a subtable of table <span 
class="cmtt-10x-x-109">my.ms</span>. Its name is given by keyword <span 
class="cmtt-10x-x-109">WEATHER </span>of
     <span 
class="cmtt-10x-x-109">my.ms</span>.
     </p></li>
     <li 
  class="enumerate" id="x1-74008x4">Often the result of a query on a subtable of a measurement set is used to select columns from the main
     table. However, several subtables do not have an explicit key, but use the row number as an implicit
     key. The function <span 
class="cmtt-10x-x-109">ROWID() </span>can be used to return the row number as the subtable query result.
     E.g.
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-106">
       select from MY.MS where DATA_DESC_ID in
      <br />      [select from ::DATA_DESCRIPTION where
      <br />         SPECTRAL_WINDOW_ID in [0,2,4] giving [ROWID()]]
</div>
     <!--l. 3434--><p class="nopar" > Note that the function <span 
class="cmtt-10x-x-109">ROWNUMBER </span>cannot be used here, because it will give the row number in the
     selection and not (as <span 
class="cmtt-10x-x-109">ROWID </span>does) the row number in the original table. Furthermore, <span 
class="cmtt-10x-x-109">ROWID </span>gives a
     0-relative row number which is needed to be able to use it as a selection criterium on the 0-relative
     values in the measurement set.
     </p></li>
     <li 
  class="enumerate" id="x1-74010x5">Select if any channel has a UV distance <!--l. 3443--><math 
 xmlns="http://www.w3.org/1998/Math/MathML"  
display="inline" > <mo 
class="MathClass-rel">&#x003C;</mo></math>
     100 wavelengths.
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-107">
       select from MY.MS where any(sqrt(sumsqr(UVW[:2])) / c() *
      <br />      [select CHAN_FREQ from ::SPECTRAL_WINDOW][DATA_DESC_ID,]
      <br />         &#x003C; 100)
</div>
     <!--l. 3448--><p class="nopar" > In a MeasurementSet the UVW coordinates are stored in meters, so they have to be multiplied with
     the frequency and divided by speed of light to get them in wavelengths. <br 
class="newline" />Because TaQL has no proper join operation, it is not possible to select directly on the
     DATA_DESC_ID. However, using a nested query and indexing the result with the DATA_DESC_ID
     has the same eﬀect. It only requires that CHAN_FREQ has the same length in all rows in the subtable.
     <br 
class="newline" />Using the new <a 
href="#x1-660004.10.17">derivedmscal</a> functions, below a much nicer solution is given.
     </p></li>
     <li 
  class="enumerate" id="x1-74012x6">
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-108">
       select from MY.MS where any(mscal.uvwwvls() &#x003C; 100)
</div>
     <!--l. 3463--><p class="nopar" > It shows how the UVWWVLS function in <span 
class="cmtt-10x-x-109">derivedmscal </span>can be used to obtain the UVW coordinates
     in wavelengths.
     </p></li>
     <li 
  class="enumerate" id="x1-74014x7">Calculate the angular distance between the Mars and Jupiter as seen from the WSRT for the coming 30
     days.
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-109">
       calc angdist(meas.app(&#x2019;mars&#x2019;,    date()+[0:31], &#x2019;WSRT&#x2019;),
      <br />               meas.app(&#x2019;jupiter&#x2019;, date()+[0:31], &#x2019;WSRT&#x2019;))
</div>
     <!--l. 3473--><p class="nopar" ></p></li></ol>
<!--l. 3477--><p class="noindent" >
</p>
   <h3 class="sectionHead"><span class="titlemark">5   </span> <a 
 id="x1-750005"></a>Aggregation, GROUPBY, HAVING</h3>
<!--l. 3478--><p class="noindent" >Similar to SQL it is possible to do aggregation and grouping in TaQL and to do selection on the groups using
the HAVING clause.
</p><!--l. 3481--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">5.1   </span> <a 
 id="x1-760005.1"></a>Aggregation and GROUPBY</h4>
<!--l. 3482--><p class="noindent" >One or more aggregated values can be calculated for a group deﬁned by the GROUPBY clause. The
aggregate functions described in <a 
href="#x1-620004.10.13">section 4.10.13</a> can be used. For example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-110">
  SELECT ANTENNA1, ANTENNA2, gcount(), sqrt(sumsqr(UVW[:2]))
 <br />      FROM my.ms GROUPBY ANTENNA1,ANTENNA2
</div>
<!--l. 3490--><p class="nopar" > A group is formed for the unique values of the columns given in the GROUPBY clause. In the example
above a group per baseline is formed. Usually an aggregate function is ued to calculate a value for the group.
In the example above the aggregate function <span 
class="cmtt-10x-x-109">gcount() </span>counts the number of rows per baseline.
<br 
class="newline" />Often only the GROUPBY columns and aggregated values are part of the SELECT clause, but the example
shows that other values (here the baseline length) can also be selected. Non-aggregated values get the values
in the last row of a group.
</p><!--l. 3501--><p class="indent" >   Usually aggregated values and GROUPBY are used jointly, but it is possible to leave out one of them. If
GROUPBY is not given, the entire table is a single group. For example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-111">
  SELECT gcount() from my.ms
</div>
<!--l. 3506--><p class="nopar" > does not have groups, thus shows the total number of rows in the MS.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-112">
  SELECT ANTENNA1,ANTENNA2 from my.ms GROUPBY ANTENNA1,ANTENNA2
</div>
<!--l. 3510--><p class="nopar" > does not use aggregate functions, but shows the unique baselines in the MS. Apart from the order, it has the
same result as
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-113">
  SELECT ANTENNA1,ANTENNA2 from my.ms ORDERBY UNIQUE ANTENNA1,ANTENNA2
</div>
<!--l. 3515--><p class="nopar" > but is somewhat faster.
</p><!--l. 3518--><p class="indent" >   In the examples above a sole aggregate function is used, but it is also possible to use it in an expression.
Similarly, an expression can be used in the GROUPBY. For example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-114">
  select ctod(gmean(TIME)), gcount() from ~/data/GER.MS
 <br />    groupby round((TIME -
 <br />      [select gmin(TIME) from ~/data/GER.MS][0])/INTERVAL/5)
</div>
<!--l. 3525--><p class="nopar" > groups the MS in chunks of 5 time slots. Note that the nested query gets the TIME of the ﬁrst time slot.
The result is a set, hence the 0th element has to be taken.
</p><!--l. 3530--><p class="indent" >   Note that an aggregate function can only be used in the SELECT and HAVING clause, so TaQL will give
an error message if used elsewhere.
</p><!--l. 3533--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">5.2   </span> <a 
 id="x1-770005.2"></a>HAVING</h4>
<!--l. 3534--><p class="noindent" >The HAVING clause can be used to select speciﬁc groups. For example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-115">
  SELECT TIME, gmax(amplitude(DATA)) as MAXA from my.ms GROUPBY TIME
 <br />      HAVING MAXA &#x003E; 100
 <br />  SELECT TIME, gmax(amplitude(DATA)) from my.ms GROUPBY TIME
 <br />      HAVING gmax(amplitude(DATA)) &#x003E; 100
</div>
<!--l. 3540--><p class="nopar" > groups by time, but only selects the groups for which the maximum amplitude of the DATA is more
than 100. Both examples give the same result, but the ﬁrst one is more eﬃcient. Not only it is
less typing, but it is faster because it reuses the result column MAXA of the SELECT part.
<br 
class="newline" />Similar to WHERE, any expression can be used in HAVING, but the result has to be a bool scalar
value.
</p><!--l. 3549--><p class="indent" >   As shown in the example, HAVING will normally use aggregate functions, but it is not strictly needed.
However, selections without an aggregate function could as well be done in the WHERE clause.
<br 
class="newline" />Usually HAVING will be used in combination with GROUPBY, but it can be used without. It can
also be used without an aggregate function in the SELECT. However, it is an error if both are
omitted.
</p><!--l. 3558--><p class="noindent" >
</p>
   <h3 class="sectionHead"><span class="titlemark">6   </span> <a 
 id="x1-780006"></a>Some further remarks</h3>
<!--l. 3559--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">6.1   </span> <a 
 id="x1-790006.1"></a>Joining tables</h4>
<!--l. 3560--><p class="noindent" >As discussed in some previous sections it is possible to join tables on row number. Two examples show how to
do it.
</p><!--l. 3563--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">6.1.1   </span> <a 
 id="x1-800006.1.1"></a>Join on row number</h5>
                                                                                            
                                                                                            
   <div class="verbatim" id="verbatim-116">
  SELECT FROM mytable t1,othertable t2
 <br />    WHERE not all(t1.DATA ~= t2.DATA)
</div>
<!--l. 3567--><p class="nopar" > This command can be used to check if the data in <span 
class="cmtt-10x-x-109">mytable </span>is about equal to the data in <span 
class="cmtt-10x-x-109">othertable</span>. Both
tables have to have the same number of rows. <br 
class="newline" />The join is done on row number, thus the data in corresponding rows are compared.
</p><!--l. 3574--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">6.1.2   </span> <a 
 id="x1-810006.1.2"></a>Join using an indexed subquery</h5>
                                                                                            
                                                                                            
   <div class="verbatim" id="verbatim-117">
  SELECT [SELECT NAME FROM ::ANTENNA][ANTENNA1]
 <br />         FROM ~/GER1.MS
</div>
<!--l. 3578--><p class="nopar" > This example shows how a subquery is used to join the main table of a MeasurementSet with its
ANTENNA subtable. The subquery returns a list with the names of all antennae, which subsequently
is indexed with the antenna number to get the antenna name for each row in the main table.
<br 
class="newline" />The join is done using the ANTENNA1 column which gives the row number in the subtable, thus the index
in the subquery result.
</p><!--l. 3586--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">6.1.3   </span> <a 
 id="x1-820006.1.3"></a>Join using a subquery set</h5>
                                                                                            
                                                                                            
   <div class="verbatim" id="verbatim-118">
  SELECT FROM ~/GER1.MS WHERE ANTENNA1 IN
 <br />         [SELECT ROWID() FROM ::ANTENNA WHERE NAME ~ p/CS*/]
</div>
<!--l. 3590--><p class="nopar" > This example shows another way to use a subquery for a join of the main table of a MeasurementSet with its
ANTENNA subtable. It selects all baselines for which the ﬁrst station is a core station. The subquery returns
a set containing the ids of the core stations, which is used to select the correct stations in the main
table.
</p><!--l. 3597--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">6.1.4   </span> <a 
 id="x1-830006.1.4"></a>Join using derivedmscal</h5>
<!--l. 3598--><p class="noindent" >Several UDFs in the <span 
class="cmtt-10x-x-109">derivedmscal </span>library make it possible to easily join a MeasuementSet or CASA
Calibration Table with a subtable like ANTENNA or SPECTRAL_WINDOW. These functions know which
columns to use making the join straightforward like in
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-119">
  SELECT mscal.ant1name(), mscal.ant2name() from ~/GER1.MS
</div>
<!--l. 3604--><p class="nopar" > The library also contain the more general SUBCOL function making it possible to join any table with a
subtable. For example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-120">
  SELECT mscal.subcol(&#x2019;NAMES&#x2019;,&#x2019;NAME&#x2019;,NAMEID) from obs.parmdb
</div>
<!--l. 3609--><p class="nopar" > to get the parameter name for a LOFAR ParmDB table. A ParmDB table has a subtable NAMES
containing the NAME and other info of a parameter. The column NAME_ID is used to reference that
subtable.
</p><!--l. 3615--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">6.2   </span> <a 
 id="x1-840006.2"></a>Optimization</h4>
<!--l. 3616--><p class="noindent" >A lot of development work could be done to improve the query optimization. At this stage only a few simple
optimizations are done. </p>
     <ul class="itemize1">
     <li class="itemize">Constant subexpressions are calculated only once. E.g. <br 
class="newline" />in <span 
class="cmtt-10x-x-109">COL*sin(180/pi()) </span>the part <span 
class="cmtt-10x-x-109">sin(180/pi()) </span>is evaluated once.
     </li>
     <li class="itemize">If a subquery generates intervals of reals or dates, overlapping intervals are combined and eliminated.
     E.g.
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-121">
       select from GER.MS where TIME in [select from ::POINTING where
      <br />   sumsqr(DIRECTION[1])&#x003E;0 giving [TIME-INTERVAL/2=:=TIME+INTERVAL/2]]
</div>
     <!--l. 3627--><p class="nopar" > can generate many identical or overlapping intervals. They are sorted and combined where possible to
     make the set as small as possible.
     </p></li>
     <li class="itemize">If the righthand side of the IN operator is a single value, IN is turned into ==.
     </li>
     <li class="itemize">If the righthand side of the IN operator is a set of integer values with a min-max range of
     <!--l. 3634--><math 
 xmlns="http://www.w3.org/1998/Math/MathML"  
display="inline" > <mo 
class="MathClass-rel">&#x003C;</mo></math>=1024*1024,
     that set is turned into a boolean vector to get linear lookup time.</li></ul>
<!--l. 3638--><p class="indent" >   TaQL does not recognize common subexpressions nor does it attempt to optimize the query. It means
that the user can optimize a query by specifying the expression carefully. When using operator
<!--l. 3641--><math 
 xmlns="http://www.w3.org/1998/Math/MathML"  
display="inline" ><mo 
class="MathClass-rel">∣</mo><mo 
class="MathClass-rel">∣</mo></math> or &#x0026;&#x0026;,
attention should be paid to the contents of the left and right branches. Both operators evaluate the right
branch only if needed, so if possible the left branch should be the shortest one, i.e., the fastest to
evaluate.
</p><!--l. 3647--><p class="indent" >   The user should also use functions, operators, and subqueries in a careful way. </p>
     <ul class="itemize1">
     <li class="itemize"><span 
class="cmtt-10x-x-109">SQUARE(COL) </span>is (much) faster than <span 
class="cmtt-10x-x-109">COL</span><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">**</span></span></span><span 
class="cmtt-10x-x-109">2 </span>or <span 
class="cmtt-10x-x-109">POW(COL,2)</span>, because SQUARE is faster. It is also
     faster than <span 
class="cmtt-10x-x-109">COL*COL</span>, because it accesses column <span 
class="cmtt-10x-x-109">COL </span>only once. <br 
class="newline" />Similarly <span 
class="cmtt-10x-x-109">SQRT(COL) </span>is faster than <span 
class="cmtt-10x-x-109">COL</span><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">**</span></span></span><span 
class="cmtt-10x-x-109">0.5 </span>or <span 
class="cmtt-10x-x-109">POW(COL,0.5)</span>
     </li>
     <li class="itemize"><span 
class="cmtt-10x-x-109">SQUARE(U) + SQUARE(V) </span><!--l. 3659--><math 
 xmlns="http://www.w3.org/1998/Math/MathML"  
display="inline" > <mo 
class="MathClass-rel">&#x003C;</mo></math>
     <span 
class="cmtt-10x-x-109">1000</span><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109">**</span></span></span><span 
class="cmtt-10x-x-109">2 </span>is considerably faster than <br 
class="newline" /><span 
class="cmtt-10x-x-109">SQRT(SQUARE(U) + SQUARE(V)) </span><!--l. 3661--><math 
 xmlns="http://www.w3.org/1998/Math/MathML"  
display="inline" > <mo 
class="MathClass-rel">&#x003C;</mo></math>
     <span 
class="cmtt-10x-x-109">1000</span>, because the <span 
class="cmtt-10x-x-109">SQRT </span>function does not need to be evaluated for each row.
     </li>
     <li class="itemize"><span 
class="cmtt-10x-x-109">TIME IN [</span><!--l. 3665--><math 
 xmlns="http://www.w3.org/1998/Math/MathML"  
display="inline" ><mn>0</mn> <mo 
class="MathClass-rel">&#x003C;</mo><mo 
class="MathClass-punc">:</mo><mo 
class="MathClass-rel">&#x003C;</mo> <mn>4</mn></math><span 
class="cmtt-10x-x-109">]</span>
     is faster than <span 
class="cmtt-10x-x-109">TIME</span><!--l. 3666--><math 
 xmlns="http://www.w3.org/1998/Math/MathML"  
display="inline" > <mo 
class="MathClass-rel">&#x003E;</mo></math><span 
class="cmtt-10x-x-109">0</span>
     <span 
class="cmtt-10x-x-109">&#x0026;&#x0026; TIME</span><!--l. 3666--><math 
 xmlns="http://www.w3.org/1998/Math/MathML"  
display="inline" > <mo 
class="MathClass-rel">&#x003C;</mo></math><span 
class="cmtt-10x-x-109">4</span>,
     because in the ﬁrst way the column is accessed only once.
     </li>
     <li class="itemize">Returning a column from a subquery can be done directly or as a set. E.g.
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-122">
       SELECT FROM maintable WHERE time IN
      <br />      [SELECT time FROM othertable WHERE windspeed &#x003C; 5]
</div>
     <!--l. 3675--><p class="nopar" > could also be expressed as
                                                                                            
                                                                                            
</p>
     <div class="verbatim" id="verbatim-123">
       SELECT FROM maintable WHERE time IN
      <br />      [SELECT FROM othertable WHERE windspeed &#x003C; 5 GIVING [time]]
</div>
     <!--l. 3680--><p class="nopar" > The latter (as a set) is slower. So, if possible, the column should be returned directly. This is also easier
     to write. <br 
class="newline" />An even more important optimization for this query is writing it as:
                                                                                            
                                                                                            
</p>
     <div class="verbatim" id="verbatim-124">
       SELECT FROM maintable WHERE time IN
      <br />      [SELECT DISTINCT time FROM othertable WHERE windspeed &#x003C; 5]
</div>
     <!--l. 3687--><p class="nopar" > Using the DISTINCT qualiﬁer has the eﬀect that duplicates are removed which often results in a much
     smaller set.
     </p></li>
     <li class="itemize">Testing if a subquery contains at least N elements can be done in two ways:
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-125">
       count([select column from table where expression]) &#x003E;= N
      <br />and
      <br />  exists (select from table where expression limit N)
</div>
     <!--l. 3698--><p class="nopar" > The second form is by far the best, because in that case the subquery will stop the matching process as
     soon as N matching rows are found. The ﬁrst form will do the subquery for the entire table.
     <br 
class="newline" />Furthermore in the ﬁrst form a column has to be selected, which is not needed in the second
     form.
     </p></li>
     <li class="itemize">Sometimes operator <span 
class="cmtt-10x-x-109">IN </span>and function <span 
class="cmtt-10x-x-109">ANY </span>can be used to test if an element in an array matches a value.
     E.g.
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-126">
       WHERE any(arraycolumn == value)
      <br />and
      <br />  WHERE value IN arraycolumn
</div>
     <!--l. 3712--><p class="nopar" > give the same result. Operator <span 
class="cmtt-10x-x-109">IN </span>is faster because it stops when ﬁnding a match. If using <span 
class="cmtt-10x-x-109">ANY </span>all
     elements are compared ﬁrst and thereafter <span 
class="cmtt-10x-x-109">ANY </span>tests the resulting bool array.
     </p></li>
     <li class="itemize">It was already shown in the <a 
href="#x1-470004.8">section 4.8</a> that indexing arrays should be done with care.</li></ul>
<!--l. 3725--><p class="noindent" >
</p>
   <h3 class="sectionHead"><span class="titlemark">7   </span> <a 
 id="x1-850007"></a>Modifying a table</h3>
<!--l. 3726--><p class="noindent" >Usually TaQL will be used to get a subset from a table. However, as described in the ﬁrst sections, it
can also be used to change the contents of a table using the UPDATE, INSERT, or DELETE
command. Note that a table has to be writable, otherwise those commands exit with an error
message.
</p><!--l. 3732--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">7.1   </span> <a 
 id="x1-860007.1"></a>UPDATE</h4>
                                                                                            
                                                                                            
   <div class="verbatim" id="verbatim-127">
  UPDATE table SET update_list [FROM table_list]
 <br />                               [WHERE ...] [ORDERBY ...]
 <br />                               [LIMIT ...] [OFFSET ...]
</div>
<!--l. 3737--><p class="nopar" > updates all or some rows in the ﬁrst table. More input tables can be given in the FROM clause and used in
clauses like SET and WHERE. Unlike SQL it is possible to specify more tables in the UPDATE part which is
the same as specifying them in the FROM clause. However, using the FROM clause makes it more clear that
only the ﬁrst table is updated. <br 
class="newline" /><span 
class="cmtt-10x-x-109">update</span><span 
class="cmtt-10x-x-109">_list </span>is a comma-separated list of <span 
class="cmtt-10x-x-109">column=expression </span>parts. Each part tells to update the given
column using the expression. Both scalar and array columns are supported. E.g.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-128">
  UPDATE vla.ms SET ANTENNA1=ANTENNA1-1, ANTENNA2=ANTENNA2-1
</div>
<!--l. 3751--><p class="nopar" > to make the antenna numbers zero-based if accidently they were written one-based.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-129">
  UPDATE this.ms set DATA=t2.DATA, FLAG=t2.FLAG
 <br />             FROM that.ms t2 where all(FLAG)
 <br />  UPDATE this.ms, that.ms t2 set DATA=t2.DATA, FLAG=t2.FLAG
 <br />                             where all(FLAG)
</div>
<!--l. 3760--><p class="nopar" > are equivalent. They copy the DATA and FLAG column of that.ms to this.ms for rows where all data in
this.ms are ﬂagged. Note the use of the shorthand (alias) <span 
class="cmtt-10x-x-109">t2</span>.
</p><!--l. 3764--><p class="indent" >   If an array gets an array value, the shape of the array can be changed (provided it is allowed for that
table column). Arrays can also be updated with a scalar value causing all elements in the array to be set to
that scalar value.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-130">
  UPDATE vla.ms SET FLAG=F
</div>
<!--l. 3770--><p class="nopar" > It sets all elements of the arrays in column FLAG to False.
</p><!--l. 3773--><p class="indent" >   Type promotion and demotion will be done where possible. For example, an integer column can get the
value of a double expression (the result will be truncated). <br 
class="newline" />Unit conversion will be done as needed. Thus if a column and its expression have diﬀerent units, the
expression result is automatically converted to the column&#x2019;s unit. Of course, the units must be of the same
type to be able to convert the data.
</p><!--l. 3781--><p class="indent" >   Note that if multiple <span 
class="cmtt-10x-x-109">column=expression </span>parts are given, the columns are changed in the order as
speciﬁed in the update-list. It means that if an updated column is used in an expression for a later column,
the new value is used when evaluating the expression. e.g., in
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-131">
  UPDATE vla.ms SET DATA=DATA+1, SUMD=sum(DATA)
</div>
<!--l. 3788--><p class="nopar" > the <span 
class="cmtt-10x-x-109">SUMD </span>update uses the new <span 
class="cmtt-10x-x-109">DATA </span>values.
</p><!--l. 3791--><p class="indent" >   Thus to swap the values of the ANTENNA1 and ANTENNA2 column, one can <span 
class="cmbx-10x-x-109">not </span>do:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-132">
  UPDATE vla.ms SET ANTENNA1=ANTENNA2, ANTENNA2=ANTENNA1
</div>
<!--l. 3795--><p class="nopar" > To solve this problem a temporary table (in this case in memory) can be used to save the value of e.g.,
ANTENNA1:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-133">
  UPDATE my.ms
 <br />      set ANTENNA1 = ANTENNA2, ANTENNA2 = orig.ANTENNA1
 <br />      FROM [select ANTENNA1 from my.ms giving as memory] orig
</div>
<!--l. 3802--><p class="nopar" >
</p><!--l. 3804--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">7.1.1   </span> <a 
 id="x1-870007.1.1"></a>Partial Array Update</h5>
<!--l. 3805--><p class="noindent" >It is possible to update part of an array using <a 
href="#x1-470004.8">array indexing and slicing</a>. E.g.,
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-134">
  UPDATE vla.ms SET FLAG[1,1]=T
 <br />  UPDATE vla.ms SET FLAG[1,]=T
</div>
<!--l. 3810--><p class="nopar" > The ﬁrst example sets only a single array element, while the second one sets an entire row in the array.
Similar to numpy it is also possible to use a mask like
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-135">
  UPDATE vla.ms SET FLAG[isnan(DATA)]=T
</div>
<!--l. 3816--><p class="nopar" > which sets the ﬂag for the DATA values being a NaN. The data and mask must have the same shape. Note
this is easier to write than the similar command
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-136">
  UPDATE vla.ms SET FLAG = iif(isnan(DATA), T, FLAG)
</div>
<!--l. 3822--><p class="nopar" > Masking and slicing can be combined making it possible to use masking on a part of an array. If the mask is
given ﬁrst, the slice is taken from both the data and mask. If the slice is given ﬁrst, it is only applied to the
data; the mask should have the same shape as the slice. For example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-137">
  UPDATE vla.ms SET FLAG[isnan(DATA)][,0]=T
 <br />  UPDATE vla.ms SET FLAG[,0][isnan(DATA[,0])]=T
</div>
<!--l. 3831--><p class="nopar" > Both commands set the ﬂag for NaN data in the XX polarization. The ﬁrst one is somewhat easier to write,
but processes the entire DATA and FLAG before taking the slice. The second one only reads and processes
the required parts of DATA and FLAG, thus is more eﬃcient.
</p><!--l. 3838--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">7.1.2   </span> <a 
 id="x1-880007.1.2"></a>Update columns from a masked array</h5>
<!--l. 3839--><p class="noindent" >If a column is updated with the value of a masked array, only the array part of the masked array is used.
However, it is also possible to jointly update the data column and mask column from a masked array by
combining them in parentheses like:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-138">
  UPDATE vla.ms SET (DATA,FLAG)=maskedarray
</div>
<!--l. 3845--><p class="nopar" > It writes the data part into DATA and the mask into FLAG. As above it is possible to use a slice or mask
operator on the combination like:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-139">
  UPDATE vla.ms SET (DATA,FLAG)[,0]=maskedarray
 <br />  UPDATE vla.ms SET (DATA,FLAG)[isnan(DATA)]=maskedarray
</div>
<!--l. 3851--><p class="nopar" > The slice or mask is applied to both columns.
</p><!--l. 3855--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">7.2   </span> <a 
 id="x1-890007.2"></a>INSERT</h4>
<!--l. 3856--><p class="noindent" >The <span 
class="cmtt-10x-x-109">INSERT </span>command adds rows to the table. It can take three forms:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-140">
  INSERT INTO table_list SET column=expr, column=expr, ...
 <br />  INSERT INTO table_list [(column_list)] VALUES (exprlist),(exprlist), ...
 <br />  INSERT INTO table_list [(column_list)] SELECT_command
</div>
<!--l. 3861--><p class="nopar" > The ﬁrst and second form are basically equivalent, but diﬀer in syntax. The ﬁrst form has the same syntax
as the UPDATE command, while the second form is the SQL syntax making it possible to leave out the
column names (see below). In both forms it is possible to jointly specify data column and mask column if the
value is a masked array. This is done by combining them in parentheses like <span 
class="cmtt-10x-x-109">(DATA,FLAG) </span>as described in the
previous subsection for the UPDATE command.
</p><!--l. 3871--><p class="indent" >   The ﬁrst form adds one row to the table and puts the values given in the expressions into the columns.
<br 
class="newline" />For example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-141">
  INSERT INTO my.ms SET ANTENNA1=0, ANTENNA2=1
</div>
<!--l. 3876--><p class="nopar" > adds one row, puts 0 in ANTENNA1 and 1 in ANTENNA2.
</p>
<!--l. 3879--><p class="noindent" ><span class="likeparagraphHead"><a 
 id="x1-900007.2"></a></span>
   The second form can add multiple rows to the table. It puts the values given in the expression lists into
the columns given in the column list. If the column list is not given, it defaults to all stored columns in the
table in the order as they appear in the table description. Multiple expression lists can be given; each list
results in the addition of a row. Each expression in the expression list can be as complex as needed; for
example, a subquery can also be given. Note that a subquery is evaluated before the new row is added,
so the new row is not taken into account if the subquery is done on the table being modiﬁed.
<br 
class="newline" />It should be clear that the number of columns has to match the number of expressions. <br 
class="newline" />Note that row cells not mentioned in the column list, are not written, thus may contain rubbish in the new
rows. <br 
class="newline" />The data types and units of expressions and columns have to conform in the same way as for the UPDATE
command; values have to be convertible to the column data type and unit. <br 
class="newline" />For example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-142">
  INSERT INTO my.ms (ANTENNA1,ANTENNA2) VALUES (0,1),(2,3)
</div>
<!--l. 3901--><p class="nopar" > adds two rows, putting 0 and 2 in ANTENNA1 and 1 and 3 in ANTENNA2.
</p><!--l. 3904--><p class="indent" >   The LIMIT clause can be used to add multiple rows while giving fewer expressions. LIMIT can be given
at the beginning or the end of the command. For example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-143">
  INSERT INTO my.ms (COL1) VALUES (rowid()) LIMIT 100
 <br />  INSERT LIMIT 5 INTO my.ms (COL1,COL2) VALUES (0,0),(1,1)
</div>
<!--l. 3910--><p class="nopar" > The ﬁrst example will add 100 rows where the value in each row is the row number. The second example
shows that multiple expression lists can be given. It will iterate through them while adding rows. Thus COL1
and COL2 will have the values 0, 1, 0, 1, and 0 in the new rows.
</p>
<!--l. 3916--><p class="noindent" ><span class="likeparagraphHead"><a 
 id="x1-910007.2"></a></span>
   The third form evaluates the SELECT command and copies the rows found in the selection to the table
being modiﬁed (which is given in the INTO part). The columns used in the modiﬁed table are deﬁned in the
column list. As above, they default to all stored columns. The columns used in the selection have to be
deﬁned in the column-list part of the SELECT command. They also default to all stored columns.
<br 
class="newline" />For example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-144">
  INSERT INTO my.ms select FROM my.ms
</div>
<!--l. 3927--><p class="nopar" > appends all rows and columns of <span 
class="cmtt-10x-x-109">my.ms </span>to itself. Please note that only the original number of rows is
copied.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-145">
  INSERT INTO my.ms (ANTENNA1,ANTENNA2) select ANTENNA2,ANTENNA1
 <br />   FROM other.ms WHERE ANTENNA1&#x003E;0
</div>
<!--l. 3933--><p class="nopar" > copies rows from <span 
class="cmtt-10x-x-109">other.ms </span>where ANTENNA1<!--l. 3934--><math 
 xmlns="http://www.w3.org/1998/Math/MathML"  
display="inline" > <mo 
class="MathClass-rel">&#x003E;</mo></math>0.
It swaps the values of ANTENNA1 and ANTENNA2. All other columns are not written, thus may contain
rubbish.
</p><!--l. 3938--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">7.3   </span> <a 
 id="x1-920007.3"></a>DELETE</h4>
                                                                                            
                                                                                            
   <div class="verbatim" id="verbatim-146">
  DELETE FROM table_list
 <br />    [WHERE ...] [ORDERBY ...] [LIMIT ...] [OFFSET ...]
</div>
<!--l. 3942--><p class="nopar" > deletes some or all rows from a table.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-147">
  DELETE FROM my.ms WHERE ANTENNA1&#x003E;13 OR ANTENNA2&#x003E;13
</div>
<!--l. 3946--><p class="nopar" > deletes the rows matching the WHERE expression. <br 
class="newline" />If no selection is done, all rows will be deleted. <br 
class="newline" />It is possible to specify more than one table in the FROM clause to be able to use, for example,
keywords from other tables. Rows will be deleted from the ﬁrst table mentioned in the FROM
part.
</p><!--l. 3953--><p class="noindent" >
</p>
   <h3 class="sectionHead"><span class="titlemark">8   </span> <a 
 id="x1-930008"></a>Creating a new table</h3>
<!--l. 3954--><p class="noindent" >TaQL can be used to create a new table. The data managers to be used can be given in full detail. The
syntax is:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-148">
  CREATE TABLE tablename AS options colspecs LIMIT nrows DMINFO datamanagers
</div>
<!--l. 3959--><p class="nopar" > The command consists of 4 parts, all of them optional. </p>
     <ul class="itemize1">
     <li class="itemize">The table name and options can be given in the same way as in the <a 
href="#x1-180003.3">GIVING</a> clause.
     </li>
     <li class="itemize">The columns are deﬁned in the <span 
class="cmtt-10x-x-109">colspecs </span>part. If not given, a table without any column is
     created. Below column speciﬁcation is described in more detail.
     </li>
     <li class="itemize">An expression giving the number of rows can be speciﬁed in the LIMIT part. If not given, it
     defaults to 0.
     </li>
     <li class="itemize">For expert users data managers can be deﬁned in the optional DMINFO part described further
     down.</li></ul>
<!--l. 3973--><p class="indent" >   The CREATE TABLE command can be used in a nested query making it possible to ﬁll it immediately.
For example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-149">
  update [create table a.tab col1 int limit 10] set col1=rowid()
</div>
<!--l. 3977--><p class="nopar" > creates a table with one column and ten rows. The column is ﬁlled with the row number. Note that the
following command would do the same.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-150">
  select rowid() as col1 int limit 10 giving a.tab
</div>
<!--l. 3982--><p class="nopar" >
</p><!--l. 3984--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">8.1   </span> <a 
 id="x1-940008.1"></a>Column speciﬁcation</h4>
<!--l. 3985--><p class="noindent" >The <span 
class="cmtt-10x-x-109">colspecs </span>part deﬁnes the column names, their data types, and optional shapes and units. It can
optionally be enclosed in square brackets or parentheses (for SQL compatibility). It is a comma separated list
of column speciﬁcations. Each speciﬁcation looks like:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-151">
  columnname datatype [NDIM=n, SHAPE=[d1,d2,...], UNIT=&#x2019;s&#x2019;,
 <br />                       DMTYPE=&#x2019;s&#x2019;, DMGROUP=&#x2019;s&#x2019;, COMMENT=&#x2019;s&#x2019;]
</div>
<!--l. 3993--><p class="nopar" > The possible data type strings are given in <a 
href="#x1-290004.1">section 4.1</a>. The part enclosed in square brackets is optional. Zero
or more of these keywords can be used. It makes it possible to deﬁne array columns and/or default
data manager to be used. The square brackets are optional if only one such keyword is used.
</p>
     <ul class="itemize1">
     <li class="itemize"><span 
class="cmtt-10x-x-109">NDIM=n </span>deﬁnes if the column contains scalars or arrays. <br 
class="newline" />A negative value means a scalar, which is the default (unless shape is also given). A value 0 means
     an array of any dimensionality. A positive value means an array with the given dimensionality.
     </li>
     <li class="itemize"><span 
class="cmtt-10x-x-109">SHAPE=[d1,d2,...] </span>makes it possible to deﬁne the exact array shape. <br 
class="newline" />If given and if NDIM is positive, they should be consistent.
     </li>
     <li class="itemize"><span 
class="cmtt-10x-x-109">UNIT=&#x2019;s&#x2019; </span>deﬁnes the unit to be used for the column. <br 
class="newline" />It can be any valid unit (simple or compound). It is a string, thus must always be enclosed in
     quotes.
     </li>
     <li class="itemize"><span 
class="cmtt-10x-x-109">COMMENT </span>deﬁnes comments for the column. <br 
class="newline" />It has a string value, thus quotes have to be used.
     </li>
     <li class="itemize"><span 
class="cmtt-10x-x-109">DMTYPE, DMGROUP </span>are rather speciﬁc and are for the expert user. <br 
class="newline" />They have a string value, thus quotes have to be used.</li></ul>
<!--l. 4019--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">8.2   </span> <a 
 id="x1-950008.2"></a>Data manager speciﬁcation</h4>
<!--l. 4020--><p class="noindent" >The <span 
class="cmtt-10x-x-109">datamanagers </span>part makes it possible for the expert user to deﬁne the data managers to be used by
columns. It is a comma separated list of data manager speciﬁcations looking like the output of the
<span 
class="cmtt-10x-x-109">table.getdminfo </span>command in Python. Each speciﬁcation has to be enclosed in square brackets. For
example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-152">
  dminfo [NAME=&#x0022;ISM1&#x0022;,TYPE=&#x0022;IncrementalStMan&#x0022;,COLUMNS=[&#x0022;col1&#x0022;]],
 <br />         [NAME=&#x0022;SSM1&#x0022;,TYPE=&#x0022;StandardStMan&#x0022;,
 <br />          SPEC=[BUCKETSIZE=1000],COLUMNS=[&#x0022;col2&#x0022;,&#x0022;col3&#x0022;]]
</div>
<!--l. 4030--><p class="nopar" > The case of the keyword names used (e.g., NAME) is important. They have to be given in uppercase. The
following keywords can be given: <br 
class="newline" /><span 
class="cmtt-10x-x-109">NAME </span>deﬁnes the unique name of the data manager. <br 
class="newline" /><span 
class="cmtt-10x-x-109">TYPE </span>deﬁnes the type of data manager. <br 
class="newline" /><span 
class="cmtt-10x-x-109">SPEC </span>is a list of keywords giving the characteristics of the data manager. This is highly data manager type
speciﬁc. If shapes have to be given here, they always have to be in Casacore format, thus in Fortran order.
TaQL has no knowledge about these internals. <br 
class="newline" /><span 
class="cmtt-10x-x-109">COLUMNS </span>is a list of column names deﬁning all columns that have to be bound to the data manager.
</p><!--l. 4044--><p class="noindent" >
</p>
   <h3 class="sectionHead"><span class="titlemark">9   </span> <a 
 id="x1-960009"></a>Modifying the table structure</h3>
<!--l. 4045--><p class="noindent" >TaQL can be used to modify the table structure, i.e., to add, rename, and remove columns and keywords. It
is also possible to add rows. The syntax is:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-153">
  ALTER TABLE tablename FROM table_list subcommand_list
</div>
<!--l. 4050--><p class="nopar" > It changes the table with the given name. The tables given in the optional <a 
href="#x1-190003.4">FROM clause</a> can be used in
expressions deﬁning keyword values. Any number of subcommands can be given, separated by
whitespace and/or comma. The following subcommands can be given. They are explained in the next
subsections.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-154">
  ADD COLUMN colspecs DMINFO datamanagers
 <br />  RENAME COLUMN old TO new, old TO new, ...
 <br />  DELETE COLUMN column_list
 <br />  SET KEYWORD name=value AS dtype, ...
 <br />  COPY KEYWORD name=name AS dtype, ...
 <br />  RENAME KEYWORD old TO new, old TO new
 <br />  DELETE KEYWORD keyword_list
 <br />  ADD ROW nrows
</div>
<!--l. 4067--><p class="nopar" > The nouns COLUMN and KEYWORD can also be given in the plural form. The whitespace
between verb and noun is optional. For SQL-compatibility DROP can be used instead of DELETE.
<br 
class="newline" />For example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-155">
  ALTER TABLE my.tab RENAME COLUMN Col1 to Col1A, ADDCOLUMNS Col1 I4
</div>
<!--l. 4074--><p class="nopar" > renames column Col1 to Col1A and adds a new column Col1 with data type I4.
</p><!--l. 4077--><p class="indent" >   Note that TaQL has no way of showing keywords that have a record value. The program <span 
class="cmti-10x-x-109">showtable </span>can be
used for that purpose.
</p><!--l. 4080--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">9.1   </span> <a 
 id="x1-970009.1"></a>ADD COLUMN</h4>
                                                                                            
                                                                                            
   <div class="verbatim" id="verbatim-156">
  ADD COLUMN colspec DMINFO datamanagers
</div>
<!--l. 4083--><p class="nopar" > adds one or more columns to the table. The speciﬁcation of the columns and the optional data managers is
the same as used in the <a 
href="#x1-930008">CREATE TABLE</a> command. Thus for each column a data type, dimensionality or
shape, and unit can be given. The data manager(s) for the new columns can be speciﬁed in the DMINFO
part. If not given, StandardStMan will be used. For example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-157">
  ADD COLUMN NCol1 R4, NCol2 R8 [UNIT=&#x0022;m&#x0022;, NDIM=3]
</div>
<!--l. 4094--><p class="nopar" > adds two columns, a 4-byte ﬂoating point scalar column and an 8-byte ﬂoating point 3-dim array column.
They will be stored with StandardStMan.
</p><!--l. 4098--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">9.2   </span> <a 
 id="x1-980009.2"></a>RENAME COLUMN</h4>
                                                                                            
                                                                                            
   <div class="verbatim" id="verbatim-158">
  RENAME COLUMN old1 TO new1, old2 TO new2, etc.
</div>
<!--l. 4101--><p class="nopar" > renames one or more columns in a table. For example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-159">
  RENAME COLUMN NAME to NAME_SAV, ADDR to ADDR_SAV
</div>
<!--l. 4106--><p class="nopar" >
</p><!--l. 4108--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">9.3   </span> <a 
 id="x1-990009.3"></a>DELETE COLUMN</h4>
                                                                                            
                                                                                            
   <div class="verbatim" id="verbatim-160">
  DELETE COLUMN col1, col2, etc.
</div>
<!--l. 4111--><p class="nopar" > removes one or more columns. Note that if multiple columns are combined in a TiledStMan, they have to be
removed at the same time. Thus in that case
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-161">
  DELETE COLUMN col1, col2
 <br />  DELETE COLUMN col1, DELETE COLUMN col2
</div>
<!--l. 4118--><p class="nopar" > are not the same, because the second example might fail.
</p><!--l. 4121--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">9.4   </span> <a 
 id="x1-1000009.4"></a>SET KEYWORD</h4>
                                                                                            
                                                                                            
   <div class="verbatim" id="verbatim-162">
  SET KEYWORD key1=value1 AS dtype, etc.
</div>
<!--l. 4124--><p class="nopar" > adds a keyword with the given value or replaces the value if the keyword already exists. The value of a
keyword can be a scalar, array, or arbitrarily deeply nested record. See <a 
href="#x1-440004.5">section 4.5</a> how to specify a keyword
name in a column or nested record. The <span 
class="cmtt-10x-x-109">AS dtype </span>part can be used to explicitly set the data type of a new
keyword. For an existing keyword, the data type of the new value has to match the data type of the current
value.
</p><!--l. 4135--><p class="indent" >   The value can be an expression, possibly using values from another table given in the FROM clause. It
has to be a constant expression, thus cannot depend on column values. Of course, column values can be used
when aggregated to a single value. If no data type is given, the data type of the expression result is used. If
given, upward and downward coercion is possible (e.g., integer to ﬂoat and also ﬂoat to integer). For
example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-163">
  SET KEYWORD key1=4
 <br />  SET KEYWORD ::key1=4+5 AS U4
 <br />  SET KEYWORD key1 = otherkey as I4
 <br />  SET KEYWORD col::ckey.subrec.fld1 = [4,5,6.]
 <br />  SET KEYWORD col::ckey=[=], col::ckey.subrec=[=]
 <br />  SET KEWYORD key=[] AS I4
</div>
<!--l. 4149--><p class="nopar" > The 1st example sets table keyword <span 
class="cmti-10x-x-109">key1 </span>to 4. Its data type is not given, thus is the expression&#x2019;s data type,
in this case I8. <br 
class="newline" />The 2nd example sets <span 
class="cmti-10x-x-109">key1 </span>to 9, but as an unsigned 4 byte integer. Note that the <span 
class="cmtt-10x-x-109">:: </span>part is redundant.
<br 
class="newline" />The 3rd example copies the value of keyword <span 
class="cmti-10x-x-109">otherkey </span>while converting its data type to I4. Note that if no
data type is given, the data type of <span 
class="cmti-10x-x-109">otherkey </span>is NOT preserved, because it is seen as a TaQL expression which
has data type I8 (or R8). <br 
class="newline" />The 4th example sets the <span 
class="cmti-10x-x-109">ckey.subrec.ﬂd1 </span>in column <span 
class="cmti-10x-x-109">col </span>to the given vector. It is a nested structure, thus ﬁeld
<span 
class="cmti-10x-x-109">ﬂd1 </span>in ﬁeld <span 
class="cmti-10x-x-109">subrec </span>of column keyword <span 
class="cmti-10x-x-109">ckey </span>will be set. Its data type will be R8. <br 
class="newline" />Note that the command in the 4th example does not create the higher level records. If not existing yet, the
5th example can be used to create them, where [=] denotes an empty record (it is the old Glish syntax for an
empty struct). <br 
class="newline" />The last example shows how to create a key with an empty integer vector as value. In such a case the data
type must be given, because it cannot be derived from the value.
</p>
<!--l. 4170--><p class="noindent" ><span class="likeparagraphHead"><a 
 id="x1-1010009.4"></a></span>
   Setting a keyword to the value of another keyword is easily possible. For instance:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-164">
  SET KEYWORD key2 = otherkey
</div>
<!--l. 4175--><p class="nopar" > However, it has two problems. <br 
class="newline" />1) As explained above the data type might not be preserved. <br 
class="newline" />2) Keywords having a record value cannot be copied this way, because TaQL expressions do not support
record values.
</p><!--l. 4181--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">9.5   </span> <a 
 id="x1-1020009.5"></a>COPY KEYWORD</h4>
                                                                                            
                                                                                            
   <div class="verbatim" id="verbatim-165">
  COPY KEYWORD key = otherkey AS dtype, etc.
</div>
<!--l. 4184--><p class="nopar" > copies the value of keyword <span 
class="cmti-10x-x-109">otherkey </span>to <span 
class="cmti-10x-x-109">key</span>. It can be used for any keyword value, thus also for records. The
optional <span 
class="cmtt-10x-x-109">AS dtype </span>part can be used to change the data type.
</p><!--l. 4190--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">9.6   </span> <a 
 id="x1-1030009.6"></a>RENAME KEYWORD</h4>
                                                                                            
                                                                                            
   <div class="verbatim" id="verbatim-166">
  RENAME KEYWORD old1 TO new1, old2 TO new2, etc.
</div>
<!--l. 4193--><p class="nopar" > renames one or more table or column keywords. If the old keyword is a ﬁeld in a column or a nested
record, the new name should only contain the new ﬁeld name, not the full keyword path. For
example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-167">
  RENAME KEYWORD NAME to NAME_SAV, Col1::CNAME to CNAME_SAV
 <br />  RENAME KEYWORD KEYS.SET.NAME to NAME_SAV
</div>
<!--l. 4201--><p class="nopar" > The ﬁrst example renames the table keyword NAME and the keyword CNAME of column Col1.
<br 
class="newline" />The second example renames a ﬁeld in the nested records of table keyword KEYS.
</p><!--l. 4207--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">9.7   </span> <a 
 id="x1-1040009.7"></a>DELETE KEYWORD</h4>
                                                                                            
                                                                                            
   <div class="verbatim" id="verbatim-168">
  DELETE KEYWORD key1, key2, ...
</div>
<!--l. 4210--><p class="nopar" > removes one or more table or column keywords.
</p><!--l. 4213--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">9.8   </span> <a 
 id="x1-1050009.8"></a>ADD ROW</h4>
<!--l. 4214--><p class="noindent" >adds the given number of rows to the table.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-169">
  ADD ROW nrows
</div>
<!--l. 4217--><p class="nopar" > where <span 
class="cmti-10x-x-109">nrows </span>can be any expression. For example,
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-170">
 ALTER TABLE mytab ADD ROW [SELECT GCOUNT() from othertab]
</div>
<!--l. 4222--><p class="nopar" > makes <span 
class="cmti-10x-x-109">mytab </span>the same size as <span 
class="cmti-10x-x-109">othertab </span>(assuming it was empty).
</p><!--l. 4226--><p class="noindent" >
</p>
   <h3 class="sectionHead"><span class="titlemark">10   </span> <a 
 id="x1-10600010"></a>Counting in a table</h3>
<!--l. 4227--><p class="noindent" >Before TaQL had the GROUPBY command, the COUNT command could be used instead of the <a 
href="#x1-620004.10.13"><span 
class="cmtt-10x-x-109">gcount</span>
aggregate function</a> to count the number of occurrences in a table. <br 
class="newline" />For backward compatibility this command can still be used, but its usage is discouraged, also because usually
GROUPBY is faster.
</p><!--l. 4233--><p class="indent" >   The exact syntax is:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-171">
  COUNT column-list FROM table-list [WHERE expression]
</div>
<!--l. 4236--><p class="nopar" > It counts the number of rows for each unique tuple in the column list of the table (after the possible
WHERE selection is done). For example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-172">
  COUNT TIME FROM my.ms
</div>
<!--l. 4242--><p class="nopar" > counts the number of rows per timestamp.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-173">
  COUNT ANTENNA1,ANTENNA2 FROM my.ms
</div>
<!--l. 4246--><p class="nopar" > counts the number of rows per baseline.
</p><!--l. 4249--><p class="indent" >   As in the other TaQL commands a column in the column list can be any expression, but that will be
slower than straight columns.
</p><!--l. 4252--><p class="noindent" >
</p>
   <h3 class="sectionHead"><span class="titlemark">11   </span> <a 
 id="x1-10700011"></a>Calculations on a table</h3>
<!--l. 4253--><p class="noindent" >TaQL can be used to get derived values from a table by means of an expression. The expression can
result in any data type and value type. For example, if the expression uses an array column, the
result might be a vector of arrays (an array for each row). If the expression uses a scalar column,
the result might be a vector of scalars or even a single scalar if a reduce function like SUM is
used.
</p><!--l. 4260--><p class="indent" >   The CALC command was developed before the GROUPBY was available and before SELECT could be
used without the FROM part. Currently, SELECT is more powerful than the CALC command. For example,
multiple expressions can be given in a SELECT command. However, especially in Python sessions CALC
has the advantage that it returns the results as a numpy-array or a list instead of a Casacore
table.
</p><!--l. 4267--><p class="indent" >   The exact syntax is:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-174">
  CALC expression [FROM table_list]
</div>
<!--l. 4270--><p class="nopar" > The part in square brackets can be omitted if no column is (directly) used in the expression. The examples
will make clear what that means. <br 
class="newline" />The following syntax is still available for backward compatibility:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-175">
  CALC FROM table_list CALC expression
</div>
<!--l. 4276--><p class="nopar" >
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-176">
  CALC 1in cm
</div>
<!--l. 4280--><p class="nopar" > is a simple expression not using a table. It shows how the CALC command can be used as a desk calculator
to convert 1 inch to cm.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-177">
  CALC mean(column1+column2) FROM mytable
</div>
<!--l. 4286--><p class="nopar" > gives a vector of scalars containing the mean per row.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-178">
  CALC sum([SELECT FROM mytable GIVING [mean(column1+column2)]])
</div>
<!--l. 4291--><p class="nopar" > gives a single scalar giving the sum of the means in each row. Note that in this command the CALC
command does not need the FROM clause, because it does not use a column itself. Columns are only used in
the nested query which has a FROM clause itself.
</p><!--l. 4297--><p class="noindent" >
</p>
   <h3 class="sectionHead"><span class="titlemark">12   </span> <a 
 id="x1-10800012"></a>Examples</h3>
<!--l. 4298--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">12.1   </span> <a 
 id="x1-10900012.1"></a>Selection examples</h4>
<!--l. 4299--><p class="noindent" >Some examples are given starting with simple ones.
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">12.1.1   </span> <a 
 id="x1-11000012.1.1"></a>Reference table results</h5>
<!--l. 4301--><p class="noindent" >The result of the following queries is a reference table, because no expressions have been given in the
column-list. This will be the most common case when using TaQL.
     </p><dl class="description"><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">SELECT FROM some.ms WHERE ANTENNA1 != ANTENNA2  </span><br 
class="newline" />selects the cross-correlations in a MeasurementSet.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">SELECT NAME FROM some.ms::ANTENNA  </span><br 
class="newline" />selects the NAME of all antennae in a MeasurementSet.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">SELECT unique ANTENNA1,ANTENNA2 FROM some.ms  </span><br 
class="newline" />gives the baselines used in a MeasurementSet.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">SELECT ANTENNA1,ANTENNA2 FROM some.ms GROUPBY ANTENNA1,ANTENNA2 </span><br 
class="newline" />does the same using the GROUPBY clause.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">SELECT FROM mytable ORDERBY column0 DESC limit 10  </span><br 
class="newline" />selects the 10 highest values of <span 
class="cmtt-10x-x-109">column0</span>.
                                                                                            
                                                                                            
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">SELECT FROM some.MS WHERE near(MJD(1999/03/30/17:27:15), TIME)  </span><br 
class="newline" />selects the rows with the given time from a MeasurementSet. <br 
class="newline" />Note that the TIME is stored in seconds, but will automatically be converted to days.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">SELECT FROM some.MS where TIME in  </span><br 
class="newline" /><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span></span></span>  <span 
class="cmtt-10x-x-109">[</span><span 
class="cmsy-10x-x-109">{</span><span 
class="cmtt-10x-x-109">MJD(1999/03/30/17:27:15),MJD(1999/03/30/17:29:15)</span><span 
class="cmsy-10x-x-109">}</span><span 
class="cmtt-10x-x-109">]  </span><br 
class="newline" />selects the rows in the given closed time interval.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">SELECT FROM some.MS where TIME in  </span><br 
class="newline" /><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span></span></span>  <span 
class="cmtt-10x-x-109">[MJD(1999/03/30/17:27:15),MJD(1999/03/30/17:29:15)]  </span><br 
class="newline" />selects the rows having one of the given times. <br 
class="newline" />Note the diﬀerence with the previous example where an interval was given. Here a set of two
     individual time values is given.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">SELECT NAME FROM some.ms::ANTENNA WHERE NAME !</span><span 
class="cmtt-10x-x-109"> p/[CR]S*/ </span><br 
class="newline" />selects the names of the international LOFAR stations (not core or remote).
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">SELECT FROM some.ms WHERE ntrue(FLAG) &#x003E;= 3 </span><br 
class="newline" />selects rows where at least 3 visibilities are ﬂagged.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">SELECT FROM book.table WHERE nelements(author) &#x003E; 1 </span><br 
class="newline" />selects books with more than 1 author.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">SELECT FROM some.ms WHERE any(ANTENNA1==[0,0,1] &#x0026;&#x0026; ANTENNA2==[1,3,2]) </span><br 
class="newline" />selects the antenna pairs (baselines) 0-1, 0-3, and 1-2. <br 
class="newline" />It requires some explanation. The two comparisons result in boolean vectors (with 3 elements).
     It matching elements are both true, the baseline in the table row matches. Thus the vectors are
     and-ed to see if any two matching elements are true.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">SELECT FROM some.ms WHERE ANTENNA1 in [0,0,1] &#x0026;&#x0026; ANTENNA2 in [1,3,2]) </span><br 
class="newline" />looks the same as above, but will select all baselines between the two sets, thus also 1-1, 1-3,
     and 0-2.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">SELECT FROM some.ms t1, that.ms t2 WHERE !all(near(t1.DATA, t2.DATA, 1e-5)) </span><br 
class="newline" />selects all rows where the DATA columns in both tables are not equal (with some tolerance).
     Note the use of shorthands t1 and t2.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">SELECT FROM mytable WHERE cos(0d1m) &#x003C;= </span><br 
class="newline" /><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span></span></span> <span 
class="cmtt-10x-x-109">sin(52deg) * sin(DEC) + cos(52deg) * cos(DEC) * cos(3h30m - RA)  </span><br 
class="newline" />selects observations with an direction (in say J2000) inside a cone with a radius of 1 arcmin
     around (3h30m, 52deg). To ﬁnd them the condition DISTANCE<!--l. 4371--><math 
 xmlns="http://www.w3.org/1998/Math/MathML"  
display="inline" > <mo 
class="MathClass-rel">&#x003C;</mo><mo 
class="MathClass-rel">=</mo></math>RADIUS
     must be fulﬁlled, which is equivalent to COS(RADIUS)<!--l. 4372--><math 
 xmlns="http://www.w3.org/1998/Math/MathML"  
display="inline" > <mo 
class="MathClass-rel">&#x003C;</mo><mo 
class="MathClass-rel">=</mo></math>COS(DISTANCE).
                                                                                            
                                                                                            
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">SELECT FROM mytable WHERE [RA,DEC] INCONE [3h30m, 52deg, 0d1m]  </span><br 
class="newline" />does the same as above in an easier (and faster) way.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">SELECT FROM mytable WHERE angdist([RA,DEC], [3h30m, 52deg]) &#x003C;= 0d1m]  </span><br 
class="newline" />is another way to do the above.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">SELECT FROM mytable WHERE object == pattern(&#x0022;3C*&#x0022;) &#x0026;&#x0026; </span><br 
class="newline" /><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span></span></span>  <span 
class="cmtt-10x-x-109">[RA,DEC] INCONE [3h30m, 52deg, 0d1m]  </span><br 
class="newline" />ﬁnds all 3C objects inside that cone.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">SELECT ANTENNA1,ANTENNA2,sqrt(sumsqr(UVW[:2])) </span><br 
class="newline" /><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span></span></span>  <span 
class="cmtt-10x-x-109">FROM some.ms GROUPBY ANTENNA1,ANTENNA2  </span><br 
class="newline" />ﬁnds the 10 longest baselines. It groups by ANTENNA1 and ANTENNA2 to get the unique
     baselines. UVW[:2] denotes the U and V coordinate giving the baseline length.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">select from MY.MS where DATA</span><span 
class="cmtt-10x-x-109">_DESC</span><span 
class="cmtt-10x-x-109">_ID in [select from ::DATA</span><span 
class="cmtt-10x-x-109">_DESCRIPTION where </span><br 
class="newline" /><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span></span></span>  <span 
class="cmtt-10x-x-109">SPECTRAL</span><span 
class="cmtt-10x-x-109">_WINDOW</span><span 
class="cmtt-10x-x-109">_ID in [0,2,4] giving [ROWID()]] </span><br 
class="newline" />ﬁnds all rows in a measurement set matching the given spectral windows. It uses a nested query
     to ﬁnd the DATA_DESC_ID for each spectral window.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">select from MY.MS where TIME in [select from ::SOURCE where REST</span><span 
class="cmtt-10x-x-109">_FREQUENCY &#x003C;</span>
     <span 
class="cmtt-10x-x-109">180MHz </span><br 
class="newline" /><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span></span></span> <span 
class="cmtt-10x-x-109">giving [TIME-INTERVAL/2 =:= TIME+INTERVAL/2]] </span><br 
class="newline" />ﬁnds all rows in a measurement set observing sources with a rest frequency less than 180 Mhz.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">select from VLA.MS, </span><br 
class="newline" /><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span></span></span> <span 
class="cmtt-10x-x-109">[select from VLA.MS where sumsqr(UVW[:2]) &#x003C; 625] as TIMESEL </span><br 
class="newline" /><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span></span></span>  <span 
class="cmtt-10x-x-109">where TIME in [select distinct TIME from TIMESEL] </span><br 
class="newline" /><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span></span></span>  <span 
class="cmtt-10x-x-109">&#x0026;&#x0026; any([ANTENNA1,ANTENNA2] in [select from TIMESEL giving </span><br 
class="newline" /><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span></span></span>  <span 
class="cmtt-10x-x-109">[iif(UVW[2] &#x003C; 0, ANTENNA1, ANTENNA2)]]) </span><br 
class="newline" />selects rows where an antenna (VLA has 25 m diameter) is shadowed. <br 
class="newline" />The  query  in  the  FROM  command  ﬁnds  all  rows  where  an  antenna  is  shadowed  (i.e.,  its
     UV-distance  less  than  25  meters)  and  creates  a  temporary  table.  This  selection  (named
     TIMESEL)  is  done  ﬁrst  otherwise  two  2  equal  selections  are  needed  in  the  main  WHERE
     command. The last line determines which antenna is shadowed (based on the W coordinate).
     The two lines above selects the times and baselines where an antenna is shadowed.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">select from MS </span><br 
class="newline" /><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span></span></span> <span 
class="cmtt-10x-x-109">where DATA</span><span 
class="cmtt-10x-x-109">_DESC</span><span 
class="cmtt-10x-x-109">_ID in [select from ::DATA</span><span 
class="cmtt-10x-x-109">_DESCRIPTION </span><br 
class="newline" /><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span></span></span> <span 
class="cmtt-10x-x-109">where SPECTRAL</span><span 
class="cmtt-10x-x-109">_WINDOW</span><span 
class="cmtt-10x-x-109">_ID in [select from ::SPECTRAL</span><span 
class="cmtt-10x-x-109">_WINDOW </span><br 
class="newline" /><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span></span></span> <span 
class="cmtt-10x-x-109">where NET</span><span 
class="cmtt-10x-x-109">_SIDEBAND==1 giving [ROWID()]] giving [ROWID()]] </span><br 
class="newline" />ﬁnds all rows in the MeasurementSet with the given NET_SIDEBAND. <br 
class="newline" />The MeasurementSet uses a table to map spectral-window-id to data-desc-id. Hence two nested
                                                                                            
                                                                                            
     subqueries are needed.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">select findcone(REFERENCE</span><span 
class="cmtt-10x-x-109">_DIR[0,], </span><br 
class="newline" /><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span></span></span> <span 
class="cmtt-10x-x-109">[16h34m33.805,62d45m36.83, 12h29m06.7,2d3m9], 1arcsec) </span><br 
class="newline" /><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span></span></span> <span 
class="cmtt-10x-x-109">from MS/FIELD </span><br 
class="newline" />compares the direction given in the ﬁrst argument with the directions given in the second function
     argument using the search radius given in the third argument. It returns the index of the ﬁrst
     matching cone (thus 0 or 1). If no cone matches, it returns -1. <br 
class="newline" />It can be used in the following example to ﬁnd the name of the source matching a direction.
     </dd><dt class="description">
 </dt><dd 
class="description"><span 
class="cmtt-10x-x-109">select [&#x2019;unknown&#x2019;,&#x2019;3C343&#x2019;,&#x2019;3C273&#x2019;][1+findcone(...)] from MS/FIELD  </span>where   ...   is   the
     ﬁndcone argument list given in the previous example. 1 is added to cope with the case that no
     cone matches.</dd></dl>
<!--l. 4457--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">12.1.2   </span> <a 
 id="x1-11100012.1.2"></a>Plain table results</h5>
<!--l. 4458--><p class="noindent" >The following examples result in a plain table, thus in a deep copy of the query results, because the
column-list contains an expression or a data type.
     </p><dl class="description"><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">SELECT column0+column1 FROM mytable  </span><br 
class="newline" />creates a table of 1 column with name Col_1. Its data type is on the expression data type.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">SELECT column0+column1 Res I4 FROM mytable  </span><br 
class="newline" />creates a table of 1 column with name <span 
class="cmtt-10x-x-109">Res</span>. Its data type is a 4 byte signed integer.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">SELECT colx colx R4 FROM mytable  </span><br 
class="newline" />creates a table of 1 column with name <span 
class="cmtt-10x-x-109">colx</span>. The sole purpose of this selection is to convert the
     data type of the column.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">SELECT means(DATA,0) AS DATA</span><span 
class="cmtt-10x-x-109">_MEAN C4 FROM my.ms  </span><br 
class="newline" />creates a table of 1 column with name <span 
class="cmtt-10x-x-109">DATA</span><span 
class="cmtt-10x-x-109">_MEAN</span>. Column DATA in a Casacore MeasurementSet
     is a 2-dimensional array with axes polarization and frequency. This command calculates and
     stores the mean in each polarization. If no data type was given, the means would have been
     stored as double precision complex (which is the expression data type). <br 
class="newline" />Note that this command is valid when using python style; in glish style <span 
class="cmtt-10x-x-109">MEANS(DATA,2) </span>should
     be used.
     </dd></dl>
                                                                                            
                                                                                            
<!--l. 4487--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">12.2   </span> <a 
 id="x1-11200012.2"></a>Modiﬁcation examples</h4>
<!--l. 4488--><p class="noindent" >
     </p><dl class="description"><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">update MY.MS set VIDEO</span><span 
class="cmtt-10x-x-109">_POINT=MEANS(DATA,2) where isdefined(DATA)  </span><br 
class="newline" />sets the VIDEO_POINT of each correlation to the mean of the DATA for that correlation. Note
     that the 2 indicates averaging over the second axis, thus the frequency axis.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">update MY.MS set FLAG</span><span 
class="cmtt-10x-x-109">_ROW=T where isdefined(FLAG) &#x0026;&#x0026; all(FLAG) </span><br 
class="newline" />sets FLAG_ROW in the rows where the entire FLAG array is set.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">delete from MY.MS where FLAG</span><span 
class="cmtt-10x-x-109">_ROW </span><br 
class="newline" />deletes all ﬂagged rows.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">insert into MY.MS select from OTHER.MS where !FLAG</span><span 
class="cmtt-10x-x-109">_ROW </span><br 
class="newline" />copies all unﬂagged rows from OTHER.MS to MY.MS.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">insert into MY.MS/DATA</span><span 
class="cmtt-10x-x-109">_DESCRIPTION </span><br 
class="newline" /><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span></span></span> <span 
class="cmtt-10x-x-109">(SPECTRAL</span><span 
class="cmtt-10x-x-109">_WINDOW</span><span 
class="cmtt-10x-x-109">_ID,POLARIZATION</span><span 
class="cmtt-10x-x-109">_ID,FLAG</span><span 
class="cmtt-10x-x-109">_ROW) </span><br 
class="newline" /><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span></span></span> <span 
class="cmtt-10x-x-109">values (1,0,F) </span><br 
class="newline" />adds a row to the DATA_DESCRIPTION subtable and initializes it.
     </dd></dl>
<!--l. 4513--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">12.2.1   </span> <a 
 id="x1-11300012.2.1"></a>Applying running median to an image</h5>
<!--l. 4514--><p class="noindent" >The following command shows how a running median can be applied to an Casacore image.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-179">
  update my.imgd set map = map - runningmedian(map,25,25)&#x2019;)
</div>
<!--l. 4518--><p class="nopar" > The running medians are subtracted from the data in the copy. It uses a half window size of 25x25, thus the
full window is 51x51. <br 
class="newline" />When doing this, one should take care that in case of a spectral line cube the image is not too large,
otherwise it won&#x2019;t ﬁt in memory. If too large, it should be done in chunks like:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-180">
  update my.imgd set map[,,sc:ec,] =
 <br />             map[,,sc:ec,] - runningmedian(map[,,sc:ec,],25,25)&#x2019;)
</div>
<!--l. 4528--><p class="nopar" > where <span 
class="cmtt-10x-x-109">sc </span>and <span 
class="cmtt-10x-x-109">ec </span>are the start and end frequency channel. In this example it is assumed that the axes of the
image are RA, DEC, freq, Stokes. <br 
class="newline" />Note that the image is updated, so it should have been copied before if the original data needs to be
kept.
</p><!--l. 4536--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">12.3   </span> <a 
 id="x1-11400012.3"></a>Table creation examples</h4>
<!--l. 4537--><p class="noindent" >
     </p><dl class="description"><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">create table mytab (col1 I4, col2 I4, col3 R8)  </span><br 
class="newline" />creates table <span 
class="cmtt-10x-x-109">mytab </span>of 3 scalar columns.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">create table mytab  </span><br 
class="newline" />creates an empty table.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">create table mytab colarr R4 ndim=0  </span><br 
class="newline" />creates a table of 1 array column with arbitrary dimensionality.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">create table mytab colarr R4 [shape=[4,128], dmtype=&#x2019;TiledColumnStMan&#x2019;]  </span><br 
class="newline" />creates  a  table  of  1  array  column  with  the  given  shape.  The  column  is  stored  with  the
     TiledColumnStMan storage manager using its default settings.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">create table mytab colarr R4 shape=[4,128]  </span><br 
class="newline" /><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span></span></span>  <span 
class="cmtt-10x-x-109">dminfo [TYPE=&#x2019;TiledColumnStMan&#x2019;, NAME=&#x2019;TCSM&#x2019;,  </span><br 
class="newline" /><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span></span></span>  <span 
class="cmtt-10x-x-109">SPEC=[DEFAULTTILESHAPE=[4,32,64]], COLUMNS=[&#x2019;colarr&#x2019;]] </span><br 
class="newline" />creates  a  table  of  1  array  column  with  the  given  shape.  The  column  is  stored  with  the
     TiledColumnStMan storage manager using the given settings.</dd></dl>
<!--l. 4563--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">12.4   </span> <a 
 id="x1-11500012.4"></a>Calculation examples</h4>
<!--l. 4564--><p class="noindent" >
                                                                                            
                                                                                            
     </p><dl class="description"><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">calc 1+2  </span><br 
class="newline" />uses TaQL as a desktop calculator.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">calc 7-Apr-2007 - 20-Nov-1979  </span><br 
class="newline" />calculates the number of days between these dates.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">calc sum([select from MY.MS giving [ntrue(FLAG)]])  </span><br 
class="newline" />determines the total number of ﬂags set in the measurement set.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">calc mean(abs(DATA))  </span><br 
class="newline" /> <span 
class="cmtt-10x-x-109">from [select from MY.MS where ANTENNA1==0]</span>
     <!--l. 4577--><p class="noindent" >calculates for each row the mean of the data for the selected subset of the measurement set.
     </p></dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">calc mean([select from MY.MS where ANTENNA1==0  </span><br 
class="newline" /><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span></span></span> <span 
class="cmtt-10x-x-109">giving [mean(abs(DATA))]])</span>
     <!--l. 4584--><p class="noindent" >looks like the previous example. It, however, calculates the mean of the mean of the data in each
     row for the selected subset of the measurement set.
     </p></dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">calc max([select from MY.MS where isdefined(DATA)  </span><br 
class="newline" /><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span></span></span>  <span 
class="cmtt-10x-x-109">giving [max(abs(VIDEO</span><span 
class="cmtt-10x-x-109">_POINT-MEANS(DATA,0)))]])</span>
     <!--l. 4592--><p class="noindent" >shows the maximum absolute diﬀerence between VIDEO_POINT of each correlation and the
     mean of the DATA for that correlation. Note that the 2 indicates averaging over the ﬁrst axis,
     thus the frequency axis.
</p>
     </dd></dl>
<!--l. 4599--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">12.5   </span> <a 
 id="x1-11600012.5"></a>Aggregation/groupby examples</h4>
<!--l. 4600--><p class="noindent" >
     </p><dl class="description"><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">select gcount(*) from my.ms  </span><br 
class="newline" />counts the number of rows in the table.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">select TIME, gcount(*) from my.ms groupby TIME  </span><br 
class="newline" />counts the number of rows (usually number of baselines) per time slot.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">select ANTENNA1,ANTENNA2,gfirst(TIME),glast(TIME),gcount()  </span><br 
class="newline" /><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span></span></span>  <span 
class="cmtt-10x-x-109">from my.ms groupby ANTENNA1,ANTENNA2  </span><br 
class="newline" />counts the number of rows (usually number of time slots) and shows the ﬁrst and last time per
     baseline.
                                                                                            
                                                                                            
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">select gmean(DATA) from my.ms  </span><br 
class="newline" /><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span></span></span>  <span 
class="cmtt-10x-x-109">groupby int((TIME - [select TIME from my.ms limit1][0]) / INTERVAL / 10))</span>
     <br 
class="newline" />calculates the average of DATA for every 10 time slots. Note it also averages in frequency
     and polarization. The following example shows how to average each frequency channel and
     polarization.
     </dd><dt class="description">
 </dt><dd 
class="description">  <span 
class="cmtt-10x-x-109">select boxedmean(gaggr(DATA), 10, 4) from my.ms  </span><br 
class="newline" /><span class="obeylines-h"><span class="verb"><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span><span 
class="cmtt-10x-x-109"> </span></span></span>  <span 
class="cmtt-10x-x-109">groupby int((TIME - [select TIME from my.ms limit1][0]) / INTERVAL / 10))</span>
     <br 
class="newline" />calculates the average of DATA per polarization for every 10 time slots and 4 frequency channels.
     Note it it ﬁrst combines the data of each 10 time slots in a single array, after which the <span 
class="cmtt-10x-x-109">boxedmean</span>
     function is used to average every [10,4,1] box.</dd></dl>
<!--l. 4631--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">12.5.1   </span> <a 
 id="x1-11700012.5.1"></a>Obtaining the ﬂux density from visibility data</h5>
<!--l. 4632--><p class="noindent" >The Miriad program <span 
class="cmtt-10x-x-109">uvflux </span>estimates the source I ﬂux density and its standard deviation at the phase
center without having to make an image. A single, not too complicated TaQL command (courtesy
Dijkema, Heald) provides the same functionality on a MeasurementSet. For LOFAR it is best to use
baselines with a length between 5 and 10 km. The command shows various aspects of TaQL that
are explained below. The numbers at the beginning of the lines point to the text following the
example.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-181">
4.    select gstddev(SUMMED) as STDVALS,
 <br />4.           gmean(SUMMED) as MEANVALS,
 <br />4.           gcount(SUMMED) as NVALS
 <br />3.    from (select gmean(
 <br />1.                  sum(iif(FLAG[,0:4:3], 0, abs(DATA[,0:4:3])))
 <br />1.                   / nfalse(FLAG[,::3])
 <br />3.                 ) as SUMMED
 <br />            from ~/data/GER.MS
 <br />2.          where mscal.baseline(&#x2019;5km~10km) &#x0026;&#x0026; !all(FLAG)
 <br />3.          groupby TIME)
</div>
<!--l. 4650--><p class="nopar" > A subquery is used to get the average ﬂux (I = 0.5*(XX+YY)) per time slot.
     </p><ol  class="enumerate1" >
     <li 
  class="enumerate" id="x1-117002x1">For each baseline it gets the mean of the channels. Note that it uses <span 
class="cmtt-10x-x-109">sum/n </span>to ignore ﬂagged
     visibilities. The <span 
class="cmtt-10x-x-109">iif </span>function tells to use 0 for them. Also note that XX is the 1st and YY
     the 4th polarisation, hence [0:4:3] (or [::3]) indexes these polarisations. Once masked arrays are
     supported by TaQL, it could be written as:   <span 
class="cmtt-10x-x-109">mean(DATA[,::3][FLAG[,::3]])</span>
     </li>
     <li 
  class="enumerate" id="x1-117004x2">It only uses the baselines with lengths between 5 and 10 km where not all visibilities are ﬂagged.
     Note that a <span 
class="cmtt-10x-x-109">mscal </span>user deﬁned function is used for the baseline selection as described in <a 
href="#x1-660004.10.17">section
     4.10.17</a>.
     </li>
     <li 
  class="enumerate" id="x1-117006x3">Thereafter  the  average  ﬂux  per  time  slot  is  determined  in  the  subquery  using  the  <span 
class="cmtt-10x-x-109">gmean</span>
     aggregation and GROUPBY functionality. The result is an intermediate table with one column
     called SUMMED and a row per time slot.
     </li>
     <li 
  class="enumerate" id="x1-117008x4">Finally,  the  outer  query  uses  aggregate  functions  to  calculate  the  overall  mean,  standard
     deviation, and number of time slots from the result of the subquery. The ﬁnal result is a table
     with 1 row and 3 columns.</li></ol>
<!--l. 4673--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">12.5.2   </span> <a 
 id="x1-11800012.5.2"></a>Number of fully ﬂagged baselines per antenna</h5>
<!--l. 4674--><p class="noindent" >The example below counts per antenna the number of fully ﬂagged baselines, excluding the autocorrelations.
It uses grouping and aggregate functions twice; ﬁrst per baseline, thereafter per antenna. It also uses the
<a 
href="#x1-210116">concatenation</a> and <a 
href="#x1-210074">backreferencing</a> features. It also shows the results when using the <span 
class="cmtt-10x-x-109">time </span>keyword, which
shows that the processing time is dominated by the ﬁrst query.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-182">
time select gsum(t1.cnt), t1.ANTENNA,
 <br />       (select NAME from ~/data/3C343.MS::ANTENNA)[t1.ANTENNA] as NAME
 <br />  from (select gcount() as cnt, ANTENNA1 as ANTENNA, ANTENNA2
 <br />          from ~/data/3C343.MS where all(FLAG) and ANTENNA1!=ANTENNA2
 <br />          groupby ANTENNA1,ANTENNA2) t0,
 <br />  [t0,
 <br />   (select cnt, ANTENNA2 as ANTENNA, 0 as ANTENNA2 from t0),
 <br />   (select 0 as cnt, rowid() as ANTENNA, 0 as ANTENNA2
 <br />           from ~/data/3C343.MS::ANTENNA)] t1
 <br />  groupby t1.ANTENNA orderby t1.ANTENNA
 <br />
 <br />  From query          0.8 real        0.58 user        0.08 system
 <br />  From query            0 real           0 user           0 system
 <br />  From query            0 real           0 user           0 system
 <br />  Subquery              0 real           0 user           0 system
 <br />  Groupby               0 real           0 user           0 system
 <br />  Orderby               0 real           0 user           0 system
 <br />  Projection            0 real           0 user           0 system
 <br /> Total time          0.83 real         0.6 user        0.08 system
</div>
<!--l. 4702--><p class="nopar" >
     </p><ol  class="enumerate1" >
     <li 
  class="enumerate" id="x1-118002x1">The ﬁrst inner select counts the number of fully ﬂagged baselines per baseline and stores the
     result with the antennas making up a baseline in a temporary table with shorthand <span 
class="cmtt-10x-x-109">t0</span>.. In this
     way the expensive counting part needs to be executed only once.
     </li>
     <li 
  class="enumerate" id="x1-118004x2">This table has to be summed for both antennas of the baselines, which is done in the second
     part creating a concatenated table with shorthand <span 
class="cmtt-10x-x-109">t1</span>. It backreferences the ﬁrst table <span 
class="cmtt-10x-x-109">t0 </span>twice.
     First to use it directly to count for ANTENNA1, thereafter to count for ANTENNA2 by doing
     a select to make the ANTENNA2 the ANTENNA column.
     </li>
     <li 
  class="enumerate" id="x1-118006x3">The table does not contain the antennas having no fully ﬂagged baselines. Therefore the third
     part of the concatenation copies the ANTENNA table to insert zero counts for all antennas.
     </li>
     <li 
  class="enumerate" id="x1-118008x4">Finally the outer select (in the ﬁrst line) sums the values in the concatenated table per antenna.
     It also retrieves the name of the antenna by indexing in the selection of all antenna names.</li></ol>
<!--l. 4729--><p class="noindent" >
</p>
                                                                                            
                                                                                            
   <h3 class="sectionHead"><span class="titlemark">13   </span> <a 
 id="x1-11900013"></a>Interface to TaQL</h3>
<!--l. 4730--><p class="noindent" >User and a programmer interfaces to TaQL are available. The program <span 
class="cmtt-10x-x-109">taql </span>and some Python and
Glish functions form the user interface, while C++ classes and functions form the programmer
interface.
</p><!--l. 4735--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">13.1   </span> <a 
 id="x1-12000013.1"></a>Python interface <span 
class="cmtt-10x-x-109">python-casacore</span></h4>
<!--l. 4736--><p class="noindent" >The main TaQL interface in Python is formed by the <a 
href="../../../pyrap/docs/pyrap_tables.html#pyrap.tables.table.query" ><span 
class="cmtt-10x-x-109">query</span></a> function in module <a 
href="../../../pyrap/docs/pyrap_tables.html" ><span 
class="cmtt-10x-x-109">table</span></a>. The function can be
used to compose and execute a TaQL command using the various (optional) arguments given to the <span 
class="cmtt-10x-x-109">query</span>
function. E.g.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-183">
   import casacore.tables as pt
 <br />   tab = pt.table(&#x2019;mytable&#x2019;)
 <br />   seltab1 = tab.query (&#x2019;column1 &#x003E; 0&#x2019;)
 <br />   seltab2 = seltab1.query (query=&#x2019;column2&#x003E;5&#x2019;,
 <br />                            sortlist=&#x2019;time&#x2019;,
 <br />                            columns=&#x2019;column1,column2&#x2019;,
 <br />                            name=&#x2019;result.tab&#x2019;)
</div>
<!--l. 4751--><p class="nopar" > The ﬁrst command opens the table <span 
class="cmtt-10x-x-109">mytable</span>. The second command does a simple query resulting in a
temporary table. That temporary table is used in the next command resulting in a persistent table. The
latter function call is transformed to the TaQL command:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-184">
  SELECT column1,column2 FROM \$1 WHERE column2&#x003E;5
 <br />  ORDERBY time GIVING result.tab
</div>
<!--l. 4760--><p class="nopar" > During execution $1 is replaced by table <span 
class="cmtt-10x-x-109">seltab1</span>. <br 
class="newline" />Note that the <span 
class="cmtt-10x-x-109">name </span>argument generates the <span 
class="cmtt-10x-x-109">GIVING </span>part to make the result persistent.
</p><!--l. 4765--><p class="indent" >   The functions <span 
class="cmtt-10x-x-109">sort </span>and <span 
class="cmtt-10x-x-109">select </span>exist as convenience functions for a query consisting of a sort or
column selection only. Both functions have an optional second <span 
class="cmtt-10x-x-109">name </span>parameter to make the result
persistent.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-185">
   t1 = tab.sort (&#x2019;time&#x2019;)
 <br />   t1 = tab.select (&#x2019;column1,column2&#x2019;)
</div>
<!--l. 4772--><p class="nopar" >
</p><!--l. 4774--><p class="indent" >   The <span 
class="cmtt-10x-x-109">calc </span>function can be used to execute a TaQL <span 
class="cmtt-10x-x-109">calc </span>command on the current table. The result can be
kept in a variable. For example, the following returns a vector containing the median of the <span 
class="cmtt-10x-x-109">DATA </span>column in
each table row:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-186">
  med = t.calc (&#x2019;median(DATA)&#x2019;)
</div>
<!--l. 4780--><p class="nopar" >
</p><!--l. 4782--><p class="indent" >   It is possible to embed Python variables and expressions in a TaQL command using the syntax
<span 
class="cmtt-10x-x-109">$variable </span>and <span 
class="cmtt-10x-x-109">$(expression)</span>. A variable can be a standard numeric or string scalar or vector. It
can also be a table tool. An expression has to result in a numeric or string scalar or vector.
E.g
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-187">
  from casacore.tables import *
 <br />  tab = table(&#x2019;mytable&#x2019;)
 <br />  coldata = tab.getcol (&#x2019;col&#x2019;);
 <br />  colmean = sum(coldata) / len(coldata);
 <br />  seltab1 = tab.query (&#x2019;col &#x003E; $colmean&#x2019;)
 <br />  seltab2 = tab.query (&#x2019;col &#x003E; $(sum(coldata)/len(coldata))&#x2019;)
 <br />  seltab3 = tab.query (&#x2019;col &#x003E; mean([SELECT col from $tab])&#x2019;)
</div>
<!--l. 4796--><p class="nopar" > These three queries give the same result. <br 
class="newline" />The substitution mechanism is described in more detail in <a 
href="../../../pyrap/docs/pyrap_util.html" >pyrap.util</a>.
</p><!--l. 4801--><p class="indent" >   The most generic function that can be used is <a 
href="../../../pyrap/docs/pyrap_tables.html#pyrap.tables.taql" >taql</a> (or its synonym <span 
class="cmtt-10x-x-109">tablecommand</span>). The full TaQL
command has to be given to that command. The result is a table object. E.g.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-188">
  import pyrap.tables as pt
 <br />  t = pt.taql(&#x2019;select from GER.MS where ANTENNA1==1&#x2019;);
</div>
<!--l. 4809--><p class="nopar" >
</p><!--l. 4811--><p class="indent" >   By default, these commands will use the Python style for a TaQL statement. The <span 
class="cmtt-10x-x-109">style </span>argument can be
used to choose another style.
</p><!--l. 4815--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">13.2   </span> <a 
 id="x1-12100013.2"></a>Interface to Glish</h4>
<!--l. 4816--><p class="noindent" >The Glish interface is formed by script <span 
class="cmtt-10x-x-109">table.g</span>. By default, it will use the Glish style for a TaQL statement.
For example:
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-189">
  include &#x2019;table.g&#x2019;
 <br />  tab := table(&#x2019;mytable&#x2019;)
 <br />  seltab1 := tab.query (&#x2019;column1 &#x003E; 0&#x2019;)
 <br />  seltab2 := seltab1.query (query=&#x2019;column2&#x003E;5&#x2019;,
 <br />                            sortlist=&#x2019;time&#x2019;,
 <br />                            columns=&#x2019;column1,column2&#x2019;,
 <br />                            name=&#x2019;result.tab&#x2019;)
 <br />  t := tablecommand(&#x2019;select from GER.MS where ANTENNA1==1&#x2019;,
 <br />                    style=&#x2019;&#x2019;);    # use default (glish) style
 <br />  med := t.calc (&#x2019;median(DATA)&#x2019;)
</div>
<!--l. 4831--><p class="nopar" >
</p><!--l. 4833--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">13.3   </span> <a 
 id="x1-12200013.3"></a>Program <span 
class="cmtt-10x-x-109">taql</span></h4>
<!--l. 4834--><p class="noindent" >The program <span 
class="cmtt-10x-x-109">taql </span>makes it possible to execute TaQL commands from the shell. Commands can be given in
diﬀerent ways: </p>
     <ul class="itemize1">
     <li class="itemize">The TaQL command can be given directly as command line arguments to the <span 
class="cmti-10x-x-109">taql </span>program.
     The arguments will be combined to a single command (separated by a space). Note that using
     multiple arguments instead of a single (quoted) argument makes it easier to use tab-completion
     for the table name. It will execute the command, show the result, and exit.
     </li>
     <li class="itemize">Using the -f option, the name of a ﬁle containing one or more TaQL commands can be given. The
     commands can be split over multiple lines, where a # can be used for comments. A semicolon
     has to be used to separate commands. The special commands listed below for the interactive
     case, can also be given.
     </li>
     <li class="itemize">The program is run interactively if command nor -f is given. It will run until the user stops via the
     command <span 
class="cmtt-10x-x-109">exit</span>, <span 
class="cmtt-10x-x-109">quit</span>, or <span 
class="cmtt-10x-x-109">q </span>or by giving Ctrl/D. Command editing and recall is possible, unless taql was
     built without readline support. Of course, a ﬁle can be used as input by redirection to stdin.
     This is more or less the same as using -f, but a command cannot be split over multiple
     lines and no semicolon is needed to separate commands. Interactive commands are kept
     in $HOME/.taql_history making command recall possible across multiple taql sessions.
     <br 
class="newline" />A few types of commands can be given:
          <ul class="itemize2">
          <li class="itemize"><span 
class="cmtt-10x-x-109">help</span>, <span 
class="cmtt-10x-x-109">h </span>or <span 
class="cmtt-10x-x-109">? </span>shows brief help information.
                                                                                            
                                                                                            
          </li>
          <li class="itemize"><span 
class="cmtt-10x-x-109">show </span>can be used to show to available units or measure types.
          </li>
          <li class="itemize">A  full  TaQL  command.  If  no  GIVING  part  is  given,  the  resulting  table  is  not  made
          persistent. It shows the number of matching rows.
          </li>
          <li class="itemize">A full TaQL command preceded by <span 
class="cmtt-10x-x-109">varname=</span>, where <span 
class="cmtt-10x-x-109">varname </span>is the name under which
          the resulting table is kept in this session. Thus the result is not a persistent table (unless
          GIVING was given), but it is kept temporarily. The <span 
class="cmtt-10x-x-109">varname </span>can be used in subsequent
          commands like <span 
class="cmtt-10x-x-109">SELECT FROM $varname</span>.
          </li>
          <li class="itemize"><span 
class="cmtt-10x-x-109">varname= </span>without a further command removes the temporary result.
          </li>
          <li class="itemize"><span 
class="cmtt-10x-x-109">varname </span>shows the number of rows in the temporary result. It can be followed by one or
          more question marks to show the column names and details about them. <br 
class="newline" />Note that if an unknown varname is given, it is treated as a TaQL command resulting in a
          parse error.
          </li>
          <li class="itemize">Comments can be given after the hash (#) character. Empty lines are ignored.</li></ul>
     </li></ul>
<!--l. 4884--><p class="noindent" >If columns are selected in the TaQL command, their values are printed. By default they are separated by tabs,
but the -d option can be used to deﬁne another delimiter. Epoch, position, and direction measures
are printed in a formatted way. Note that TaQL&#x2019;s <span 
class="cmtt-10x-x-109">str </span>function oﬀers nice formatting for any
value. Also the result of CALC commands is printed. Otherwise only the number of selected (or
updated or deleted) rows is printed. Options like <span 
class="cmti-10x-x-109">-nops </span>can be given to suppress printing the
results.
</p><!--l. 4894--><p class="indent" >   By default the program <span 
class="cmti-10x-x-109">taql </span>uses the Python style. The <span 
class="cmti-10x-x-109">-s </span>option can be used to specify a
style.
</p><!--l. 4897--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">13.4   </span> <a 
 id="x1-12300013.4"></a>C++ interface</h4>
<!--l. 4898--><p class="noindent" >The C++ programmer can use TaQL commands and expressions at various levels,
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">13.4.1   </span> <a 
 id="x1-12400013.4.1"></a>TaQL query string</h5>
<!--l. 4900--><p class="noindent" >The function <span 
class="cmtt-10x-x-109">tableCommand </span>in <a 
href="../html/classcasa_1_1TableParse.html" >TableParse.h</a> can be used to execute a TaQL command. The result is a <a 
href="../html/classcasa_1_1Table.html" >Table</a>
object. E.g.,
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-190">
  Table seltab1 = tableCommand
 <br />         (&#x0022;select from mytable where column1&#x003E;0&#x0022;);
 <br />  Table seltab2 = tableCommand
 <br />         (&#x0022;select column1,column2 from $1 where column2&#x003E;5&#x0022;
 <br />          &#x0022; orderby time giving result.tab&#x0022;, seltab1);
</div>
<!--l. 4912--><p class="nopar" > These examples do the same as the Python ones shown above. <br 
class="newline" />Note that in the second function call the table name <span 
class="cmtt-10x-x-109">$1 </span>is replaced by the object <span 
class="cmtt-10x-x-109">seltab1 </span>passed to the
function. <br 
class="newline" />There is no style argument, so if an explicit style is needed it should be the ﬁrst part of the TaQL statement.
Note that the Glish style is the default style.
</p><!--l. 4921--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">13.4.2   </span> <a 
 id="x1-12500013.4.2"></a>Expression string</h5>
<!--l. 4922--><p class="noindent" >The function <span 
class="cmtt-10x-x-109">parse </span>in <a 
href="../html/classcasa_1_1RecordGram.html" >RecordGram.h</a> can be used to parse a TaQL expression. The result is a
<a 
href="../html/classcasa_1_1ExprNode.html" >TableExprNode</a> object that can be evaluated for each row in the table. E.g.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-191">
  Table tab(&#x0022;mytable&#x0022;);
 <br />  TableExprNode expr = RecordGram::parse (tab, &#x0022;column1&#x003E;0&#x0022;);
 <br />  Table seltab1 = tab(expr);
</div>
<!--l. 4932--><p class="nopar" > The example above does the same as the ﬁrst example in the previous section. There are, however, better
ways to use this functionality.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-192">
  Table tab(&#x0022;somename&#x0022;);
 <br />  TableExprNode expr = RecordGram::parse (tab, &#x0022;ANTENNA1=1&#x0022;);
 <br />  for (uInt row=0; row&#x003C;tab.nrow(); ++row) {
 <br />    if (expr.getBool(row)) {
 <br />      // expression is true for this row, so do something ...
 <br />    }
 <br />  }
</div>
<!--l. 4943--><p class="nopar" > The example above shows a boolean scalar expression, but it can also be a numeric expression or an array
expression as shown in the example below. Note that TaQL expression results have data type Bool, Int64,
Double, DComplex, String, or MVTime.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-193">
  TableExprNode expr = RecordGram::parse (tab, &#x0022;abs(DATA)&#x0022;);
 <br />  Array&#x003C;Double&#x003E; data;
 <br />  for (uInt row=0; row&#x003C;tab.nrow(); ++row) {
 <br />    expr.get (row, data);
 <br />  }
</div>
<!--l. 4955--><p class="nopar" >
</p><!--l. 4957--><p class="indent" >   Class RecordGram can also be used to apply TaQL to C++ vectors of values or Records. The
RecordGram class documentation and its test program describe these features in more detail.
</p><!--l. 4961--><p class="noindent" >
</p>
   <h5 class="subsubsectionHead"><span class="titlemark">13.4.3   </span> <a 
 id="x1-12600013.4.3"></a>Expression classes</h5>
<!--l. 4962--><p class="noindent" >The other expression interface is a true C++ interface having the advantage that C++ variables can be used
directly. Class <a 
href="../html/classcasa_1_1Table.html" >Table</a> contains functions to sort a table or to select columns or rows. When selecting rows class
<a 
href="../html/classcasa_1_1TableExprNode.html" >TableExprNode</a> (in ExprNode.h) has to be used to build a WHERE expression which can be executed by the
overloaded function operator in class <span 
class="cmtt-10x-x-109">Table</span>. E.g.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-194">
  Int limit = 0;
 <br />  Table tab (&#x0022;mytable&#x0022;);
 <br />  Table seltab = tab(tab.col(&#x0022;column1&#x0022;) &#x003E; limit);
</div>
<!--l. 4975--><p class="nopar" > does the same as the ﬁrst example shown above. See classes <a 
href="../html/classcasa_1_1Table.html" >Table</a>, <a 
href="../html/classcasa_1_1TableExprNode.html" >TableExprNode</a>, and <a 
href="../html/classcasa_1_1TableExprNodeSet.html" >TableExprNodeSet</a>
for more information on how to construct a WHERE expression.
</p><!--l. 4985--><p class="noindent" >
</p>
   <h3 class="sectionHead"><span class="titlemark">14   </span> <a 
 id="x1-12700014"></a>Writing user deﬁned functions</h3>
<!--l. 4986--><p class="noindent" >A C++ user deﬁned function has to be written as a class derived from the abstract base class
<a 
href="../html/classcasa_1_1UDFBase.html" >UDFBase</a>. The documentation of this base class describes how to write a UDF. Furthermore
one can look at class <a 
href="../html/classcasa_1_1UDFMSCal.html" >UDFMSCal</a> that contains the UDFs described in subsection <a 
href="#x1-660004.10.17">User deﬁned
functions</a>.
</p><!--l. 4995--><p class="indent" >   It is possible to write a UDF that operates on an individual expression (for each table row) and returns
the result. It is, however, also possible to write a UDF acting as an aggregate function. In that case it will
return a result based on the values of all rows in a group. See the desription of the <a 
href="#x1-230003.6">GROUPBY clause</a> for
more information on the GROUPBY clause and aggregate functions.
</p><!--l. 5003--><p class="indent" >   Note that a class can contain multiple UDFs as done in UDFMSCal. Also note that a single UDF can
operate on multiple data types which is similar to a function like <span 
class="cmtt-10x-x-109">min </span>that can operate on scalars and arrays
of diﬀerent data types.
</p><!--l. 5008--><p class="indent" >   A UDF class can contain a <span 
class="cmtt-10x-x-109">HELP </span>function, which should return help information. This function is called
by a help command like
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-195">
   show function meas [subtype]
</div>
<!--l. 5012--><p class="nopar" > It returns an overview of the functions in the UDF class and possible other information. The optional
<span 
class="cmtt-10x-x-109">subtype </span>argument can be used to return more speciﬁc information. Note that the same result is given
by
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-196">
   meas.help(&#x2019;subtype&#x2019;)
</div>
<!--l. 5019--><p class="nopar" >
</p><!--l. 5021--><p class="indent" >   TaQL ﬁnds a UDF by looking in a dictionary mapping the UDF name to a function constructing an
object of the UDF class. If not found, it tries to load the shared library with the lowercase name of the
library part of the UDF (like in <span 
class="cmtt-10x-x-109">derivedmscal.pa1</span>). If the load is successful, it calls an initialization
function in the shared library that should add all UDF functions in the library to the dictionary. The
description of the <a 
href="../html/classcasa_1_1UDFBase.html" >UDFBase</a> class shows how this should be done.
</p><!--l. 5030--><p class="noindent" >
</p>
   <h4 class="subsectionHead"><span class="titlemark">14.1   </span> <a 
 id="x1-12800014.1"></a>UDFs in Python</h4>
<!--l. 5031--><p class="noindent" >NOTE: This section is for a future version of TaQL. It has not been fully implemented yet.
</p><!--l. 5034--><p class="indent" >   For performance reasons User Deﬁned Functions will usually be implemented in C++. It is, however,
possible to implement them in Python, both regular functions and aggregate functions. This can be done by
means of the <span 
class="cmtt-10x-x-109">pytaql </span>module of Casacore.
</p><!--l. 5039--><p class="indent" >   A UDF has to be implemented in Python by subclassing <span 
class="cmtt-10x-x-109">pytaqlbase</span>, that can be imported from
<span 
class="cmtt-10x-x-109">Casacore.python</span>. The subclass has to implement a few functions, some are optional. The functions are
called in the order given below.
</p>
     <ul class="itemize1">
     <li class="itemize"><span 
class="cmtt-10x-x-109">_</span><span 
class="cmtt-10x-x-109">_init</span><span 
class="cmtt-10x-x-109">_</span><span 
class="cmtt-10x-x-109">_(self)</span><br 
class="newline" />The class constructor must call the __init__ function of the superclass.
     </li>
     <li class="itemize"><span 
class="cmtt-10x-x-109">needTable(self)</span><br 
class="newline" />This optional function tells if the UDF needs the Table object of the table being queried. If
     True is returned, the function setTable is called thereafter. The Table object can be used by
     UDFs needing extra info (e.g., keywords) from the table being queried or from its subtables
     (comparable to derivedmscal). It requires the import of <span 
class="cmtt-10x-x-109">pyrap.tables </span>at the beginning of the
     UDF script.
     </li>
     <li class="itemize"><span 
class="cmtt-10x-x-109">setTable(self, tab)</span><br 
class="newline" />This function makes it possible to keep the Table object. It must be implemented if <span 
class="cmtt-10x-x-109">needTable </span>returns
     True. The object should be kept like:
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-197">
         self.tab = pyrap.tables.table (tab, _oper=3)
</div>
     <!--l. 5063--><p class="nopar" >
     </p></li>
     <li class="itemize"><span 
class="cmtt-10x-x-109">setup(self, valuetypes, datatypes, units)</span><br 
class="newline" />This function is called once at the beginning. It gets the value types, data types, and units of the
     function arguments. The length of the sequences tells the number of arguments.
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-198">
      valuetypes  int seq   value type of each argument
      <br />                       0=scalar 1=array 2=set
      <br /> datatypes   int seq   data type of each argument
      <br />                       0=bool 1=int 2=float 3=complex
      <br />                       4=string 6=date
      <br /> units       strings   unit of each argument (empty=no unit)
</div>
     <!--l. 5076--><p class="nopar" > The UDF should check if the argument types are correct and determine the result type. It has to
     return a dict containing the following ﬁelds:
                                                                                            
                                                                                            
</p>
     <div class="verbatim" id="verbatim-199">
      ndim      int       dimensionality of result
      <br />                     -1=scalar 0=unknown
      <br /> shape     int seq   shape (if fixed, otherwise empty sequence)
      <br /> dtype     int       data type of result
      <br /> unit      string    optional unit of result
      <br /> isaggr    bool      True = UDF is aggregate function
</div>
     <!--l. 5087--><p class="nopar" >
     </p></li>
     <li class="itemize"><span 
class="cmtt-10x-x-109">getValue(self, argValues, rownr)</span><br 
class="newline" />This function must return the function value for the given argument values. It is only called if <span 
class="cmtt-10x-x-109">setup</span>
     does not set <span 
class="cmtt-10x-x-109">isaggr=True</span>. Normally the <span 
class="cmtt-10x-x-109">rownr </span>argument is not needed, but it could be used to obtain
     special info from the Table object for that row.
     </li>
     <li class="itemize"><span 
class="cmtt-10x-x-109">getAggrValue(self, rownrs)</span><br 
class="newline" />This function must return the value of the aggregate function for the given rows. The argument values
     are not passed, because their sizes may exhaust memory. Instead the list of row numbers in the
     aggregation group are given. For each row the following function must be called to get a list of the
     argument values for that row.
                                                                                            
                                                                                            
     <div class="verbatim" id="verbatim-200">
         getArgValues(self, rownr)
</div>
     <!--l. 5102--><p class="nopar" >
</p>
     </li></ul>
<!--l. 5105--><p class="noindent" >Such a UDF can be called in TaQL like <span 
class="cmtt-10x-x-109">py.module.class </span>where the class defaults to the module name.
<br 
class="newline" />An example of UDFs in Python is given below. The ﬁrst one is a regular UDF, the second one an aggregate
UDF.
                                                                                            
                                                                                            
</p>
   <div class="verbatim" id="verbatim-201">
# tpytaql.py: Test script for pytaqlbase
 <br />
 <br />from casacore.pytaqlbase import pytaqlbase
 <br />##import pyrap.tables as pt
 <br />
 <br />class tpytaql(pytaqlbase):
 <br />    &#x0022;&#x0022;&#x0022;
 <br />    A test (and example) for a pytaql UDF.
 <br />    It returns the sum of the values in the argument.
 <br />    &#x0022;&#x0022;&#x0022;
 <br />
 <br />    def __init__(self):
 <br />        &#x0022;&#x0022;&#x0022; The constructor must call the __init__ in the base class. &#x0022;&#x0022;&#x0022;
 <br />        pytaqlbase.__init__(self)
 <br />
 <br />    def setup(self, valuetypes, datatypes, units):
 <br />        &#x0022;&#x0022;&#x0022; Setup the pytaql object. &#x0022;&#x0022;&#x0022;
 <br />        if len(valuetypes) != 1:
 <br />            raise ValueError(&#x0022;UDF tpytaql should have exactly 1 argument&#x0022;)
 <br />        self.isScalar = valuetypes[0]==0
 <br />        return {&#x2019;ndim&#x2019;:0, &#x2019;dtype&#x2019;:datatypes[0], &#x2019;unit&#x2019;:units[0]}
 <br />
 <br />    def getValue(self, argValues, rownr):
 <br />        &#x0022;&#x0022;&#x0022; Get the value of the function for the given table row. &#x0022;&#x0022;&#x0022;
 <br />        if self.isScalar:
 <br />            return argValues[0];
 <br />        return argValues[0].sum()    # sum of numpy array
 <br />
 <br />
 <br />
 <br />class tpytaqlaggr(pytaqlbase):
 <br />    &#x0022;&#x0022;&#x0022;
 <br />    A test (and example) for a pytaql aggregation UDF.
 <br />    It returns the difference of the total of both arguments.
 <br />    &#x0022;&#x0022;&#x0022;
 <br />
 <br />    def __init__(self):
 <br />        &#x0022;&#x0022;&#x0022; The constructor must call the __init__ in the base class. &#x0022;&#x0022;&#x0022;
 <br />        pytaqlbase.__init__(self)
 <br />
 <br />## The following functions show how to get and keep a Table object.
 <br />## Note the import of pyrap.tables is also required.
 <br />##    def needTable(self):
 <br />##        return True
                                                                                            
                                                                                            
 <br />##    def setTable(self, tab):
 <br />##        self.tab = pt.table(tab, _oper=3)
 <br />##        print &#x0022;nrows&#x0022;,self.tab.nrows()
 <br />
 <br />    def setup(self, valuetypes, datatypes, units):
 <br />        &#x0022;&#x0022;&#x0022; Setup the pytaql object. &#x0022;&#x0022;&#x0022;
 <br />        if len(valuetypes) != 2:
 <br />            raise ValueError(&#x0022;tpytaqlaggr UDF should have exactly 2 arguments&#x0022;)
 <br />        self.isScalar0 = valuetypes[0]==0
 <br />        self.isScalar1 = valuetypes[1]==0
 <br />        return {&#x2019;ndim&#x2019;:0, &#x2019;dtype&#x2019;:datatypes[0],
 <br />                &#x2019;unit&#x2019;:units[0], &#x2019;isaggr&#x2019;:True}
 <br />
 <br />    def getAggrValue(self, rownrs):
 <br />        &#x0022;&#x0022;&#x0022; Get the value of the aggregate function for the given table rows. &#x0022;&#x0022;&#x0022;
 <br />        v = 0;
 <br />        for rownr in rownrs:
 <br />            argValues = self.getArgValues (rownr);
 <br />            if self.isScalar0:
 <br />                v += argValues[0];
 <br />            else:
 <br />                v += argValues[0].sum()
 <br />            if self.isScalar1:
 <br />                v -= argValues[1];
 <br />            else:
 <br />                v -= argValues[1].sum()
 <br />        return v
</div>
<!--l. 5181--><p class="nopar" >
</p><!--l. 5184--><p class="noindent" >
</p>
   <h3 class="sectionHead"><span class="titlemark">15   </span> <a 
 id="x1-12900015"></a>Possible future developments</h3>
<!--l. 5185--><p class="noindent" >In the near or far future TaQL can be enhanced by adding new features and by doing optimizations.
</p>
     <ul class="itemize1">
     <li class="itemize">Add ROLLUP/CUBE to the GROUPBY clause.
     </li>
     <li class="itemize">Implement the OVER/PARTITION clause.
     </li>
     <li class="itemize">Add explicit JOIN clause (probably only equi-joins).
     </li>
     <li class="itemize">Add UNION, INTERSECTION, and DIFFERENCE.
                                                                                            
                                                                                            
     </li>
     <li class="itemize">Handle invalid subexpressions (e.g., exceeding array bounds) as null arrays which can be tested
     with the function ISNULL.</li></ul>
    
</body></html>