Chandra X-Ray Observatory
	(CXC)
Skip to the navigation links
Last modified: November 2012

URL: http://cxc.harvard.edu/ciao/ahelp/ciao_stacklib.html
AHELP for CIAO 4.9

ciao_stacklib

Context: contrib

Synopsis

Support routines for using stacks in CIAO (CIAO contributed package).

Syntax

from ciao_contrib.stacklib import *

Description

The ciao_contrib.stacklib module provides one utility routine for using CIAO stacks, and is provided as part of the CIAO contributed scripts package.

Loading the routine

The module can be loaded into ChIPS or Sherpa by saying:

from ciao_contrib.stacklib import *

Contents

The module provides two routines - expand_stack() and make_stackfile() - which are described below.

expand_stack

This routine is now deprecated (as of CIAO 4.5) since the build() routine from the CIAO stk module has the same functionality.

The expand_stack() routine takes a single argument - a string - and expand it using the stack libeary into an array of strings. If the input argument is called pval, the following table shows the value returned by expand_stack() for a range of inputs, where we have

chips> cat files.lis
src1/a.fits 
src2/b.fits
Input (pval) Output from expand_stack(pval)
"src.fits" ["src.fits"]
"src1.fits,src2.fits" ["src1.fits", "src2.fits"]
"src1.fits[cols x,y] src2.fits[bin sky;energy]" ["src1.fits[cols x,y]", "src2.fits[bin sky;energy]"]
"@src.lis" ["src1/a.fits", "src2/b.fits"]
"@src.lis[cols time,energy]" ["src1/a.fits[cols time,energy]", "src2/b.fits[cols time,energy]"]
"evt2.fits[ccd_id=lgrid(0:3:1)]" ["evt2.fits[ccd_id=0]", "evt2.fits[ccd_id=1]", "evt2.fits[ccd_id=2]", "evt2.fits[ccd_id=3]"]

make_stackfile

The routines in the ciao_contrib.runtool module will convert array inputs to stack syntax, but sometimes it can be useful to use make_stackfile() to create a temporary stack file directly. The routine takes an array of strings and writes them out to a temporary file, returning a reference to the temporary file. This can then be used as input to tools that require a stack. The file itself will be deleted when the variable goes out of scope, or it's close() method is called.

The routine's signature is:

make_stackfile(infiles, dir="/tmp/", suffix='')

where infiles is the list of files to write as a stack and the dir and suffix arguements are used by tempfile.NamedTemporaryFile to create the temporary file (dir determines where the file is created and suffix gives the suffix of the file). The return value is a NamedTemporaryFile instance, so the .name attribute gives the name of the file.

So, after

stk = make_stackfile(["foo.fits", "bar.fits", "baz.fits"])
stkname = "@" + stk.name

you can use the stkname variable as input to a tool that accepts a stack. Onceyou have finished with the stack you can call

stk.close()

or just let the stk variable go out of scope.

Each element of infiles is taken to be a file name relative to the current working directory; the absolute path is used when writing the value out to the stack file so that it can be written to a different location. See 'ahelp stack' for more information on how relative and absolute paths are handled by the stack library.

This routine is somewhat experimental and may be removed.

Example 1

import paramio
import stk
means = paramio.pget("dmstat", "out_mean")
means = stk.build(means)
means = map(float, means)

In this example we get the out_mean parameter of dmstat, which can contain multiple values as a stack, and use the build routine from the stk module to convert it into an array of strings. The final line uses the Python map command to apply the float routine to each element of means, converting the string into a floating-point value.

We could have instead used

import ciao_contrib.stacklib as stacklib
means = stacklib.expand_stack(means)

but this approach is deprecated, as of CIAO 4.5, in favor if stk.build().

Example 2

import ciao_contrib.runtool as rt
from ciao_contrib.stacklib import make_stackfile
tmpfile = make_stackfile(images)
nimages = len(images)
opstr = '+'.join(["img{}".format(i) for i in range(nimages+1)])
opstr = "imgout=" + opstr
rt.dmimgcalc(infile='@' + tmpfile.name, outfile='out.img',
operation=opstr)
tmptile.close()

In this example we assume that images is an array of names of images that we want to add up to create the file out.img. Since the dmimgcalc tool can accept a stack for its infile argument we use make_stackfile to create a temporary file containing all the file names, and pass it to dmimgcalc iwth a leading '@' character. Since we need to tell dmimgcalc how to combine the images we use Python list comprehension to create a string of the form

imgout=img1+...+imgn

where n is the number of images to combine.

Note

In this particular example, if we did not want to re-use the stack file after the dmimgcalc call, we could have taken advantage of the stack support provided by the ciao_contrib.runtool module to say:

rt.dmimgcalc(infile=images, outfile='out.img', operation=opstr)

and so avoid the need for using make_stackfile.

Changes in the December 2012 release

The expand_stack() routine is deprecated; please use stk.build() instead.

Bugs

See the bugs pages for an up-to-date listing of known bugs.

Refer to the CIAO bug pages for an up-to-date listing of known issues.


Last modified: November 2012
Smithsonian Institute Smithsonian Institute

The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA.   Email:   cxchelp@head.cfa.harvard.edu Smithsonian Institution, Copyright © 1998-2017. All rights reserved.