NAME

Astro::FITS::HdrTrans - Translate FITS headers into generic headers and back again

SYNOPSIS

  use Astro::FITS::HdrTrans qw/ translate_from_FITS translate_to_FITS /;

  %generic_headers = translate_from_FITS(\%FITS_headers);

  %FITS_headers = translate_to_FITS(\%generic_headers);

DESCRIPTION

Converts information contained in instrument-specific FITS headers to and from generic headers. A list of generic headers are given at the end of the module documentation.

REVISION

$Id: HdrTrans.pm,v 1.18 2003/09/16 02:23:36 bradc Exp $

PUBLIC VARIABLES

The following variables are not exported by default, but can be exported.

@generic_headers

Provides a list of generic headers that may or may not be available in the generic header hash, depending on if translations were set up for these headers in the instrument-specific subclasses.

Currently only the time-related headers (UTSTART, UTEND, and UTDATE) have type-checking done; these three generic headers must be returned as Time::Piece objects when translating from FITS headers into generic headers, and must be given as Time::Piece objects when translating from generic headers back into FITS headers. A warning is raised if any of these headers are not Time::Piece objects.

PRIVATE VARIABLES

The following variables are private to this module.

@valid_classes

This parameter is a list of valid classes for which translations can be made. A class in this list does not include the Astro::FITS::HdrTrans prefix. For example, if the Astro::FITS::HdrTrans::IRCAM class were to be used for translations, this list would include only IRCAM.

Values in this list are case-sensitive.

Values in this list can be added to using the push_class method.

PUBLIC METHODS

The following methods are not exported by default, but can be exported.

translate_from_FITS

Converts a hash containing instrument-specific FITS headers into a hash containing generic headers.

  %generic_headers = translate_from_FITS(\%FITS_headers,
                                         class => \@classes,
                                         prefix => 'ORAC_',
                                        );

This method takes a reference to a hash containing untranslated headers, and a hash reference containing the following optional keys:

*

class - A reference to a list of subclasses to try to use for header translations. This list overrides the default list. If left blank, the default list will be used.

*

prefix - A string prefix to add to the front of every translated header name. For example, if this prefix is set to 'ORAC_', then the translated header for the instrument value, whose key is normally 'INSTRUMENT', will have a key named 'ORAC_INSTRUMENT'. The original keys will not be in the returned hash. If left blank, no prefix will be added.

This method returns a hash of generic headers.

translate_to_FITS

Converts a hash containing generic headers into one containing instrument-specific FITS headers.

  %FITS_headers = translate_to_FITS(\%generic_headers,
                                    class => \@classes,
                                   );

This method takes a reference to a hash containing untranslated headers, and a hash reference containing the following optional keys:

*

class - A reference to a list of subclasses to try to use for header translations. This list overrides the default list. If left blank, the default list will be used.

*

prefix - A string prefix to remove from the generic header key before doing header translation. Why you would want to do this is if you've used a prefix in the translate_from_FITS call, and want to translate back from the generic headers returned from that method. If left blank, no prefix will be removed.

This method returns a hash of instrument-specific headers.

push_class

Allows another class to be pushed onto the list of valid classes.

  push_class( \@classes );
  push_class( $class );

If an array reference is passed, all classes contained in that array will be added to the list. If a scalar is passed, that single class will be added to the list.

GENERIC HEADERS

The following is a list of currently-supported generic headers. If no type is defined for the header, then it is assumed to be a scalar in any format.

AIRMASS_START - Airmass at the start of the observation.

AIRMASS_END - Airmass at the end of the observation.

ALTITUDE - Telescope altitude. Must be in meters above mean sea level.

AZIMUTH_START - Telescope azimuth at the start of the observation.

AZIMUTH_END - Telescope azimuth at the end of the observation.

BACKEND - Backend used.

BOLOMETERS - Number of bolometers used in array.

CAMERA - Camera used for observation.

CHOP_ANGLE - Chop angle.

CHOP_COORDINATE_SYSTEM - Coordinate system used for chopping.

CHOP_THROW - Distance of chop throw.

CONFIGURATION_INDEX - Unique identifier for hardware configuration.

COORDINATE_UNITS - Units of coordinate system.

COORDINATE_TYPE - Type of coordinate (typically B1950 or J2000).

CYCLE_LENGTH - Length of observation cycle.

DEC_BASE - Base declination position of observation. Must be a string in colon-delimited sexagesimal format (ie. +41:16:09.4), where the degrees, minutes, and seconds are zero-padded to two digits.

DEC_SCALE - Pixel scale in declination.

DEC_SCALE_UNITS - Units for declination pixel scale.

DEC_TELESCOPE_OFFSET - Offset in declination from base position. Must be in arcseconds.

DETECTOR_BIAS - Detector bias.

DETECTOR_INDEX - Position number in detector scan.

DETECTOR_READ_TYPE - Read type of detector.

DR_GROUP - Data reduction group to which observation belongs.

DR_RECIPE - Data reduction recipe to be used.

ELEVATION - Elevation of telescope above sea level.

ELEVATION_START - Telescope elevation at the start of the observation. Must be in degrees. 90 is zenith, 0 is horizon.

ELEVATION_END - Telescope elevation at the end of the observation. Must be in degrees. 90 is zenith, 0 is horizon.

EPOCH - Epoch in which observation was taken.

EQUINOX - Equinox in which observation was taken.

EXPOSURE_TIME - Exposure time of observation. Must be in decimal seconds.

FILENAME - Name of data file.

FILTER - Filter in which observation was taken.

GAIN - Detector gain.

GALACTIC_LATITUDE - Galactic latitude of observation. Must be a colon-separated sexagesimal string (ie. 121:10:12).

GALACTIC_LONGITUDE - Galactic longitude of observation. Must be a colon-separated sexagesimal string (ie. -21:34:12).

GRATING_DISPERSION - Wavelength dispersion.

GRATING_NAME - Name of grating/grism used.

GRATING_ORDER - Order of grating/grism used.

GRATING_WAVELENGTH - Central wavelength of grating/grism used.

INSTRUMENT - Instrument name.

INST_DHS - Unique combination of instrument name and data handling system.

LATITUDE - Latitude of telescope. Must be a colon-separated sexagesimal string (ie. 19:49:20.75).

LONGITUDE - Longitude of telescope. Must be a colon-separated sexagesimal string (ie. -155:28:13.18).

MSBID - Unique identifier for minimum schedulable block.

NSCAN_POSITIONS - Number of scan positions.

NUMBER_OF_COADDS - Number of coadds.

NUMBER_OF_CYCLES - Number of cycles.

NUMBER_OF_DETECTORS - Number of detectors.

NUMBER_OF_EXPOSURES - Number of exposures.

NUMBER_OF_OFFSETS - Number of offsets in dither pattern.

NUMBER_OF_READS - Number of reads.

NUMBER_OF_SUBFRAMES - Number of subframes.

OBJECT - Object name.

OBSERVATION_MODE - Mode of observation for multi-mode instruments.

OBSERVATION_NUMBER - Number of observation.

OBSERVATION_TYPE - Type of observation (ie. DARK, FLAT, etc.)

POLARIMETRY - Polarimetry mode?

PROJECT - Project name.

RA_BASE - Base right ascension position of observation. Must be a colon-delimited sexagesimal string (ie. 00:42:44.31).

RA_SCALE - Pixel scale in right ascension.

RA_SCALE_UNITS - Units for right ascension pixel scale.

RA_TELESCOPE_OFFSET - Offset in right ascension from base position. Must be in arcseconds.

REST_FREQUENCY - Rest frequency of spectral line.

ROTATION - Angle of the declination axis with respect to the frame's y axis, measured counter-clockwise.

SAMPLING - Sampling type.

SCAN_INCREMENT - Increment of scan.

SEEING - Seeing when observation was taken.

SLIT_ANGLE - Angle of slit on sky.

SLIT_NAME - Name of slit used.

SLIT_WIDTH - Width of slit.

SPEED_GAIN - Readout speed.

STANDARD - Is observation of a standard?

SYSTEM_VELOCITY - System velocity.

TAU - Atmospheric extinction at time of observation.

TELESCOPE - Name of telescope.

UTDATE - UT date on which observation was taken. Must be a Time::Piece object.

UTEND - End time of observation. Must be a Time::Piece object.

UTSTART - Start time of observation. Must be a Time::Piece object.

VELOCITY -

VELSYS -

WAVEPLATE_ANGLE - Polarimetry waveplate angle.

X_BASE - Base x-position of observation.

Y_BASE - Base y-position of observation.

X_OFFSET - Offset in x-direction from base position.

Y_OFFSET - Offset in y-direction from base position.

X_SCALE - Pixel scale in x-direction.

Y_SCALE - Pixel scale in y-direction.

X_DIM - Size of array in x-direction.

Y_DIM - Size of array in y-direction.

X_LOWER_BOUND - Lower bound of array in x-direction.

X_UPPER_BOUND - Upper bound of array in x-direction.

Y_LOWER_BOUND - Lower bound of array in y-direction.

Y_UPPER_BOUND - Upper bound of array in y-direction.

ZENITH_DISTANCE_START - Zenith distance at start of observation.

ZENITH_DISTANCE_END - Zenith distance at end of observation.

NOTES

• A number of the generic headers are more easily represented by objects. For example, all headers to do with the object coordinates (DEC_BASE, COORDINATE_UNITS, COORDINATE_TYPE, EPOCH, EQUINOX, and RA_BASE) are be better represented with a single Astro::Coords object. Such headers will at some point be merged into a single object header, but for backwards compatibility will be retained.

AUTHOR

Brad Cavanagh <b.cavanagh@jach.hawaii.edu>

COPYRIGHT

Copyright (C) 2003 Particle Physics and Astronomy Research Council. All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.