API

Primary Interface

hustle_tools.run_pipeline

hustle_tools.run_pipeline.run_pipeline(config_files_dir, stages=(0, 1, 2))[source]

Wrapper for all Stages of the HUSTLE-tools pipeline.

Parameters:

config_files_dir (str) – folder which contains the .hustle files needed to run the stages you want to run.
stages (tuple, optional) – the stages that you want to run. Defaults to (0, 1, 2).

Stage 0: Data Handling

Get Files From MAST

hustle_tools.stage_0.get_files_from_mast.download_from_MAST(data_products, visit_number, outdir, token=None, verbose=2)[source]

From the provided list of data products, downloads only those that have the appropriate visit number.

Parameters:

data_products (_type_) – output of queryMAST.py.
visit_number (str) – The visit number you want to download, e.g. “01”, “02”, etc.
outdir (str) – The directory you want the files downloaded to.
token (str, optional) – A MAST authentication token, if you are downloading proprietary data. Defaults to None.
verbose (int, optional) – From 0 to 2, how much detail you want the output logs to have. Defaults to 2.

hustle_tools.stage_0.get_files_from_mast.get_files_from_mast(programID, target_name, visit_number, outdir, token=None, extensions=None, verbose=2)[source]

Queries MAST database and downloads specified files from specified program, target, and visit number.

Parameters:

programID (str) – ID of the observing program you want to query data from. On MAST, referred to as “proposal_ID”.
target_name (str) – Name of the target object you want to query data from. On MAST, referred to as “target_name”.
visit_number (str) – The visit number you want to download, e.g. “01”, “02”, etc.
outdir (str) – The directory you want the files downloaded to.
token (str, optional) – A MAST authentication token, if you are downloading proprietary data. Defaults to None.
extensions (lst of str, optional) – File extensions you want to download. If None, take all file extensions. Otherwise, take only the files specified. Defaults to None.
verbose (int, optional) – From 0 to 2, how much detail you want the output logs to have. Defaults to 2.

hustle_tools.stage_0.get_files_from_mast.query_MAST(programID, target_name, extensions, verbose=2)[source]

Queries MAST database to find list of data products related to your observations.

Parameters:

programID (str) – ID of the observing program you want to query data from. On MAST, referred to as “proposal_ID”.
target_name (str) – Name of the target object you want to query data from. On MAST, referred to as “target_name”.
extensions (lst of str, optional) – File extensions you want to download. If None, take all file extensions. Otherwise, take only the files specified. Defaults to None.
verbose (int, optional) – From 0 to 2, how much detail you want the output logs to have. Defaults to 2.

Returns:

Filenames to request to download from MAST.

Return type:

lst of str

Collect And Move Files

hustle_tools.stage_0.collect_and_move_files.collect_and_move_files(visit_number, fromdir, outdir, verbose=2)[source]

Collects, renames, and moves the spec, direct, visit-related, and misc files to the right directories.

Parameters:

visit_number (str) – The visit number that we want to look at.
fromdir (str) – The directory where the orbitNframeN, orbitNdirectN, and misc files are kept.
outdir (str) – Where the files will be moved to.
verbose (int, optional) – From 0 to 2, how much detail you want the output logs to have. Defaults to 2.

hustle_tools.stage_0.collect_and_move_files.collect_files(search_dir, visit_number, verbose=2)[source]

Searches the search_dir for files of the right visit_number.

Parameters:

search_dir (str) – The visit number that we want to look at.
visit_number (str) – The directory that you want to locate files in.
verbose (int, optional) – From 0 to 2, how much detail you want the output logs to have. Defaults to 2.

Returns:

Lists of filepaths inside of the directory sorted by direct/spec/misc.

Return type:

lst of str

hustle_tools.stage_0.collect_and_move_files.identify_orbits(spec_flt, spec_spt, direct_flt, direct_spt, jit_files, misc_files, outdir, verbose=2)[source]

Opens each file and checks exposure time starts to find orbits.

Parameters:

spec_flt (lst of str) – The filepaths to the spectroscopic flt images. Used to find orbits.
spec_spt (lst of str) – The filepaths to the spectroscopic spt images corresponding to the flt images.
direct_flt (lst of str) – The filepaths to the direct flt images.
direct_spt (lst of str) – The filepaths to the direct spt images corresponding to the flt images.
jit_files (lst of str) – The filepaths to the jitter files, one for each orbit.
misc_files (lst of str) – The filepaths to the miscellanous files.
outdir (str) – Where the files will be moved to, or where the .flt files already are.
verbose (int, optional) – From 0 to 2, how much detail you want the output logs to have. Defaults to 2.

Locate Target

hustle_tools.stage_0.locate_target.check_subarray(direct_flt, spec_flts)[source]

Checks the subarray corner info for the direct and spec flt files and alerts the user to discrepancies.

Parameters:

direct_spt (str) – Path to the direct flt.
spec_spts (list of str) – Paths to the spec flts.

Returns:

Discrepancies in x and y between these values.

Return type:

list, list

hustle_tools.stage_0.locate_target.locate_target(direct_image, test=False)[source]

Uses the direct image and user feedback to locate the target, necessary for trace calibration and source tracking in later stages.

Parameters:

direct_image (str) – Path to the direct image.
test (bool, optional) – Whether you are running in testing mode. Only used for validation on github. Defaults to False.

Returns:

Location of the direct image in x, y floats.

Return type:

float, float

Stage 1: Reduction

Temporal Outlier Rejection

hustle_tools.stage_1.temporal_outlier_rejection.array1D_clip(array, threshold=3.5)[source]

Function to detect and replace outliers in a 1D array above or below a certain sigma threshold imposed.

Parameters:

array (np.array) – pixel time series to be cleaned for outliers.
threshold (float, optional) – threshold at which to call a value an outlier. Defaults to 3.5.

Returns:

cleaned time series and mask marking where outliers were found.

Return type:

np.array

hustle_tools.stage_1.temporal_outlier_rejection.fixed_iteration_rejection(obs, sigmas=[10, 10], replacement=None, verbose=0, show_plots=0, save_plots=0, output_dir=None)[source]

Iterates a fixed number of times using a different sigma at each iteration to reject cosmic rays.

Parameters:

obs (xarray) – obs.images DataSet contains the images.
sigmas (list, optional) – sigma to use for each iteration. len(sigmas) is the number of iterations that will be run. Defaults to [10,10].
replacement (int, optional) – if None, replace outlier pixels with median in time. If int, replace with median of int values either side in time. Defaults to None.
verbose (int, optional) – how detailed you want the printed statements to be. Defaults to 0.
show_plots (int, optional) – how many plots you want to show. Defaults to 0.
save_plots (int, optional) – how many plots you want to save. Defaults to 0.
output_dir (str, optional) – where to save the plots to, if save_plots is greater than 0. Defaults to None.

Returns:

obs with .images cleaned of CRs and with .data_quality updated to indicate where CRs were found.

Return type:

xarray

hustle_tools.stage_1.temporal_outlier_rejection.free_iteration_rejection(obs, threshold=3.5, verbose=0, show_plots=0, save_plots=0, output_dir=None)[source]

Function to replace outliers in the temporal dimension.

Parameters:

obs (xarray) – obs.images DataSet contains the images.
threshold (float, optional) – sigma at which to reject outliers until no more are found at this level. Defaults to 3.5.
verbose (int, optional) – how detailed you want the printed statements to be. Defaults to 0.
show_plots (int, optional) – how many plots you want to show. Defaults to 0.
save_plots (int, optional) – how many plots you want to save. Defaults to 0.
output_dir (str, optional) – where to save the plots to, if save_plots is greater than 0. Defaults to None.

Returns:

obs with .images cleaned of CRs and with .data_quality updated to indicate where CRs were found.

Return type:

xarray

Spatial Outlier Rejection

hustle_tools.stage_1.spatial_outlier_rejection.build_fine_structure_model(data_frame)[source]

Builds a fine structure model for the data frame.

Parameters:: data_frame (np.array) – Native resolution data.
Returns:: 2D array of fine structure model.
Return type:: np.array

hustle_tools.stage_1.spatial_outlier_rejection.build_noise_model(data_frame, readnoise)[source]

Builds a noise model for the given data frame, following van Dokkum 2001 methods.

Parameters:

data_frame (np.array) – frame from the images DataSet, used to build the noise model.
readnoise (float) – readnoise estimated to be in the data frame.

Returns:

2D array same size as the data frame, a noise model describing noise in the frame.

Return type:

np.array

hustle_tools.stage_1.spatial_outlier_rejection.laplacian_edge_detection(obs, sigma=10, factor=2, n=2, build_fine_structure=False, contrast_factor=5, verbose=0, show_plots=0, save_plots=0, output_dir=None)[source]

Uses Laplacian Edge Detection (van Dokkum 2001) to detect cosmic rays and hot/cold pixels.

Parameters:

obs (xarray) – obs.images DataSet contains the images.
sigma (float, optional) – sigma to use for detecting bad pixels and replacing them. Defaults to 10.
factor (int, optional) – subsampling factor, minimum value 2 to work. Higher values increase computation time but don’t tend to improve the routine much, so best left at 2. Defaults to 2.
n (int, optional) – how many iterations you want to run. Useful for catching large blobs of bad pixels, as LED detects edges and not interiors. Defaults to 2.
build_fine_structure (bool, optional) – whether to build a fine structure model to protect the trace against LED. Defaults to False.
contrast_factor (int, optional) – the threshold for rejection when a fine structure model is in use. Defaults to 5.
verbose (int, optional) – how detailed you want the printed statements to be. Defaults to 0.
show_plots (int, optional) – how many plots you want to show. Defaults to 0.
save_plots (int, optional) – how many plots you want to save. Defaults to 0.
output_dir (str, optional) – where to save the plots to, if save_plots is greater than 0. Defaults to None.

Returns:

obs with the .data cleaned of bad pixels and the .data_quality updated to reflect where bad pixels were found.

Return type:

xarray

hustle_tools.stage_1.spatial_outlier_rejection.resample_frame(data_frame, original_shape)[source]

Resamples a subsampled array back to the original shape.

Parameters:

data_frame (np.array) – subsampled frame from the images DataSet.
original_shape (tuple of int) – original shape of the subsampled array.

Returns:

2D array with original shape resampled from the data frame.

Return type:

np.array

hustle_tools.stage_1.spatial_outlier_rejection.spatial_2D_smooth(sub_image, kernel=(5, 5), sigma=10)[source]

Uses scipy.signal.medfil2d to correct spatial outliers. Adapted from routine developed by Trevor Foote (tof2@cornell.edu).

Parameters:

sub_image (array-like) – a frame to clean of outliers.
kernel (tuple, optional) – tuple of two odd ints which define the kernel used for smoothing. Defaults to (5,5).
sigma (float, optional) – threshold at which to remove an outlier. Defaults to 10.

Returns:

the median-filtered image, cleaned image, and maps of where pixels were hit in x and y.

Return type:

array-like, array-like, array-like, array-like

hustle_tools.stage_1.spatial_outlier_rejection.spatial_smoothing(obs, type='1D_smooth', kernel=11, sigma=10, bounds_set=[[260, 370, 640, 1100]], verbose=0, show_plots=0, save_plots=0, output_dir=None)[source]

Uses 2D median filtering to catch and remove hot pixels.

Parameters:

obs (xarray) – obs.images contains the dataset we are cleaning.
type (str) – options are “1D_smooth” (to use row-wise scipy median-filtering) or “2D_smooth” (to use scipy 2D median-filtering).
kernel (int or tup, optional) – the size of the kernel used to compute the median-filtered image. If using 1D_smooth, should be an odd int. If using 2D_smooth, should be a tuple of two odd ints. Defaults to 11.
sigma (float, optional) – threshold at which to remove an outlier. Defaults to 10.
bounds_set (array-like, optional) – whether to only perform spatial smoothing on a subset of the array, for time-saving. If None, corrects for the full frame. Defaults to [[260, 370, 640, 1100],].
verbose (int, optional) – how detailed you want the printed statements to be. Defaults to 0.
show_plots (int, optional) – how many plots you want to show. Defaults to 0.
save_plots (int, optional) – how many plots you want to save. Defaults to 0.
output_dir (str, optional) – where to save the plots to, if save_plots is greater than 0. Defaults to None.

Returns:

obs with images cleaned and data quality flags updated.

Return type:

xarray

hustle_tools.stage_1.spatial_outlier_rejection.subsample_frame(data_frame, factor=2)[source]

Subsamples the input frame by the given subsampling factor.

Parameters:

data_frame (np.array) – Frame from the images DataSet, used to build the noise model.
factor (int, optional) – Factor by which to subsample the array which must be >= 2. Defaults to 2.

Returns:

2D array same shape as data frame, subsampled by factor.

Return type:

np.array

Background Subtraction

hustle_tools.stage_1.bckg_subtract.Gauss1D(x, H, A, x0, sigma)[source]

Function to return a 1D Gaussian profile.

Parameters:

x (np.array-like) – independent variable.
H (float) – constant offset.
A (float) – amplitude of Gaussian.
x0 (float) – center of Gaussian.
sigma (float) – width of Gaussian.

Returns:

1D Gaussian profile array.

Return type:

np.array

hustle_tools.stage_1.bckg_subtract.Pagul_bckg_subtraction(obs, pagul_path, masking_parameter=0.001, smooth_fits=True, smooth_parameter=3.0, median_on_columns=True, verbose=0, show_plots=0, save_plots=0, output_dir=None)[source]

Scales the supplied Pagul et al. G280 sky image to each frame and subtracts the scaled image as background.

Parameters:

obs (xarray) – obs.images contains the data to be corrected.
pagul_path (str) – path to your chosen Pagul et al. sky image. There are a few options from different years, chips, calibrations, etc.
masking_parameter (float, optional) – how aggressively to mask the source. Values of 0.001 or less recommended. A good value should make the Pagul et al. scaling parameters similar to the frame mode. Defaults to 0.001.
smooth_fits (bool, optional) – whether to smooth the scaling parameters in time. Helps prevent background “flickering” in event of minor bckg bimodality. Defaults to True.
smooth_parameter (float, optional) – if smooth_fits is True, sigma for smoothing. Defaults to 3.0.
median_on_columns (bool, optional) – if True, take the median value of the Pagul et al. sky image along columns. Approximately eliminates contamination from poorly-sampled parts of sky. Defaults to True.
verbose (int, optional) – how detailed you want the printed statements to be. Defaults to 0.
show_plots (int, optional) – how many plots you want to show. Defaults to 0.
save_plots (int, optional) – how many plots you want to save. Defaults to 0.
output_dir (str, optional) – where to save the plots to, if save_plots is greater than 0. Defaults to None.

Returns:

obs with sky-corrected images and with bkg values saved to [‘bkg_vals’] keyword.

Return type:

xarray

hustle_tools.stage_1.bckg_subtract.calculate_mode(array, hist_min, hist_max, hist_bins, exp_num=0, fit=None, show_plots=0, save_plots=0, output_dir=None)[source]

Function to return the mode of an image

Parameters:

array (np.array) – 2D image array.
hist_min (float) – lower bound of values to consider when building the histogram.
hist_max (float) – upper bound of values to consider when building the histogram.
hist_bins (int) – number of bins to use for the calculation.
fit (str or None, optional) – type of fit to apply to the histogram. Options are ‘Gaussian’ (fits a 1D Gaussian to the histogram), ‘median’ (takes the median of the histogram), or can be left as None to use just the histogram’s mode. Defaults to None.
ind (int, optional) – index of this array, used for naming the plot. Defaults to 0.
method (str, optional) – method used to calculate background value. Options are ‘full-frame’ or ‘corners’. Defaults to None.
verbose (int, optional) – how detailed you want the printed statements to be. Defaults to 0.
show_plot (bool, optional) – whether to show this plot. Defaults to False.
save_plot (bool, optional) – whether to save this plot. Defaults to False.
output_dir (str, optional) – where to save the plot to, if save_plot is True. Defaults to None.

Returns:

background value for this array.

Return type:

float

hustle_tools.stage_1.bckg_subtract.column_by_column_subtraction(obs, rows=array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]), sigma=3, mask_trace=True, width=100, verbose=0, show_plots=0, save_plots=0, output_dir=None)[source]

Perform 1/f column-by-column background subtraction on each frame.

Parameters:

obs (xarray) – obs.images contains the data to be corrected.
rows (array-like, optional) – indices of rows to treat as the background. Ignored if mask_trace is True. Defaults to [i for i in range(10)].
sigma (int, optional) – used to clean outliers from the background. Defaults to 3.
mask_trace (bool, optional) – whether to fit a mask to the trace so that it does not affect the computed bckg value. Defaults to True.
width (int, optional) – if mask_trace is True, how far from the trace up and down to mask out. Defaults to 100.
verbose (int, optional) – how detailed you want the printed statements to be. Defaults to 0.
show_plots (int, optional) – how many plots you want to show. Defaults to 0.
save_plots (int, optional) – how many plots you want to save. Defaults to 0.
output_dir (str, optional) – where to save the plots to, if save_plots is greater than 0. Defaults to None.

Returns:

obs with sky-corrected images and with bkg images saved to [‘bkg_vals’] keyword.

Return type:

xarray

hustle_tools.stage_1.bckg_subtract.uniform_value_bkg_subtraction(obs, fit=None, bounds=None, hist_min=-20, hist_max=50, hist_bins=1000, verbose=0, show_plots=0, save_plots=0, output_dir=None)[source]

Function to compute a uniform background value per frame, using either the full frame or using subsets of the image.

Parameters:

obs (xarray) – obs.images contains the data to be corrected.
fit (str or None, optional) – type of fit to apply to the histogram. Options are ‘Gaussian’ (fits a 1D Gaussian to the histogram), ‘median’ (takes the median of the histogram), or can be left as None to use just the histogram’s mode. Defaults to None.
bounds (list of int, optional) – bounds from which to draw the corners, if using corners. Use None to draw from the full frame. Defaults to None.
hist_min (int, optional) – lower bound for bckg values. Defaults to -20.
hist_max (int, optional) – upper bound for bckg values. Defaults to 50.
hist_bins (int, optional) – number of bins for calculating the mode. Cannot exceed number of pixels available. Defaults to 1000.
verbose (int, optional) – how detailed you want the printed statements to be. Defaults to 0.
show_plots (int, optional) – how many plots you want to show. Defaults to 0.
save_plots (int, optional) – how many plots you want to save. Defaults to 0.
output_dir (str, optional) – where to save the plots to, if save_plots is greater than 0. Defaults to None.

Returns:

obs with sky-corrected images and with bkg values saved to [‘bkg_vals’] keyword.

Return type:

xarray

Displacement Estimation

hustle_tools.stage_1.compute_displacements.refine_location(obs, window=20, verbose=0, show_plots=0, save_plots=0, output_dir=None)[source]

Function to refine the target location in the direct image.

Parameters:

obs (xarray) – obs.direct_image contains the direct image of the source.
window (int, optional) – how far around the source to draw the window for centroiding. Defaults to 20.
verbose (int, optional) – how detailed you want the printed statements to be. Defaults to 0.
show_plots (int, optional) – how many plots you want to show. Defaults to 0.
save_plots (int, optional) – how many plots you want to save. Defaults to 0.
output_dir (str, optional) – where to save the plots to, if save_plots is greater than 0. Defaults to None.

hustle_tools.stage_1.compute_displacements.track_0thOrder(obs, guess, verbose=0, show_plots=0, save_plots=0, output_dir=None)[source]

Tracks the 0th order through all frames using centroiding.

Parameters:

obs (xarray) – obs.images contains the images.
guess (lst of float) – initial x, y offset guess for the 0th order’s location.
verbose (int, optional) – how detailed you want the printed statements to be. Defaults to 0.
show_plots (int, optional) – how many plots you want to show. Defaults to 0.
save_plots (int, optional) – how many plots you want to save. Defaults to 0.
output_dir (str, optional) – where to save the plots to, if save_plots is greater than 0. Defaults to None.

Returns:

location of the dispersed 0th order in x, y floats.

Return type:

lst of lst of float

hustle_tools.stage_1.compute_displacements.track_bkgstars(obs, bkg_stars, window=15, verbose=0, show_plots=0, save_plots=0, output_dir=None)[source]

Function to compute the x & y displacement of a given background star.

Parameters:

obs (xarray) – obs.images contains the images of the stars.
bkg_stars (list of list) – estimated positions of stars to track.
window (int, optional) – how far around the star to draw the window for centroiding. Defaults to 15.
verbose (int, optional) – how detailed you want the printed statements to be. Defaults to 0.
show_plots (int, optional) – how many plots you want to show. Defaults to 0.
save_plots (int, optional) – how many plots you want to save. Defaults to 0.
output_dir (str, optional) – where to save the plots to, if save_plots is greater than 0. Defaults to None.

Returns:

relative and average positions of each star in time.

Return type:

np.array, np.array

Stage 2: Extraction

Trace Fitting

hustle_tools.stage_2.trace_fitting.Gauss1D(x, H, A, x0, sigma)[source]

Creates a 1D Gaussian on the given x range.

Parameters:

x (np.array) – independent variable in the Gaussian.
H (float) – vertical offset.
A (float) – amplitude of the Gaussian.
x0 (float) – center of the Gaussian.
sigma (float) – width of the Gaussian.

Returns:

Gaussian profile on domain x.

Return type:

np.array

hustle_tools.stage_2.trace_fitting.fit_trace(obs, trace_x, trace_y, profile_width=40, pol_deg=7, fit_type='Gaussian', fit_trace=False, plot_profile=None, order='+1', verbose=0, show_plots=0, save_plots=0, output_dir=None)[source]

Refines the trace vertical location by fitting profile curves to the cross-dispersion profiles.

Parameters:

obs (xarray) – obs.images contains the images.
trace_x (np.array) – calibrated x positions of trace pixels.
trace_y (np.array) – calibrated y positions of trace pixels.
profile_width (int, optional) – how far up and down to fit the trace profile. Defaults to 40.
pol_deg (int, optional) – degree of polynomial to fit to the trace position, if fit_trace is True. Defaults to 7.
fit_type (str, optional) – Actually has to be Gaussian? Defaults to ‘Gaussian’.
fit_trace (bool, optional) – if True, fit a polynomial to the refined x, y positions of the trace in each frame. Defaults to False.
plot_profile (list, optional) – a specific profile we have requested to plot. Defaults to None.
verbose (int, optional) – How detailed you want the printed statements to be. Defaults to 0.
show_plots (int, optional) – How many plots you want to show. Defaults to 0.
save_plots (int, optional) – How many plots you want to save. Defaults to 0.
output_dir (str, optional) – Where to save the plots to, if save_plots is greater than 0. Defaults to None.

Returns:

refined trace positions and widths.

Return type:

np.array,np.array

hustle_tools.stage_2.trace_fitting.get_calibration_0th(obs, source_pos, path_to_cal, verbose=0, show_plots=0, save_plots=0, output_dir=None)[source]

Uses a custom method based on GRISMCONF and the source position to locate the 0th order for removal purposes.

Parameters:

x0 (float) – Embedded x position of the source.
y0 (float) – Embedded y position of the source.
path_to_cal (str) – Path to the calibration file used to locate the trace.

Returns:

the x and y position of the 0th order.

Return type:

float, float

hustle_tools.stage_2.trace_fitting.get_calibration_trace(order, x0, y0, path_to_cal)[source]

Uses the supplied calibration software and source position to locate the trace and assign wavelength solution.

Parameters:

order (str) – Options are “+1”, “-1”, “+2”, “-2”, etc. Used to grab the right calibration from the calibration file.
x0 (float) – Embedded x position of the source.
y0 (float) – Embedded y position of the source.
path_to_cal (str) – Path to the calibration file used to locate the trace.

Returns:

the x and y positions of the calibrated trace, the assigned wavelength solution, and the sensitivity correction function.

Return type:

list,list,np.array,scipy.interpolate

hustle_tools.stage_2.trace_fitting.get_trace_solution(obs, order, source_pos, refine_calibration, path_to_cal, verbose=0, show_plots=0, save_plots=0, output_dir=None)[source]

Pulls the region of each image that has the trace in it, with wavelength solution provided by GRISMCONF.

Parameters:

obs (xarray) – obs.images DataSet contains the images and obs.subarr_coords DataSet is used to trick the configuration into thinking it is embedded.
order (str) – options are “+1”, “-1”, “+2”, “-2”, etc. Which order you want to pull.
source_pos (tup) – x, y float position of the source in the unembedded direct image.
refine_calibration (bool) – if True, uses Gaussian fitting to improve the location of the trace.
path_to_cal (str) – path to the GRISMCONF calibration file used to locate the trace.
verbose (int, optional) – How detailed you want the printed statements to be. Defaults to 0.
show_plots (int, optional) – How many plots you want to show. Defaults to 0.
save_plots (int, optional) – How many plots you want to save. Defaults to 0.
output_dir (str, optional) – Where to save the plots to, if save_plots is greater than 0. Defaults to None.

Returns:

trace x and y positions, wavelength solutions, optional trace widths, and optional sensitivity correction functions.

Return type:

np.array,np.array,np.array,np.array,scipy.interpolate

hustle_tools.stage_2.trace_fitting.sens_correct(spec, spec_err, wav, fs)[source]

Simple function to apply the sensitivity correction to a spectrum.

Parameters:

spec (array-like) – spectrum without correction.
spec_err (array-like) – spectrum uncertainties without correction.
wav (array-like) – wavelength solution from GRISMCONF.
fs (array-like) – sensitivity correction from GRISMCONF.

Returns:

the spectrum and its uncertainties adjusted for the sensitivity of the detector.

Return type:

array-like, array-like

Time And Relative Detrending In Space (TARDIS)

hustle_tools.stage_2.tardis.time_and_relative_detrending_in_space(obs, trace_x, trace_y, order, sigmas=[5.0, 3.5], flux_threshold=1000, windows=[10, 5], replacement='tseries', verbose=0, show_plots=0, save_plots=0, output_dir=None)[source]

Estimates systematic trends to catch cosmic rays otherwise not detected by any of the Stage 1 cleaning routines.

Parameters:

obs (xarray) – obs.images DataSet contains the images.
trace_x (array-like) – x-coordinates of the trace to be corrected.
trace_y (array-like) – y-coordinates of the trace to be corrected.
order (str) – For plot file naming purposes.
sigmas (lst of float, optional) – sigmas to reject outliers at for each window supplied. Defaults to [5.0,3.5].
flux_threshold (float, optional) – median e-/s value at which a pixel’s time series will be subjected to this method. Method fails if there is insufficient flux by which to estimate systematics. Defaults to 1000.
windows (int, optional) – median time-series of pixels is computed using pixels +/- window length away from target pixel. Defaults to [10,5].
replacement (str, optional) – if ‘tseries’, replaces outliers with scaled median time-series of nearby pixels. If ‘median’, replace outlier pixels with pixel’s median value in time. Defaults to ‘tseries’.
verbose (int, optional) – how detailed you want the printed statements to be. Defaults to 0.
show_plots (int, optional) – how many plots you want to show. Defaults to 0.
save_plots (int, optional) – how many plots you want to save. Defaults to 0.
output_dir (str, optional) – where to save the plots to, if save_plots is greater than 0. Defaults to None.

Returns:

obs with .images cleaned of CRs and with .data_quality updated to indicate where CRs were found.

Return type:

xarray

Extraction

hustle_tools.stage_2.standard_extraction.box(trace)[source]

The simplest extraction method, this routine sums the trace along columns without any weighting.

Parameters:: trace (np.array) – one frame in time showing the trace at integration k.
Returns:: 1D array of the unweighted spectrum from that trace.
Return type:: np.array

hustle_tools.stage_2.standard_extraction.create_circular_mask(h, w, center=None, radius=None)[source]

Simple function to draw a circular mask on the trace.

Parameters:

h (int) – the x shape of the array.
w (int) – the y shape of the array.
center (int, optional) – x,y center of the circle to draw. Defaults to None.
radius (int, optional) – the radius of the circle to draw. Defaults to None.

Returns:

a mask which covers a circle on the array.

Return type:

np.array

hustle_tools.stage_2.standard_extraction.determine_ideal_halfwidth(obs, order, trace_x, trace_y, wavs, indices=([0, 10], [-10, -1]), verbose=0, show_plots=0, save_plots=0, output_dir=None)[source]

Extracts multiple standard white light curves and determines the half-width that minimizes scatter out of transit/eclipse.

Parameters:

obs (xarray) – obs.images DataSet contains the images.
order (str) – used to label plots appropriately.
trace_x (np.array) – x positions of the pixels in the trace solutions.
trace_y (np.array) – y positions of the pixels in the trace solutions.
wavs (np.array) – wavelength solution for each image.
indices (tuple, optional) – indices that define the out-of-transit/eclipse flux, for which scatter is measured. Defaults to ([0,10],[-10,-1]).
verbose (int, optional) – How detailed you want the printed statements to be. Defaults to 0.
show_plots (int, optional) – How many plots you want to show. Defaults to 0.
save_plots (int, optional) – How many plots you want to save. Defaults to 0.
output_dir (str, optional) – Where to save the plots to, if save_plots is greater than 0. Defaults to None.

Returns:

half-width integer that minimizes scatter.

Return type:

int

hustle_tools.stage_2.standard_extraction.est_errs(time, flx, kick_outliers=True)[source]

Simple function for estimating the scatter in the out-of-transit/eclipse flux.

Parameters:

time (np.array) – timestamps for exposures.
flx (np.array) – oot/ooe flux.
kick_outliers (bool, optional) – Whether to remove outliers like CRs from the array to get more accurate scatter estimation. Defaults to True.

Returns:

residuals from the rampslope fit to the oot/ooe flux.

Return type:

np.array

hustle_tools.stage_2.standard_extraction.get_trace(frame, halfwidth, xs, ys)[source]

Short function to pull a trace region from a frame using the given solution and halfwidth.

Parameters:

frame (np.array) – one frame from obs.images Dataset.
halfwidth (int) – halfwidth of extraction. Pulls pixels from A-hw to A+hw where A is the central row index.
xs (np.array) – x positions of the pixels in the trace solution.
ys (np.array) – y positions of the pixels in the trace solution.

Returns:

dispersion profiles from the trace.

Return type:

np.array

hustle_tools.stage_2.standard_extraction.rampslope(x, a, b, c, d)[source]

A exp(b t) + c t + d trend.

Parameters:

x (np.array) – time.
a (float) – amplitude of the exponential.
b (float) – “slope” of the exponential.
c (float) – linear trend slope.
d (float) – linear trend intercept.

Returns:

ramp-slope trend.

Return type:

np.array

hustle_tools.stage_2.standard_extraction.residuals_(fit, x, flx, kick_outliers=False)[source]

Residuals function for fitting a ramp-slope time-series to oot/ooe flux.

Parameters:

fit (np.array) – guess of parameters for the fit.
x (np.array) – time.
flx (np.array) – flux.
kick_outliers (bool, optional) – Whether to remove outliers like CRs from the array to get more accurate scatter estimation. Defaults to True.

Returns:

residuals of the fit.

Return type:

np.array

hustle_tools.stage_2.standard_extraction.standard_extraction(obs, halfwidth, trace_x, trace_y, order='+1', masks=[], verbose=0, show_plots=0, save_plots=0, output_dir=None)[source]

Extracts a standard 1D spectrum from every image using no weighting.

Parameters:

obs (xarray) – obs.images contains the data.
halfwidth (int) – “halfwidth” of the extraction aperture, which spans from A-hw to A+hw where A is the index of the central row.
trace_x (np.array) – x positions of the pixels in the trace solution.
trace_y (np.array) – y positions of the pixels in the trace solution.
order (str) – for labelling plots correctly.
masks (list) – x, y, radii of objects in the aperture you want to mask.
verbose (int, optional) – How detailed you want the printed statements to be. Defaults to 0.
show_plots (int, optional) – How many plots you want to show. Defaults to 0.
save_plots (int, optional) – How many plots you want to save. Defaults to 0.
output_dir (str, optional) – Where to save the plots to, if save_plots is greater than 0. Defaults to None.

Returns:

1D spectrum and errors.

Return type:

np.array,np.array

hustle_tools.stage_2.optimal_extraction.optimal_extraction(obs, trace_x, traces_y, masks=[], width=25, thresh=17.0, prof_type='polyfit', iterate=False, zero_bkg=None, verbose=0, show_plots=0, save_plots=0, output_dir=None)[source]

Performs an optimal extraction with a spatial profile of choice following the methods of Horne 1986.

Parameters:

obs (xarray) – dataset from which we will extract the 1D spectra.
trace_x (array-like) – x column solutions of the trace to extract.
traces_y (arary-like) – y row solutions of the trace to extract.
masks (list, optional) – x, y, radii of objects in the aperture you want to mask. Defaults to [].
width (int, optional) – aperture halfwidth for extraction. For optimal, ideally use a very large window since the weighting will take care of the rest. Defaults to 25.
thresh (float, optional) – _description_. Defaults to 17..
prof_type (str, optional) – the type of profile to use for optimal extraction. Options are ‘median’, ‘polyfit’, ‘smooth’, or ‘curved_poly’. Defaults to ‘polyfit’.
iterate (bool, optional) – whether to iterate over the profile to remove outliers. Defaults to False.
zero_bkg (np.array, optional) – the 0th-order background signal, which is needed for variance estimation if it was removed earlier. Defaults to None.
verbose (int, optional) – how detailed you want the printed statements to be. Defaults to 0.
show_plots (int, optional) – how many plots you want to show. Defaults to 0.
save_plots (int, optional) – how many plots you want to save. Defaults to 0.
output_dir (str, optional) – where to save the plots to, if save_plots is greater than 0. Defaults to None.

Returns:

optimally-extracted 1D spectra and uncertainties.

Return type:

array-like, array-like

hustle_tools.stage_2.optimal_extraction.spatial_profile(exp_ind, image_org, window=40, threshold=4.0, normalize=False, show_plots=0, save_plots=0, output_dir=0)[source]

Builds a spatial profile using row-wise polynomial fits for every row in the image. Used in the “polyfit” method of profile building.

Parameters:

exp_ind (int) – index of the exposure.
image_org (array-like) – original image to be modelled.
window (int, optional) – length of the window. Defaults to 40.
threshold (_type_, optional) – _description_. Defaults to 4..
normalize (bool, optional) – _description_. Defaults to False.
show_plots (int, optional) – _description_. Defaults to 0.
save_plots (int, optional) – _description_. Defaults to 0.
output_dir (int, optional) – _description_. Defaults to 0.

Returns:

_description_

Return type:

_type_

hustle_tools.stage_2.optimal_extraction.spatial_profile_curved_poly(exp_ind, sub_image_org, image, tx_main, ty_main, low_val, up_val, init_spec=None, fit_thresh=4.0, fit_degree=5, window=50, correct_thresh=None, show_plots=0, save_plots=0, output_dir=0)[source]

Builds a spatial profile using curved polynomial fits. Used in the “curved_poly” method of profile building.

Parameters:

exp_ind (int) – index of the exposure.
sub_image_org (array-like) – original image to fit a profile to.
image (_type_) – _description_
tx_main (_type_) – _description_
ty_main (_type_) – _description_
low_val (_type_) – _description_
up_val (_type_) – _description_
init_spec (_type_, optional) – _description_. Defaults to None.
fit_thresh (_type_, optional) – _description_. Defaults to 4..
fit_degree (int, optional) – _description_. Defaults to 5.
window (int, optional) – _description_. Defaults to 50.
correct_thresh (_type_, optional) – _description_. Defaults to None.
show_plots (int, optional) – how many plots you want to show. Defaults to 0.
save_plots (int, optional) – how many plots you want to save. Defaults to 0.
output_dir (str, optional) – where to save the plots to, if save_plots is greater than 0. Defaults to None.

Returns:

_description_

Return type:

_type_

hustle_tools.stage_2.optimal_extraction.spatial_profile_median(images, show_plots=0, save_plots=0, output_dir=None)[source]

Uses the entire time series of data to compute a median image, normalized and then used as the spatial profile.

Parameters:

images (array-like) – full time series of observation.
show_plots (int, optional) – how many plots you want to show. Defaults to 0.
save_plots (int, optional) – how many plots you want to save. Defaults to 0.
output_dir (str, optional) – where to save the plots to, if save_plots is greater than 0. Defaults to None.

Returns:

spatial profile for optimal extraction.

Return type:

array-like

hustle_tools.stage_2.optimal_extraction.spatial_profile_smooth(image_org, kernel=11, threshold=5.0, std_window=20, median_window=7, show_plots=0, save_plots=0, output_dir=0)[source]

Builds a spatial profile using 1D smoothing.

Parameters:

image_org (array-like) – original images to be modelled and cleaned.
kernel (int, optional) – odd int which defines the size of the row filter. Defaults to 11.
threshold (float, optional) – threshold at which to kick outliers. Defaults to 5..
std_window (int, optional) – window over which to calculate the standard deviation of the row. Defaults to 20.
median_window (int, optional) – window over which to calculate the median of the row. Defaults to 7.
show_plots (int, optional) – how many plots you want to show. Defaults to 0.
save_plots (int, optional) – how many plots you want to save. Defaults to 0.
output_dir (str, optional) – where to save the plots to, if save_plots is greater than 0. Defaults to None.

Returns:

the spatial profile, cleaned image, and maps of where pixels were hit in x and y.

Return type:

array-like, array-like, array-like, array-like

hustle_tools.stage_2.optimal_extraction.window_profile(image, init_pix, fin_pix, pol_degree=6, threshold=6.0)[source]

Uses row-wise polynomials to build the window profile. TBD Carlos.

Parameters:

image (_type_) – _description_
init_pix (_type_) – _description_
fin_pix (_type_) – _description_
pol_degree (int, optional) – _description_. Defaults to 6.
threshold (_type_, optional) – _description_. Defaults to 6..

Returns:

_description_

Return type:

array-like, array-like, array-like, array-like

1D Spectral Alignment

hustle_tools.stage_2.align_spectra.align_profiles(obs, trace_x, traces_y, order, width=25, verbose=0, show_plots=0, save_plots=0, output_dir=None)[source]

Function to find the y displacement of the psf.

Parameters:

obs (xarray) – used to measure the profile shifts.
trace_x (np.array) – dispersion solution of the profiles.
traces_y (np.array) – cross-dispersion solution of the profiles.
order (str) – which order we are aligning, for plot naming.
width (int, optional) – how far from the trace center to measure. Defaults to 25.
verbose (int, optional) – How detailed you want the printed statements to be. Defaults to 0.
show_plots (int, optional) – How many plots you want to show. Defaults to 0.
save_plots (int, optional) – How many plots you want to save. Defaults to 0.
output_dir (str, optional) – Where to save the plots to, if save_plots is greater than 0. Defaults to None.

Returns:

cross-dispersion shifts over time.

Return type:

np.array

hustle_tools.stage_2.align_spectra.align_spectra(obs, specs, specs_err, order, trace_x, wavelengths, align=False, verbose=0, show_plots=0, save_plots=0, output_dir=None)[source]

Aligns 1D spectra and uncertainties using cross-correlation.

Parameters:

obs (xarray) – used to attach the spectra to an xarray object.
specs (np.array) – array of 1D spectra.
specs_err (np.array) – array of 1D spectral uncertainties.
order (str) – for labelling plots correctly.
trace_x (np.array) – x positions of the trace solution.
wavelengths (np.array) – used to find acceptable indices.
align (bool, optional) – whether to apply the alignment to the spectra. Defaults to False.
verbose (int, optional) – How detailed you want the printed statements to be. Defaults to 0.
show_plots (int, optional) – How many plots you want to show. Defaults to 0.
save_plots (int, optional) – How many plots you want to save. Defaults to 0.
output_dir (str, optional) – Where to save the plots to, if save_plots is greater than 0. Defaults to None.

Returns:

aligned obs spectra.

Return type:

xarray

hustle_tools.stage_2.align_spectra.cross_corr(spec, temp_spec, order='+1', i=0, trim=1, fit_window=5, subpix_width=0.01, show_plots=0, save_plots=0, output_dir=None)[source]

Function to perform cross-correlation of two arrays. Based on ExoTic-JEDI align_spectra.py code

Parameters:

spec (np.array) – spectra that need to be aligned over time.
temp_spec (np.array) – template spectrum used to measure position shifts.
order (str) – for labelling plots correctly.
i (float) – for labelling plots correctly.
trim (int, optional) – how many indices to take out from beginning and end of each spectrum. Improves cross-correlation when 0s are at ends. Defaults to 1.
fit_window (int, optional) – used for measuring shifts. Defaults to 5.
subpix_width (float, optional) – how finely to interpolate the spectra when measuring the shifts. Defaults to 0.01.
show_plots (int, optional) – how many plots you want to show. Defaults to 0.
save_plots (int, optional) – how many plots you want to save. Defaults to 0.
output_dir (str, optional) – where to save the plots to, if save_plots is greater than 0. Defaults to None.

Returns:

cross-dispersion shifts

Return type:

np.array

1D Spectral Cleaning

hustle_tools.stage_2.clean_spectra.clean_spectra(spec, sigma, verbose=0)[source]

Replace spectral outliers in time with their temporal median.

Parameters:

spec (np.array) – spectrum to clean.
sigma (float) – threshold at which to reject a value as an outlier.
verbose (int, optional) – How detailed you want the printed statements to be. Defaults to 0.

Returns:

input spectrum cleaned of final outliers.

Return type:

np.array

Plotting Backend

Plotting Background Subtraction

hustle_tools.plotting.plot_bkgsubtraction.plot_bkgcorrection(exp_times, pre_bkg, post_bkg, method, output_dir=None, save_plot=False, show_plot=False)[source]

Plots the pre- and post-subtraction median background flux for the upper right corner of the image.

Parameters:

exp_times (np.array) – BJD exposure times for each frame.
pre_bkg (np.array) – 1D array of measured background values.
post_bkg (np.array) – 1D array of corrected background values.
method (str) – The method used for background subtraction, useful to distinguish each plot file from each other.
output_dir (str, optional) – output directory where the plot will be saved. Defaults to None.
save_plot (bool, optional) – whether to save the plot to a file. Defaults to False.
show_plot (bool, optional) – whether to interrupt execution to show the user the plot. Defaults to False.

hustle_tools.plotting.plot_bkgsubtraction.plot_bkgvals(exp_times, bkg_vals, method, output_dir=None, save_plot=False, show_plot=False)[source]

Function to create measured background value plots for all methods.

Parameters:

exp_times (np.array) – BJD exposure times for each frame.
bkg_vals (np.array) – 1D or 2D array of measured background values.
method (str) – The method used for background subtraction, useful to distinguish each plot file from each other.
output_dir (str, optional) – output directory where the plot will be saved. Defaults to None.
save_plot (bool, optional) – whether to save the plot to a file. Defaults to False.
show_plot (bool, optional) – whether to interrupt execution to show the user the plot. Defaults to False.

hustle_tools.plotting.plot_bkgsubtraction.plot_corners(image, corners, min=0.001, max=10000.0, show_plot=False, save_plot=False, output_dir=None)[source]

Function to plot exposure with rectangles to indicate the corners used for background subtraction.

Parameters:

image (np.array) – 2D image from the obs xarray.
corners (lst of lsts) – x, y bounds of each rectangle used to define the corners from which the background is measured.
min (int, optional) – darkest point for the colormap. Defaults to 1e-3.
max (int, optional) – brightest point for the colormap. Defaults to 1e4.
show_plot (bool, optional) – whether to interrupt execution to show the user the plot. Defaults to False.
save_plot (bool, optional) – whether to save this plot. Defaults to False.
output_dir (str, optional) – output directory where the plot will be saved. Defaults to None.

hustle_tools.plotting.plot_bkgsubtraction.plot_histogram(bin_cents, array, mode, median, exp_num, gaussian_center=False, gaussian_fit=None, show_plots=False, save_plots=False, output_dir=None)[source]

Plots a histogram of the background values for the given exposure.

Parameters:

bin_cents (array-like) – centers of each bin.
array (array-like) – flattened image data for which the histogram was computed.
mode (float) – mode of the array without any fit or trim.
median (float) – median of the array without any fit or trim.
exp_num (float) – exposure number.
gaussian_center (float, optional) – if not False, center of the Gaussian fit to plot. Defaults to False.
gaussian_fit (array-like, optional) – if not None, the Gaussian fit to plot. Defaults to None.
show_plots (bool, optional) – whether to show this plot. Defaults to False.
save_plots (bool, optional) – whether to save this plot. Defaults to False.
output_dir (str, optional) – where to save the plot to, if save_plot is True. Defaults to None.

hustle_tools.plotting.plot_bkgsubtraction.plot_mode_v_params(exp_times, modes, meds, params, output_dir=None, save_plot=False, show_plot=False)[source]

Function to create a diagnostic plot for Pagul et al. bkg subtraction.

Parameters:

exp_times (np.array) – BJD exposure times for each frame.
modes (np.array) – measured mode of each frame, used for comparison.
meds (np.array) – measured median of each frame, used for comparison.
params (np.array) – Pagul+ sky image scaling parameter. Ideally, the mode and scaling parameters should not be too different.
output_dir (str, optional) – output directory where the plot will be saved. Defaults to None.
save_plot (bool, optional) – whether to save the plot to a file. Defaults to False.
show_plot (bool, optional) – whether to interrupt execution to show the user the plot. Defaults to False.

Plotting Displacements

hustle_tools.plotting.plot_displacements.plot_0th_order(exp_time, xs, ys, show_plot=False, save_plot=False, output_dir=None)[source]

Function to plot the location of the 0th order over time.

Parameters:

exp_times (np.array) – BJD exposure times for each frame.
xs (np.array) – 0th order x positions.
ys (np.array) – 0th order y positions.
show_plot (bool, optional) – whether to interrupt execution to show the user the plot. Defaults to False.
save_plot (bool, optional) – whether to save the plot to a file. Defaults to False.
output_dir (str, optional) – output directory where the plot will be saved. Defaults to None.

hustle_tools.plotting.plot_displacements.plot_bkg_stars(image, exp_time, mean_loc, mean_pos, stars_pos, show_plot=False, save_plot=False, output_dir=None)[source]

Function to plot the displacements of the background stars.

Parameters:

image (np.array) – 2D image array showing all of the stars in context.
exp_times (np.array) – BJD exposure times for each frame.
mean_loc (np.array) – mean absolute location of each star.
mean_pos (np.array) – mean relative position of each star.
stars_pos (np.array) – relative position of each star over time.
show_plot (bool, optional) – whether to interrupt execution to show the user the plot. Defaults to False.
save_plot (bool, optional) – whether to save the plot to a file. Defaults to False.
output_dir (str, optional) – output directory where the plot will be saved. Defaults to None.

Plotting Exposures

hustle_tools.plotting.plot_exposures.plot_exposure(images, line_data=None, scatter_data=None, extent=None, xlimits=None, ylimits=None, title=None, min=0.001, max=10000.0, mark_size=30, linestyles=None, cbar_orient='vertical', cbar_aspect=20, cbar_pad=0.05, cbar_fraction=0.15, show_plot=False, save_plot=False, filename=None, output_dir=None)[source]

Function to plot an image given certain parameters.

Parameters:

images (np.array) – images from the obs.images.
line_data (list, optional) – list of lists of x, y values denoting lines you want to draw on the plot. Defaults to None.
scatter_data (list, optional) – list of x, y points you want to scatter on the plot. Defaults to None.
extent (tuple of float, optional) – if not None, defines bounds of array you want to plot. Defaults to None.
xlimits (tuple of float, optional) – if not None, defines x axis limits of array you want to plot. Defaults to None.
ylimits (tuple of float, optional) – if not None, defines y axis limits of array you want to plot. Defaults to None.
title (str, optional) – title for the plot. Defaults to None.
min (int, optional) – darkest point for the colormap. Defaults to 1e-3.
max (int, optional) – brightest point for the colormap. Defaults to 1e4.
mark_size (int, optional) – size of scatter points, if scatter_data is not None. Defaults to 30.
linestyles (list of str, optional) – style for each line, if line_data is not None. Defaults to None.
cbar_orient (str, optional) – colorbar orientation. Defaults to ‘vertical’.
cbar_aspect (float, optional) – colorbar aspect ratio. Defaults to 20.
cbar_fraction (float, optional) – colorbar axis fraction. Defaults to 0.15.
cbar_pad (float, optional) – colorbar padding. Defaults to 0.05.
show_plot (bool, optional) – whether to interrupt execution to show the user the plot. Defaults to False.
save_plot (bool, optional) – whether to save this plot. Defaults to False.
filename (list of str, optional) – name for each plot file. Defaults to None.
output_dir (str, optional) – where to save the plots to, if save_plots is True. Defaults to None.

Plotting Quicklooks

hustle_tools.plotting.plot_quicklook.create_dq_gif(exp_times, images, dq, sections, output_dir, show_fig=False, save_fig=False)[source]

Function to create an animation showing all the data quality flags.

Parameters:

exp_times (np.array) – exposure times for each image.
images (np.array) – array of 2D images to pull a light curve from.
dq (np.array) – Array of 2D images showing pixels flagged for DQ.
sections (lst of lst of int) – the subsection(s) of image you measured flux in.
output_dir (str) – where to save the gif to.
show_fig (bool, optional) – whether to show the figure or not. Defaults to False.
save_fig (bool, optional) – wether to save the figure or not. Defaults to False.

hustle_tools.plotting.plot_quicklook.create_gif(exp_times, images, total_flux, partial_flux, sections, output_dir, show_fig=False, save_fig=False)[source]

Function to create an animation showing all the exposures.

Parameters:

exp_times (np.array) – exposure times for each image.
images (np.array) – array of 2D images to pull a light curve from.
total_flux (np.array) – flux summed across each 2D image.
partial_flux (np.array) – flux summed from the section of each 2D image.
sections (lst of lst of int) – the subsection(s) of image you measured flux in.
output_dir (str) – where to save the gif to.
show_fig (bool, optional) – whether to show the figure or not. Defaults to False.
save_fig (bool, optional) – wether to save the figure or not. Defaults to False.

hustle_tools.plotting.plot_quicklook.get_images(data_dir, traces_included=('+1',), verbose=0)[source]

Function to retrieve images and exposure times from data files.

Parameters:

data_dir (str) – directory where the images you want to load are.
traces_included (tup of str, optional) – which traces’ fluxes are
to (included in the quicklook gif. Defaults)
verbose (int, optional) – how detailed you want the printed statements to be. Defaults to 0.

Returns:

images, exposure times, flux of the whole images, and flux from the section.

Return type:

np.array,np.array,np.array,np.array

hustle_tools.plotting.plot_quicklook.parse_xarr(obs, traces_included=('+1',), verbose=0)[source]

Function to retrieve images and exposure times from reduced xarray.

Parameters:

obs (xarray) – xarray containing the reduced images.
traces_included (tup of str, optional) – which traces’ fluxes are
to (included in the quicklook gif. Defaults)
verbose (int, optional) – how detailed you want the printed statements to be. Defaults to 0.

Returns:

images, exposure times, flux of the whole images, and flux from the section.

Return type:

np.array,np.array,np.array,np.array

hustle_tools.plotting.plot_quicklook.quicklookup(data_dir, traces_included=('+1',), verbose=0, show_plots=0, save_plots=0, output_dir=None)[source]

Wrapper for quicklookup functions.

Parameters:

data_dir (str or xarray) – directory where the images you want to load are, or axarray containing the data already reduced.
traces_included (tup of str, optional) – which traces’ fluxes are included in the quicklook gif. Defaults to (“+1”,).
verbose (int, optional) – how detailed you want the printed statements to be. Defaults to 0.
show_plots (int, optional) – how many plots you want to display. Defaults to 0.
save_plots (int, optional) – how many plots you want to save. Defaults to 0.
output_dir (str, optional) – directory where the gif should be saved, if save_plots >= 1. Defaults to None.

Plotting Spectra

hustle_tools.plotting.plot_spectra.plot_2d_spectra(wav, spec, order='+1', show_plot=False, save_plot=False, filename=None, output_dir=None)[source]

Plots 2D image of the normalised spectra over time.

Parameters:

wav (np.array) – wavelength solution for given orders.
spec (np.array) – 1D extracted spectra.
show_plot (bool, optional) – whether to interrupt execution to show the user the plot. Defaults to False.
save_plot (bool, optional) – whether to save this plot to a file. Defaults to False.
filename (str, optional) – name to give this file, if saving. Defaults to None.
output_dir (str, optional) – where to save the file, if saving. Defaults to None.

hustle_tools.plotting.plot_spectra.plot_many_spectra(wavelengths, spectra, order='+1', labels=None, show_plot=False, save_plot=False, filename=None, output_dir=None)[source]

Function to plot multiple extracted spectra overtop each other.

Parameters:

wavelengths (np.array) – wavelength solution for given order.
spectra (np.array) – 1D extracted spectra.
order (str, optional) – which order this is, for plot title. Defaults to “+1”.
labels (tup, optional) – legend labels for each spectrum. Defaults to None.
show_plot (bool, optional) – whether to interrupt execution to show the user the plot. Defaults to False.
save_plot (bool, optional) – whether to save this plot to a file. Defaults to False.
filename (str, optional) – name to give this file, if saving. Defaults to None.
output_dir (str, optional) – where to save the file, if saving. Defaults to None.

hustle_tools.plotting.plot_spectra.plot_one_spectrum(wavelengths, spectrum, order='+1', show_plot=False, save_plot=False, filename=None, output_dir=None)[source]

Function to plot one extracted spectrum.

Parameters:

wavelengths (np.array) – wavelength solution for given order.
spectrum (np.array) – 1D extracted spectrum.
order (str, optional) – which order this is, for plot title. Defaults to “+1”.
show_plot (bool, optional) – whether to interrupt execution to show the user the plot. Defaults to False.
save_plot (bool, optional) – whether to save this plot to a file. Defaults to False.
filename (str, optional) – name to give this file, if saving. Defaults to None.
output_dir (str, optional) – where to save the file, if saving. Defaults to None.

hustle_tools.plotting.plot_spectra.plot_spec_gif(wav, spec, order='+1', show_plot=False, save_plot=False, filename=None, output_dir=None)[source]

Plots gifs of the extracted spectra over time.

Parameters:

wav (np.array) – wavelength solution for given orders.
spec (np.array) – 1D extracted spectra.
order (str, optional) – which order we are plotting, for plot title. Defaults to “+1”.
show_plot (bool, optional) – whether to interrupt execution to show the user the plot. Defaults to False.
save_plot (bool, optional) – whether to save this plot to a file. Defaults to False.
filename (str, optional) – name to give this file, if saving. Defaults to None.
output_dir (str, optional) – where to save the file, if saving. Defaults to None.

Plotting Time Series

hustle_tools.plotting.plot_timeseries.plot_aperture_lightcurves(obs, tested_hws, wlcs, show_plot=False, save_plot=False, filename=None, output_dir=None)[source]

Plot each extracted broad-band light curve per halfwidth, to show which halfwidth produced the nicest light curve.

Parameters:

obs (xarray) – just need the .exp_time from this.
tested_hws (array-like) – int, the halfwidths of extraction that we tested.
wlcs (array-like) – each light curve extracted.
show_plot (bool, optional) – whether to interrupt execution to show the user the plot. Defaults to False.
save_plot (bool, optional) – whether to save this plot to a file. Defaults to False.
filename (str, optional) – name to give this file, if saving. Defaults to None.
output_dir (str, optional) – where to save the file, if saving. Defaults to None.

hustle_tools.plotting.plot_timeseries.plot_flags_per_time(series_x, series_y, style='line', line_data=None, scatter_data=None, title=None, xlabel=None, ylabel=None, xmin=0, xmax=1, ymin=0, ymax=10000.0, mark_size=30, line_style='-', show_plot=False, save_plot=False, filename=None, output_dir=None)[source]

Function to plot number of flagged pixels vs time.

Parameters:

series_x (array-like) – series of x coordinates for plotting.
series_y (array-like) – series of y coordinates for plotting.
style (str) – options are ‘line’ or ‘scatter’. Defaults to ‘line’.
line_data (array-like, optional) – x, y values defining lines to overplot on top of series_x, series_y. Defaults to None.
scatter_data (array-like, optional) – x, y values defining scatter points to overplot on top of series_x, series_y. Defaults to None.
title (str, optional) – title for the plot. Defaults to None.
xlabel (str, optional) – x axis label. Defaults to None.
ylabel (str, optional) – y axis label. Defaults to None.
xmin (float, optional) – x axis lower limit. Defaults to 0.
xmax (float, optional) – x axis upper limit. Defaults to 1.
ymin (float, optional) – y axis lower limit. Defaults to 0.
ymax (float, optional) – y axis upper limit. Defaults to 1e4.
mark_size (float, optional) – size of scatter points. Defaults to 30.
line_style (str, optional) – mpl style of line. Defaults to ‘-‘.
show_plot (bool, optional) – whether to interrupt execution to show the user the plot. Defaults to False.
save_plot (bool, optional) – whether to save this plot to a file. Defaults to False.
filename (list of str, optional) – names to give each output file, if saving. Defaults to None.
output_dir (str, optional) – where to save the files to. Defaults to None.

hustle_tools.plotting.plot_timeseries.plot_raw_whitelightcurve(times, spec, order='+1', show_plot=False, save_plot=False, filename=None, output_dir=None)[source]

Plots the uncorrected broad-band light curve for this order, as a diagnostic of your cleaning process.

Parameters:

times (np.array) – mid-exposure time of each frame.
spec (np.array) – 1D extracted spectra.
order (str, optional) – which order we are plotting, for plot title. Defaults to “+1”.
show_plot (bool, optional) – whether to interrupt execution to show the user the plot. Defaults to False.
save_plot (bool, optional) – whether to save this plot to a file. Defaults to False.
filename (str, optional) – name to give this file, if saving. Defaults to None.
output_dir (str, optional) – where to save the file, if saving. Defaults to None.

Plotting Traces

hustle_tools.plotting.plot_traces.plot_fitted_positions(trace_x, trace_y, trace, exp_num, fitted_trace=None, show_plot=False, save_plot=False, filename=None, output_dir=None)[source]

Plots the GRISMCONF y-pos versus the fitted y-pos of the trace.

Parameters:

trace_x (array-like) – GRISMCONF solution to the columns.
trace_y (array-like) – GRISMCONF solution to the rows.
trace (array-like) – computed solution to the rows, to be compared to the GRISMCONF solution.
exp_num (int) – which frame this is, for plot title and filename.
fitted_trace (array-like, optional) – a polynomial fit to the trace center, may or may not be performed. Defaults to None.
show_plot (bool, optional) – whether to interrupt execution to show the user the plot. Defaults to False.
save_plot (bool, optional) – whether to save this plot to a file. Defaults to False.
filename (str, optional) – name to give this file, if saving. Defaults to None.
output_dir (str, optional) – where to save the file, if saving. Defaults to None.

hustle_tools.plotting.plot_traces.plot_profile_fit(y_vals, profile, gaussian_fit, cal_center, fit_center, order='+1', column=0, show_plot=False, save_plot=False, output_dir=None)[source]

Plot the fitted trace profiles.

Parameters:

y_vals (array-like) – y positions of the fits.
profile (array-like) – pulled profiles as a function of y.
gaussian_fit (array-like) – fitted profiles as a function of y.
cal_center (float) – calculated center of the pulled profiles.
fit_center (float) – fitted center of the fitted profiles.
order (str, optional) – which order is being plotted, for file naming. Defaults to “+1”.
column (int, optional) – which column’s fit is being plotted, for file naming. Defaults to 0.
show_plot (bool, optional) – whether to show this plot. Defaults to False.
save_plot (bool, optional) – whether to save this plot. Defaults to False.
output_dir (str, optional) – where this plot is being saved to, if save_plot is True. Defaults to None.

Configuration File Backend

Config Parser

hustle_tools.read_and_write_config.parser.parse_config(path_to_config_file)[source]

Parses config files to create a dictionary of inputs.

Parameters:: path_to_config_file (str) – path to the .hustle file that is being read.
Returns:: instructions for run_pipeline to follow.
Return type:: dict

Config Writer

hustle_tools.read_and_write_config.writer.Stage0_info()[source]

Retrieves writer information for Stage 0.

Returns:: header and comments for writing the config.
Return type:: str, list, dict, dict

hustle_tools.read_and_write_config.writer.Stage1_info()[source]

Retrieves writer information for Stage 1.

Returns:: header and comments for writing the config.
Return type:: str, list, dict, dict

hustle_tools.read_and_write_config.writer.Stage2_info()[source]

Retrieves writer information for Stage 2.

Returns:: header and comments for writing the config.
Return type:: str, list, dict, dict

hustle_tools.read_and_write_config.writer.write_config(config_dict, run_name, stage, outdir)[source]

Unpacks a dictionary and writes it out to a config file.

Parameters:

config_dict (dict) – dictionary used to guide the execution of a Stage of HUSTLE-tools.
run_name (str) – name of this run, used to give the config file a unique and identifiable name.
stage (int) – which Stage was executed, which sets the template of the config file.
outdir (outdir) – path to where the config file is to be stored.