Docstrings

LOADING

_GMOS_loader

specsuite.loading._GMOS_loader (
  path,
  file,
  return_RN = False,
): [SOURCE]

Description:
Controls how to load data from Gemini Observatory's GMOS-N instrument. The resulting output will be oriented such that the x-axis is the dispersion axis (left is blue / right is red) and the y-axis is the cross-dispersion axis.

Parameters:
path :: str
Directory pointing toward the FITS file you wish to load. This should not include the name of the file itself.
file :: str
Name of the FITS file in the specified directory to load.
return_RN :: bool
Determines whether the read noise image should be returned as an additional return. Defaults to 'False'.

Returns:
image :: np.ndarray
A 2D array loaded in from the specified FITS file.

_kosmos_loader

specsuite.loading._kosmos_loader (
  path,
  file,
  clip_overscan = True,
): [SOURCE]

Description:
Controls how to load data from Apache Point Observatory's KOSMOS instrument. The resulting output will be oriented such that the x-axis is the dispersion axis (left is blue / right is red) and the y-axis is the cross-dispersion axis.

Parameters:
path :: str
Directory pointing toward the FITS file you wish to load. This should not include the name of the file itself.
file :: str
Name of the FITS file in the specified directory to load.
clip_overscan :: bool
Determines whether to clip the overscan region of the detector.

Returns:
image_data :: np.ndarray
A 2D array loaded in from the specified FITS file.

average_matching_files

specsuite.loading.average_matching_files (
  path,
  tag,
  instrument = "kosmos",
  ignore = [],
  crop_bds = [0, None],
  mode = "median",
  debug = False,
  progress = False,
): [SOURCE]

Description:
Extracts images from a user-given path, and finds the average pixel value for every pixel across all images. This defaults to the 'median' average, but can be changed to take the 'mean' average as well.

Parameters:
path :: str
Path to data directory.
tag :: str
Tag to search for in filenames.
instrument :: str
The name of the instrument your FITS data was taken from. This is only used to determine which loading function to use.
ignore :: list
List of data indexes to ignore in averaging.
crop_bds :: list
The region along the cross-dispersion (spatial) axis to keep (all other rows will be dropped).
mode :: str
Type of average to take of images. Valid inputs include 'median' and 'mean'.
debug :: bool
Toggles the display of image stats.
progress :: bool
Toggles the progress bar.

collect_images_array

specsuite.loading.collect_images_array (
  path,
  tag,
  ignore = None,
  crop_bds = [0, None],
  instrument = "kosmos",
  clip_overscan = True,
  debug = False,
  progress = False,
): [SOURCE]

Description:
Collect a list of images from a user-given path corresponding to a specified tag. Images can be ignore by passing their indexes as an additional argument.

Parameters:
path :: str
Path to data directory containing image data.
tag :: str
Tag to search for in filenames.
ignore :: list
List of file indexes to ignore.
crop_bds :: list
The region along the cross-dispersion (spatial) axis to keep (all other rows will be dropped).
instrument :: str
The name of the instrument the FITS data was taken from. This is used to determine which loading function should be used.
clip_overscan :: bool
Allows the overscan region to be cropped out of the returned array.
debug :: bool
Allows for diagnostic information to be printed. This includes the names of all files found with the given 'tag' and whether any of them failed to load.
progress :: bool
Whether a progress bar should be displayed.

Returns:
image_collection :: np.ndarray
An array of 2D images corresponding to each valid file found in the provided path.

extract_image

specsuite.loading.extract_image (
  path,
  file,
  instrument,
): [SOURCE]

Description:
Attempts to extract image data from a given FITS file using a method specific to the user-specified instrument.

Parameters:
path :: str
Directory pointing toward the FITS file you wish to load. This should not include the name of the file itself.
file :: str
Name of the FITS file in the specified directory to load.
instrument :: str
Specifies which loading function should be used for the FITS file. Currently, the only supported instruments are... - KOSMOS - GMOS

Returns:
image :: np.ndarray | None
A 2D array containing the image found in the resulting FITS file. If there is issue with loading the data, a 'None' is returned.

extract_times

specsuite.loading.extract_times (
  path,
  tag,
  ignore = [],
  time_lbl = "DATE-OBS",
  ra_lbl = "RA",
  dec_lbl = "DEC",
  lat_lbl = "LATITUDE",
  long_lbl = "LONGITUD",
  time_format = "isot",
  time_scale = "tai",
  loc_units = (Unit("hourangle"), Unit("deg")),
  loc_frame = "icrs",
): [SOURCE]

Description:
Extracts time data from the headers of a set of observations. Assumes that the header has information about the observation time.

Parameters:
path :: str
Directory pointing toward the FITS file you wish to load. This should not include the name of the file itself.
tag :: str
A sub-string that can help differentiate between desired and undesired files in a directory. If an empty string is provided, no files are filtered out (based on the 'tag' criteria).
ignore :: list
Filenames to ignore when loading in data. The 'ignore' filenames must exactly match how they appear in the file navigator (including .fits extension).
time_lbl :: str
Header label for observation time.
ra_lbl :: str
Header label for RA of target.
dec_lbl :: str
Header label for DEC of target.
lat_lbl :: str
Header label for latitude of target.
long_lbl :: str
Header label for longitude of target.
time_format :: str
Astropy Time() format that represents the time data in the header.
time_scale :: str
Astropy Time() scale that represents the time data in the header.
loc_units :: tuple
Astropy SkyCoord() units that represents the (RA, DEC) data in the header.
loc_frame :: str
Astropy SkyCoord() frame that represents the (RA, DEC) data in the header.

Returns:
times_bc :: np.ndarray
Array of JD barycentric times that have been corrected for variations in light travel time. Has attached astropy units of days.

filter_files

specsuite.loading.filter_files (
  files,
  tag,
  ignore,
): [SOURCE]

Description:
Filters down a list of filenames if they to not satisfy the following requirements... 1) The file ends with '.fits' extension 2) The provided 'tag' is not in the filename 3) The filename is not given in 'ignore' list

Parameters:
files :: list
Several filenames to filter based on the above criteria.
tag :: str
A sub-string that can help differentiate between desired and undesired files in a directory. If an empty string is provided, no files are filtered out (based on the 'tag' criteria).
ignore :: list
Filenames to ignore when loading in data. The 'ignore' filenames must exactly match how they appear in the file navigator (including .fits extension).

Returns:
files :: list
All remaining files once filtering has been performed.

load_metadata

specsuite.loading.load_metadata (
  path,
  tag,
  ignore = [],
): [SOURCE]

Description:
Loads an dictionary of all data for a collection of FITS files. This metadata comes from the header of the first FITS card.

Parameters:
path :: str
Path to data directory.
tag :: str
Tag to search for in filenames.
ignore :: list
List of data indexes to ignore.

Returns:
metadata :: dict
Dictionary containing the metadata found for each key in the FITS headers. Keys-value pairs that are identical across all exposures are combined into a single value.

split_chips

specsuite.loading.split_chips (
  images,
): [SOURCE]

Description:
Attempts to split up a series of 2D images into separate arrays for each "chip" that has been combined. This function assumes that "chip gaps" are indicated by a column that is entirely comprised of NaN values.

Parameters:
images :: np.ndarray
A series of images that are comprised of multiple chips joined by a "chip gap" comprised of NaN values.

Returns:
sub_images :: np.ndarray
A list of images where each entry has N sub-images that make up each chip that was detected.

WARPING

combine_within_tolerance

specsuite.warping.combine_within_tolerance (
  values,
  tolerance,
): [SOURCE]

Description:
Takes a user-given list and combines values that are within a given tolerance. This is helpful for when a dense sample of features is non-ideal and should be combined into a single feature.

Parameters:
values :: np.ndarray
List of values to be analyzed.
tolerance :: float
The theshold at which two data points should be combined.

Returns:
combined_values :: list
List of values where close points have been averaged and combined.

dewarp_image

specsuite.warping.dewarp_image (
  image,
  models,
  debug = False,
  progress = False,
): [SOURCE]

Description:
Uses a 'warp model' to undo distortion in a 2D image. This is done by rebinning each row onto a consistent wavelength bin proportional to the overlapping area between the raw image data and a warped set of new pixel locations.

Parameters:
image :: np.ndarray
Image that is horizontally warped according to a set of models the user also provides.
models :: list
List of models that describe how vertical lines are warped along the image's horizontal axis.
debug :: bool
Enables diagnostic plots.
progress :: bool
Enables a progress bar.

Returns:
unwarped_image :: np.ndarray
A dewarped version of the provided image.

extract_background

specsuite.warping.extract_background (
  images,
  warp_model,
  mask_region = (None, None),
  return_spectrum = False,
  progress = False,
  debug = False,
): [SOURCE]

Description:
Extracts the sky background for a series of exposures where a trace should be masked out. It uses a 'warp model' that describes how straight emission lines are 'bent' on the imaging plane. This function assumes that flatfielding has been applied and that sky emissions are approximately uniform along the spatial axis.

Parameters:
images :: np.ndarray
A series of exposures to extract backgrounds from.
warp_model :: list
List of models that describe how vertical lines are warped along the image's horizontal axis.
mask_region :: tuple
The pixel locations (vertical) to mask out during the background extraction.
return_spectrum :: bool
Whether or not to return the super-sampled spectra used for interpolating the sky background. If 'True', three additional arguments are returned. These are the effective pixel locations, effective flux, and the 'effpix map'.
progress :: bool
Controls whether or not progress bars are shown.
debug :: bool
Allows for diagnostic plots to be shown.

Returns:
background_images :: np.ndarray
A series of images representing the approximated sky background for each image.
supersampled_effpix :: np.ndarray
The grid of 'effective pixel locations' that the sky emission spectra was extracted for. This is essentially a flattened version of the 'effpix_map'.
supersampled_spectra :: np.ndarray
The effective flux found for each of the effective pixel locations.
effpix_map :: np.ndarray
A 2D array with the same size as an individual image. The value at each pixel represents the 'effective pixel location' for that given pixel.

find_cal_lines

specsuite.warping.find_cal_lines (
  image,
  std_variation = 50.0,
  row = None,
  debug = False,
): [SOURCE]

Description:
Finds pixel positions of spectral lines in a provided image. The image does not need to range from any specific wavelength to another. The only requirement is that the lines are located vertically on the image plane.

Parameters:
image :: np.ndarray
Image with calibration lines.
std_variation :: float
How many standard deviations a peak must exceed the baseline to be counted as a line.
row :: int
Which row to pull a 1D profile from. If no argument is provided, this function will default to the row at the center of the cross-dispersion axis.
debug :: bool
Allows for a diagnostic plot to be shown.

Returns:
non_zero_indices :: np.ndarray
List of pixel locations for detected lines.
rel_intensity :: np.ndarray
List of the relative intensity of the detected lines.

generate_effpix_map

specsuite.warping.generate_effpix_map (
  xs,
  rows,
  models,
): [SOURCE]

Description:
Generates a 2D map of the effective location of each pixel center across the detector. It uses models that describe the warping across the detector as a function of row and column positions.

Parameters:
xs :: np.ndarray
A 1D array holding all column pixel positions.
rows :: np.ndarray
A 1D array holding all row pixel positions.
models :: np.ndarray
An array holding how light warping changes as a function of column and row pixel positions. This function assumes that each fitting coefficient changes according to a linear relationship.

Returns:
effpix_map :: np.ndarray
A 2D array detailing the effective location of each pixel center.

generate_warp_model

specsuite.warping.generate_warp_model (
  image,
  guess,
  tolerance = 16,
  line_order = 2,
  warp_order = 1,
  ref_idx = None,
  debug = False,
): [SOURCE]

Description:
Models how straight vertical lines in a wavelength calibration image are being warped. Assumes a relatively low amount of straight-line warping and that these lines are continuous. This function allows for the type of warping to change along the horizontal axis of the detector. This is functionally achieved by binning down a given image and identifying the brightest pixels across the vertical axis of a detector in a small region around each line.

Parameters:
image :: np.ndarray
A 2D arclamp image with strong emission features.
guess :: np.ndarray
The pixel positions (along the dispersion axis) of strong emissions features in the provided image. These can be slightly wrong, as the 'tolerance' determines how broad of a region to analyze around each of these guesses.
tolerance :: int
Number of pixels around your guess to use for building a warp model. The tolerance should at least be large enough that the entire emission line falls within a given window, but it is often better to provide a slightly larger tolerance if you are uncertain in the accuracy of your guesses.
line_order :: int
Order of x-warping (i.e. How does our vertial warping change with x-position along the detector).
warp_order :: int
Order of y-warping (i.e. What shape does a straight line projected onto our detector take on).
ref_idx :: int
Which row (along cross-dispersion axis) to use for measuring the relative changes from row to row. This choice should be near the brightest portion of the emission line.
debug :: bool
Allows for diagnostic plots to be displayed.

Returns:
warp_models :: list
Collection of models describing how y-warping coefficients change as a function of x.

UTILS

_gaussian

specsuite.utils._gaussian (
  x,
  A,
  mu,
  sigma,
): [SOURCE]

Description:
Generates a 1D Gaussian profile on the user-provided grid of x-points. If an error is encountered, then 'None' will be returned instead of a Numpy array.

Parameters:
x :: np.ndarray
A set of x-points over which to evaluate the Gaussian profile. This can be a single value, but must still be contained in a list (i.e., [1]).
A :: float
The amplitude of the Gaussian profile.
mu :: float
The mean of the Gaussian profile.
sigma :: float
The standard deviation of the Gaussian profile.

Returns:
profile :: np.ndarray
The 1D Gaussian profile evaluated on the provided grid of x-points.

_moffat

specsuite.utils._moffat (
  x,
  A,
  mu,
  gamma,
  offset = 0.0,
): [SOURCE]

Description:
Generates a 1D Moffat profile on the user-provided grid of x-points. If an error is encountered, then 'None' will be returned instead of a Numpy array. Note: This is technically a 'modified Moffat profile' since the exponent has been set to 2.5.

Parameters:
x :: np.ndarray
A set of x-points over which to evaluate the Moffat profile. This can be a single value, but must still be contained in a list (i.e., [1]).
A :: float
The amplitude of the Moffat profile.
mu :: float
The mean of the Moffat profile.
gamma :: float
A shape parameter for the Moffat profile.
offset :: float
A constant offset applied to all points.

Returns:
profile :: np.ndarray
The 1D Moffat profile evaluated on the provided grid of x-points.

animate_images

specsuite.utils.animate_images (
  image_array,
  delay = 10,
  savedir = "result.gif",
  iterable = None,
  iterable_label = "Index",
  kwargs,
): [SOURCE]

Description:
Attempts to create a GIF from an array of 2D Numpy arrays. This creates a series of temporary images in a '__TEMP_FRAMES__' directory, then uses 'magick' to convert them to a GIF. These frames should be deleted automatically once the GIF has been created. All '**kwargs' will be fed directly into 'specsuite.plot_image'.

Parameters:
image_array :: np.ndarray
An array containing several 2D images. Each individual image will become a frame in the resulting GIF. Additionally, the GIF will preserve the order of this array.
delay :: int
The time (1/100 seconds) between frames.
savedir :: str
The directory (+filename) to save the GIF under.
iterable :: list
A 1D list with the same length as 'image_array'. This will be plotted at the top of the plot and updates with every frame. If none is provided, this defaults to the image index.
iterable_label :: str
The 'name' you would like to associate with the 'iterable'. Defaults to 'Index'.

apply_new_pixel_grid

specsuite.utils.apply_new_pixel_grid (
  flux,
  error,
  current_pixels,
  progress = False,
): [SOURCE]

Description:
Corrects for pixel offsets between individual exposures by interpolating every exposure onto the same sub-pixel grid. This is done by linearly interpolating on the unnormalized cummulative distribution function of each exposure.

Parameters:
flux :: np.ndarray
A 2D array of fluxes oriented so that the dimensions represent (N_exposures, N_pixels).
error :: np.ndarray
A 2D array of 1-sigma uncertainties with the same dimensions as 'flux'.
current_pixels :: np.ndarray
A 2D array containing the 'effective pixel positions' of the 'flux' and 'error' arrays.
progress :: bool
Toggles the progress bar.

Returns:
interpolated_flux :: np.ndarray
A 2D array of fluxes interpolated onto a single pixel grid. May contain NaN values if any 'current_pixels' cannot be linearly interpolated without extrapolating outside the assumed pixel bounds.
interpolated_error :: np.ndarray
A 2D array of error-propagated errors for the 'interpolated_flux' array.

butterworth_filter

specsuite.utils.butterworth_filter (
  x,
  x0,
  n,
  lower_limit = 0.0,
  upper_limit = 1.0,
): [SOURCE]

Description:
A 1D filter throughput model corresponding to the 'Butterworth' filter normalized between 0 and 1.

Parameters:
x :: float
A 1D array of values to generate the filter model on.
x0 :: float
The cutoff value at which the filter transitions from its lower to upper limits.
n :: float
A shape parameter (filter order) that controls the behavior of the filter near the cutoff value. A negative value peaks on the left of 'x0', and a positive value peaks to the right.
lower_limit :: float
An optional parameter that sets the lower limit of the filter. Defaults to 0.0.
upper_limit :: float
An optional parameter that sets the upper limit of the filter. Defaults to 1.0.

Returns:
filter_throughput :: np.ndarray
The estimated filter throughput (0.0 - 1.0).

convolve_to_resolution

specsuite.utils.convolve_to_resolution (
  x,
  y,
  R,
): [SOURCE]

Description:
Convolves an input spectrum using a Gaussian kernel where the kernel width is determined by the desired resolution R.

Parameters:
x :: np.ndarray
Wavelength array (in Angstroms).
y :: np.ndarray
Flux array corresponding to the wavelengths.
R :: float
Desired spectral resolution (lambda/delta_lambda).

Returns:
y_conv :: np.ndarray
Convolved flux array at the same wavelengths.

correct_lightcurve_shifting

specsuite.utils.correct_lightcurve_shifting (
  flux,
  error,
  N_divisions = 1,
  model_flux = None,
  mode = "median",
  poly_order = 3,
  apply_window = True,
  progress = False,
): [SOURCE]

Description:
Attempts to model the sub-pixel offsets between exposures in a spectrophotometric observation. Flux will be conserved during interpolation, meaning that non-constant offsets can create sudden jumps/drops in flux for pixels that are larger/smaller than they initially were. For any 'invalid' values that would require interpolating outside the range of the provided flux array will be returned as a NaN.

Parameters:
flux :: np.ndarray
A 2D array of fluxes oriented so that the dimensions represent (N_exposures, N_pixels).
error :: np.ndarray
A 2D array of errors for each entry in the 'flux' array.
N_divisions :: int
The number of equal chunks to split each exposure into to infer the offset. Generally, large values (N > 5) fail to accurately infer sub-pixel offsets due to a lack of distinct features in each sub-region.
model_flux :: np.ndarray
A model for the flux present in each exposure. If 'None', this defaults to the average flux at each pixel across every exposure.
mode :: str
Determines how sub-pixel offset information will be handled. 'median' calculates the median sub-pixel offset across each sub-region. 'fit' will use a polynomial with an order given by 'poly_order' to infer how offset varies along the dispersion axis of your flux array.
poly_order :: int
The polynomial order to use for 'fit' mode. To prevent issues with over-fitting, 'poly_order' must be less than or equal to 'N_divisions'.
apply_window :: bool
Optionally disables the 'Hanning' window that is applied to sub-regions before performing phase correlation.
progress :: bool
Toggles the progress bar.

Returns:
interpolated_flux :: np.ndarray
Interpolated flux at each valid 'target_pixels' location.
interpolated_error :: np.ndarray
Propagated 1-sigma uncertainties of 'interp_flux'.

estimate_exposure_offsets

specsuite.utils.estimate_exposure_offsets (
  flux,
  model_flux = None,
  N_divisions = 1,
  mode = "median",
  poly_order = 3,
  apply_window = True,
  progress = False,
): [SOURCE]

Description:
Attempts to estimate the effective pixel positions of the input 'flux' array compared to the 'model_flux'. This is done by performing a phase correlation of a model spectra against each individual exposure. The phase correlation produces an estimate of the sub-pixel offset(s) between the model and a given exposure. If 'N_divisions' > 1, this process is performed multiple sub-regions in every single exposure.

Parameters:
flux :: np.ndarray
A 2D array of fluxes oriented so that the dimensions represent (N_exposures, N_pixels).
model_flux :: np.ndarray
A 1D flux model to use for estimating sub-pixel offsets. If no model is provided, the median across all exposures will be used by default.
N_divisions :: int
The number of equal segments to split each individual exposure into before estimating pixel offsets.
mode :: str
Controls how sub-pixel offset information is used. If 'median', the median sub-pixel offset across all sub-regions is used for a given exposure. If 'fit', a polynomial is fit to extracted offsets and used to infer how offsets change the 'pixel axis' of the data.
poly_order :: int
The order of polynomial to fit to sub-pixel offets. Only matters if 'fit' mode is used, and must be <= 'N_divisions' to prevent over-fitting errors.
apply_window :: bool
Controls whether or not the 'hanning' window is used to smooth out edge effects before performing phase correlation. Defaults to 'True'.
progress :: bool
Toggles the progress bar.

Returns:
offset_pixels :: np.ndarray
The 'true' pixel array that each exposure in 'flux' lies on. These are defined relative to the 'model_flux', and may contain values outside of the model's pixel locations.

estimate_shift

specsuite.utils.estimate_shift (
  ref_fft,
  data_fft,
): [SOURCE]

Description:
Attempts to estimate the sub-pixel shift between two signals. This is done in two steps, first by finding the peak coarse shift, then by refining this estimate using the slope of the phase correlation.

Parameters:
ref_fft :: np.ndarray
The Fourier transform of the reference signal.
data_fft :: np.ndarray
The Fourier transform of the data signal.

Returns:
shift :: float
The estimated sub-pixel shift between the two signals.

flatfield_correction

specsuite.utils.flatfield_correction (
  image,
  flat,
  debug = False,
): [SOURCE]

Description:
Applies a simple flatfield correction to one or more 2D images. This function assumes that each entry along the first axis is a 2D image with the same size as 'flat'.

Parameters:
image :: np.ndarray
Image(s) that should be divided by the normalized flatfield image. This can be a single 2D image or an array of 2D images.
flat :: np.ndarray
A single unnormalized flatfield image, ideally the median of several flatfield exposures.
debug :: bool
Allows for diagnostic plotting.

Returns:
flatfielded_ims :: np.ndarray
The resulting image(s) after being divided by the normalized flatfield.

heavyside_step_filter

specsuite.utils.heavyside_step_filter (
  x,
  x0,
  lower_limit = 0.0,
  upper_limit = 1.0,
): [SOURCE]

Description:
A 1D filter throughput model corresponding to the 'heavyside step' filter normalized between 0 and 1.

Parameters:
x :: float
A 1D array of values to generate the filter model on.
x0 :: float
The cutoff value at which the filter transitions from its lower to upper limits.
lower_limit :: float
An optional parameter that sets the lower limit of the filter. Defaults to 0.0.
upper_limit :: float
An optional parameter that sets the upper limit of the filter. Defaults to 1.0.

Returns:
filter_throughput :: np.ndarray
The estimated filter throughput (0.0 - 1.0).

peak_phase_shift

specsuite.utils.peak_phase_shift (
  ref_fft,
  data_fft,
  alpha = 0.5,
): [SOURCE]

Description:
Estimates the shift between two signals by finding the peak of the phase correlation. This is a coarse estimate that can be refined using the 'phase_slope_shift' function.

Parameters:
ref_fft :: np.ndarray
The Fourier transform of the reference signal.
data_fft :: np.ndarray
The Fourier transform of the data signal.
alpha :: float
A power to apply to the magnitude of the cross-correlation. This can dampen or amplify the normalization factor, a factor of 0.5 has worked reasonably well as a default.

Returns:
shift :: float
The estimated shift between the two signals. This can be a non-integer value due to sub-pixel refinement.

perform_cdf_interpolation

specsuite.utils.perform_cdf_interpolation (
  flux,
  error,
  current_pixels,
  target_pixels,
): [SOURCE]

Description:
Flux-conserving interpolation using linear interpolation of the cumulative distribution function (CDF). This function assumes that x-errors are negligible and that the input flux array has errors that are independent and random. Any 'target_pixels' that fall outside the range spanned by 'current_pixels' will be returned with a NaN value.

Parameters:
flux :: np.ndarray
The original flux values.
error :: np.ndarray
1-sigma uncertainties corresponding to `flux`.
current_pixels :: np.ndarray
The pixels locations of that the 'flux' and 'error' arrays are currently sampled on.
target_pixels :: np.ndarray
The desired pixels to interpolate onto. Only locations (xd) that lie within the range spanned by 'current_pixels' will be calculated.

Returns:
interp_flux :: np.ndarray
Interpolated flux at each valid 'target_pixels' location.
interp_error :: np.ndarray
Propagated 1-sigma uncertainties of 'interp_flux'.

phase_slope_shift

specsuite.utils.phase_slope_shift (
  ref_fft,
  data_fft,
): [SOURCE]

Description:
Estimates the sub-pixel shift between two signals by calculating the slope of the phase correlation. This is a refinement step that can be applied after finding the peak shift using 'peak_phase_shift'.

Parameters:
ref_fft :: np.ndarray
The Fourier transform of the reference signal.
data_fft :: np.ndarray
The Fourier transform of the data signal.

Returns:
shift :: float
An estimate of the sub-pixel shift between the two signals.

plot_image

specsuite.utils.plot_image (
  image,
  xlim = None,
  ylim = None,
  xlabel = "Dispersion Axis (pix)",
  ylabel = "Cross-Dispersion Axis (pix)",
  cbar_label = "Counts",
  title = "",
  figsize = (10, 3),
  cmap = "inferno",
  savedir = "None",
  kwargs,
): [SOURCE]

Description:
A simple wrapper for matplotlib.pyplot.imshow(). By default, this function uses a handful of style options to keep all visualizations consistent within our documentation. You should be able to overwrite these options and provide any of the standard additional KWARGS.

Parameters:
image :: np.ndarray
A single 2D array. If it is not a Numpy array, the function will attempt to convert it into one.
xlim :: tuple
The (xmin, xmax) to show. If none is provided, defaults to the entire horizontal span of the image.
ylim :: tuple
The (ymin, ymax) to show. If none is provided, defaults to the entire vertical span of the image.
xlabel :: str
Text to write along the x-axis (bottom) of the image.
ylabel :: str
Text to write along the y-axis (left) of the image.
cbar_label :: str
A text label assigned to the colorbar.
title :: str
A title to plot at the top of the image.
figsize :: tuple
The dimensions (horizontal, vertical) of the image.
cmap :: str
Name of the matplotlib colormap to use.
savedir :: str
Directory (+filename) to save the generated image at. If an argument is provided, then 'plt.show()' will not run.

rebin_image_columns

specsuite.utils.rebin_image_columns (
  image,
  bin,
): [SOURCE]

Description:
Rebins an image along a single axis. The bin size must be an integer multiple of the axis size being rebinned.

Parameters:
image :: np.ndarray
Original image to be rebinned.
bin :: int
Size each bin in pixels along the columns of the provided image.

Returns:
rebinned_image :: np.ndarray
An image where the columns have been rebinned into bin length pixels.

THROUGHPUT

generate_flux_conversion

specsuite.throughput.generate_flux_conversion (
  w_measured,
  w_model,
  f_measured,
  f_model,
  err,
  sigma_clip = 50.0,
  order = 7,
  max_iter = 50,
  debug = False,
): [SOURCE]

Description:
Generates a numpy polynomial that predicts the physical flux [flam] / CCD count as a function of wavelength [Angstroms].

Parameters:
w_measured :: np.ndarray
A 1D array of wavelengths for your CCD spectrum (in Angstroms).
w_model :: np.ndarray
A 1D array of wavelengths for your known spectrum (in Angstroms).
f_measured :: np.ndarray
A 1D array of flux for your CCD spectrum.
f_model :: np.ndarray
A 1D array of flux for your known spectrum.
err :: np.ndarray
A 1D array of errors for you CCD flux.
sigma_clip :: float
The max number of standard deviations a point is allowed to be from the calibration model. Outlier points are removed from future fits.
order :: int
Polynomial order of the flux conversion.
max_iter :: int
Maximum number of fits to perform before manually stopping.
debug :: bool
Plots the final fit against the user-provided data.

Returns:
p_flux_conversion :: np.poly1d
An n-th order polynomial that takes wavelength [Angstroms] as an argument. The returned value converts CCD counts into physical units [flam], meaning it is in units of flam/count.

load_STIS_spectra

specsuite.throughput.load_STIS_spectra (
  name = "None",
  filetype = "model",
  wavelength_bounds = None,
  debug = False,
): [SOURCE]

Description:
Attempts to download spectra data from the STIS website (see url below). It only looks for data contained in the first data table.

Parameters:
name :: str
Name of the star to load data for. This should match an entry in the "Star name" column of Table 1.
filetype :: str
Determines which type of model to load from the STIS database. The only valid options are "model" or "stis".
wavelength_bounds :: tuple
The (wmin, wmax) region of the STIS spectra to keep. Both values must have astropy units compatible with wavelength.
debug :: bool
Allows diagnostic information to be output.

Returns:
wavs :: np.ndarray
Retrieved model wavelengths (Angstroms)
flux :: np.ndarray
Retrieved model flux (flam)
cont :: np.ndarray
Retrieved model flux (flam)

EXTRACTION

_infer_achromatic_deviations

specsuite.extraction._infer_achromatic_deviations (
  ratios,
  max_iterations = 5,
  outlier_threshold = 3,
  debug = True,
): [SOURCE]

Description:
Infers the achromatic deviations in flux for each wavelength bin by fitting a constant offset to the 'ratios' output from '_infer_flux_baselines'. The output is a 2D array of the same shape as 'flux' where each column is the flux / fitted baseline for that wavelength bin. This can be thought of as the ratio of the observed flux to the expected baseline, with the wavelength-dependent trends removed.

Parameters:
ratios :: np.ndarray
The output from '_infer_flux_baselines', which is the ratio of the observed flux to the fitted baseline for each wavelength bin.
max_iterations :: int
The maximum number of iterations for sigma-clipping to remove outliers when fitting the achromatic deviations. Should be a positive integer.
outlier_threshold :: int
The number of MADs above which a point is considered an outlier when fitting the achromatic deviations. Should be a positive integer.
debug :: bool
Enables optional debugging plots.

Returns:
achromatic_bump :: np.ndarray
A 2D array with the same shape as 'flux' and 'error' that contains the correction factor to remove achromatic bumps.
achromatic_bump_error :: np.ndarray
A 2D array with the same shape as 'flux' and 'error' that contains the uncertainty on the correction factor to remove achromatic bumps.

_infer_flux_baselines

specsuite.extraction._infer_flux_baselines (
  times,
  flux,
  error,
  max_iterations = 5,
  outlier_threshold = 3,
  debug = True,
): [SOURCE]

Description:
Approximates the baseline flux for each wavelength bin by fitting a sloped line to the flux for the bin over time. The output array is a 2D array of the same shape as 'flux' where each column is the flux / fitted baseline for that wavelength bin. This can be thought of as the ratio of the observed flux to the expected baseline.

Parameters:
times :: np.ndarray
The times at which each exposure was taken, should correspond to the rows of 'flux' and 'error'. There should be no astropy units associated with this array.
flux :: np.ndarray
A 2D array of flux values with shape (N_exposures, N_wavelength_bins).
error :: np.ndarray
A 2D array of flux uncertainties with the same shape as 'flux'.
max_iterations :: int
The maximum number of iterations for sigma-clipping to remove outliers when fitting the baseline. Should be a positive integer.
outlier_threshold :: int
The number of MADs above which a point is considered an outlier when fitting the baseline. Should be a positive integer.
debug :: bool
Enables optional debugging plots.

Returns:
ratios :: np.ndarray
The ratio of the observed flux to the fitted baseline for each wavelength bin, with the same shape as 'flux'.

boxcar_extraction

specsuite.extraction.boxcar_extraction (
  images,
  backgrounds,
  RN = 0.0,
  debug = False,
): [SOURCE]

Description:
Performs a simple boxcar extraction on an image (or series of images). This assumes that both arrays of images of dimensions corresponding to... (cross-dispersion, dispersion) If that is not the case, please rotate your data arrays before feeding them into this function.

Parameters:
images :: np.ndarray
A 2D (or array of several 2D) science exposures that have been background subtracted.
backgrounds :: np.ndarray
A 2D (or array of several 2D) background exposures that have been subtracted off of your science images.
RN :: float | np.ndarray
The read noise associated with your detector.
debug :: bool
Allows for optional plotting.

Returns:
flux_array :: np.ndarray
A 2D array containing the flux of each provided exposure. Has a shape of (image index, pixel position).
error_array :: np.ndarray
A 2D array containing the undertainty of each provided exposure. Has a shape of (image index, pixel position).

estimate_atmospheric_loss

specsuite.extraction.estimate_atmospheric_loss (
  wavelengths,
  flux,
  error,
  times,
  airmass,
  p0 = None,
  bounds = None,
  max_iterations = 5,
  outlier_threshold = 5.0,
  return_components = False,
  debug = False,
): [SOURCE]

Description:
Uses a multi-component modelling approach to estimate atmospheric losses for ground-based, time-series spectroscopic observations. The chromatic model includes airmass-dependent extinction from Rayleigh scattering, O2 absorption, H2O absorption, and an achromatic loss term to account for an average loss across all wavelengths. It also includes a wavelength offset parameter to account for calibration errors and a resolution parameter to apply convolution to the model. O2 and H2O extinction is estimated using pre-computed models based on the TelFit package. The achromatic model attempts to capture deviations in flux that happen sporadically across all wavelengths in any given exposure. This could be caused by clouds, instrumental issues, or any plausibly-achromatic source of light loss.

Parameters:
wavelengths :: np.ndarray
A 1D array of wavelengths at which the extinction model should be evaluated.
flux :: np.ndarray
A 2D array of flux values with shape (N_exposures, N_wavelength_bins). Should be on a linear scale (not magnitudes) and should not have any telluric correction applied.
error :: np.ndarray
A 2D array of flux uncertainties with the same shape as 'flux'.
times :: np.ndarray
The times at which each exposure was taken, should correspond to the rows of 'flux' and 'error'. There should be no astropy units associated with this array, but if there are, they will be removed internally.
airmass :: np.ndarray
A 1D array of airmass values for each exposure, should correspond to the rows of 'flux' and 'error'.
p0 :: dict
A dictionary containing the initial guess for the model parameters. The expected keys are: 'rs_tau0', 'o2_abundance', 'humidity', 'w_offset', 'loss_constant', and 'R'. If None, default values will be used.
bounds :: dict
A dictionary containing the bounds for the model parameters during fitting. The expected keys are the same as for p0, and the values should be tuples specifying the (min, max) bounds for each parameter. If None, default bounds will be used.
max_iterations :: int
The maximum number of iterations for sigma-clipping routines to remove outliers when fitting the extinction model and achromatic deviations. Should be a positive integer.
outlier_threshold :: float
The number of MADs above which a point is considered an outlier when fitting the extinction model and achromatic deviations. Should be a positive float.
return_components :: bool
If True, also returns the individual extinction components (O2, H2O, Rayleigh) as separate arrays in a dictionary. Default is False.
debug :: bool
Enables optional debugging plots for the extinction model fitting and achromatic deviation fitting processes.

Returns:
atmospheric_correction_model :: np.ndarray
A 2D array with the same shape as 'flux' and 'error' that contains the multiplicative correction factor to remove atmospheric losses.
extinction_components :: dict
A dictionary containing the individual extinction components as separate arrays with keys 'o2', 'humidity', and 'rayleigh'. Only returned if 'return_components' is True.
achromatic_correction :: np.ndarray
A 2D array with the same shape as 'flux' and 'error' that contains the multiplicative correction factor to remove achromatic bumps. Only returned if 'return_components' is True.

estimate_extinction_coefficients

specsuite.extraction.estimate_extinction_coefficients (
  airmass,
  flux,
  error,
  max_iterations = 5,
  clip_threshold = 5.0,
): [SOURCE]

Description:
Attempts to estimate the extinction coefficients (taus) over the course of a single night of observations. The provided data arrays should correspond to a comparison star that should be relatively non-variable over the course of the night.

Parameters:
airmass :: np.ndarray
Airmass values corresponding to each observation in the flux array. Plane-parallel estimates are accurate enough!
flux :: np.ndarray
2D array of shape (n_observations, n_wavelength_bins) containing the flux measurements for the comparison star at each wavelength bin and observation time.
error :: np.ndarray
2D array of shape (n_observations, n_wavelength_bins) containing the uncertainties associated with each flux measurement in the flux array.
max_iterations :: int
Maximum number of iterations used for the sigma-clipping process.
clip_threshold :: float
The threshold (in units of median absolute deviation) beyond which a data point is considered an outlier and excluded from the fit.

Returns:
taus :: np.ndarray
1D array of estimated extinction coefficients (taus) for each wavelength bin.
taus_error :: np.ndarray
1D array of uncertainties associated with each estimated extinction coefficient.

fit_achromatic_bumps

specsuite.extraction.fit_achromatic_bumps (
  times,
  flux,
  error,
  airmasses,
  throughput_model,
  max_iterations = 5,
  outlier_threshold = 3,
  debug = False,
): [SOURCE]

Description:

Parameters:
times :: np.ndarray
The times at which each exposure was taken, should correspond to the rows of 'flux' and 'error'. There should be no astropy units associated with this array, but if there are, they will be removed internally.
flux :: np.ndarray
A 2D array of flux values with shape (N_exposures, N_wavelength_bins).
error :: np.ndarray
A 2D array of flux uncertainties with the same shape as 'flux'.
airmasses :: np.ndarray
A 1D array of airmass values for each exposure, should correspond to the rows of 'flux' and 'error'. There should be no astropy units associated with this array.
throughput_model :: ExtinctionModel
A model that takes in airmass values and outputs the expected throughput at each wavelength. This is used to correct the flux values before fitting the baseline, to try and remove the effects of telluric absorption.
max_iterations :: int
The maximum number of iterations for sigma-clipping routines to remove outliers. Should be a positive integer.
outlier_threshold :: int
The number of MADs above which a point is considered an outlier when fitting the baseline or achromatic deviations. Should be a positive integer.
debug :: bool
Enables optional debugging plots.

Returns:
achromatic_correction :: np.ndarray
A 2D array with the same shape as 'flux' and 'error' that contains the multiplicative correction factor to remove achromatic bumps.

fit_extinction_model

specsuite.extraction.fit_extinction_model (
  wavelengths,
  taus,
  taus_error,
  p0 = None,
  bounds = None,
  debug = False,
): [SOURCE]

Description:
Fits a multi-component telluric extinction model to the input data. This model includes molecular absorption from O2 and H2O, Rayleigh scattering, and an achromatic loss term. The model is convolved to a specified resolution and includes a wavelength offset parameter to account for calibration errors.

Parameters:
wavelengths :: np.ndarray
A 1D array of wavelengths at which the extinction model should be evaluted. Ideally, this should have some astropy units attached, but if not will assume Angstroms.
taus :: np.ndarray
A 1D array of the same length as wavelengths, containing the estimated effective optical depth (tau) of the atmosphere at each wavelength.
taus_error :: np.ndarray
A 1D array of the same length as wavelengths, containing the uncertainties on the tau estimates.
p0 :: dict
A dictionary containing the initial guess for the model parameters. The expected keys are: 'rs_tau0', 'o2_abundance', 'humidity', 'w_offset', 'loss_constant', and 'R'. If None, default values will be used.
bounds :: dict
A dictionary containing the bounds for the model parameters during fitting. The expected keys are the same as for p0, and the values should be tuples specifying the (min, max) bounds for each parameter. If None, default bounds will be used.
debug :: bool
Optional plotting.

Returns:
best_model :: np.ndarray
The best-fit telluric throughput model evaluated at the input wavelengths.
fitted_values :: np.ndarray
The best-fit values for the model parameters in the following order: - rs_tau0 - o2_abundance - humidity - w_offset - loss_constant - R
fitted_values_errors :: np.ndarray
The 1-sigma uncertainties on the fitted parameters, calculated from the covariance matrix returned by curve_fit.

generate_extinction_model

specsuite.extraction.generate_extinction_model (
  wavelengths,
  rs_tau0 = 0.0,
  aero_tau0 = 0.0,
  o2_abundance = 20000,
  o3_abundance = 258,
  humidity = 50,
  w_offset = 0.0,
  loss_constant = 1.0,
  R = 2000,
  airmass = 1.0,
): [SOURCE]

Description:
Generates a model for telluric extinction with individual contributions from Rayleigh scattering, O2 absorption, and H2O absorption. There is also a 'constant loss' term to account for achromatic losses, a wavelength offset to account for calibration errors, and a resolution parameter to apply convolution to the model.

Parameters:
wavelengths :: np.ndarray
A 1D array of wavelengths at which to evaluate the extinction model. Ideally, this should have some astropy units attached, but if not will assume Angstroms.
rs_tau0 :: float
The unitless tau0 parameter for Rayleigh scattering, which sets the overall strength of the Rayleigh scattering contribution.
aero_tau0 :: float
The unitless tau0 parameter for Rayleigh scattering, which sets the overall strength of the aerosol scattering contribution.
o2_abundance :: float
The abundance of O2 in the atmosphere, which scales the O2 absorption model. Typically, a value around 100000-300000 is reasonable for Earth's atmosphere.
o3_abundance :: float
The column density of O3 in the atmosphere, which scales the O3 absorption model. Typically, a value around 250-300 is reasonable for Earth's atmosphere. Technically, this is in Dobson units, but converting into ppm can be fairly tricky.
humidity :: float
The relative humidity percentage, which scales the H2O absorption model. Only values 0 <= humidity <= 100 are physically meaningful.
w_offset :: float
A wavelength offset in the same units as the input wavelengths, which accounts for a linear shift in the wavelength solution.
loss_constant :: float
A constant multiplicative factor between 0 and 1 that accounts for achromatic losses such as clouds or instrumental throughput issues.
R :: float
The spectral resolution (lambda/delta_lambda) to which the model should be convolved. Uses an FFT convolution for runtime efficiency.
airmass :: float
The airmass of the observation, which scales all extinction components.

Returns:
complete_model :: np.ndarray
The combined extinction model evaluated at the input wavelengths.

generate_spatial_profile

specsuite.extraction.generate_spatial_profile (
  image,
  profile = "moffat",
  profile_order = 7,
  bin_size = 8,
  repeat = True,
  debug = False,
): [SOURCE]

Description:
Generates a 'spatial profile' as outlined in Horne (1986). Spatial profiles predict the likelihood that a photon would land at a given cross-dispersion location for each wavelength. This function assumes that the dispersion axis is located along the x-axis.

Parameters:
image :: np.ndarray
The image that a spatial profile is fit to.
profile :: str
Name of the type of profile to fit for. Currently, the only valid options are... - moffat - gaussian
profile_order :: int
The order of the polynomial used to fit to each constant in the specified spatial profile (i.e., along the dispersion axis, the mean evolve as what order of polynomial?)
bin_size :: int
Size of each bin used for 'binning down' the provided image before fitting.
repeat :: bool
Allows the initial fit to each parameter to influence the initial guesses in a second series of fits.
debug :: bool
Allows for optional debugging plots to be shown.

horne_extraction

specsuite.extraction.horne_extraction (
  images,
  backgrounds,
  profile = "moffat",
  profile_order = 3,
  RN = 0.0,
  bin_size = 16,
  max_iter = 5,
  masks = None,
  return_spatial_profiles = False,
  repeat = True,
  debug = False,
  progress = False,
): [SOURCE]

Description:
Performs a profile-weighted (Horne) extraction for a series of science exposures.

Parameters:
images :: np.ndarray
A single (or multiple) 2D exposures containing a point-source trace to extract flux from.
backgrounds :: np.ndarray
A single (or multiple) 2D exposures contianing the background subtracted off of the science exposures. Used for calculating the uncertainty of the reduction.
profile :: str
Which type of 1D profile to use for generating a spatial profile. Valid options are 'moffat' or 'gaussian'.
profile_order :: int
The polynomial order that describes how the 1D profile (in the fitted spatial profile) changes with pixel position along the dispersion axis.
RN :: float | np.ndarray
The read noise of your exposure. If the provided argument is a float, then every pixel will be assigned an equal read noise. Otherwise, if provided a 2D array, then each exposure will be assigned the corresponding value for that pixel.
bin_size :: int
The number of pixels (dispersion axis) to lump into a single bin when generating a spatial profile. Generally, a higher value increases the probability that 'generate_spatial_profile()' converges, but the precision of the extracted profile is lower.
max_iter :: int
The number of iterations to repeat the Horne extraction algorithm for. The cosmic ray masking has been removed, so the only benefit from increasing 'max_iter' is the potential to get a better constraint on the spatial profile.
masks :: np.ndarray
A single (or multiple) 2D mask containing pixels that represent known outliers in your data. This can be used to handle dead pixels, cosmic rays, etc.
return_spatial_profiles :: bool
Determines whether or not to return all spatial profiles. If yes, the third output of this function will be an array filled with the final spatial profile used to extract flux from the corresponding exposure.
repeat :: bool
Whether to repeat the spatial profile generation once an initial pass has been made. When your data is particularly noisy, it is helpful to keep this as 'True'.
debug :: bool
Allows for optional plotting.
progress :: bool
Enables a progress bar to be displayed.

Returns:
flux :: np.ndarray
An array containing the extracted flux for each exposure.
flux_err :: np.ndarray
An array containing the extracted error for each exposure.

trace_fit

specsuite.extraction.trace_fit (
  image,
  bin = 16,
  trace_order = 2,
  debug = False,
): [SOURCE]

Description:
Fits a trace to a signal across the horizontal axis of an image. This is done by rebinning a user-given image, fitting a gaussian to each rebinned column, and fitting an n-dimensional curve to these gaussian positions.

Parameters:
image :: np.ndarray
Image with a signal spanning the horizontal axis of the detector.
bin :: int
Number of pixels to group into a single bin. Must be an integer multiple of the horizontal pixel count.
trace_order :: int
Order of the polynomial to be fit to our trace fit data.
debug :: bool
Allows plot generation.

Returns:
xpoints :: np.ndarray
Horizontal pixel positions corresponding to our detected trace fit. This has been converted from the downsampled x-values to the original image x-values.
locs :: np.ndarray
Vertical locations of the detected trace positions.
stds :: np.ndarray
Standard deviations associated with each gaussian fit in the downsampled image.
p_center :: np.poly1d
Polynomial fit that traces our signal out across the detector.

WAVECAL

calculate_evidence

specsuite.wavecal.calculate_evidence (
  valid_keys,
  d_obs,
  sig_d,
  pad,
): [SOURCE]

Description:
Calculates the Bayesian evidence (i.e., the probability of a given key being calculated integrated over all triplet pairs).

Parameters:
valid_keys :: np.ndarray
All possibe keys (rounded distances) across all triplet pairs.
d_obs :: np.ndarray
The calculated relative distances corresponding to each triplet pair.
sig_d :: np.ndarray
The calculated error in each distance measurement provided in 'd_obs'.
pad :: float
The size of half a bin in the geometric hashing routine. This should be equivalent to 0.5 * 10^(-rounding).

Returns:
evidence :: np.ndarray
A 1D array containing the probability that each key is measured across all possible triplet combinations.
prob_mass :: np.ndarray
A 2D array containing the probability mass for all possible triplet combinations.

cast_votes

specsuite.wavecal.cast_votes (
  n_model_points,
  n_data_points,
  prob_mass,
  evidence,
  valid_keys,
  hash_table,
  di_v,
  dj_v,
  dk_v,
): [SOURCE]

Description:
Casts votes for each possible combination of points using a traditional geometric hashing scheme. If a pair of triplets produces a key found in the hash table, then the data points will be added as a possible match for each of model points listed for that entry in the hash table. However, the votes are weighted by the Bayesian probability of that match being correct.

Parameters:
n_model_points :: int
The total number of model points.
n_data_points :: int
The total number of data points.
prob_mass :: np.ndarray
A 2D array containing the probability mass for all possible triplet combinations.
evidence :: np.ndarray
A 1D array containing the probability that each key is measured across all possible triplet combinations.
valid_keys :: np.ndarray
A list of all possible keys in the hash table. This is stored in a separate list to prevent unecessary duplicate lookups.
hash_table :: dict
A hash table where each key corresponds to the relative distance calculated from three points.
di_v :: np.ndarray
The indices of all b1 values in the data triplet array.
dj_v :: np.ndarray
The indices of all b2 values in the data triplet array.
dk_v :: np.ndarray
The indices of all p values in the data triplet array.

Returns:
votes :: np.ndarray
The probability-weighted votes indicating which pairs of model and data points is most likely.

compute_triplet_values_from_indices

specsuite.wavecal.compute_triplet_values_from_indices (
  lines_round,
  triplet_idx,
): [SOURCE]

Description:
Using a list of rounded line positions, this function calculates the relative distances of each possible triplet of points. It also returns some related, useful arrays that can be used for filtering. All calculations are vectorized to reduce runtime.

Parameters:
lines_round :: np.ndarray
A 1D array containing rounded line positions.
triplet_idx :: np.ndarray
A 2D array (N x 3) containing the indices of each line that make up the triplet. The length N should be equal to the total number of valid triplets that can be formed from 'lines_round', and each entry should be a value representing an index location in the 'lines_round' array.

Returns:
b1 :: np.ndarray
A 1D array containing all of the first base points.
b2 :: np.ndarray
A 1D array containing all of the second base points.
p :: np.ndarray
A 1D array containing all of the reference points.
d :: np.ndarray
A 1D array containing all of the scale-normalized distances calculated using b1, b2, and p. If the calculated scale is 0.0 or the reference point is the same as one of the base points, the corresponding entry is replaced with a NaN value.
valid :: np.ndarray
A 1D array filled with boolean entries indicating whether the calculated distance is a NaN or not.
i :: np.ndarray
The indices of all b1 values in the 'triplet_idx' array.
j :: np.ndarray
The indices of all b2 values in the 'triplet_idx' array.
k :: np.ndarray
The indices of all p values in the 'triplet_idx' array.

correct_wavelengths

specsuite.wavecal.correct_wavelengths (
  rainbow,
  p_wavecal,
  N_divisions = 5,
): [SOURCE]

Description:
Corrects for the sub-pixel shifts in the spectral energy distributions (SEDs) of the Rainbow object. This is done by splitting the SED into 'N_divisions' segments, estimating the offset between each sement and a reference SED, and then taking the median over all segments. Using the wavelength solution, p_wavecal, the pixel position shifts are then converted into wavelength shifts.

Parameters:
rainbow :: Rainbow
The Rainbow object to correct.
p_wavecal :: np.poly1d
The wavelength solution to use for converting pixel positions into wavelengths (in units of Angstroms).
N_divisions :: int
The number of segments to split the SED into for estimating the sub-pixel shifts. A higher number of divisions may yield a more accurate estimate, but may also be more susceptible to noise.

match_features

specsuite.wavecal.match_features (
  raw_data_lines,
  raw_model_lines,
  iterations = 10,
  rounding = 3,
  sigma = 2.0,
  order = 2,
  debug = False,
): [SOURCE]

Description:
Attempts to find the most probable matches in lines bewteen two lists. This function assumes that the model lines have no (or negligible) error, and that all data lines have a constant error described by 'sigma'.

Parameters:
raw_data_lines :: np.ndarray
A 1D list of lines indicating the pixel positions of line emissions.
raw_model_lines :: np.ndarray
A 1D list of line indicating the known wavelengths of some of the observed data lines. This list can be shorter or longer than 'raw_data_lines,' but this will impact the accuracy of the voting routine.
iterations :: int
The number of iterations to repeat feature matching. For well-behaved examples, the votes will converge to a consistent answer after a handful of iterations. However, excessive looping can lead to a gradual break in the accuracy of the calculated matches.
rounding :: int
How many decimal places to measure relative distances to. For example, using 'rounding=3' will calculate distances to three decimal places.
sigma :: float
The uncertainty (in the same units as 'raw_data_lines') of data line locations.
order :: int
The polynomial order to fit to the matched features. We highly recommend keeping this at 'order=2'.
debug :: bool
Allows for diagnostic plots to be shown.

Returns:
votes :: np.ndarray
A 2D array showing the probability of a given data line being paired with a given model line.

sigma_d_from_triplets

specsuite.wavecal.sigma_d_from_triplets (
  b1,
  b2,
  p,
  sigma_measured,
): [SOURCE]

Description:
Calculates the uncertainty in relative distance measurements for a given triplet of points.

Parameters:
b1 :: np.ndarray
A 1D array containing all of the first base points.
b2 :: np.ndarray
A 1D array containing all of the second base points.
p :: np.ndarray
A 1D array containing all of the reference points.
sigma_measured :: float
An estimate of the uncertainty in line positions. Assumes that the same error applies to all points.

Returns:
sigma_d :: np.ndarray
A 1D array representing the uncertainty in distance measurements for each triplet.

COSMIC_RAYS

_cluster_in_grid

specsuite.cosmic_rays._cluster_in_grid (
  x_points,
  y_points,
  R,
): [SOURCE]

Description:
Groups an array of points that lie within a box of width R around one another.

Parameters:
x_points :: np.ndarray
All the x-coordinates of points to be grouped.
y_points :: np.ndarray
All the y-coordinates of points to be grouped.
R :: float
Width of the box used for grouping points together.

Returns:
averaged_points :: np.ndarray()
An array of averaged points.

_expand_mask

specsuite.cosmic_rays._expand_mask (
  mask,
  ray_padding = 1,
): [SOURCE]

Description:
Uses JAX convolution to pad zero-valued pixels surrounding nonzero-valued pixels. This can be performed multiple times to produce several layers of padding.

Parameters:
mask :: np.ndarray
An array with binary (1 or 0) entries.
ray_padding :: int
How many pixels surrounding a cosmic ray to flag as 'potentially contaminated.' These padded pixels will all have a value between 0 and 1 to allow users to easily filter them out after processing.

Returns:
mask :: np.ndarray
A nearly-identical array to the input mask, but with non-zero values for pixels surrounding each non-zero entry in the original array.

_gaussian_mask

specsuite.cosmic_rays._gaussian_mask (
  shape,
  mean,
  std,
): [SOURCE]

Description:
Create an N-dimensional Gaussian mask where the mean and standard deviation is specified along each dimension.

Parameters:
shape :: np.ndarray
An array of N integers that specifies the shape of the mask.
mean :: np.ndarray
An array of N floats that control the mean of the gaussian profiles along each dimension. Must have the same number of entries as 'shape'.
std :: np.ndarray
An array of N floats indicating the standard deviation of the gaussian profiles along each dimension.

Returns:
gaussian :: np.ndarray
An n-dimensional NumPy array with Gaussian values

flag_cosmic_rays

specsuite.cosmic_rays.flag_cosmic_rays (
  images,
  gauss_stds = None,
  thresh = 2000.0,
  group_radius = 20,
  progress = False,
  debug = False,
): [SOURCE]

Description:
Masks out low-frequency features using a 3D DFT with several masks. This function will then attempt to identify the remaining bright pixels and group them together if they reside within a user-specified distance from each other.

Parameters:
images :: np.ndarray
A 3D array of images ordered such that dimensions are (time, y, x).
gauss_stds :: np.ndarray
A tuple of std values to be used when constructing an n-dimensional Gaussian mask. The order of each entry should correspond with the respective dimension of your image array.
thresh :: float
The minimum brightness required to flag a bright pixel as a potential cosmic ray. Note that this threshold applies to the reconstructed image after filtering has been applied.
group_radius :: int
The distance (pixels) within which two bright pixels will be grouped into a single coordinate at located between them.
progress :: bool
Toggles progress bar.
debug :: bool
Allows for diagnostic plotting.

Returns:
cosmic_ray_locs :: dict
A dictionary containing the image indexes in which cosmic rays were found, along with a list of each cosmic ray's location.
reconstructed_ims :: np.ndarray
An array of images where low-frequency contributions have been damped in the FFT. Has the same shape as the input image array.

replace_cosmic_rays

specsuite.cosmic_rays.replace_cosmic_rays (
  images,
  masks,
  time_kernel = 5,
  progress = False,
): [SOURCE]

Description:

Parameters:
images :: np.ndarray
Raw time-series array of images used for averaging out cosmic ray contamination.
masks :: np.ndarray
A collection of masks that represet the location of cosmic rays along the detector. Any non-zero entry in a mask will be converted to 1.
time_kernel :: int
The number of images to take the median over when converting the cosmic ray pixels into filtered ones.
progress :: bool
Toggles progress bar.

Returns:
filtered_ims :: np.ndarray
A time-series array where cosmic rays have been replaced with the median of surrounding exposures at that location.

verify_cosmic_rays

specsuite.cosmic_rays.verify_cosmic_rays (
  images,
  locs,
  thresh,
  time_kernel_size = 10,
  ray_padding = 1,
  group_radius = 20,
  progress = False,
  debug = False,
): [SOURCE]

Description:
Verifies a handful of user-specified cosmic rays by analyzing a small region around the flagged pixels(s).

Parameters:
images :: np.ndarray
Array of images in which cosmic rays have been identified. The ordering of this image array should correspond with the entries in the 'locs' dictionary.
locs :: dict
Has entries of the form: {0: [(x1,y1), (x2,y2), ...], 1: [...]} The keys should indicate the image index each list of points refers to. Each point should represent a single cosmic ray where the (x,y) coordinate are ints representing its pixel position.
thresh :: float
The minimum σ-normalized difference to consider a confirmed cosmic ray. Pixels matching this condition will be represented as 1s in the corresponding mask.
time_kernel_size :: int
The number of surrounding images to check for generating a median exposure. Specifically, the median exposure will range from -N//2 to N//2.
ray_padding :: int
How many pixels around confirmed cosmic ray pixels to also provide a nonzero value in the output mask.
group_radius :: int
The distance (pixels) within which two bright pixels will be grouped into a single coordinate at located between them.
progress :: bool
Toggles progress bar.
debug :: bool
Allows for optional diagnostic plots.

Returns:
masks :: np.ndarray
Masks containing 0 for non-contaminated pixels, and non-zero entries for potentially-contaminated pixels.
verified_cosmic_rays :: dict
A dictionary containing the 'confirmed' cosmic rays found in each exposure.