pypeit.par.parset module

Define a utility base class used to hold parameters.

class pypeit.par.parset.ParDatabase(inp)[source]

Bases: object

NOTE: This isn’t used in pypeit yet…

Class used as a list of ParSets in a glorified structured numpy array.

Very similar to yanny when converted to a numpy array.

Can be initialized using a list of ParSet objects, or an SDSS parameter file.

Todo

Check that the data types are the same for all ParSet objects in the list
Better handle the NaN values when converting None to a float type
Add from_par_file classmethod?

__getitem__(key)[source]

Return the value of the designated key.

Parameters:: key (str) – Key for new parameter

static _set_dtypes(inp, i)[source]

append(pdb)[source]

class pypeit.par.parset.ParSet(pars, values=None, defaults=None, options=None, dtypes=None, can_call=None, descr=None, cfg_section=None, cfg_comment=None)[source]

Bases: object

Generic base class to handle and manipulate a list of operational parameters. A glorified dictionary that constrains and types its components.

Todo

Write a test for equality?

Parameters:

pars (list) – A list of keywords for a list of parameter values.
values (list, optional) – Initialize the parameters to these values. If not provided, all parameters are initialized to None or the provided default.
defaults (list, optional) – For any parameters not provided in the values list, use these default values. If not provided, no defaults are assumed.
options (list, optional) – Force the parameters to be one of a list of options. Each element in the list can be a list itself. If not provided, all parameters are allowed to take on any value within the allowed data type.
dtypes (list, optional) – Force the parameter to be one of a list of data types. Each element in the list can be a list itself. If not provided, all parameters are allowed to have any data type.
can_call (list, optional) – Flag that the parameters are callable operations. Default is False.
descr (list, optional) – A list of parameter descriptions. Empty strings by default.
cfg_section (str, optional) – The top-level designation for a configuration section written based on the contents of this parameter set.
cfg_comment (str, optional) – Comment to be placed at the top-level of the configuration section written based on the contents of this parameter set.

Raises:

TypeError – Raised if the input parameters are not lists or if the input keys are not strings.
ValueError – Raised if any of the optional arguments do not have the same length as the input list of parameter keys.

npar

Number of parameters

Type:: int

data

Dictionary with the parameter values

Type:: dict

default

Dictionary with the default values

Type:: dict

options

Dictionary with the allowed options for the parameter values

Type:: dict

dtype

Dictionary with the allowed data types for the parameters

Type:: dict

can_call

Dictionary with the callable flags

Type:: dict

descr

Dictionary with the description of each parameter.

Type:: dict

cfg_section

The top-level designation for a configuration section written based on the contents of this parameter set.

Type:: str

cfg_comment

Comment to be placed at the top-level of the configuration section written based on the contents of this parameter set.

Type:: str

__getitem__(key)[source]

Return the value of the designated key.

Parameters:: key (str) – Key for new parameter

__iter__()[source]: Return an iterable to the parameter values.

__len__()[source]: Return the number of parameters.

__repr__()[source]: Return a string representation of the parameters.

__setitem__(key, value)[source]

Set the value for a key.

Parameters:

key (str) – Key for new parameter
value (dtype) – Parameter value, must have a type in the list provided (dtype), if the list is provided

Raises:

ValueError – Raised if the parameter value is not among the allowed options (options).
TypeError – Raised if the parameter value does not have an allowed data type (dtype) or if the provided value is not a callable object, but is expected to be by can_call.

static _config_comment(comment, indent, full_width=72)[source]

Create the list of lines for the description of a given parameter in the configuration file.

Parameters:

comment (str) – The description of the configuration parameter.
indent (str) – The string used to indent the text.
full_width (int, optional) – The full width allowed for each output string in the returned list.

Returns:

List of the strings to write to the output configuration file.

Return type:

list

static _data_string(data, use_repr=True, verbatim=False)[source]

Convert a single datum into a string

Simply return strings, recursively convert the elements of any objects with a __len__ attribute, and use the object’s own __repr__ attribute for all other objects.

Parameters:

data (object) – The object to stringify.
use_repr (bool, optional) – Use the objects __repr__ method; otherwise, use a direct string conversion.
verbatim (bool, optional) – Use quotes around the provided string to indicate that the string should be representated in a verbatim (fixed width) font.

Returns:

A string representation of the provided data.

Return type:

str

static _data_table_string(data_table, delimeter='print')[source]

Provided the array of data, format it with equally spaced columns and add a header (first row) and contents delimeter.

Parameters:: data_table (numpy.ndarray) – Array of string representations of the data to print.
Returns:: Single long string with the data table.
Return type:: str

_output_string(header=None, value_only=False)[source]

Constructs the short-format table strings for the __repr__() method.

Parameters:

header (str, optional) – String header to provide for the table. This is typically the name of the configuration section.
value_only (bool, optional) – By default, the table includes the parameter key, its current value, the default value, its data type, and if the value can be a callable function. If value_only=True, only the parameter key and current value are returned.

Returns:

Single long string with the parameter table for the __repr__() method.

Return type:

str

static _rst_class_name(p)[source]

_types_list(key)[source]: Return the string names for the specified data types.

_wrap_print(head, output, tcols)[source]

Wrap the contents of an output string for a fixed terminal width. Used for the long-format info() method.

Parameters:

head (str) – The inline header for the output. Can be an empty string, but cannot be None.
output (str) – The main body of the text to write.
tcols (int) – The allowed width for the output.

add(key, value, default=None, options=None, dtype=None, can_call=None, descr=None)[source]

Add a new parameter.

Parameters:

key (str) – Key for new parameter
value (dtype) – Parameter value, must have a type in the list provided by dtype, if the list is provided
default (dtype, optional) – Define a default value for the parameter, must have a type in the list provided by dtype, if the list is provided. No default if not provided.
options (list, optional) – List of discrete values that the parameter is allowed to have. Allowed to be anything if not provided.
dtype (list, optional) – List of allowed data types that the parameter can have. Allowed to be anything if not provided.
can_call (bool, optional) – Flag that the parameters are callable operations. Default is False.

Raises:

ValueError – Raised if the keyword alread exists.

static config_lines(par, section_name=None, section_comment=None, section_level=0, exclude_defaults=False, include_descr=True)[source]

Recursively generate the lines of a configuration file based on the provided ParSet or dict (see par).

Parameters:

section_name (str, optional) – Name to give to the top-level of the configuration output.
section_comment (str, optional) – Description to provide for the top-level configuration output.
section_level (int, optional) – The level for the configuration output. Sets the indentation level and the number of square brackets assigned to the section name.
exclude_defaults (bool, optional) – Do not include any parameters that are identical to the defaults.
include_descr (bool, optional) – Include the descriptions of each parameter as comments.

Returns:

The list of the lines to write to a configuration file.

Return type:

list

classmethod from_dict(cfg)[source]

Instantiate a ParSet from a dictionary.

This simply constructs a ParSet that behaves exactly like a dictionary. That is, no constraints are put on the types, options, etc., of the parameters.

Warning

Use of this method of instantiating a ParSet only sets the parameter keys and values, not its other attributes (e.g., options, dtypes, etc). In essentially all use cases, the ParSet should be used as a base class where the from_dict() method is overwritten such that these higher-level attributes of the derived class are maintained in the header I/O. See, e.g., pypeit.par.pypeitpar.

Parameters:: cfg (dict-like) – Dictionary-like object used to set the parameters and parameter values for the ParSet.

classmethod from_header(hdr, prefix=None)[source]

Instantiate the ParSet using data parsed from a fits header.

This is a simple wrapper for ParSet.parse_par_from_hdr() and ParSet.from_dict().

Warning

The to/from header methods in the ParSet base class only saves the parameter keys and values, not its other attributes (e.g., options, dtypes, etc). In essentially all use cases, the ParSet should be used as a base class where the from_dict() method is overwritten such that these higher-level attributes of the derived class are maintained in the header I/O. See, e.g., pypeit.par.pypeitpar.

Parameters:

hdr (astropy.io.fits.Header) – Header object with the parameters.
prefix (str, optional) – Prefix of the relevant header keywords, which overwrites the string defined for the class. If None, uses the default for the class.

info(basekey=None)[source]: A long-form version of __repr__ that includes the parameter descriptions.

keys()[source]: Return the list of parameter set keys.

static parse_par_from_hdr(hdr, prefix)[source]

Parse the dictionary of parameters written to a header

Parameters:

hdr (astropy.io.fits.Header) – Header object to parse.
prefix (str) – The prefix used for the header keywords.

Returns:

A dictionary with the parameter keywords and values.

Return type:

dict

prefix = 'PAR': Class Prefix for header keywords when writing the parset to an astropy.io.fits.Header object.

to_config(cfg_file=None, section_name=None, section_comment=None, section_level=0, append=False, quiet=False, exclude_defaults=False, include_descr=True)[source]

Write/Append the parameter set to a configuration file.

Parameters:

cfg_file (str, optional) – The name of the file to write/append to. If None (default), the function will just return the list of strings that would have been written to the file. These lines can be used to construct a configobj instance.
section_name (str, optional) – The top-level name for the config section. This must be provided if cfg_section is None or any of the parameters are not also ParSet instances themselves.
section_comment (str, optional) – The top-level comment for the config section based on this ParSet.
section_level (int, optional) – The top level of this ParSet. Used for recursive output of nested ParSet instances.
append (bool, optional) – Append this configuration output of this ParSet to the file. False by default. If not appending and the file exists, the file is automatically overwritten.
quiet (bool, optional) – Suppress all standard output from the function.
exclude_defaults (bool, optional) – Do not include any parameters that are identical to the defaults.
include_descr (bool, optional) – Include the descriptions of each parameter as comments.

Raises:

ValueError – Raised if there are types other than ParSet in the parameter list, cfg_section is None, and no section_name argument was provided.

to_header(hdr=None, prefix=None, quiet=False)[source]

Write the parameters to a fits header.

Any element that has a value of None or is a ParSet itself is not written to the header.

Parameters:

hdr (astropy.io.fits.Header, optional) – Header object for the parameters. If provided, the header is not copied and directly modified. If None, the baseline header is empty.
prefix (str, optional) – Prefix to use for the header keywords, which overwrites the string defined for the class. If None, uses the default for the class.
quiet (bool, optional) – Suppress print statements.

Returns:

Header with the parameter data included.

Return type:

astropy.io.fits.Header

to_rst_table(parsets_listed=[])[source]

Construct a reStructuredText table describing the parameter set.

Parameters:: parsets_listed (list, optional) – A list of
Returns:: Returns a list of lines that can be written to an *.rst file.
Return type:: list

validate_keys(required=None, can_be_None=None)[source]