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?
- 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.
- cfg_section
The top-level designation for a configuration section written based on the contents of this parameter set.
- Type:
- cfg_comment
Comment to be placed at the top-level of the configuration section written based on the contents of this parameter set.
- Type:
- __getitem__(key)[source]
Return the value of the designated key.
- Parameters:
key (str) – Key for new parameter
- __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 bycan_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:
- Returns:
List of the strings to write to the output configuration file.
- Return type:
- static _data_string(data, use_repr=False, 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:
- Returns:
A string representation of the provided
data
.- Return type:
- 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:
- _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:
- _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.
- 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 parametervalue (
dtype
) – Parameter value, must have a type in the list provided by dtype, if the list is provideddefault (
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
ordict
(seepar
).- 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:
- 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, theParSet
should be used as a base class where thefrom_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()
andParSet.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, theParSet
should be used as a base class where thefrom_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.
- static parse_par_from_hdr(hdr, prefix)[source]
Parse the dictionary of parameters written to a header
- 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 ifcfg_section
is None or any of the parameters are not alsoParSet
instances themselves.section_comment (
str
, optional) – The top-level comment for the config section based on thisParSet
.section_level (
int
, optional) – The top level of thisParSet
. Used for recursive output of nestedParSet
instances.append (
bool
, optional) – Append this configuration output of thisParSet
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: