diff options
Diffstat (limited to 'funtools/doc/combo.html')
-rw-r--r-- | funtools/doc/combo.html | 117 |
1 files changed, 117 insertions, 0 deletions
diff --git a/funtools/doc/combo.html b/funtools/doc/combo.html new file mode 100644 index 0000000..ab0bc28 --- /dev/null +++ b/funtools/doc/combo.html @@ -0,0 +1,117 @@ +<!-- =defdoc funcombine funcombine n --> +<HTML> +<HEAD> +<TITLE>Combining Region and Table Filters</TITLE> +</HEAD> +<BODY> + +<!-- =section funcombine NAME --> +<H2><A NAME="funcombine">FunCombine: Combining Region and Table Filters</A></H2> + +<!-- =section funcombine SYNOPSIS --> +<H2>Summary</H2> +<P> +This document discusses the conventions for combining region and table +filters, especially with regards to the comma operator. + + +<!-- =section funcombine DESCRIPTION --> +<H2><A NAME="conventions">Comma Conventions</A></H2> +<P> +Filter specifications consist of a series of boolean expressions, +separated by commas. These expressions can be table filters, +spatial region filters, or combinations thereof. Unfortunately, +common usage requires that the comma operator must act differently +in different situations. Therefore, while its use is intuitive in +most cases, commas can be a source of confusion. + +<P> +According to long-standing usage in IRAF, when a comma separates two +table filters, it takes on the meaning of a boolean <B>and</B>. Thus: +<PRE> + foo.fits[pha==1,pi==2] +</PRE> +is equivalent to: +<PRE> + foo.fits[pha==1 && pi==2] +</PRE> + +When a comma separates two spatial region filters, however, it has +traditionally taken on the meaning of a boolean <B>or</B>. Thus: +<PRE> + foo.fits[circle(10,10,3),ellipse(20,20,8,5)] +</PRE> +is equivalent to: +<PRE> + foo.fits[circle(10,10,3) || ellipse(20,20,8,5)] +</PRE> +(except that in the former case, each region is given a unique id +in programs such as funcnts). + +<P> +Region and table filters can be combined: +<PRE> + foo.fits[circle(10,10,3),pi=1:5] +</PRE> +or even: +<PRE> + foo.fits[pha==1&&circle(10,10,3),pi==2&&ellipse(20,20,8,5)] +</PRE> +In these cases, it is not obvious whether the command should utilize an +<B>or</B> or <B>and</B> operator. We therefore arbitrarily chose to +implement the following rule: +<UL> +<LI> if both expressions contain a region, the operator used is <B>or</B>. +<LI> if one (or both) expression(s) does not contain a region, the operator +used is <B>and</B>. +</UL> +This rule handles the cases of pure regions and pure column filters properly. +It unambiguously assigns the boolean <B>and</B> to all mixed cases. Thus: +<PRE> + foo.fits[circle(10,10,3),pi=1:5] +</PRE> +and +<PRE> + foo.fits[pi=1:5,circle(10,10,3)] +</PRE> +both are equivalent to: +<PRE> + foo.fits[circle(10,10,3) && pi=1:5] +</PRE> + +<P> +[NB: This arbitrary rule <b>replaces the previous arbitrary rule</b> +(pre-funtools 1.2.3) which stated: +<UL> +<LI> if the 2nd expression contains a region, the operator used is <B>or</B>. +<LI> if the 2nd expression does not contain a region, the operator +used is <B>and</B>. +</UL> +In that scenario, the <B>or</B> operator was implied by: +<PRE> + pha==4,circle 5 5 1 +</PRE> +while the <B>and</B> operator was implied by +<PRE> + circle 5 5 1,pha==4 +</PRE> +Experience showed that this non-commutative treatment of the comma +operator was confusing and led to unexpected results.] + +<P> +The comma rule must be considered provisional: comments and complaints +are welcome to help clarify the matter. Better still, we recommend +that the comma operator be avoided in such cases in favor of an +explicit boolean operator. + +<!-- =section funcombine SEE ALSO --> +<!-- =text See funtools(n) for a list of Funtools help pages --> +<!-- =stop --> + +<P> +<A HREF="./help.html">Go to Funtools Help Index</A> + +<H5>Last updated: November 16, 2005</H5> + +</BODY> +</HTML> |