ACID_code.utils

All of the utility functions for the ACID package. Some functions may not be useful to the user.

Functions

`auto_window`(taus[, c])	Automated windowing procedure following Sokal (1989) in emcee documentation.
`autocorr_func_1d`(x[, norm])	Autocorrelation estimate using FFT from the emcee tutorial.
`autocorr_gw2010`(y[, c])	Goodman & Weare (2010) autocorrelation estimate from emcee documentation
`autocorr_new`(y[, c])	New integrated autocorrelation time estimate from emcee documentation
`backend_to_sampler`(backend, log_prob_fn)
`calc_deltav`(wavelengths)	Calculates velocity pixel size
`clip_wavelengths`(wavelengths, ...[, pad])	Clips the linelist to only include lines within the wavelength range of the observed spectrum.
`collapse_SNR`(sn, wavelengths)	Collapses the SN of a 1D or 2D wavelength and sn array to the median of the SNs on the central 2/3 wavelengths.
`combine_profiles`(spectra[, errors, covariances])	Combine multiple profiles into one.
`configure_mp_environ`(os)	Configures the multiprocessing environment variables to check for SLURM and set appropriate thread limits.
`convert_moves_to_emcee`(moves)	Converts a list of move specifications to emcee moves.
`drop_edges`(array[, n_pix])	Drops the edges of an array by a specified number of pixels.
`drop_invalid`(wavelengths, flux[, errors, ...])	Drops any pixels where the wavelength, flux, or error is infinite or <= 0.
`findfiles`(directory, file_type)	Finds files in a directory matching a specific file type, excluding corrected spectra.
`flux_to_od`([flux, errors, linelist, cov_matrix])	Converts flux, errors, linelist, and covariance matrix to optical depth.
`get_available_memory`()	Returns the available memory in bytes.
`get_normalisation_coeffs`(wl)	Calculates normalization coefficients for wavelength array
`guess_SNR`(frame_wavelengths, frame_flux, ...)	Estimates S/N for each frame.
`guess_errors`(frame_wavelengths, frame_flux, ...)	Estimates errors for each frame based on the flux and S/N.
`mask_invalid`(wavelengths, flux[, errors, ...])	Masks any pixels where the wavelength, flux, or error is infinite or <= 0.
`next_pow_2`(n)	Calculates the next power of 2 greater than or equal to n.
`od_to_flux`([od, errors, linelist, cov_matrix])	Converts optical depth to flux, errors, linelist, and covariance matrix.
`robust_mean`(data[, nsig, axis])	Calculates the robust mean of the input data by excluding outliers beyond a specified number of standard deviations from the median.
`sampler_nbytes`(sampler)
`save_backend_to_hdf5`(backend, filename)
`set_dict_defaults`(input_dict, default_dict)	Sets default values in a dictionary if they are not already present.

ACID_code.utils.convert_moves_to_emcee(moves: list[tuple])[source]

Converts a list of move specifications to emcee moves.

Parameters:

moves (list[tuple], optional) –

A list of tuples specifying the moves for the MCMC sampler. The format tries to follow the emcee documentation as closely as possible. However, the config cannot store classes directly, so move names are used instead and converted when building the sampler.

Each tuple should have the form:

(move_name: str, fraction: float, move_kwargs: dict | None)

where:

”move_name” is the name of the emcee move. Supported variants currently include “RedBlueMove”, “StretchMove”, “WalkMove”, “KDEMove”, “DEMove”, “DESnookerMove”, “MHMove”, and “GaussianMove”. Refer to the emcee documentation for more details on each move type. Input move names are checked against the “emcee.moves” module, so other moves from that module may also work, although not all have been tested with ACID.
”fraction” is the fraction of walkers to which this move should be applied.
”move_kwargs” is an optional dictionary of keyword arguments passed to the move class initialisation.

Returns:

A list of emcee move objects corresponding to the input specifications.

Return type:

list

ACID_code.utils.mask_invalid(wavelengths, flux, errors=None, return_mask=False, verbose=2)[source]

Masks any pixels where the wavelength, flux, or error is infinite or <= 0. Replaces bad pixels with NaN, which ACID can handle.

Parameters:

wavelengths (array_like) – The wavelength values of the spectrum.
flux (array_like) – The flux values of the spectrum.
errors (array_like) – The error values associated with the spectrum.

Returns:

A tuple containing the cleaned wavelength, flux, and error arrays.

Return type:

tuple

ACID_code.utils.drop_invalid(wavelengths, flux, errors=None, return_mask=False, verbose=2)[source]

Drops any pixels where the wavelength, flux, or error is infinite or <= 0.

Parameters:

wavelengths (array_like) – The wavelength values of the spectrum.
flux (array_like) – The flux values of the spectrum.
errors (array_like) – The error values associated with the spectrum.

Returns:

A tuple containing the cleaned wavelength, flux, and error arrays.

Return type:

tuple

ACID_code.utils.clip_wavelengths(wavelengths, wavelengths_linelist, depths_linelist, pad=5)[source]

Clips the linelist to only include lines within the wavelength range of the observed spectrum. Includes a pad either side of the wavelength range so that the wings of lines outside the range can also contribute to the fit.

Parameters:

wavelengths (np.ndarray) – Wavelengths of the observed spectrum
wavelengths_linelist (np.ndarray) – Wavelengths from the linelist
depths_linelist (np.ndarray) – Depths from the linelist
pad (float, optional) – Number of angstroms to pad on either side of the wavelength range. By default, 5.

Returns:

wavelengths_linelist (np.ndarray) – Clipped wavelengths from the linelist
depths_linelist (np.ndarray) – Clipped depths from the linelist

ACID_code.utils.drop_edges(array, n_pix=2)[source]

Drops the edges of an array by a specified number of pixels.

Parameters:

array (np.ndarray) – The input array.
n_pix (int, optional) – Number of pixels to drop from each edge. Default is 2.

Returns:

The array with edges dropped.

Return type:

np.ndarray

ACID_code.utils.calc_deltav(wavelengths: ACID_code.Array1D) → ACID_code.Scalar[source]

Calculates velocity pixel size

Calculates the velocity pixel size for the LSD velocity grid based off the spectral wavelengths.

Parameters:: wavelengths (Array1D) – Wavelengths for Acid input spectrum (in Angstroms), must be a 1D array of positive values.
Returns:: Velocity pixel size in km/s
Return type:: float

ACID_code.utils.guess_SNR(frame_wavelengths: Array1D | Array2D, frame_flux: Array1D | Array2D, frame_errors: Array1D | Array2D) → Array1D | Scalar[source]

Estimates S/N for each frame. Takes the median S/N in the central two-thirds of the wavelength range. Fully vectorized so that all the frames can be passed at once.

Parameters:

frame_wavelengths (Array1D | Array2D) – Array/list of wavelengths for each frame.
frame_flux (Array1D | Array2D) – Array/list of flux values for each frame.
frame_errors (Array1D | Array2D) – Array/list of error values for each frame.

Returns:

Array of estimated signal-to-noise ratios for each frame.

Return type:

Array1D | Scalar

ACID_code.utils.guess_errors(frame_wavelengths: Array1D | Array2D, frame_flux: Array1D | Array2D, frame_sn: Scalar | Array1D) → Array1D | Array2D[source]

Estimates errors for each frame based on the flux and S/N. Fully vectorized so that all the frames can be passed at once.

Parameters:

frame_wavelengths (Array1D | Array2D) – Array/list of wavelengths for each frame.
frame_flux (Array1D | Array2D) – Array/list of flux values for each frame.
frame_sn (Scalar | Array1D) – Estimated signal-to-noise ratio for each frame. Can be a single value or an array of values for each frame.

Returns:

Array of estimated error values for each frame. The dimensions will match those of frame_flux, with the same number of frames and pixels.

Return type:

Array1D | Array2D

ACID_code.utils.collapse_SNR(sn: Array1D | Array2D, wavelengths: Array1D | Array2D) → Array1D | Scalar[source]

Collapses the SN of a 1D or 2D wavelength and sn array to the median of the SNs on the central 2/3 wavelengths.

Parameters:

sn (Array1D | Array2D) – Signal-to-noise ratio array.
wavelengths (Array1D | Array2D) – Wavelength array.

Returns:

Collapsed signal-to-noise ratio.

Return type:

Array1D | Scalar

ACID_code.utils.get_normalisation_coeffs(wl: ACID_code.Array1D) → tuple[Scalar, Scalar][source]

Calculates normalization coefficients for wavelength array

Parameters:: wl (array_like) – Wavelength array for which normalization coefficients are calculated.
Returns:: A tuple containing the normalization coefficients (a, b).
Return type:: tuple

ACID_code.utils.get_available_memory()[source]

Returns the available memory in bytes. Checks if in a SLURM environment and uses its memory allocation if available.

Returns:: Available memory in bytes.
Return type:: int

ACID_code.utils.save_backend_to_hdf5(backend, filename)[source]

ACID_code.utils.backend_to_sampler(backend, log_prob_fn)[source]

ACID_code.utils.set_dict_defaults(input_dict: dict | None, default_dict: dict) → dict[source]

Sets default values in a dictionary if they are not already present.

Parameters:

input_dict (dict | None) – The dictionary to set defaults in (or none if not provided).
default_dict (dict) – The dictionary containing default key-value pairs.

Returns:

The updated dictionary with defaults set.

Return type:

dict

ACID_code.utils.findfiles(directory: str, file_type: str) → list[str][source]

Finds files in a directory matching a specific file type, excluding corrected spectra.

Parameters:

directory (str) – The directory to search for files.
file_type (str) – The file type to search for.

Returns:

A list of files matching the specified file type, excluding corrected spectra.

Return type:

list[str]

ACID_code.utils.robust_mean(data: ndarray, nsig: int | float = 3, axis: int = 0) → ndarray | float[source]

Calculates the robust mean of the input data by excluding outliers beyond a specified number of standard deviations from the median.

Parameters:

data (np.ndarray) – Input data array.
nsig (int | float, optional) – Number of standard deviations to use for outlier rejection. Defaults to 3.
axis (int, optional) – Axis along which to compute the robust mean. Defaults to 0.

Returns:

Robust mean of the input data.

Return type:

float

ACID_code.utils.combine_profiles(spectra: ACID_code.Array2D, errors: Array2D | None = None, covariances: Array3D | None = None) → tuple[source]

Combine multiple profiles into one.

Parameters:

spectra (Array2D) – Input profiles, should have dimensions (n_profiles, n_pix).
errors (Array2D, optional) – 1-sigma errors for each profile. Used only if covariances is None. Should have dimensions (n_profiles, n_pix).
covariances (Array3D or list of Array2D, optional) – Full covariance matrix for each profile. Should have dimensions (n_profiles, n_pix, n_pix). If provided, this is used instead of errors for the combination, and the combined covariance matrix is also returned.

Returns:

combined_profile (Array1D)
combined_errors (Array1D) – sqrt(diag(combined_covariance))
combined_covariance (Array2D) – Only returned if covariances is provided.

ACID_code.utils.flux_to_od(flux: ndarray = None, errors: ndarray = None, linelist: ndarray = None, cov_matrix: ndarray = None) → tuple | ndarray[source]

Converts flux, errors, linelist, and covariance matrix to optical depth. The formula used for the conversion is: - Optical depth (od) is calculated as -log(flux). - Errors in optical depth are calculated as errors / flux. - Linelist in optical depth is calculated as -log(1 - linelist). - Covariance matrix in optical depth is calculated as cov_matrix / (flux[:, np.newaxis] * flux[np.newaxis, :]).

Parameters:

flux (np.ndarray) – Input flux array.
errors (np.ndarray, optional) – Input errors array. Defaults to None.
linelist (np.ndarray, optional) – Input linelist array. Defaults to None.
cov_matrix (np.ndarray, optional) – Input covariance matrix, corresponding to errors. Defaults to None.

Returns:

A tuple containing any of the following, depending on which inputs were provided: - the flux in optical depth - errors in optical depth - linelist in optical depth - covariance matrix in optical depth The function appends the above inputs in the respective order to the output tuple if they were input.

Return type:

tuple

ACID_code.utils.od_to_flux(od: ndarray = None, errors: ndarray = None, linelist: ndarray = None, cov_matrix: ndarray = None) → tuple | ndarray[source]

Converts optical depth to flux, errors, linelist, and covariance matrix. The formula used for the conversion is: - Flux is calculated as exp(-od). - Errors in flux are calculated as errors * flux. - Linelist in flux is calculated as 1 - exp(-linelist). - Covariance matrix in flux is calculated as cov_matrix * (flux[:, np.newaxis] * flux[np.newaxis, :]).

Parameters:

od (np.ndarray) – Input optical depth array.
errors (np.ndarray, optional) – Input errors array. Defaults to None.
linelist (np.ndarray, optional) – Input linelist array. Defaults to None.
cov_matrix (np.ndarray, optional) – Input covariance matrix. Defaults to None.

Returns:

A tuple containing any of the following, depending on which inputs were provided: - the flux in flux units - errors in flux units - linelist in flux units - covariance matrix in flux units The function appends the above inputs in the respective order to the output tuple if they were input.

Return type:

tuple

ACID_code.utils.configure_mp_environ(os)[source]

Configures the multiprocessing environment variables to check for SLURM and set appropriate thread limits. See Multiprocessing section of the documentation for more details on why this is done.

Parameters:: os (module) – The os module to use for setting environment variables.

ACID_code.utils.next_pow_2(n)[source]

Calculates the next power of 2 greater than or equal to n.

Parameters:: n (int) – Input number. Must be real and non-negative.
Returns:: The next power of 2 greater than or equal to n.
Return type:: int

ACID_code.utils.auto_window(taus: ndarray, c: float = 5.0)[source]: Automated windowing procedure following Sokal (1989) in emcee documentation. Returns the window index to use in taus[window].

ACID_code.utils.autocorr_func_1d(x, norm=True)[source]: Autocorrelation estimate using FFT from the emcee tutorial.

ACID_code.utils.autocorr_gw2010(y, c=5.0)[source]: Goodman & Weare (2010) autocorrelation estimate from emcee documentation

ACID_code.utils.autocorr_new(y, c=5.0)[source]: New integrated autocorrelation time estimate from emcee documentation

ACID_code.utils.sampler_nbytes(sampler) → ACID_code.IntLike[source]