ACID_code_v2.Acid

Accurate Continuum fItting and Deconvolution (ACID) class. This class contains the ACID method which fits the continuum of spectra and performs Least Squares Deconvolution (LSD) to obtain LSD profiles for each spectrum. It also contains many internal methods used within the main ACID function.

Initialises the Acid class with inputted parameters. The parameters set here arre independent of the choice of the ACID and ACID_HARPS functions, which take different formats for inputted spectra.

Parameters:

velocities (np.ndarray | None, optional) – Velocity grid for LSD profiles (in km/s). For example, use: np.arange(-25, 25, 0.82) to create. If None, a default grid from -25 to 25 km/s with a spacing calculated by calc_deltav. It is highly recommended to choose your own velocity grid, by default None
linelist_path (str | None, optional) – Can be a path to linelist in string format, a dictionary with keys “wavelengths” and “depths”, a Linelist class, or a list/array indexed such that 0 is the wavelengths and 1 is the depths. If None, you can directly provide linelist_wl and linelist_depths instead. At least one of linelist_path or linelist_wl and linelist_depths must be provided. By default None.
linelist_wl (np.ndarray | list | None, optional) – Wavelengths of lines in linelist (in Angstroms). Only necessary if linelist_path is not provided. Must be same length as linelist_depths. If None, linelist_path must be provided., by default None
linelist_depths (np.ndarray | list | None, optional) – Depths of lines in linelist (between 0 and 1). Only necessary if linelist_path is not provided. Must be same length as linelist_wl. If None, linelist_path must be provided., by default None
verbose (bool | int | None, optional) – An integer between 0 and 3. If 0, nothing is printed. If 2, prints out useful progress information, as well as ACID warnings about any potential issues with the input data or autocorrelation warnings. If True, defaults to 2. If False, defaults to 0. If you want to ignore the warnings but still keep progress information, set verbose to 1. A verbosity of 3 will produce additional plots, such as the result of the continuum fit. By default None, which defaults to 2 (True). If set, overrides any verbose setting in the dataclass.
telluric_lines (np.ndarray | list | None, optional) – List of wavelengths (in Angstroms) of telluric lines to be masked. This can also include problematic lines/features that should be masked also. For each wavelengths in the list ~3Å eith side of the line is masked. By default None
name (str, optional) – Name to call any saved files, by default ‘ACID’
seed (int | None, optional) – Random seed for reproducibility, set it to None to be a random seed, by default 42 (the answer to life, the universe and everything)
data (Data|None, optional) – An optional backend Data object to use for storing data. Allows previously calculated results to be skipped. If None, a new Data object is created, by default None. Please note that if the Data class already has a saved ACID config class, then those config values will overwrite the inputted values in initialisation or ACID method.

Fits the continuum of the given spectra and performs LSD on the continuum corrected spectra, returning an LSD profile for each spectrum given. Spectra must cover a similiar wavelength range.

Parameters:

wavelengths (np.ndarray | list | None, optional) – An array of wavelengths for each frame (in Angstroms). For multiple frames this should be a 2-d array such that wavelengths[i] corresponds to the wavelengths for the ith frame. Can only be None if a data instance was provided in initialisation.
flux (np.ndarray | list | None, optional) – An array of spectral frames (in flux). For multiple frames this should be a 2-d array such that flux[i] corresponds to the spectral fluxes for the ith frame. Can only be None if a data instance was provided in initialisation., by default None
errors (np.ndarray | list | None, optional) – Errors for each frame (in flux). For multiple frames this should be a 2-d array such that errors[i] corresponds to the spectral errors for the ith frame. Can only be None if a data instance was provided in initialisation., by default None
sn (int | np.ndarray | list | None, optional) – Average signal-to-noise ratio for each frame (used to calculate minimum line depth to consider from line list). Each frame should have only one S/N value, so for multiple frames this should be a 1-d array such that sn[i] corresponds to the S/N for the ith frame. If None, the S/N will be estimated from the input spectra, by default None
all_frames (str | np.ndarray | None, optional) –
Output array for resulting profiles. Only neccessary if looping ACID function over many wavelength regions or order (in the case of echelle spectra). General shape needs to be (no. of frames, no. of orders, 2, no. of velocity pixels). If not provided, one is created with that shape.

The only allowed string is “default” due to legacy behaviour, which now acts the same as None, by default None
deterministic_profile (bool, optional) – If True, fits both the continuum and the LSD profile simultaneously. If False, only fits the continuum in mcmc, the profile is inferred from the continuum fit. Setting this to False can significantly speed up compution time, depending on the machine used as it is not as easy to parallelise. It may decrease accuracy, and is not fully tested as of yet, by default True.
poly_ord (int, optional) – Order of polynomial to fit as the continuum, by default 3
pix_chunk (int, optional) – Size of ‘bad’ regions in pixels. ‘bad’ areas are identified by the residuals between an inital model and the data. If a residual deviates by a specified percentage (dev_perc) for a specified number of pixels, by default 20
dev_perc (int, optional) – Allowed deviation percentage. ‘bad’ areas are identified by the residuals between an inital model and the data. If a residual deviates by a specified percentage (dev_perc) for a specified number of pixels, by default 25
n_sig (int, optional) – Number of sigma to clip in sigma clipping. Ill fitting lines are identified by sigma-clipping the residuals between an inital model and the data. The regions that are clipped from the residuals will be masked in the spectra. This masking is only applied to find the continuum fit and is removed when LSD is applied to obtain the final profiles, by default 1
order (int, optional) – Only applicable if an all_frames output array has been provided as this is the order position in that array where the result should be input. i.e. if order = 5 the output profile and errors would be inserted in all_frames[:, 5]., by default 0
skips (int, optional) – An option to only select one in every n pixels, where n is the integer argument. This is only useful for testing to get a quick result, by default 1
parallel (bool, optional) – If True uses multiprocessing to calculate the profiles for each frame in parallel, by default True
cores (int, optional) – Number of cores to use if parallel=True. If None, all available cores will be used, by default None
nsteps (int, optional) – nsteps (int, optional): Number of steps for the MCMC to run, try increasing if it doesn’t converge, by default 10000
max_steps (int | None, optional) – If set, the sampler will run until max_steps or convergence is reached by estimation using the emcee autocorrelation time (tau). The sampler will check for convergence every ‘check_interval’ steps, and will require a minimum number of checks (‘min_checks’) and a minimum tau factor (‘min_tau_factor’) before it can stop. The stopping criterion is met when the change in tau is less than ‘tau_tol’ for all parameters. By default None, which means no maximum. If a value is inputted, the nsteps parameter is ignored. The continue_sampling method in Result or Acid can still be used normally to continue after either stopping criterion is reached.
check_interval (int, optional) – Interval (in steps) at which to check for MCMC convergence if max_steps is set, by default 1000. Only used if max_steps is set.
min_checks (int, optional) – Minimum number of checks before MCMC can be stopped, by default 3. Only used if max_steps is set.
min_tau_factor (int, optional) – Minimum tau factor for MCMC stopping criterion, by default 50. Only used if max_steps is set.
tau_tol (float, optional) – Tolerance for tau convergence in MCMC stopping criterion, by default 0.01. Only used if max_steps is set.
run_mcmc (bool, optional) – If True, runs the MCMC to fit the model, by default True. Can be set to False to perform all of the preparation for MCMC without actually running it. The ACID function will still update the class and data attributes.
**kwargs (dict, optional) – Additional keyword arguments. kwargs are passed to the Result class when returning the Result object, see Result class for more details on what kwargs can be passed. Note that any kwargs that are also in the class initialisation will be ignored, and the inputted value will not be used. This is to avoid confusion for users who may accidentally input an argument that is meant for the class initialisation rather than the ACID function, which takes different arguments. The ignored kwargs are checked for and printed at the start of the function.

Returns:

Result object containing the LSD profiles and associated data. See Result class for methods and attributes. If run_mcmc is False, None is returned, but the class attributes are still updated (so that acid.data can be used for example).

Return type:

Result

Raises:

TypeError – If the input types are not as expected.

ACID_HARPS(filelist: list, order_range: list | ndarray | None = None, save_path: str = './', file_type: str = 'e2ds', **kwargs)[source]

ACID for HARPS e2ds and s1d spectra (DRS pipeline 3.5)

Fits the continuum of the given spectra and performs LSD on the continuum corrected spectra, returning an LSD profile for each file given. Files must all be kept in the same folder as well as their corresponding blaze files. If ‘s1d’ are being used their e2ds equivalents must also be in this folder. Result files containing profiles and associated errors for each order (or corresponding wavelength range in the case of ‘s1d’ files) will be created and saved to a specified folder. It is recommended that this folder is seperate to the input files.

Parameters:

filelist (list of strings) – List of files. Files must come from the same observation night as continuum is fit for a combined spectrum of all frames. A profile and associated errors will be produced for each file specified.
order_range (array, optional) – Orders to be included in the final profiles. If s1d files are input, the corresponding wavelengths will be considered, by default None.
save_path (str, optional) – Path to the directory where output files will be saved, by default ‘./’
file_type (str, optional) – Type of the input files, either “e2ds” or “s1d”, by default ‘e2ds’
**kwargs – Additional arguments to be passed to the ACID function. See ACID function for details.

Returns:

Result object containing the LSD profiles and associated data. ACID_HARPS=True flag is set to allow legacy subscripting and iteration if needed. The legacy subscript and iteration methods will access the following attributes: list

Barycentric Julian Date for files

list: Profiles (in normalised flux)
list: Errors on profiles (in normalised flux)

It can be accessed for example by: >>> result = Acid.ACID_HARPS(…) >>> BJDs = result.BJDs >>> profiles = result.profiles >>> errors = result.errors or >>> BJDs, profiles, errors = result

Return type:

Object

combine_spec(frame_wavelengths: ndarray | None = None, frame_flux: ndarray | None = None, frame_errors: ndarray | None = None, frame_sns: ndarray | None = None, output: bool = True)[source]

Combines multiple spectral frames into one spectrum

Parameters:

frame_wavelengths (array, optional) – Wavelengths for the spectral frames, by default None
frame_flux (array, optional) – Fluxes for the spectral frames, by default None
frame_errors (array, optional) – Errors for the spectral frames, by default None
frame_sns (array, optional) – Signal-to-noise ratio for the spectral frames, by default None
output (bool, optional) – Whether to output the combined spectrum, by default True

Returns:

combined_wavelengthsarray: Wavelengths for the combined spectrum
combined_spectrumarray: Fluxes for the combined spectrum
combined_errorsarray: Errors for the combined spectrum
combined_snfloat: Signal-to-noise ratio for the combined spectrum

Return type:

Tuple, if output is True, containing

continuumfit(fluxes: ndarray, wavelengths: ndarray, errors: ndarray, poly_ord: int | integer = 3, plot_result: bool = False)[source]

Provides an initial, normalised continuum fit using inputted spectra.

Parameters:

fluxes (np.ndarray) – The flux values of the spectrum.
wavelengths (np.ndarray) – The wavelengths corresponding to the spectrum.
errors (np.ndarray) – The error values associated with the spectrum.
poly_ord (int) – The order of the polynomial to fit to the continuum. By default 3.
plot_result (bool, optional) – If True, plots the original spectrum and the fitted continuum, by default False

Returns:

A tuple containing the polynomial coefficients, the normalized flux, and the normalized errors.

Return type:

tuple

residual_mask()[source]: Masks regions of the spectrum based on residuals from an initial model fit.

run_mcmc(nsteps, state=None)[source]

run_mcmc_until_converged(max_steps: int | integer, state=None)[source]

Continue MCMC sampling for additional steps. This should be called in Result class by the user. This necessarily requires a Data instance to have been put into the ACID init.

Parameters:

sampler (emcee.EnsembleSampler) – The existing MCMC sampler to continue sampling from.
nsteps (int) – Number of additional steps to run the MCMC for.
max_steps (int, optional) – Maximum number of steps to run the MCMC for in total (including previous steps). If specified, the MCMC will stop if this number of steps is reached even if convergence has not been reached, by default None. If input, nsteps is ignored.
max_steps_kwards (dict, optional) – Additional keyword arguments to be passed to the run_mcmc_until_converged function if max_steps is specified, by default None. The kwargs description can be found in Acid.ACID(), they are the 4 kwargs appearing after max_steps. Typos for kwargs are silently ignored.

Returns:

The MCMC sampler after running for the additional steps.

Return type:

emcee.EnsembleSampler

get_result()[source]

Return a Result object for this instance or one passed explicitly.

Parameters:: self (Acid instance, optional) – The Acid instance to get the Result for. If None, must be called on an instance of Acid.
Returns:: The Result object for the given Acid instance.
Return type:: Result

read_in_frames(order, filelist, file_type, directory=None)[source]

combineprofiles(spectra, errors)[source]