diff options
Diffstat (limited to 'funtools/doc/pod/funcolumnactivate.pod')
-rw-r--r-- | funtools/doc/pod/funcolumnactivate.pod | 239 |
1 files changed, 239 insertions, 0 deletions
diff --git a/funtools/doc/pod/funcolumnactivate.pod b/funtools/doc/pod/funcolumnactivate.pod new file mode 100644 index 0000000..d5f6e3a --- /dev/null +++ b/funtools/doc/pod/funcolumnactivate.pod @@ -0,0 +1,239 @@ +=pod + +=head1 NAME + + + +B<FunColumnActivate - activate Funtools columns> + + + +=head1 SYNOPSIS + + + + + + #include <funtools.h> + + void FunColumnActivate(Fun fun, char *s, char *plist) + + + + + +=head1 DESCRIPTION + + + + +The B<FunColumnActivate()> routine determines which columns (set up +by FunColumnSelect()) +ultimately will be read and/or written. By default, all columns that +are selected using +FunColumnSelect() +are activated. The +FunColumnActivate() +routine can be used to turn off/off activation of specific columns. + + +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 "+" are activated and +columns preceded by a "-" are de-activated. If a column is named +without "+" or "-", it is activated. The reserved strings "$region" +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 "$x" and "$y" are used to activate the current +binning columns. Thus, if the columns DX and DY are specified as +binning columns: + + [sh $] fundisp foo.fits[bincols=(DX,DY)] + +then "$x" and "$y" will refer to these columns in a call to +FunColumnActivate(). + + +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: + + +=over 4 + + + + +=item * + +B<"pi pha time"> # only these three columns will be active + + +=item * + +B<"-pi -pha -time"> # all but these columns will be active + + +=item * + +B<"pi -pha"> # only pi is active, pha is not, others are not + + +=item * + +B<"+pi -pha"> # same as above + + +=item * + +B<"pi -pha -time"> # only pi is active, all others are not + + +=item * + +B<"pi pha"> # pha and pi are active, all others are not + + +=item * + +B<"pi pha -x -y"> # pha and pi are active, all others are not + + +=back + + + + +You can use the column activation list to reorder columns, since +columns are output in the order specified. For example: + + # 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 + + # 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 + + + +A "+" sign by itself means to activate all columns, so that you can reorder +just a few columns without specifying all of them: + + # 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 + +The column activation/deactivation is performed in the order of the +specified column arguments. This means you can mix "+", "-" (which +de-activates all columns) and specific column names to reorder and +select columns in one command. For example, consider the following: + + # 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 + +We first activate "time", "pi", and "pha" so that they are output first. +We then activate all of the other columns, and then de-activate "x" and "y". +Note that this is different from: + + # 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 + +Here, "x" and "y" are de-activated, but then all columns including "x" and +"y" are again re-activated. + + +Typically, +FunColumnActivate() uses a +list of columns that are passed into the program from the command line. For +example, the code for funtable contains the following: + + char *cols=NULL; + + /* open the input FITS file */ + if( !(fun = FunOpen(argv[1], "rc", NULL)) ) + gerror(stderr, "could not FunOpen input file: %s\n", argv[1]); + + /* set active flag for specified columns */ + if( argc >= 4 ) cols = argv[3]; + FunColumnActivate(fun, cols, NULL); + + +The FunOpen() call sets the +default columns to be all columns in the input file. The +FunColumnActivate() 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: + + funtable test.ev foo.ev "pi pha time" + +will process only the three columns mentioned, while: + + funtable test.ev foo.ev "-time" + +will process all columns except "time". + + +If FunColumnActivate() +is called with a null string, then the environment variable +B<FUN_COLUMNS> 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: + + /* set active flag for specified columns */ + if( argc >= 4 ){ + FunColumnActivate(fun, argv[3], NULL); + } + + + + + +=head1 SEE ALSO + + + +See funtools(n) for a list of Funtools help pages + + +=cut |