scopesim.effects.fits_headers.ExtraFitsKeywords

scopesim.effects.fits_headers.ExtraFitsKeywords#

class scopesim.effects.fits_headers.ExtraFitsKeywords(cmds=None, **kwargs)#

Bases: Effect

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:

  • filename (str, optional) – Name of a .yaml nested dictionary file. See below for examples

  • yaml_string (str, optional) – A triple-” string containing the contents of a yaml file

  • header_dict (nested 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
__init__(cmds=None, **kwargs)#

Methods

__init__([cmds])

apply_to(hdul, **kwargs)

Add extra fits keywords from a yaml file including !,#-stings.

get_from_meta(item)

info()

Print basic information on the effect, notably the description.

report([filename, output, rst_title_chars])

For Effect objects, generates a report based on the data and meta-data.

Attributes

data

display_name

include

meta_string

required_keys

table

z_order

apply_to(hdul, **kwargs)#

Add extra fits keywords from a yaml file including !,#-stings.

Parameters:

optical_train (scopesim.OpticalTrain, optional) – Used to resolve #-strings

info() → None#

Print basic information on the effect, notably the description.

report(filename=None, output='rst', rst_title_chars='*+', **kwargs)#

For Effect objects, generates a report based on the data and meta-data.

This is to aid in the automation of the documentation process of the instrument packages in the IRDB.

Note

If the Effect can generate a plot, this will be saved to disc

Parameters:

  • filename (str, optional) – Where to save the RST file

  • output (str, optional) – [“rst”, “latex”] Output file format

  • rst_title_chars (2-str, optional) – Two unique characters used to denote rst subsection headings. Options: = - ` : ‘ “ ~ ^ _ * + # < >

  • parameters (Additional)

  • ---------------------

  • **kwargs (Either from the self.meta["report"] dictionary or via)

  • "report_table_include" (False)

  • "report_table_caption"

  • "report_plot_caption"

  • "report_plot_include" (False)

  • "report_plot_file_formats" (["png"]) – Multiple formats can be saved. The last entry is used for the RST.

  • "report_plot_filename" (None) – If None, uses self.meta[“name”] as the filename

  • "file_description" (str) – Taken from the header of a file, if available

  • "class_description" (str) – Taken from the docstring of the subclass

  • "changes_str" (list of str) – Take from the header of a file, if available

Returns:

rst_str – The full reStructureText string

Return type:

str

Notes

The format of the RST output is as follows:

<ClassType>: <effect name>
**************************
File Description: <description for file meta data>
Class Description: <description from class docstring>
Changes: <list of changes from file meta data>

Data
++++
.. figure:: <Figure_name>.png
    If the <Effect> object contains a ``.plot()`` function, add
    plot and write it to disc
Figure caption

Table caption
Table
    If the <Effect> object contains a ``.table()`` function, add
    a pprint version of the table

Meta-data
+++++++++
::
    A code block print out of the ``.meta`` dictionary
Contents