Association File Interpretation

Association files serve as FITS tables which relate a set of input files to the generation of calibrated or combined products.

A module which provides utilities for reading, writing, creating and updating association tables and shift files.

author:  Warren Hack, Nadia Dencheva version:  ‘0.1 (2008-01-03)’

class pytools.asnutil.ASNMember(xoff=0.0, yoff=0.0, rot=0.0, xshift=0.0, yshift=0.0, scale=1.0, dshift=False, abshift=False, refimage='', shift_frame='', shift_units='pixels', row=0)

Notes

A dictionary like object representing a member of an association table. It looks like this:

'j8bt06nzq': {'abshift': False,
          'dshift': True,
          'refimage': 'j8bt06010_shifts_asn.fits[wcs]',
          'rot': 359.99829,
          'row': 1,
          'scale': 1.000165,
          'shift_frame': 'input',
          'shift_units': 'pixels',
          'xoff': 0.0,
          'xshift': 0.4091132,
          'yoff': 0.0,
          'yshift': -0.56702018}

If abshift is True, shifts, rotation and scale refer to absolute shifts. If dshift is True, they are delta shifts.

class pytools.asnutil.ASNTable(inlist=None, output=None, shiftfile=None)

Notes

A dictionary like object which represents an association table. An ASNTable object looks like this:

{'members': 
        {'j8bt06nyq': {'abshift': False,
                   'dshift': True,
                   'refimage': 'j8bt06010_shifts_asn.fits[wcs]',
                   'rot': 0.0,
                   'row': 0,
                   'scale': 1.0,
                   'shift_frame': 'input',
                   'shift_units': 'pixels',
                   'xoff': 0.0,
                   'xshift': 0.0,
                   'yoff': 0.0,
                   'yshift': 0.0},
        'j8bt06nzq': {'abshift': False,
                   'dshift': True,
                   'refimage': 'j8bt06010_shifts_asn.fits[wcs]',
                   'rot': 359.99829,
                   'row': 1,
                   'scale': 1.000165,
                   'shift_frame': 'input',
                   'shift_units': 'pixels',
                   'xoff': 0.0,
                   'xshift': 0.4091132,
                   'yoff': 0.0,
                   'yshift': -0.56702018}},
        'order': ['j8bt06nyq', 'j8bt06nzq'],
        'output': 'j8bt06nyq'}

Examples

Creating an ASNTable object from 3 filenames and a shift file would be done using:

>>> asnt=ASNTable([fname1,fname2,  fname3], shiftfile='shifts.txt')

The ASNTable object would have the ‘members’ and ‘order’ in the association table populated based on infiles and shiftfile.

This creates a blank association table from the ASNTable object:

>>> asnt.create()

Parameters :  

`inlist`: a list :

a python list of filenames

`output` a string :

a user specified output name or ‘final’

`shiftfile`: a string :

a name of a shift file, if given, the association table will be updated with the values in the shift file

buildPrimary(fasn, output=None)

create(shiftfile=None)

update(members=None, shiftfile=None, replace=False)

write(output=None)

Purpose :  Write association table to a file.

class pytools.asnutil.ShiftFile(filename='', form='delta', frame=None, units='pixels', order=None, refimage=None, **kw)

A shift file has the following format (name, Xsh, Ysh, Rot, Scale):

# frame: output
# refimage: tweak_wcs.fits[wcs]
# form: delta 
# units: pixels 
j8bt06nyq_flt.fits    0.0  0.0    0.0    1.0
j8bt06nzq_flt.fits    0.4091132  -0.5670202    359.9983    1.000165

This object creates a dict like object representing a shift file used by Pydrizzle and Mirashift.

Purpose :  

Create a dict like ShiftFile object from a shift file on disk or from variables in memory. If a file name is provided all other parameters are ignored.

Parameters :  

`filename`: string :

name of shift file on disk, see above the expected format

`form`: string :

form of shifts (absolute|delta)

`frame`: string :

frame in which the shifts should be applied (input|output)

`units`: string :

in which the shofts are measured (pixels?)

`order`: list :

Keeps track of the order of the files

`refimage`: string :

name of reference image

`**d`: dictionary :

keys: file names values: a list: [Xsh, Ysh, Rot, Scale] The keys must match the files in the order parameter.

Raises :  

ValueError :

If reference file can’t be found

Examples

These examples demonstrate a couple of the most common usages.

1. Read a shift file on disk using:

   >>> sdict = ShiftFile('shifts.txt')
   

2. Pass values for the fields of the shift file and a dictionary with all files:

    >>> d={'j8bt06nyq_flt.fits': [0.0, 0.0, 0.0, 1.0], 
   'j8bt06nzq_flt.fits': [0.4091132, -0.5670202, 359.9983, 1.000165]}
   
    >>> sdict = ShiftFile(form='absolute', frame='output', units='pixels', order=['j8bt06nyq_flt.fits',
    'j8bt06nzq_flt.fits'], refimage='tweak_wcs.fits[wcs]', **d)

The return value can then be used to provide the shift information to code in memory.

readShiftFile(filename)

Reads a shift file from disk and populates a dictionary.

verifyShiftFile()

Verifies that reference file exists.

writeShiftFile(filename='shifts.txt')

Writes a shift file object to a file on disk using the convention for shift file format.

pytools.asnutil.readASNTable(fname, output=None, prodonly=False)

Given a fits filename repesenting an association table reads in the table as a dictionary which can be used by pydrizzle and multidrizzle.

Algorithm :  

An association table is a FITS binary table with 2 required columns: ‘MEMNAME’, ‘MEMTYPE’. It checks ‘MEMPRSNT’ column and removes all files for which its value is ‘no’.

Parameters :  

`fname`: string :

name of association table

`output`: string :

name of output product - if not specified by the user, the first PROD-DTH name is used if present, if not, the first PROD-RPT name is used if present, if not, the rootname of the input association table is used.

`prodonly`: bool :

what files should be considered as input if True - select only MEMTYPE=PROD* as input if False - select only MEMTYPE=EXP as input

Returns :  

`asndict`: dict-object :

A dictionary-like object with all the association information

Examples

An association table can be read from a file using the following commands:

>>> from pytools import asnutil
>>> asntab = asnutil.readASNTable('j8bt06010_shifts_asn.fits', prodonly=False)

The asntab object can now be passed to other code to provide relationships between input and output images defined by the association table.