HOW-TO Photometric pipeline(2): transformation tables

The photometric pipeline distinguishes between two types of photometric bands: key bands, and user bands. The key bands are the Sloan \(u'g'r'i'\) bands. These bands are fully supported by the photometric pipeline, and form the core of the contents of the standard star catalog. Any other band than these four Sloan bands is a user band.

Processing data that has been observed in one of the key bands is easy in the photometric pipeline: all the necessary data is present in the system. However, an extra data item is required to process data that has been observed in a user band. This extra data item is a transformation table. For every filter of which the photometric band is a user band, a transformation table should be present in the system. These transformation tables are represented in the photometric pipeline by the PhotTransformation class.

The data structure of a transformation table

The PhotTransformation class represents a table of parameters used to transform magnitudes of standard stars from one photometric system to another (color terms). The equation used to calculate this ‘transformed’ magnitude \(M({\rm T})\) from other bands is:

\[M({\rm T}) = M({\rm prm}) - CT\,\times\,[M({\rm scd}) - M({\rm trt})] + C, \label{transformequation}\]

with \(CT\) the color term, and \(C\) an additional shift that can be applied. The \(M({\rm prm})\), \(M({\rm scd})\) and \(M({\rm trt})\) parameters must each separately be set to any of the bands for which magnitude information is available in the standard star catalog.

The various components of the transform equation all map to their own attribute of a PhotTransformation object. The \(M({\rm prm})\), \(M({\rm scd})\) and \(M({\rm trt})\) parameters respectively map to the primary_band, secondary_band and tertiary_band attributes. These attributes should always be set. The \(CT\) and \(C\) parameters are assigned to the color_term and coefficient attributes of the object. Both these parameters are 0.00 by default. The uncertainties on the two parameters are assigned to the color_term_error and coefficient_error atrtibutes, respectively.

Using a transformation table

The transformation table is used in deriving a photometric catalog, where it is an extra dependency that should be set. The transformation is applied to the magnitudes of the standard stars as recorded in the standard star catalog. As is the case for making a photometric catalog without a transformation table, there are two ways in which catalogs can be produced from the awe-prompt with a transformation table.

Using a pre-cooked recipe

Deriving a photometric catalog with a transformation table using a pre-cooked recipe from the awe-prompt is done thus:

awe> from astro.recipes.PhotCalExtractResulttable import PhotcatTask
awe> raw = 'r336604.fits'
awe> task = PhotcatTask(instrument='WFC', raw=raw, chip='A5506-4', transform=1)
awe> task.execute()

where the extra transform boolean switch tells the system to use a transformation table.

Using the basic building blocks

The more elaborate way of making a photometric catalog is extended by a few extra ‘moves’:

awe> from astro.main.PhotTransformation import PhotTransformation
awe> from astro.main.PhotSrcCatalog import PhotSrcCatalog
awe> from astro.main.PhotRefCatalog import PhotRefCatalog
awe> from astro.main.AstrometricParameters import AstrometricParameters
awe> from astro.main.ReducedScienceFrame import ReducedScienceFrame
awe> frame = (ReducedScienceFrame.filename == 'r336603_4.reduced.fits')[0]
awe> query = (AstrometricParameters.reduced == frame) & (AstrometricParameters.is_valid == 1)
awe> astrom_params = query.max('creation_date')
awe> refcat = PhotRefCatalog.get()
awe> transform = PhotTransformation.get('2003-02-11', '#844', instrument='WFI')
awe> photcat = PhotSrcCatalog()
awe> photcat.refcat = refcat
awe> photcat.transform = transform
awe> photcat.frame = frame
awe> photcat.astrom_params = astrom_params
awe> photcat.refcat.retrieve()
awe> photcat.frame.retrieve()
awe> photcat.frame.weight.retrieve()
awe> photcat.make()
awe> photcat.commit()

In lines (1)-(5), the PhotTransformation class is imported together with the usual suspects. In lines (6)-(10), the necessary dependencies are retrieved from the database. In lines (11)-(19), a PhotSrcCatalog object is instantiated, its dependencies are set, and the make method is called. Please note step (13), where the extra dependency is set with the transformation table. The photometric catalog is committed to the database in step (20).

Retrieving a transformation table from the database

A transformation table for a given filter can be retrieved from the database as shown in the example below:

awe> from astro.main.PhotTransformation import PhotTransformation
awe> transform = PhotTransformation.get('2003-02-11', '#844', instrument='WFI')

which will return the transformation table for filter #844 that is valid for the given date.

Inserting a transformation table into the system

To insert a transformation table for a certain filter and instrument into the database, a simple tool is available. This tool is located in the ./awe/astro/toolbox/photometry/ directory and is called ingest_transformation. To get information about how to use the tool just type:

awe $AWEPIPE/astro/toolbox/photometry/ingest_transformation.py

and a doc-string will appear on screen. The tool only accepts input for filters and instruments that are actually present in the database. If a certain filter or instrument is not present, the tool refuses to comply.