Configuration¶

class sofia_redux.scan.configuration.configuration.Configuration(configuration_path=None, allow_error=False, verbose=False)[source]¶

Bases: Options

A handler for configuration settings used during a SOFSCAN reduction.

The configuration for a SOFSCAN reduction is highly complex and can involve hundreds of specific settings based on user intent or the contents of the data being processed.

Notes

CONDITIONS

How a reduction should proceed are handled by “conditionals”. Conditions are used to perform a set of actions or update the configuration when a specific requirement is met. An example of such is:

[conditionals]
    [[fits.SIBS_X=15.5]]
        subarray = T0, R0

This means that if the SIBS_X keyword value in the FITS header for a certain scan is equal to 15.5, then the value of subarray in the configuration should be set to [‘T0’, ‘R0’]. The first level of conditional keys should always be a requirement of the form <key><operator><value> where <operator> may be replaced by any standard Python conditional operator such as =, ==, !=, <, etc.

For SOFSCAN reductions, there are a few types of condition classes that specifically relate to settings for a given SOFSCAN iteration, the date of observation, the source being observed, and the values in the FITS header. Please see DateRangeOptions, FitsOptions, IterationOptions, and :class:`ObjectOptions for further details.

Note that all processing conditions is necessarily recursive since triggering one condition may allow other condition requirements to be met and so on. This is done during configuration validation, which will indefinitely check and apply conditions until no further changes are detected. Therefore, care should be taken when designing a configuration such that no infinite loops are created.

ALIASES

A feature of the configuration is the ability to alias keys and reference values through the Alias class. A key may be aliased using something like:

[aliases]
    pols = correlated.polarrays
    subs = correlated.subarrays

which means that the “pols” key in the configuration will always refer to the polarrays branch of the correlated options. Values may be referenced in place by using {?<key>} notation, where <key> refers to any other existing key/value in the configuration. For example, jumpdata = {?configpath}/hawc_plus/flux_jump_FS15_v3.fits.gz would replace {?configpath} with the correct value when retrieved from the configuration.

COMMANDS

There are certain keys in the configuration that are used to perform specific actions or set attributes for certain key/values. These are never passed into the set of key/values in the configuration and are processed separately. There are:

blacklist :
Never allow access to this key for any reason. It may not be altered, retrieved, or made visible to the SOFSCAN reduction. A blacklisted key should remain so for the entire reduction.
whitelist :
Always allow access to this key and never allow any modification to its value for the entire reduction.
forget :
Temporarily disable access to this keys value by the SOFSCAN reduction. Access may be granted by using the “recall” command.
recall :
Allow access to a previously forgotten key.
lock :
Do not allow any further modifications to they key values or attributes.
unlock :
Unlock a previously locked key.
add :
Add a key to the configuration. This will set the value of this key to “True” when retrieved by the reduction.
rounds :
Set the maximum number of iterations for the SOFSCAN reduction. The value must be an integer (or reference an integer).
config :
Read and merge the contents of another configuration whose file path is set as the value.

SYNTAX

Configuration files should be formatted according to configobj. A shorthand format may be used to reference multiple configuration levels using a dot separator. For example, correlated.sky.gains.range = 0.3:3 is the same as setting:

[correlated]
    [[sky]]
        [[[gains]]]
            range = 0.3:3

The “fits” key is special and is used to refer to key/values in the FITS header. For example, fits.SPECTEL1 will refer to the SPECTEL1 value in the header, not the configuration.

Initialize a Configuration object for use with a sofia_scan Reduction.

Parameters:

configuration_pathstr, optional: A path to the SOFSCAN configuration directory to be used in the reduction. If not supplied, defaults to <package_path>/data/configurations.
allow_errorbool, optional: If True, allow poorly formatted options to be skipped rather than raising an error.
verbosebool, optional: If True, issues a warning when a poorly specified option is encountered.

Attributes Summary

`blacklisted`	Return the current set of blacklisted keywords.
`command_keys`
`command_order`
`current_iteration`	Return the current iteration of the SOFSCAN reduction
`expected_path`	Return the path to the expected configuration directory.
`handler_keys`
`max_iteration`	Return the maximum number of iterations for the SOFSCAN reduction.
`preserved_cards`	Return the current dictionary of preserved FITS header keyword values.
`section_keys`
`user_path`	Return the path to the user configuration directory.

Methods Summary

`add_new_branch`(key[, value])	Add a new branch to the configuration.
`add_preserved_header_keys`(header)	Add any preserved header keys from the original header to a new header.
`apply_commands`(commands[, command_order])	Apply configuration commands to the configuration.
`apply_configuration_options`(options[, validate])	Apply options to the configuration.
`blacklist`(key)	Blacklists a given key in the configuration.
`check_trigger`(trigger)	Check to see if the requirement for a trigger has been fulfilled.
`clear`()	Clear all options, handler options, and settings.
`configuration_difference`(config)	Return the difference between this configuration and another.
`copy`()	Return a copy of the configuration.
`dot_key_in_set`(key, test_set)	Check if a dot-separated key exists in a given set of strings.
`edit_header`(header)	Add configuration settings to a FITS header.
`exists`(key[, options])	Check if a given key exists in the configuration, even if disabled.
`expand_options`(options)	Convert a potentially dot-separated dictionary to multi-level.
`find_configuration_files`(filename)	Find all matching files in the SOFSCAN configuration directories.
`flatten`(options[, base, basestring, ...])	Transforms a nested dictionary to a single level representation.
`forget`(key)	Forget a key in the configuration.
`get`(*args[, default, unalias])	Retrieve a value from the configuration.
`get_active_options`([options])	Return all options that are not disabled in the configuration.
`get_branch`(*args[, default, unalias])	Retrieve a configuration options branch.
`get_configuration_filepath`(key)	Return a file path from the given options.
`get_filepath`(key[, default, get_all])	Return the file path for a key value in the configuration.
`get_flat_alphabetical`([options, unalias, ...])	Return all configuration keys in a flattened form.
`get_keys`([branch_name])	Return a list of all keys in a given options branch.
`get_options`(*args[, default, unalias])	Retrieve the configuration options for a given key.
`get_preserved_header_keys`()	Return a set of all preserved FITS header keys in the configuration.
`get_section_handler`(section_name)	Return the configuration handler object for a specific section.
`has_option`(key)	Check if a key is available in the configuration.
`is_blacklisted`(key)	Return if a configuration key is blacklisted.
`is_configured`(key)	Check if the given key has a value in the configuration.
`is_disabled`(key)	Return if a configuration key is currently disabled.
`is_locked`(key)	Return if a configuration key is currently locked.
`key_value_to_dict`(key, value)	Convert a string key and a given value to a dictionary.
`lock`(key)	Lock a given configuration key.
`lock_rounds`([max_rounds])	Lock the number of rounds in-place for the reduction.
`matching_set_dot_key`(key, test_set)	Return the dotted key from a test set that relates to `key`.
`matching_wildcard`(string_array, wildcard_pattern)	Find and return all strings in an array matching a given pattern.
`matching_wildcard_keys`(wildcard_key[, ...])	Find all matching configuration keys for a given wildcard.
`merge_fits_options`()	Merge the FITS handler options into the main configuration body.
`merge_options`(merge_options[, options, ...])	Merge a set of options into currently existing options.
`normalize_options`(options)	Convert a dictionary prior to merging into the configuration.
`order_options`([options, unalias])	Order the keys in options alphabetically.
`parse_configuration_body`(options)	Parse configuration options and apply.
`parse_key_value`(key, value)	Parse and apply a key-value pair into the configuration.
`parse_to_section`(key, value)	Parse a key-value as a section update.
`preserve_header_keys`([header])	Assign preserved FITS header keyword values in the configuration.
`priority_file`(filename_or_key)	Returns the highest priority matching filename from configuration.
`purge`(key)	Completely remove a key from the configuration.
`put`(*args[, check])	Set a value in the configuration.
`read_configuration`(config[, validate])	Read a given configuration and apply to this Configuration.
`read_configuration_file`(filename[, validate])	Read and apply a given configuration file.
`read_configurations`(configuration_string[, ...])	Read and apply multiple configurations.
`read_fits`(header_or_file[, extension, validate])	Read contents of a FITS file or header and apply to the configuration.
`recall`(key)	Recall (remember) a given key in the configuration.
`remove_disabled_key`(key)	Enable all disabled branches upto and including key.
`resolve_filepath`(filename)	Return a full file path to the file.
`set_date`(date[, validate])	Set the observation date in the configuration.
`set_error_handling`(allow_error)	Set the error handling for all section handlers.
`set_instrument`(instrument)	Set an instrument for the configuration.
`set_iteration`(iteration[, validate])	Set the current iteration of the reduction in the configuration.
`set_object`(source_name[, validate])	Set the source object in the configuration.
`set_option`(key[, value])	Set an option in the configuration.
`set_outpath`()	Set the output directory based on the configuration.
`set_serial`(serial[, validate])	Sets options based on a scan serial number.
`set_verbosity`(verbose)	Set verbose messages, and do the same for all section handlers.
`unlock`(key)	Unlock a configuration key.
`update`(configuration_options)	Update the configuration options with another set of options..
`update_sections`(options[, validate])	Update sections in the configuration.
`validate`()	Apply all conditions to the configuration.
`whitelist`(key)	Whitelist a configuration key.

Attributes Documentation

blacklisted¶

Return the current set of blacklisted keywords.

Blacklisted keywords should not be accessible or modifiable by the reduction.

Returns:

set (str)

command_keys = ('blacklist', 'whitelist', 'forget', 'recall', 'lock', 'unlock', 'add', 'rounds', 'config')¶

command_order = ('blacklist', 'whitelist', 'unlock', 'config', 'update', 'recall', 'rounds', 'add', 'forget', 'lock')¶

current_iteration¶

Return the current iteration of the SOFSCAN reduction

Returns:

int or None: An integer if the iteration has been set previously, and None otherwise.

expected_path¶

Return the path to the expected configuration directory.

If the .sofscan2 directory is not found in the user home directory, returns the default configuration directory.

Returns:

directorystr

handler_keys = {'aliases', 'conditionals', 'date', 'fits', 'iteration', 'object'}¶

max_iteration¶

Return the maximum number of iterations for the SOFSCAN reduction.

Returns:

int or None: An int if the maximum number of iterations has been set and None otherwise.

preserved_cards¶

Return the current dictionary of preserved FITS header keyword values.

The preserved FITS header cards are those taken from the original FITS file and preserved for later use without fear that they will be modified.

Returns:

dict: A dictionary of the form {keyword: (value, comment)}.

section_keys = {'aliases', 'conditionals', 'date', 'iteration', 'object'}¶

user_path¶

Return the path to the user configuration directory.

Returns:

directorystr

Methods Documentation

add_new_branch(key, value=True)[source]¶

Add a new branch to the configuration.

Parameters:

keystr: The path to the configuration branch to add. Branch levels should be separated by a ‘.’. Note that if key is of the form “my_key_to_set=my_value”, “my_value” will be used in place of value.
valuestr or object: The value to set in the configuration.

Returns:

None

add_preserved_header_keys(header)[source]¶

Add any preserved header keys from the original header to a new header.

Parameters:

headerastropy.io.fits.Header

Returns:

None

apply_commands(commands, command_order=None)[source]¶

Apply configuration commands to the configuration.

Configuration commands are special keywords that instruct the configuration to perform a certain action such as setting an attribute for a certain key value like blacklisting it from any use in the reduction, or locking it’s value in place.

Parameters:

commandsdict or ConfigObj: The commands to apply in {command_name: actions} format, where command_name is a string, and actions may be a dict, list or comma-separated string of actions to apply for the given command name.
command_orderlist (str), optional: The order in which to apply commands. This can be very important since one might wish to unlock a key, set it’s value, and then finally re-lock it’s value in place. If the lock command is issued first, no update may take place etc.

Returns:

None

apply_configuration_options(options, validate=True)[source]¶

Apply options to the configuration.

The dictionary keys in the options are first examined and separated into commands, keyword=value settings, and configuration section updates. Sections will be updated first, followed by single keyword=value updates. Finally, configuration commands will be processed using Configuration.apply_commands().

Parameters:

optionsdict or ConfigObj: The options to apply to the configuration.
validatebool, optional: If True, validate the configuration once the options have been applied.

Returns:

None

blacklist(key)[source]¶

Blacklists a given key in the configuration.

Once a configuration key has been blacklisted, it will be unavailable for retrieval or setting throughout the entire reduction via standard configuration functions. This is a safe way to ensure certain settings are never applied.

Parameters:

keystr: The configuration key to blacklist.

Returns:

None

check_trigger(trigger)[source]¶

Check to see if the requirement for a trigger has been fulfilled.

Parameters:

triggerstr: A trigger of the form <key> or <key><operator><value>. If a single key is provided, the trigger is True so long as the bool value for the key evaluates as such. Otherwise, the value for <key> will be evaluated using <operator> (=, !=, <, <=, >, >=) agains <value>.

Returns:

bool

clear()[source]¶

Clear all options, handler options, and settings.

Returns:

None

configuration_difference(config)[source]¶

Return the difference between this configuration and another.

Parameters:

configConfiguration

Returns:

differenceConfiguration

copy()[source]¶

Return a copy of the configuration.

Returns:

Configuration

dot_key_in_set(key, test_set)[source]¶

Check if a dot-separated key exists in a given set of strings.

The key will be unaliased before any comparison is attempted.

Parameters:

keystr: The key to test.
test_setiterable (str): A list, set, tuple, etc. of strings. If the unaliased key exists in the set, returns True.

Returns:

bool

edit_header(header)[source]¶

Add configuration settings to a FITS header.

Parameters:

headerastropy.fits.Header

Returns:

None

exists(key, options=None)[source]¶

Check if a given key exists in the configuration, even if disabled.

Parameters:

keystr: The key to check.
optionsdict or ConfigObj, optional: The configuration options to check. If not supplied, uses the current configuration options.

Returns:

bool

classmethod expand_options(options)[source]¶

Convert a potentially dot-separated dictionary to multi-level.

Note that no aliasing, checking of values or any other configuration options are performed.

Parameters:

optionsConfigObj or dict: The options to expand.

Returns:

expanded_optionsConfigObj: The options expanded without any dot-separators.

Examples

>>> options = {'write.source': False, 'foo.bar.baz': 1}
>>> print(Configuration.expand_options(options))
{'write': {'source': False}, 'foo': {'bar': {'baz': 1}}}

find_configuration_files(filename)[source]¶

Find all matching files in the SOFSCAN configuration directories.

Checks the base SOFSCAN configuration directory, the user directory, and the instrument directories for any file matching that which is given. Not that alias references may be passed in as filenames too. All output files will exist and be full paths.

Parameters:

filenamestr: The filename to find.

Returns:

fileslist (str): A list of all matching files in the configuration directories.

flatten(options, base=None, basestring='', unalias=True, keep_value=False)[source]¶

Transforms a nested dictionary to a single level representation.

A nested dictionary such as {‘a’: {‘b’: {‘c’: 1}}} will be converted to a dot-separated single level version where dots (“.”) are used to mark different dictionary levels ({‘a.b.c’: 1}).

Parameters:

optionsdict or ConfigObj: The nested dictionary to flatten.
baseConfigObj, optional: The base options to update during recursive calls to flatten. This should not be provided by the user during standard use.
basestringstr, optional: The current dot-string branch representation of a dictionary level during recursive calls to flatten. It should not be provided by the user during standard use.
unaliasbool, optional: If True, unalias all keys.
keep_valuebool, optional: If True, keep .value settings in the configuration.

Returns:

flat_dictionaryConfigObj: A flattened version of options.

forget(key)[source]¶

Forget a key in the configuration.

Disables a given key in the configuration such that it’s value or status may not be altered or retrieved. If key is “blacklist” or “conditions”, all blacklisted keywords or conditions in the configuration will be removed.

Parameters:

keystr: The configuration key to forget.

Returns:

None

get(*args, default=None, unalias=True)[source]¶

Retrieve a value from the configuration.

Parameters:

argstuple (str): The configuration key levels such as [‘correlated’, ‘sky’, ‘biasgains’].
defaultobject, optional: The value to return if not found in the configuration.
unaliasbool, optional: If True, unalias all keys provided in args.

Returns:

valuestr or object: The returned string value if found in the configuration, or default if not found.

get_active_options(options=None)[source]¶

Return all options that are not disabled in the configuration.

Parameters:

optionsConfigObj or dict, optional: The options from which to prune disabled values/branches.

Returns:

enabled_optionsConfigObj

get_branch(*args, default=None, unalias=True)[source]¶

Retrieve a configuration options branch.

Parameters:

argstuple (str): The configuration key levels such as [‘correlated’, ‘sky’].
defaultobject, optional: The value to return if the branch was not found in the configuration.
unaliasbool, optional: If True, unalias all keys provided in args and any retrieved configuration values.

Returns:

branchdict or str or object: The configuration branch if present or default if not.

get_configuration_filepath(key)[source]¶

Return a file path from the given options.

Note that no check is performed to see if the path is valid or exists.

Parameters:

keystr: The configuration key from which to extract the file path.

Returns:

filepathstr or None: A string if found in the configuration, and None otherwise.

get_filepath(key, default=None, get_all=False)[source]¶

Return the file path for a key value in the configuration.

Parameters:

keystr: The name of the configuration key in which the file is referenced.
defaultstr or object, optional: The default file to look for if not found in the configuration.
get_allbool, optional: If True, return all matching file paths for a value found in the configuration. If False, only return a single highest priority file.

Returns:

str or list (str) or None: The highest priority file or a list of all found matching files. None will be returned if no file can be found.

get_flat_alphabetical(options=None, unalias=True, keep_value=False)[source]¶

Return all configuration keys in a flattened form.

The output from this method is a single-level dictionary containing flattened keys and values. A flattened key uses dot-separators to distinguish dictionary levels. E.g., a.b.c:value means {a:b:c:value}. Keys will be ordered alphabetically.

Parameters:

optionsConfigObj or dict, optional: The options to retrieve alphabetical keys. The default are the configuration options.
unaliasbool, optional: If True, unalias all keys.
keep_valuebool, optional: If True, keep .value keys in the configuration.

Returns:

dict

get_keys(branch_name=None)[source]¶

Return a list of all keys in a given options branch.

Parameters:

branch_namestr, optional: The name of the options branch in the configuration. If not supplied, return all first level active configuration branches.

Returns:

keyslist (str)

get_options(*args, default=None, unalias=True)[source]¶

Retrieve the configuration options for a given key.

The options refer to a specific branch of the configuration and must retrieve a dictionary like value. If the key refers to a singular configuration value, the default will be returned instead.

Parameters:

argstuple (str): The configuration key levels such as [‘correlated’, ‘sky’].
defaultobject, optional: The value to return if the options could not be retrieved from the configuration.
unaliasbool, optional: If True, unalias all keys in args before attempting to retrieve a value.

Returns:

optionsdict or str or object: The configuration branch or value if the options were found, or the default value otherwise. The returned options will be a copy of the configuration values, so changing these will have no impact on the actual configuration.

get_preserved_header_keys()[source]¶

Return a set of all preserved FITS header keys in the configuration.

Returns:

set (str)

get_section_handler(section_name)[source]¶

Return the configuration handler object for a specific section.

Note that the FitsOptions handler will not be returned since that configuration processing is handled in a different manner.

Parameters:

section_namestr: The name of the configuration handler to retrieve

Returns:

handlerOptions or None: Either a Aliases, Conditions, DateRangeOptions, IterationsOptions, or None if the section name does not reference a valid handler.

has_option(key)[source]¶

Check if a key is available in the configuration.

Parameters:

keystr: The configuration key to check.

Returns:

availablebool

is_blacklisted(key)[source]¶

Return if a configuration key is blacklisted.

Parameters:

keystr: The configuration key to check.

Returns:

blacklistedbool

is_configured(key)[source]¶

Check if the given key has a value in the configuration.

Parameters:

keystr: The configuration key to check.

Returns:

has_valuebool

is_disabled(key)[source]¶

Return if a configuration key is currently disabled.

Parameters:

keystr: The configuration key to check.

Returns:

disabledbool

is_locked(key)[source]¶

Return if a configuration key is currently locked.

Parameters:

keystr: The configuration key to check.

Returns:

lockedbool

static key_value_to_dict(key, value)[source]¶

Convert a string key and a given value to a dictionary.

The configuration can use a dot (“.”) separator to mark dictionary levels using a string. For example a.b.c = 1 represents [a][b][c] = 1.

Parameters:

keystr: The dot key string to convert.
valuestr or object: The final assigned value.

Returns:

dict

Examples

>>> print(Configuration.key_value_to_dict('a.b.c', 1))
{'a': {'b': {'c': 1}}}

lock(key)[source]¶

Lock a given configuration key.

Once a configuration key has been locked, its current configuration settings cannot be altered via standard configuration functions.

Parameters:

keystr: The configuration key to lock.

Returns:

None

lock_rounds(max_rounds=None)[source]¶

Lock the number of rounds in-place for the reduction.

Parameters:

max_roundsint or str or float, optional: The new maximum number of rounds for the reduction.

Returns:

None

matching_set_dot_key(key, test_set)[source]¶

Return the dotted key from a test set that relates to key.

Parameters:

keystr: The key to find.
test_setiterable (str): A list, set, tuple, etc. of strings. If the unaliased key exists in the set, returns True.

Returns:

str or None: A string if found, and None otherwise.

static matching_wildcard(string_array, wildcard_pattern)[source]¶

Find and return all strings in an array matching a given pattern.

Patterns will be parsed according to fnmatch.fnmatch().

Parameters:

string_arraylist (str): A list of strings from which to find strings matching wildcard_pattern.
wildcard_patternstr: The pattern to match using fnmatch.fnmatch().

Returns:

list (str): A list of strings matching wildcard_pattern from string_array.

matching_wildcard_keys(wildcard_key, flat_dictionary=None)[source]¶

Find all matching configuration keys for a given wildcard.

Wildcards are parsed according to fnmatch.fnmatch(). All configuration keys available in the main configuration body will be checked and returned if found.

Parameters:

wildcard_keystr: The string pattern to search for using fnmatch.fnmatch().
flat_dictionarydict or ConfigObj, optional: A flat dictionary to search through for matching keys. A flat dictionary refers to a single level dictionary. If not supplied, the configuration body is flattened (e.g. [key1][key2] = 1 is converted to key1.key2 = 1).

Returns:

list (str): A list of dot-separated keys that match wildcard_key.

merge_fits_options()[source]¶

Merge the FITS handler options into the main configuration body.

Once a FITS header has been read by the fits handler, this method creates a copy of those key/values in the main configuration body for easy access to the values or advanced handling methods.

Returns:

None

merge_options(merge_options, options=None, chain=None, keep_disabled=False)[source]¶

Merge a set of options into currently existing options.

Merges merge_options into options using rules and settings from the Configuration. Sectional keys such as ‘iteration’ or ‘conditionals’ will be parsed by this Configuration and validated. Note that final validation on the configuration body is not performed and should be done so manually.

FITS header options are NOT handled here, and will essentially be skipped over. However, fits instructions that exist in the configuration will be parsed. FITS header should instead be read in by Configuration.read_fits() and added via Configuration.merge_fits_options().

Parameters:

merge_optionsdict or ConfigObj: The new options that should be merged into options.
optionsdict or ConfigObj, optional: The options which to merge merge_options into. Generally, this should not be supplied by the user and defaults to the main configuration body of options. When supplied, it is usually for recursive calls.
chainlist (str), optional: A list of previously encountered dictionary levels for use during recursive calls. This should generally not be supplied by the user.
keep_disabledbool, optional: If True, allow a configuration value to be changed, but never remove it from the current set of disabled keys.

Returns:

None

normalize_options(options)[source]¶

Convert a dictionary prior to merging into the configuration.

Converts options to a standard multi-level dictionary with all string values. No aliasing is performed.

Parameters:

optionsdict or ConfigObj: The options to normalize.

Returns:

normalized_optionsConfigObj: The normalized options.

order_options(options=None, unalias=False)[source]¶

Order the keys in options alphabetically.

Parameters:

optionsConfigObj or dict, options: The options to order. If not supplied defaults to the configuration options.
unaliasbool, optional: If True, unalias all keys.

Returns:

ordered_optionsConfigObj

parse_configuration_body(options)[source]¶

Parse configuration options and apply.

Will filter out any sectional keys, but set and apply any other options. Note that configuration commands will always be processed last.

Parameters:

optionsdict or ConfigObj: The configuration options to parse.

Returns:

None

parse_key_value(key, value)[source]¶

Parse and apply a key-value pair into the configuration.

This method will firstly unalias any given key. Note that wildcards may be provided (’*’) to apply value to all matching keys found in the configuration. For example, if both “key1” and “key2” exist in the configuration, Configuration.parse_key_value(“key*”, “abc”) will set the value of both to “abc”.

If key relates to a configuration command it will be applied to any value found in value. For example, Configuration.parse_key_value(‘lock’, [‘key1’, ‘key2’]) will lock key1 and key2. Finally, if the key was not a command, it will be processed using Configuration.put() -> Configuration.merge() which will add the key-value to the configuration body, or process it for a certain configuration section.

Parameters:

keystr: The configuration key for which value applies. This may be an actual configuration key, configuration command, or section. Wildcards (’*’) may be used to apply value to more than one configuration key.
valuestr or dict or iterable: The value to apply for key in the configuration.

Returns:

None

parse_to_section(key, value)[source]¶

Parse a key-value as a section update.

Returns True if the key maps to a valid section in the configuration.

Parameters:

keystr: The key to attempt to parse to a section of the configuration.
valuedict or str: The values to parse to the section.

Returns:

parsed_as_sectionbool: True if the key-value successfully mapped to a section of the configuration other than the main body, and False otherwise.

preserve_header_keys(header=None)[source]¶

Assign preserved FITS header keyword values in the configuration.

Parameters:

headerfits.Header, optional: The FITS header from which to extract the keyword values. If not supplied, defaults to the previously read header in the configuration.

Returns:

None

priority_file(filename_or_key)[source]¶

Returns the highest priority matching filename from configuration.

The order of files from lowest to highest priority is: base_configuration -> user_configuration -> base_instrument -> user_instrument

The configuration options in higher priority files overrule those in lower priorities. This returns the highest priority configuration file available.

Parameters:

filename_or_keystr: The name of the file or configuration key. If a matching key is found in the configuration, it takes priority over the filename.

Returns:

str or None: The highest priority matching file, or None if not found.

purge(key)[source]¶

Completely remove a key from the configuration.

Parameters:

keystr

Returns:

None

put(*args, check=True)[source]¶

Set a value in the configuration.

Parameters:

argstuple (str): The last argument (args[-1]) should always contain the value that is being set in the configuration. All values prior to that are considered part of the configuration key. For example, args=(‘correlated’, ‘sky’, ‘biasgains’, ‘0.3:3’) sets {‘correlated’: {‘sky’: {‘biasgains’: ‘0.3:3’}}} in the configuration.
checkbool, optional: If True, check that a key is not locked before attempting to set a value. If it is locked, no changes will be made.

Returns:

None

read_configuration(config, validate=True)[source]¶

Read a given configuration and apply to this Configuration.

Parameters:

configstr or dict or ConfigObj or Configuration: The configuration to read and apply. A string value is assumed to be the file path to a configuration file, and will be read using Configuration.read_configuration_file().
validatebool, optional: If True, validate the configuration following the read. This will examine and apply all conditionals.

Returns:

None

read_configuration_file(filename, validate=True)[source]¶

Read and apply a given configuration file.

Parameters:

filenamestr: The file path to the configuration file.
validatebool, optional: If True, validate the configuration following the read.

Returns:

None

read_configurations(configuration_string, validate=True)[source]¶

Read and apply multiple configurations.

Parameters:

configuration_stringstr: A list of comma separated file paths to configuration files.
validatebool, optional: If True, validate the configuration following a read.

Returns:

None

read_fits(header_or_file, extension=0, validate=True)[source]¶

Read contents of a FITS file or header and apply to the configuration.

Parameters:

header_or_filefits.Header or str: A FITS header or the file path to a FITS file to read.
extensionint, optional: If a file path was passed in as the argument, the extension of the FITS file from which to take the header. The default is the primary (0) extension.
validatebool, optional: If True, fully validate the configuration once the FITS header has been read.

Returns:

None

recall(key)[source]¶

Recall (remember) a given key in the configuration.

Performs a reverse forget operation on the given keyword so that it’s value may be retrieved from the configuration or changed if applicable.

Parameters:

keystr: The configuration key to recall.

Returns:

None

remove_disabled_key(key)[source]¶

Enable all disabled branches upto and including key.

Parameters:

keystr

Returns:

None

resolve_filepath(filename)[source]¶

Return a full file path to the file.

If the file name given is already a complete path, it will be returned. Otherwise, it will be joined with the expected_path and returned. Note that no check is performed to see if the file exists.

Parameters:

filenamestr: The full or partial path to a given file.

Returns:

full_filepathstr

set_date(date, validate=True)[source]¶

Set the observation date in the configuration.

Parameters:

datestr or int or float: The observation date. If a string is used, it should be in ISOT format in UTC scale. Integers and floats will be parsed as MJD times in the UTC scale.
validatebool, optional: If True, validate the configuration once the date has been set.

Returns:

None

set_error_handling(allow_error)[source]¶

Set the error handling for all section handlers.

Parameters:

allow_errorbool: True if errors are permitted during configuration parsing.

Returns:

None

set_instrument(instrument)[source]¶

Set an instrument for the configuration.

Parameters:

instrumentstr or object: Should be the name of the instrument or an object with the instrument name in the “name” attribute. This will have the result of allowing access to configuration files in the <instrument> directory in the configuration path.

Returns:

None

set_iteration(iteration, validate=True)[source]¶

Set the current iteration of the reduction in the configuration.

Parameters:

iterationint: The iteration number.
validatebool, optional: If True, validate the configuration once the iteration number has been set.

Returns:

None

set_object(source_name, validate=True)[source]¶

Set the source object in the configuration.

Parameters:

source_namestr: The name of the astronomical source.
validatebool, optional: If True, validate the configuration once the source has been set.

Returns:

None

set_option(key, value=True)[source]¶

Set an option in the configuration.

The option will always be added as a branch. I.e, a dictionary in the configuration options as {key: {value: value}}. This is in contrast to Configuration.put() which will place the option as {key: value} in certain instances.

Parameters:

keystr: The configuration key to set.
valueobject, optional: The value to set in the configuration.

Returns:

None

set_outpath()[source]¶

Set the output directory based on the configuration.

If the configuration path does not exist, it will be created if the ‘outpath.create’ option is set. Otherwise, an error will be raised.

Returns:

None

set_serial(serial, validate=True)[source]¶

Sets options based on a scan serial number.

Parameters:

serialint
validatebool, optional: If True, validate the whole configuration after setting the serial options.

Returns:

None

set_verbosity(verbose)[source]¶

Set verbose messages, and do the same for all section handlers.

Parameters:

verbosebool: If True, will emit certain log messages that may otherwise be slightly annoying.

Returns:

None

unlock(key)[source]¶

Unlock a configuration key.

If a configuration key was previously locked, unlock that key and allow subsequent changes to it’s status or value in the configuration. Note that blacklisted keys cannot be unlocked.

Parameters:

keystr: The configuration key to unlock.

Returns:

None

update(configuration_options)[source]¶

Update the configuration options with another set of options..

Parameters:

configuration_optionsdict or ConfigObj: The configuration options to read and parse.

Returns:

None

update_sections(options, validate=True)[source]¶

Update sections in the configuration.

The configuration aliases, conditions, dates, iterations, and objects will be updated if present in options.

Parameters:

optionsdict or ConfigObj.: A dictionary used to update the sections.
validatebool, optional: If True, validate the configuration once all sections have been updated.

Returns:

None

validate()[source]¶

Apply all conditions to the configuration.

Returns:

None

whitelist(key)[source]¶

Whitelist a configuration key.

Whitelisting a configuration key removes it from the blacklist if set and unlocks it. It will still be disabled however. Locked options cannot be whitelisted.

Parameters:

keystr: The configuration key to whitelist.

Returns:

None

Navigation

Configuration¶