Explicitly listing all stack elements

The simplest stack is just a comma-separated list of values. For dmstat - which accepts stacks for the infile parameter - this means that the statistics of each file will be calculated separately.

Note that spaces and semi-colons are also valid stack separators, so the following forms are equivalent to the first one:

  unix% dmstat "img1.fits img2.fits"
  unix% dmstat "img1.fits;img2.fits"

When ' ', ',', and ';' do not mean a stack

Comments, spaces, and semi-colons are not treated as stack separators when they appear inside of "()", "[]", or "{}" pairs. So

"evt2.fits[cols time,sky]"

is not treated as a stack.

If a space, comma, or semi-colon is preceeded by a "\" then it is also not treated as a stack separator, i.e. the "\" character is not removed from the text:

  unix% stk_build "img1.fits\,img2.fits" stdout
  img1.fits\,img2.fits

Using UNIX wild-card substitutions

Most UNIX wild-card substitutions are supported, as long as they are protected from being expanded by the shell (which is why quotes are used around img*fits above). Thus if the current directory contained the files img1.fits and img2.fits, the stack expansion would be equivalent to "img1.fits,img2.fits". For this particular example the following would produce the same result:

  unix% dmstat "img?.fits"

Do not use [] as a wild-card expression

Since the "[]" characters are used to indicate a DM virtual-file specification (see "ahelp dmsyntax") they can not be used as a wild-card expression. This means that

"pcad*_[ao]sol1.fits"

will NOT select both the asol1 and osol1 files.

Using an external file

The most common form of specifying a stack is to store the values in an ASCII file and then setting the parameter to "@<filename>".

Thus if imgs.lis contained

  unix% cat imgs.lis
  img1.fits
  img2.fits

then the parameter would be equivalent to "img1.fits,img2.fits".

Recursive expansion

By default, recursive stack expansion is not supported, so if the file contained something like

@more_images.lis

then more_images.lis would NOT be expanded.

As will be shown in a later example, the "@+" syntax can be used to turn on recursive expansion.

Ignoring lines in a stack file

Blank lines and those beginning with a '#' character are excluded from the stack expansion.

Writing a long expression over multiple lines

Stack items can be divided over several lines by ending each line with a '\' character. This feature can be useful to break up dmtcalc expressions:

  unix% cat expr.lis
  GPHASE=(time-TSTART)* \
         (19.794885+(4.79e-13*(time-TSTART)))
  unix% dmtcalc evt2_bary.fits evt2_bary_phase.fits @expr.lis

(this expression is taken from the Create a Phase-binned Spectrum thread with example numbers filled in for the frequency and frequency derivative terms).

Filtering a stack

The syntax "@<filename>[DM expression]" tells the tool to apply the DM expression (as discussed in "ahelp dmsyntax") to each file listed in the file.

So, if imgs.lis contains img1.fits and img2.fits then this syntax is a shortform for setting infile equal to

"img1.fits[sky=region(src.reg)],img2.fits[sky=region(src.reg)]"

Filters can be applied to any form of stack

We can also apply a DM filter to a wild-card. If the current directory contained img1.fits and img2.fits then the above would be the same as setting infile equal to

"img1.fits[sky=region(src.reg)],img2.fits[sky=region(src.reg)]"

Using stacks outside the current directory

If the stack file is in another directory - here /tmp/ - then this directory name will automatically be added onto each entry in the stack.

In this example, if /tmp/img.lis contained img1.fits and img2.fits, then the above syntax would be equivalent to setting infile to

"/tmp/img1.fits,/tmp/img2.fits"

This makes it easy to use stacks in different directories: for instance if you create a file called asol.lis in the directory containing all the asol files for an observation - eg

  unix ls -1 *asol*fits* > asol.lis

then you can use "@/full/path/to/asol.lis" whenever you need these files (such as the acaoffile parameter of acis_process_events).

As will be discussed in the following examples, this behaviour can be over-ridden.

How to avoid the stack changing a file name

Two ways to avoid pre-pending "/tmp/" to the names in the stack file are:

• Include the full path to the file.
• Begin the file name with a ! character.

So, if /tmp/img2.lis contained

  unix% cat/tmp/img2.lis
  /data/Chandra/img1.fits
  !img2.fits
  img3.fits

then the stack would be expanded to

"/data/Chandra/img1.fits,img2.fits,/tmp/img3.fits"

Ignoring the location of a stack file

The "@-" for the third parameter - the hist parameter - of dmimghist tells the stack library not to prepend "/tmp/" to each entry in /tmp/bins.lis. This is useful here because, for dmimghist, the hist parameter does not refer to a list of files but a list of binning specifications.

So, if the contents of the three stacks are:

  unix% cat in.lis
  img1.fits
  img2.fits
  unix% cat out.lis
  hist1.fits
  hist2.fits
  unix% cat /tmp/bins.lis
  1:10:0.2
  -0.5:50:0.5

Then the example above is the equivalent to running

  unix% dmimghist img1.fits hist1.fits 1:10:0.2
  unix% dmimghist img2.fits hist2.fits -0.5:50:0.5

If we had used "@/tmp/bins.lis" instead, dmimghist would have seen the hist parameter set to "/tmp/1:10:0.2,/tmp/-0.5:50:0.5", which does not make sense.

This example also shows that stacks are not just used for input parameters - they can be used to determine the output names of files (here the contents of out.lis).

Recursive stacks

The "@+" syntax tells the tool that any entries in the stack beginnning with a "@" should be treated as stacks, in other words to recursively expand the stack.

If the contents of /tmp/in.lis are:

  unix% cat /tmp/in.lis
  img1.fits
  @in2.lis
  !img2.fits

and

  unix% cat /tmp/in2.lis
  evt2.fits[cols sky]

then the stack is expanded to

"/tmp/img1.fits,/tmp/evt2.fits[cols sky],img2.fits"

Note that here we are not just expanding the contents of in2.lis into the stack but are also prepending the directory name onto the entries (apart from when we explicitly stop this using the "!" syntax). This highlights the fact that the stack expansion rules are cumulative.

Using a linear grid

The lgrid option creates a linear stack of numbers: in this example the sequence 1,2,3,4,5. This stack is then used to filter the FITS region file - reg.fits - using the component column, which creates a stack of 5 regions corresponding to the first 5 entries in reg.fits. The result of this is that dmextract will extract 5 spectra - in PI space - and store the results in a single type II PHA file.

If a stack - of 5 files - had been used for the outfile parameter then dmextrat would instead have created 5 type I PHA files, one for each of the first 5 regions in reg.fits.

Using a rectangular grid

Here we use the rgrid syntax to split the event file up into a stack of rectangular regions based on the chip coordinate system (as well as filtering to ensure that only ccd_id=3 is used). These regions are then binned into images and dmstat run on each image.

The stack expansion in this example comes out to:

evt2.fits[ccd_id=3,chip=rectangle(1,1,33,257)][bin chip]
evt2.fits[ccd_id=3,chip=rectangle(1,257,33,513)][bin chip]
...

Using a polar grid

Here we run dmstat on an image, using a polar grid of regions, which expands to:

img.fits[sky=pie(4123,3950,0,10,0,180)]
img.fits[sky=pie(4123,3950,0,10,180,360)]
img.fits[sky=pie(4123,3950,10,20,0,180)]
img.fits[sky=pie(4123,3950,10,20,180,360)]
img.fits[sky=pie(4123,3950,20,30,0,180)]
img.fits[sky=pie(4123,3950,20,30,180,360)]
img.fits[sky=pie(4123,3950,30,40,0,180)]
img.fits[sky=pie(4123,3950,30,40,180,360)]

Note that the x, y, and radial grids are in the units of the selected coordinate system whereas the theta units are in degrees.