astro_metadata_translator

The astro_metadata_translator package provides generalized infrastructure for handling metadata extraction for astronomical instrumentation.

There are header translation classes implemented as subclasses of MetadataTranslator. These translation subclasses implement methods corresponding to each derived property defined in ObservationInfo. The methods are named to_{property} and can be implemented explicitly by a translation class, or implicitly by defining trivial mappings from a header item to a property, or constant mappings that are fixed for all headers independent of any header values. Defining a new translator subclass that inherits from MetadataTranslator and giving it a name, automatically registers the translator as being available for automated header translation. A translation class does not need to reside in the astro_metadata_translator package.

ObservationInfo is a class summarizing the information from the translators. An instance of this class can be instantiated from any dict-like header. By default the header translation class to use is determined by asking each registered translator whether it knows how to translate it. If an explicit translation class should be used it can be specified explicitly.

For details on the format of header correction files see fix_header.

Warning

The existing set of property names in ObservationInfo should be considered as beta quality. Some of the names could yet be changed for consistency with other data dictionaries.

Project info

Repository

https://github.com/lsst/astro_metadata_translator

JIRA component

https://jira.lsstcorp.org/issues/?jql=component%3Dastro_metadata_translator

Command Line Utilities

astrometadata

Execute main click command-line.

astrometadata [OPTIONS] COMMAND [ARGS]...

Options

--log-level <log_level>

Python logging level to use.

Options:

CRITICAL | ERROR | WARNING | INFO | DEBUG

--traceback, --no-traceback

Give detailed trace back when any errors encountered.

-p, --packages <packages>

Python packages to import to register additional translators. This is in addition to any packages specified in the METADATA_TRANSLATORS environment variable (colon-separated python module names).

dump

Dump data header to standard out in YAML format.

astrometadata dump [OPTIONS] [FILES]...

Options

-n, --hdrnum <hdrnum>

HDU number to read. If the HDU can not be found, a warning is issued but reading is attempted using the primary header. The primary header is always read and merged with this header. Negative number (the default) indicates that the second header will be merged if the FITS file supports extended FITS.

-m, --mode <mode>

Output mode. ‘yaml’ dumps the header in YAML format (this is the default). ‘fixed’ dumps the header in YAML format after applying header corrections. ‘yamlnative’ is as for ‘yaml’ but dumps the native (astropy vs PropertyList) native form. ‘yamlfixed’ is as for ‘fixed’ but dumps the native (astropy vs PropertyList) native form.

Options:

yaml | fixed | yamlnative | fixexnative

-r, --regex <regex>

When looking in a directory, regular expression to use to determine whether a file should be examined. Default: ‘.fit[s]?b’

Arguments

FILES

Optional argument(s)

translate

Translate metadata in supplied files and report.

astrometadata translate [OPTIONS] [FILES]...

Options

-q, --quiet, --no-quiet

Do not report the translation content from each header. Only report failures.

-n, --hdrnum <hdrnum>

HDU number to read. If the HDU can not be found, a warning is issued but reading is attempted using the primary header. The primary header is always read and merged with this header. Negative number (the default) indicates that the second header will be merged if the FITS file supports extended FITS.

-m, --mode <mode>

Output mode. ‘verbose’ prints all available information for each file found. ‘table’ uses tabular output for a cutdown set of metadata. ‘auto’ uses ‘verbose’ if one file found and ‘table’ if more than one is found.

Options:

auto | verbose | table

-r, --regex <regex>

When looking in a directory, regular expression to use to determine whether a file should be examined. Default: ‘.fit[s]?b’

Arguments

FILES

Optional argument(s)

write-index

Write JSON index file for entire directory.

astrometadata write-index [OPTIONS] [FILES]...

Options

-n, --hdrnum <hdrnum>

HDU number to read. If the HDU can not be found, a warning is issued but reading is attempted using the primary header. The primary header is always read and merged with this header. Negative number (the default) indicates that the second header will be merged if the FITS file supports extended FITS.

-r, --regex <regex>

When looking in a directory, regular expression to use to determine whether a file should be examined. Default: ‘.fit[s]?b’

-c, --content <content>

Content to store in JSON file. Options are: ‘translated’ stores translated metadata in the file; ‘metadata’ stores raw FITS headers in the file.

Options:

translated | metadata

-o, --outpath <outpath>

If given, write a single index with all information in specified location. Default is to write one index per directory where files are located.

Arguments

FILES

Optional argument(s)

write-sidecar

Write JSON sidecar files alongside each data file.

astrometadata write-sidecar [OPTIONS] [FILES]...

Options

-n, --hdrnum <hdrnum>

HDU number to read. If the HDU can not be found, a warning is issued but reading is attempted using the primary header. The primary header is always read and merged with this header. Negative number (the default) indicates that the second header will be merged if the FITS file supports extended FITS.

-r, --regex <regex>

When looking in a directory, regular expression to use to determine whether a file should be examined. Default: ‘.fit[s]?b’

-c, --content <content>

Content to store in JSON file. Options are: ‘translated’ stores translated metadata in the file; ‘metadata’ stores raw FITS headers in the file.

Options:

translated | metadata

Arguments

FILES

Optional argument(s)

Python API reference

astro_metadata_translator Package

Functions

cache_translation(func[, method])	Cache the result of a translation method.
fix_header(header[, search_path, ...])	Update, in place, the supplied header with known corrections.
makeObservationInfo(*[, extensions])	Construct an ObservationInfo from the supplied parameters.
merge_headers(headers[, mode, sort, first, last])	Merge multiple headers into a single dict.

Classes

DecamTranslator(header[, filename])	Metadata translator for DECam standard headers.
FitsTranslator(header[, filename])	Metadata translator for FITS standard headers.
HscTranslator(header[, filename])	Metadata translator for HSC standard headers.
MegaPrimeTranslator(header[, filename])	Metadata translator for CFHT MegaPrime standard headers.
MetadataTranslator(header[, filename])	Per-instrument metadata translation support.
ObservationGroup(members[, ...])	A collection of ObservationInfo headers.
ObservationInfo(header[, filename, ...])	Standardized representation of an instrument header for a single exposure observation.
PropertyDefinition(doc, str_type, py_type[, ...])	Definition of an instrumental property.
SdssTranslator(header[, filename])	Metadata translator for SDSS standard headers.
StubTranslator(header[, filename])	Translator where all the translations are stubbed out and issue warnings.
SubaruTranslator(header[, filename])	Metadata translator for Subaru telescope headers.
SuprimeCamTranslator(header[, filename])	Metadata translator for HSC standard headers.

Class Inheritance Diagram

astro_metadata_translator.indexing Module

Functions to support file indexing.

Functions

read_index()	Read an index file.
read_sidecar(path)	Read a metadata sidecar file.
calculate_index(headers, content_mode)	Calculate an index data structure from the supplied headers.
index_files(files, root, hdrnum, ...[, ...])	Create an index from the supplied files.
process_index_data()	Process the content read from a JSON index file.
process_sidecar_data()	Process the content read from a JSON sidecar file.

astro_metadata_translator.file_helpers Module

Support functions for script implementations.

These functions should not be treated as part of the public API.

Functions

find_files(files, regex)	Find files for processing.
read_basic_metadata_from_file(file, hdrnum)	Read a raw header from a file, merging if necessary.
read_file_info(file, hdrnum[, print_trace, ...])	Read information from file.