diff options
Diffstat (limited to 'funtools/man/man3/funcolumnactivate.3')
| -rw-r--r-- | funtools/man/man3/funcolumnactivate.3 | 330 |
1 files changed, 330 insertions, 0 deletions
diff --git a/funtools/man/man3/funcolumnactivate.3 b/funtools/man/man3/funcolumnactivate.3 new file mode 100644 index 0000000..2eda34b --- /dev/null +++ b/funtools/man/man3/funcolumnactivate.3 @@ -0,0 +1,330 @@ +.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sh \" Subsection heading +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. | will give a +.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to +.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' +.\" expand to `' in nroff, nothing in troff, for use with C<>. +.tr \(*W-|\(bv\*(Tr +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.\" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.hy 0 +.if n .na +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "funcolumnactivate 3" +.TH funcolumnactivate 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" +.SH "NAME" +FunColumnActivate \- activate Funtools columns +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <funtools.h> +.Ve +.PP +.Vb 1 +\& void FunColumnActivate(Fun fun, char *s, char *plist) +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fB\f(BIFunColumnActivate()\fB\fR routine determines which columns (set up +by \fIFunColumnSelect()\fR) +ultimately will be read and/or written. By default, all columns that +are selected using +\&\fIFunColumnSelect()\fR +are activated. The +\&\fIFunColumnActivate()\fR +routine can be used to turn off/off activation of specific columns. +.PP +The first argument is the Fun handle associated with this set of +columns. The second argument is a space-delimited list of columns to +activate or de\-activate. Columns preceded by \*(L"+\*(R" are activated and +columns preceded by a \*(L"\-\*(R" are de\-activated. If a column is named +without \*(L"+\*(R" or \*(L"\-\*(R", it is activated. The reserved strings \*(L"$region\*(R" +and '$n' are used to activate a special columns containing the filter +region value and row value, respectively, associated with +this row. For example, if a filter containing two circular regions is +specified as part of the Funtools file name, this column will contain +a value of 1 or 2, depending on which region that row was in. The +reserved strings \*(L"$x\*(R" and \*(L"$y\*(R" are used to activate the current +binning columns. Thus, if the columns \s-1DX\s0 and \s-1DY\s0 are specified as +binning columns: +.PP +.Vb 1 +\& [sh $] fundisp foo.fits[bincols=(DX,DY)] +.Ve +.PP +then \*(L"$x\*(R" and \*(L"$y\*(R" will refer to these columns in a call to +\&\fIFunColumnActivate()\fR. +.PP +In addition, if the activation string contains only columns to be +activated, then the routine will de-activate all other columns. +Similarly, if the activation string contains only +columns to de\-activate, then the routine will activate all other columns +before activating the list. This makes it simple to change the +activation state of all columns without having to know all of the +column names. For example: +.IP "\(bu" 4 +\&\fB\*(L"pi pha time\*(R"\fR # only these three columns will be active +.IP "\(bu" 4 +\&\fB\*(L"\-pi \-pha \-time\*(R"\fR # all but these columns will be active +.IP "\(bu" 4 +\&\fB\*(L"pi \-pha\*(R"\fR # only pi is active, pha is not, others are not +.IP "\(bu" 4 +\&\fB\*(L"+pi \-pha\*(R"\fR # same as above +.IP "\(bu" 4 +\&\fB\*(L"pi \-pha \-time\*(R"\fR # only pi is active, all others are not +.IP "\(bu" 4 +\&\fB\*(L"pi pha\*(R"\fR # pha and pi are active, all others are not +.IP "\(bu" 4 +\&\fB\*(L"pi pha \-x \-y\*(R"\fR # pha and pi are active, all others are not +.PP +You can use the column activation list to reorder columns, since +columns are output in the order specified. For example: +.PP +.Vb 9 +\& # default output order +\& fundisp snr.ev'[cir 512 512 .1]' +\& X Y PHA PI TIME DX DY +\& -------- -------- -------- -------- --------------------- -------- -------- +\& 512 512 6 7 79493997.45854475 578 574 +\& 512 512 8 9 79494575.58943175 579 573 +\& 512 512 5 6 79493631.03866175 578 575 +\& 512 512 5 5 79493290.86521725 578 575 +\& 512 512 8 9 79493432.00990875 579 573 +.Ve +.PP +.Vb 9 +\& # re-order the output by specifying explicit order +\& fundisp snr.ev'[cir 512 512 .1]' "time x y dy dx pi pha" +\& TIME X Y DY DX PI PHA +\& --------------------- -------- -------- -------- -------- -------- -------- +\& 79493997.45854475 512 512 574 578 7 6 +\& 79494575.58943175 512 512 573 579 9 8 +\& 79493631.03866175 512 512 575 578 6 5 +\& 79493290.86521725 512 512 575 578 5 5 +\& 79493432.00990875 512 512 573 579 9 8 +.Ve +.PP +A \*(L"+\*(R" sign by itself means to activate all columns, so that you can reorder +just a few columns without specifying all of them: +.PP +.Vb 9 +\& # reorder 3 columns and then output the rest +\& fundisp snr.ev'[cir 512 512 .1]' "time pi pha +" +\& TIME PI PHA Y X DX DY +\& --------------------- -------- -------- -------- -------- -------- -------- +\& 79493997.45854475 7 6 512 512 578 574 +\& 79494575.58943175 9 8 512 512 579 573 +\& 79493631.03866175 6 5 512 512 578 575 +\& 79493290.86521725 5 5 512 512 578 575 +\& 79493432.00990875 9 8 512 512 579 573 +.Ve +.PP +The column activation/deactivation is performed in the order of the +specified column arguments. This means you can mix \*(L"+\*(R", \*(L"\-\*(R" (which +de-activates all columns) and specific column names to reorder and +select columns in one command. For example, consider the following: +.PP +.Vb 9 +\& # reorder and de-activate +\& fundisp snr.ev'[cir 512 512 .1]' "time pi pha + \-x \-y" +\& TIME PI PHA DX DY +\& --------------------- -------- -------- -------- -------- +\& 79493997.45854475 7 6 578 574 +\& 79494575.58943175 9 8 579 573 +\& 79493631.03866175 6 5 578 575 +\& 79493290.86521725 5 5 578 575 +\& 79493432.00990875 9 8 579 573 +.Ve +.PP +We first activate \*(L"time\*(R", \*(L"pi\*(R", and \*(L"pha\*(R" so that they are output first. +We then activate all of the other columns, and then de-activate \*(L"x\*(R" and \*(L"y\*(R". +Note that this is different from: +.PP +.Vb 9 +\& # probably not what you want ... +\& fundisp snr.ev'[cir 512 512 .1]' "time pi pha \-x \-y +" +\& TIME PI PHA Y X DX DY +\& --------------------- -------- -------- -------- -------- -------- -------- +\& 79493997.45854475 7 6 512 512 578 574 +\& 79494575.58943175 9 8 512 512 579 573 +\& 79493631.03866175 6 5 512 512 578 575 +\& 79493290.86521725 5 5 512 512 578 575 +\& 79493432.00990875 9 8 512 512 579 573 +.Ve +.PP +Here, \*(L"x\*(R" and \*(L"y\*(R" are de\-activated, but then all columns including \*(L"x\*(R" and +\&\*(L"y\*(R" are again re\-activated. +.PP +Typically, +\&\fIFunColumnActivate()\fR uses a +list of columns that are passed into the program from the command line. For +example, the code for funtable contains the following: +.PP +.Vb 1 +\& char *cols=NULL; +.Ve +.PP +.Vb 3 +\& /* open the input FITS file */ +\& if( !(fun = FunOpen(argv[1], "rc", NULL)) ) +\& gerror(stderr, "could not FunOpen input file: %s\en", argv[1]); +.Ve +.PP +.Vb 3 +\& /* set active flag for specified columns */ +\& if( argc >= 4 ) cols = argv[3]; +\& FunColumnActivate(fun, cols, NULL); +.Ve +.PP +The \fIFunOpen()\fR call sets the +default columns to be all columns in the input file. The +\&\fIFunColumnActivate()\fR call +then allows the user to control which columns ultimately will be +activated (i.e., in this case, written to the new file). For example: +.PP +.Vb 1 +\& funtable test.ev foo.ev "pi pha time" +.Ve +.PP +will process only the three columns mentioned, while: +.PP +.Vb 1 +\& funtable test.ev foo.ev "\-time" +.Ve +.PP +will process all columns except \*(L"time\*(R". +.PP +If \fIFunColumnActivate()\fR +is called with a null string, then the environment variable +\&\fB\s-1FUN_COLUMNS\s0\fR will be used to provide a global value, if present. +This is the reason why we call the routine even if no columns +are specified on the command line (see example above), instead +of calling it this way: +.PP +.Vb 4 +\& /* set active flag for specified columns */ +\& if( argc >= 4 ){ +\& FunColumnActivate(fun, argv[3], NULL); +\& } +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See funtools(7) for a list of Funtools help pages |