Last modified: December 2019

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/ciao_stacklib.html
AHELP for CIAO 4.15

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 Python by saying:

from ciao_contrib.stacklib import *

Contents

The module provides one routine - make_stackfile() - which is described below.

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. Once you 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.


Examples

Example 1

import paramio
import stk
means = paramio.pget("dmstat", "out_mean")
means = stk.build(means)
mvals = [float(m) for m in means]

Replacement for expand_stack

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 a list comprehension to convert each string element in the means array to a floating-point value.

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 2019 release

The expand_stack routine has been removed. The build routine from the stk module should be used, as it has the same interface.

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.