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'.

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.

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

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).

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,
  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.
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.