`abscal.common.utils`¶

This module includes general utility functions.

Authors¶

Brian York

Use¶

Individual functions from this module are intended to be imported where needed:

from abscal.common.utils import absdate

Module Contents¶

Functions¶

`absdate`(pstrtime)	Get the date in decimal years.
`get_base_data_dir`()	Find the location of the ABSCAL data files.
`get_data_file`(module, fname[, defaults])	Find an internal data file.
`_extract_dict`(input_dict, output_dict, input_keys)	Recursively extract values from a defaults dictionary.
`get_defaults`(module, *args)	Find an internal defaults data file, load it using YAML, and return the resulting
`set_param`(param, default, row, issues, pre[, ...])	Set a parameter value
`set_params`(defaults, row, issues, pre[, overrides, ...])	Set multiple parameter values
`set_image`(images, row, issues, pre[, overrides, verbose])	Update an image based on known issues.
`air2vac`(air)	Convert a set of wavelengths from air to vacuum.
`smooth_model`(wave, flux, fwhm)	Smooth a model spectrum with a non-uniform sampling interval.
`trapezoidal`(wave, flux, wmin, wmax)	Make a trapezoidal integral
`integral`(x, y, xmin, xmax)	Return the approximate integral of y over x for the range (xmin, xmax)
`tabinv`(xarr, x)	Find the effective index in xarr of each element in x.
`linecen`(wave, spec, cont)	Find the centre of an emission line.

abscal.common.utils.absdate(pstrtime)¶

Get the date in decimal years.

This is used to figure out a target position, given that we have the target co-ordinates, the co-ordinate epoch, the annual proper motion, and the observation time.

Parameters:: pstrtime (str or Time or datetime) – The observation start time
Returns:: dt – The observation year + fractional (decimal) year
Return type:: float

abscal.common.utils.get_base_data_dir()¶

Find the location of the ABSCAL data files.

ABSCAL stores both default parameters and exposure-specific corrections and settings in a number of data files. There are default copies stored internally, but they can also be stored elsewhere. The ABSCAL_DATA environment variable points to that location, although there is always a fallback to local data if a specified file does not exist elsewhere.

Returns:: data_dir – The directory pointed to by ABSCAL_DATA (if both the environment variable and the directory to which it points exist)
Return type:: str

abscal.common.utils.get_data_file(module, fname, defaults=False)¶

Find an internal data file.

Returns the path to a file named fname in the data directory of the (sub)module named module. Keeps there from being a lot of repetitive code in order to find data file paths.

Parameters:

module (str) – The module to search in, using standard dot separators (e.g. abscal.wfc3)
fname (str) – The file name of interest
defaults (bool, default False) – Whether to append a “defaults” directory to the final path

Returns:

data_file – Full path to the data file. If no file is found at the generated path, None will be returned. This is not necessarily a failure state, because (for example) a function may call for a known-issues file even though there are no current known issues (and thus no file to return). This way, the code doesn’t need to be changed when there is a file, and a user can add a file to their local directory without needing to alter the code, because the code will just transparently find the file.

Return type:

str or None

abscal.common.utils._extract_dict(input_dict, output_dict, input_keys)¶

Recursively extract values from a defaults dictionary.

A defaults dictionary consists of:

an optional “all” key
zero or more other keys, each of whose values is a defaults dictionary

The goal is to add any matching values to an output dictionary, with more specific matching values overriding less specific matching values. As such, given an input dictionary and a list of keywords,

Add all key/value pairs from the “all” dictionary (if present) to the output dictionary.
For each keyword in the list, if that keyword is in the dictionary, call this function recursively on the value of that key, which is (see above) a dictionary.
Don’t check on whether a value already exists in the output dictionary, because more-specific overrides less-specific (if you need a default for a specific value to definitely override a more general default, nest that value as a keyword inside the more general dictionary).

Parameters:

input_dict (dict) – The dictionary to search
output_dict (dict) – The dictionary to build from
input_keys (list) – A list of keys to search for

Returns:

output_dict – The edited output dictionary

Return type:

dict

abscal.common.utils.get_defaults(module, *args)¶

Find an internal defaults data file, load it using YAML, and return the resulting dictionary.

Takes the dot-separated module path (e.g. “abscal.wfc3.reduce_grism_extract”), splits off the last item (e.g. [“abscal.wfc3”, “reduce_grism_extract”]), adds “.yaml” to the end of the second item (e.g. [“abscal.wfc3”, “reduce_grism_extract.yaml”]), adds “.defaults” to the first item (e.g. [“abscal.wfc3.defaults”, “reduce_grism_extract.yaml”]), and feeds the result into get_data_file(). Then loads the resulting file as a dictionary, and builds a new dictionary consisting of:

All key/value pairs in the “all” dictionary
All key/value pairs in any dictionary matching any of the keyword arguments
The above two items from any dictionary matching any of the keyword arguments, extending recursively into the depths of the dictionary.

The result will be a flat (i.e. single-level) dictionary.

Parameters:

module (str) – The module to search in, using standard dot separators (e.g. abscal.wfc3)
args (list) – A list of specific keyword arguments, provided to ensure the inclusion of specific sub-values or sub-dictionaries.

Returns:

defaults – Dictionary of default parameters.

Return type:

dict

abscal.common.utils.set_param(param, default, row, issues, pre, overrides={}, verbose=False)¶

Set a parameter value

Given a parameter name, that parameter’s default value, a data table row, and a JSON dictionary which may have an entry for the current row that will override the parameter, return the parameter value that should be used.

Parameters:

param (str) – The parameter to check and return
default (object) – The default value for that parameter
row (abscal.common.exposure_data_table.AbscalDataTable) – A single-row table containing the data of interest.
issues (dict) – A dictionary containing a set of parameters (one of which may be param), along with information to identify files whose parameters should be adjusted .
overrides (dict) – A dictionary containing any parameters whose value is being overridden by the user.
verbose (bool) – Whether or not informational output should be printed.

Returns:

value – The appropriate value for the parameter given

Return type:

object

abscal.common.utils.set_params(defaults, row, issues, pre, overrides={}, verbose=False)¶

Set multiple parameter values

Given a dictionary of default values, a metadata row, a dictionary of known issues and overrides, a dictionary of user-supplied overrides, and a verbose flag, produce a dictionary of parameters (all with the appropriate value) which also contains a ‘set’ key (an array of all the parameters that have been overridden from their default values).

Parameters:

defaults (dict) – A dictionary of default values (also names the parameters)
row (abscal.common.exposure_data_table.AbscalDataTable) – A single-row table containing the data of interest.
issues (dict) – A dictionary containing a set of parameters, along with information to identify files whose parameters should be adjusted.
overrides (dict) – A dictionary containing any parameters whose value is being overridden by the user.
verbose (bool) – Whether or not informational output should be printed.

Returns:

params – The supplied parameters, each with its value.

Return type:

dict

abscal.common.utils.set_image(images, row, issues, pre, overrides={}, verbose=False)¶

Update an image based on known issues.

Given an image, image metadata, and a set of known issues, determine if any of the known issues apply to the image in question and, if they do, make the appropriate edits to the image.

Parameters:

images (dict) – Dict of (SCI, ERR, DQ) np.ndarray images
row (abscal.common.exposure_data_table.AbscalDataTable) – A single-row table containing metadata on the image
issues (dict) – A dictionary containing a set of parameters, along with information to identify files whose parameters should be adjusted.
overrides (dict) – A dictionary containing any parameters whose value is being overridden by the user.
verbose (bool) – Whether or not informational output should be printed.

Returns:

image – Tuple of (SCI, ERR, DQ) np.ndarray images, as edited.

Return type:

tuple

abscal.common.utils.air2vac(air)¶

Convert a set of wavelengths from air to vacuum.

Parameters:: air (array-like) – Air wavelengths
Returns:: vac – Vacuum wavelengths
Return type:: array-like

abscal.common.utils.smooth_model(wave, flux, fwhm)¶

Smooth a model spectrum with a non-uniform sampling interval.

Based on Ralph Bohlin’s “smomod.pro”, which itself references “tin.pro”

Parameters:

wave (array-like) – Wavelength array
flux (array-like) – Flux array
fwhm (float) – FWHM of delta function.

Returns:

smoothed – Smoothed flux array.

Return type:

array-like

abscal.common.utils.trapezoidal(wave, flux, wmin, wmax)¶

Make a trapezoidal integral

Trapezoidal ‘integral’ (really an average) from Ralph Bohlin’s ‘tin.pro’ and ‘integral.pro’. Uses wmin and wmax to set limits

Parameters:

wave (array-like) – Wavelength array
flux (array-like) – Flux array
wmin (array-like) – Wavelength array shifted bluewards by FWHM/2
wmax (array-like) – Wavelength array shifted redwards by FWHM/2

Returns:

trapint – Flux array after trapezoidal integral

Return type:

array-like

abscal.common.utils.integral(x, y, xmin, xmax)¶

Return the approximate integral of y over x for the range (xmin, xmax)

Parameters:

x (array-like) – X value array
y (array-like) – Y value array. Must be the same length as x
xmin (float) – minimum x value for integral
xmax (float) – maximum x value for integral

Returns:

int – integral value

Return type:

float

abscal.common.utils.tabinv(xarr, x)¶

Find the effective index in xarr of each element in x.

The effective index for each element j in x is the value i such that \(xarr[i] <= x[j] <= xarr[i+1]\), to which is added an interpolation fraction based on the size of the intervals in xarr.

Parameters:

x_arr (array-like) – The array of values to search
x (float or array-like) – Value (or list of values) to look for in x_arr

Returns:

ieff – Effective index

Return type:

float

abscal.common.utils.linecen(wave, spec, cont)¶

Find the centre of an emission line.

Computes the centroid of an emission line over the range of

Math:: xapprox pm fwhm/2

after subtracting any continuum and half value at the remaining peak. After clipping at zero, the weights of the remaining spectral wings approach zero, so any marginally missed or included point matters little.

Parameters:

wave (np.ndarray) – 1-d array of x values
spec (np.ndarray) – 1-d array of y values
cont (float) – Approximate continuum value

Returns:

centroid (float) – The x value of the centroid
badflag (bool) – False for good data, true for bad data

abscal.common.utils¶

Authors¶

Use¶

Module Contents¶

Functions¶

`abscal.common.utils`¶