ACID_code.LSD

class ACID_code.LSD(data: object | None = None, od: bool = None, verbose: IntLike | bool | str | None = None)[source]

Class containing all useful functions for performing least-squares deconvolution. This does not simultaneously fit the continuum and perform LSD (which ACID does). It is used for the initial parameters of the ACID mcmc run and for obtaining final profiles. It can also be used as a standalone LSD implementation and for trying to do LSD without OD. For more details and an example, see Performing LSD directly in the documentation.

Initialises the LSD class, optionally with a Data instance to take parameters from.

Parameters:

data (object | None, optional) – A data instance to draw parameters and configs from, by default None
od (bool, optional) – Whether to perform LSD in optical depth space (True) or flux space (False), by default None. If None, takes from Data instance if provided, else defaults to True. We generally recommend always using optical depth as ACID was always intended, but you can set this to False if you wish to do your own testing. See Performing LSD directly in the documentation for more details.
verbose (IntLike | bool | str | None, optional) – Verbosity level, if None, uses the Config class existing value (in Data), or default of 2. Should follow the same format as Acid verbosity. Will overwrite the verbosity level in the config if a Data instance is input, by default None.

Runs the LSD algorithm to extract the average line profile from the observed spectrum.

Parameters:

wavelengths (Array1D) – Array of wavelengths of the observed spectrum in Angstroms
flux (Array1D) – Array of flux values corresponding to the wavelengths (in linear space, and should be continuum normalized)
errors (Array1D) – Array of error values corresponding to the flux
sn (Scalar) – Signal-to-noise ratio of the observed spectrum
linelist (Array2D | str | LineList | dict | None, optional) – Linelist to use for LSD, should follow the same format as Acid. If None, uses the linelist already stored in the class, if it exists, by default None.
velocities (Array1D, optional) – Array of velocities corresponding to the observed spectrum. If the class was not initialised with an Acid instance, this is required, by default None
alpha (Array2D | None, optional) – Precomputed alpha matrix, if already calculated and you want to skip directly to the Cholesky decomposition and solving for the profile, by default None

sn_clip(wavelengths_linelist: ACID_code.Array1D, depths_linelist: ACID_code.Array1D, sn: ACID_code.Scalar) → tuple[Array1D, Array1D][source]

Applies a signal-to-noise cut to the linelist, removing lines shallower than 1/(3*sn) as per Dolan et al (2024).

Parameters:

wavelengths_linelist (Array1D) – Wavelengths from the linelist
depths_linelist (Array1D) – Depths from the linelist
sn (Scalar) – Signal-to-noise ratio threshold

Returns:

Clipped wavelengths and depths from the linelist

Return type:

tuple[:py:type:`Array1D`, Array1D]

calc_alpha(wavelengths: ACID_code.Array1D, wavelengths_linelist: ACID_code.Array1D, depths_linelist: ACID_code.Array1D, velocities: Array1D | None = None) → ACID_code.Array2D[source]

Calculates the alpha matrix given flux and errors and a linelist. Note that if this function is called without using run_LSD, there is no selection of lines deeper than 1/(3*sn). If you still wish to do this, it needs to be done in linear space with the sn_clip function before converting to (if desired) OD space. The units of the alpha matrix will match the units of the input linelist.

Parameters:

wavelengths (Array1D) – Array of wavelengths of the observed spectrum in optical depth space
wavelengths_linelist (Array1D) – Array of wavelengths from the linelist in optical depth space
depths_linelist (Array1D) – Array of depths from the linelist in optical depth space
velocities (Array1D, optional) – Array of velocities, needs to either be initialised by class with Acid instance, or input here, by default None

Returns:

The alpha matrix, to be used in the Cholesky decomposition and solving for the profile. The units will match the units of the input linelist (OD or flux).

Return type:

Array2D

static calc_cholesky(alpha: ACID_code.Array2D, error: ACID_code.Array1D, **kwargs) → tuple[source]

Calculates the LHS Cholesky factorisation matrix given the alpha matrix and flux errors. The units of alpha and error should match (ie OD or flux), the output will be in the same units.

Parameters:

alpha (Array2D) – The precomputed alpha matrix
error (Array1D) – Flux errors
**kwargs (dict, optional) – Additional keyword arguments to pass to scipy.linalg.cho_factor. Overwrite_a=False must be set by us, do not pass this as a kwarg.

Returns:

c_factor – Cholesky factorisation matrix and lower/upper flag, to be put straight into solve_z as c_factor parameter

Return type:

tuple

static solve_z(alpha: ACID_code.Array2D, flux: ACID_code.Array1D, error: ACID_code.Array1D, c_factor: tuple, return_error: bool = True, return_cov: bool = False, **kwargs) → tuple[source]

Solves for the LSD profile and its errors using the Cholesky factors. All units should match between alpha, flux, and error (ie all in OD or all in flux). Returns the profile in the same units.

Parameters:

alpha (Array2D) – The precomputed alpha matrix
flux (Array1D) – The observed flux values in optical depth space
error (Array1D) – The flux errors in optical depth space
c_factor (tuple) – Cholesky factorisation matrix and lower/upper flag, to be put straight into scipy.linalg.cho_solve as c_factor parameter
return_error (bool, optional) – Whether to calculate and return the profile errors along with the profile, by default True
return_cov (bool, optional) – Whether to return the full covariance matrix instead of just the errors, by default False
**kwargs (dict, optional) – Additional keyword arguments to pass to both scipy.linalg.cho_solve calls (one for the profile, one for the covariance matrix) Overwrite_b=False is already set by default, do not pass this as a kwarg.

Returns:

profile, profile_errors, cov_z – LSD profile and its errors (if return_error is True) and covariance matrix (if return_cov is True)

Return type:

tuple

classmethod convolve_profile(profile: ACID_code.Array1D, profile_errors: ACID_code.Array1D, alpha: Array2D | None = None, velocities: Array1D | None = None, wavelengths: Array1D | None = None, linelist_wavelengths: Array1D | None = None, linelist_depths: Array1D | None = None) → tuple[Array1D, Array1D][source]

Convolve your profile either using an inputted alpha matrix or by calculating one using calc_alpha() with the inputted wavelengths and linelist. The units of the output convolved model spectrum will match the units of the input profile (ie OD or flux) and alpha matrix/linelist depths. If alpha is not input, the wavelengths and linelist inputs are required to calculate the alpha matrix. See utils.flux_to_od() and utils.od_to_flux() for conversions.

Parameters:

profile (Array1D) – The LSD profile to be convolved, in the same units as the alpha matrix (OD or flux)
profile_errors (Array1D) – The errors on the LSD profile, in the same units as the alpha matrix (OD or flux)
alpha (Array2D | None, optional) – Precomputed alpha matrix, if already calculated and you want to skip directly to the convolution, by default None
velocities (Array1D | None, optional) – Array of velocities corresponding to the observed spectrum, required if alpha is not input, by default None
wavelengths (Array1D | None, optional) – Array of wavelengths of the observed spectrum, required if alpha is not input, by default None
linelist_wavelengths (Array1D | None, optional) – Array of wavelengths from the linelist, required if alpha is not input, by default None
linelist_depths (Array1D | None, optional) – Array of depths from the linelist, required if alpha is not input. Must be in the same units as the alpha matrix (OD or flux), by default None