fits_headers

EffectsMetaKeywords

Adds meta dictionary info from all Effects to the FITS headers.

Parameters

ext_numberint, list of ints, optional

Default 0. The numbers of the extensions to which the header keywords should be added

add_excluded_effectsbool, optional

Default False. Add meta dict for effects with <effect>.include=False

keyword_prefixstr, optional

Default “HIERARCH SIM”. Custom FITS header keyword prefix. Effect meta dict entries will appear in the header as: <keyword_prefix> EFFn <key> : <value>

Examples

Yaml file entry:

name: effect_dumper
class: EffectsMetaKeywords
description: adds all effects meta dict entries to the FITS header
kwargs:
  ext_number: [0, 1]
  add_excluded_effects: False
  keyword_prefix: HIERARCH SIM

ExtraFitsKeywords

Extra FITS header keywords to be added to the pipeline FITS files.

These keywords are ONLY for keywords that should be MANUALLY ADDED to the headers after a simulation is read-out by the detector.

Simulation parameters (Effect kwargs values, etc) will be added automatically by ScopeSim in a different function, but following this format.

The dictionaries should be split into different HIERARCH lists, e.g.:

  • HIERARCH ESO For ESO specific keywords

  • HIERARCH SIM For ScopeSim specific keywords, like simulation parameters

  • HIERARCH MIC For MICADO specific keywords, (unsure what these would be yet)

More HIERARCH style keywords can also be added as needed for other use-cases.

Parameters

filenamestr, optional

Name of a .yaml nested dictionary file. See below for examples

yaml_stringstr, optional

A triple-” string containing the contents of a yaml file

header_dictnested dicts, optional

A series of nested python dictionaries following the format of the examples below. This keyword allows these dicts to be definied directly in the Effect yaml file, rather than in a seperate header keywords file.

Examples

Specifying the extra FITS keywords directly in the .yaml file where the Effect objects are described.

name: extra_fits_header_entries
class: ExtraFitsKeywords
kwargs:
  header_dict:
    - ext_type: PrimaryHDU
      keywords:
        HIERARCH:
          ESO:
            ATM:
              TEMPERAT: -5

The contents of header_dict can also be abstracted away into a seperate file, e.g. extra_FITS_keys.yaml. The file format is described below in detail below.

name: extra_fits_header_entries
class: ExtraFitsKeywords
kwargs:
  filename: extra_FITS_keys.yaml

The Effect can be added directly in an iPython session.

>>> hdr_dic = {"ext_type": "PrimaryHDU",
               "keywords":
                   {"HIERARCH":
                       {"SIM":
                           {"hello": world}
                       }
                   }
               }
>>> extra_keys = ExtraFitsKeywords(header_dict=hdr_dic)
>>> optical_train.optics_manager.add_effect(extra_keys)

Yaml file format

This document is a yaml document. Hence all new keywords should be specified in the form of yaml nested dictionaries. As each astropy.HDUList contains one or more extensions, the inital level is reserved for a list of keyword groups. For example:

- ext_type: PrimaryHDU
  keywords:
    HIERARCH:
      ESO:
        ATM:
          TEMPERAT: -5

- ext_number: [1, 2]
  keywords:
    HIERARCH:
      ESO:
        DET:
          DIT: [5, '[s] exposure length']   # example of adding a comment
    EXTNAME: "DET§.DATA"                   # example of extension specific qualifier

The keywords can be added to one or more extensions, based on one of the following ext_ qualifiers: ext_name, ext_number, ext_type

Each of these ext_ qualifiers can be a str or a list. For a list, ScopeSim will add the keywords to all extensions matching the specified type/name/number

The number of the extension can be used in a value by using the “§” string. That is, keyword values with “§” with have the extension number inserted where the “§” is.

The above example (EXTNAME: "DET§.DATA") will result in the following keyword added only to extensions 1 and 2:

  • PrimaryHDU (ext 0):

    header['HIERARCH ESO ATM TEMPERAT'] = -5
    
  • Extension 1 (regardless of type):

    header['HIERARCH ESO DET DIT'] = (5, '[s] exposure length')
    header['EXTNAME'] = "DET1.DATA"
    
  • Extension 2 (regardless of type):

    header['HIERARCH ESO DET DIT'] = (5, '[s] exposure length')
    header['EXTNAME'] = "DET2.DATA"
    

Resolved and un-resolved keywords

ScopeSim uses bang-strings to resolve global parameters. E.g: from_currsys('!ATMO.temperature') will resolve to a float These bang-strings will be resolved automatically in the keywords dictionary section.

If the keywords bang-string should instead remain unresolved and the string added verbatim to the header, we use the unresolved_keywords dictionary section.

Additionally, new functionality will be added to ScopeSim to resolve the kwargs/meta parameters of Effect objects. The format for this will be to use a new type: the hash-string. This will have this format:

#<optical_element_name>.<effect_name>.<kwarg_name>

For example, the temperature of the MICADO detector array can be accessed by:

'#MICADO_DET.full_detector_array.temperature'

In the context of the yaml file this would look like:

- ext_type: PrimaryHDU
  keywords:
    HIERARCH:
      ESO:
        DET
          TEMPERAT: '#MICADO_DET.full_detector_array.temperature'

Obviously some though needs to be put into how exactly we list the simulation parameters in a coherent manner. But this is ‘Zukunftsmusik’. For now we really just want an interface that can add the ESO header keywords, which can also be expanded in the future for our own purposes.

Below is an example of some extra keywords for MICADO headers:

- ext_type: PrimaryHDU
  keywords:
    HIERARCH:
      ESO:
        ATM:
          TEMPERAT: '!ATMO.temperature'   # will be resolved via from_currsys
          PWV: '!ATMO.pwv'
          SEEING: 1.2
        DAR:
          VALUE: '#<effect_name>.<meta_name>'   # will be resolved via effects
        DPR:
          TYPE: 'some_type'
      SIM:
        random_simulation_keyword: some_value
      MIC:
        micado_specific: ['keyword', 'keyword comment']

  unresolved_keywords:
    HIERARCH:
      ESO:
        ATM:
          TEMPERAT: '!ATMO.temperature'   # will be left as a string

- ext_type: ImageHDU
  keywords:
    HIERARCH:
      SIM:
        hello: world
        hallo: welt
        grias_di: woed
        zdrasviute: mir
        salud: el mundo

SimulationConfigFitsKeywords

Adds parameters from all config dictionaries to the FITS headers.

Parameters

ext_numberint, list of ints, optional

Default 0. The numbers of the extensions to which the header keywords should be added

resolvebool

Default True. If True, all !-strings and #-strings are resolved via from_currsys before being add to the header. If False, the unaltered !-strings or #-strings are added to the header.

keyword_prefixstr, optional

Default “HIERARCH SIM”. Custom FITS header keyword prefix. Effect meta dict entries will appear in the header as: <keyword_prefix> SRCn <key> : <value>

Examples

Yaml file entry:

name: source_descriptor
class: SimulationConfigFitsKeywords
description: adds info from all config dicts to the FITS header
kwargs:
  ext_number: [0]
  resolve: False
  keyword_prefix: HIERARCH SIM

SourceDescriptionFitsKeywords

Adds parameters from all Source fields to the FITS headers.

Parameters

ext_numberint, list of ints, optional

Default 0. The numbers of the extensions to which the header keywords should be added

keyword_prefixstr, optional

Default “HIERARCH SIM”. Custom FITS header keyword prefix. Effect meta dict entries will appear in the header as: <keyword_prefix> SRCn <key> : <value>

Examples

Yaml file entry:

name: source_descriptor
class: SourceDescriptionFitsKeywords
description: adds info from all Source fields to the FITS header
kwargs:
  ext_number: [0]
  keyword_prefix: HIERARCH SIM