API#

class caat.CAAT(filename: str = 'caat.csv')[source]#

The CAAT class stores and retrieves metadata about the transients in this repository.

This class provides functionality to retrieve the types, redshifts, coordinates, and peak information for the transients. It loads the saved metadata from the appropriate .csv file. This class also contains helper functions to create new .csv files, or merge existing files into one.

Initialize a CAAT object to handle an existing caat database file. The database file should live within the data/ directory in this repository and be a csv file with the necessary metadata. This method loads the existing file as a pandas DataFrame, or raises a Warning if none is found.

Parameters:

filename (str, optional) – The name of the caat .csv file.
"caat.csv". (Defaults to)

Raises:

Warning – No CAAT database file could be found.

classmethod combine_db_files(file1: str, file2: str, outfile: str)[source]#

Combine multiple CAAT database files into one. Assumes that the second file passed has the same columns as the first and in the same order.

Parameters:

file1 (str) – The filepath of the first database file.
file2 (str) – The filepath of the second database file.
outfile (str) – The filepath of the output database file.

classmethod create_db_file(type_list: list | None = None, base_db_name='caat.csv', tns_file='', force=False)[source]#

Create a CAAT database file given a TNS csv file. Optionally provide a list of transient types to limit the database file to.

Parameters:

type_list (list, optional) – An optional list of transient types to load. If none are provided, a preset set of types will be loaded. Defaults to None.
base_db_name (str, optional) – The name of the file to save. Defaults to “caat.csv”
tns_file (str, optional) – The name of the TNS file to parse for transient metadata, if one exists. Defaults to “”.
force (bool, optional) – Overwrite an existing CAAT database file, if one exists by the same name. Defaults to False.

get_sne_by_type(sntype: str, snsubtype: str | None = None)[source]#

Return a list of all the transients of a given type and subtype.

Parameters:

sntype (str) – The type of the objects to load.
snsubtype (str, optional) – The optional subtype of the objects to load. Should be a valid subtype of sntype. Defaults to None.

Returns:

A list of the names of the filtered transients.

Return type:

list

static read_info_from_tns_file(tns_file: str, sn_names: list, col_names: list)[source]#

Retrieve transient metadata from a TNS .csv file. The TNS file is available on the TNS website daily. This method retrieves the necessary metadata from the file, specified by the col_names parameter, for an input list of transient names.

Parameters:

tns_file (str) – The file path to a TNS .csv file.
sn_names (list) – The list of names of transients to search for in the TNS file.
col_names (list) – The names of the columns to extract from the TNS file.

Returns:

A dictionary of the retrieved column values.

Return type:

dict

static save_db_file(db_loc: str, sndb: DataFrame, force=False)[source]#

Save the CAAT database file to disk.

Parameters:

db_loc (str) – The filepath to save the new CAAT database file.
sndb (pd.DataFrame) – The CAAT database file, as a pandas DataFrame.
force (bool, optional) – Overwrite an existing file. Defaults to False.

class caat.DataCube(sn: <module 'caat.SN' from '/home/runner/work/gopreaux/gopreaux/src/caat/SN.py'> = None, name: str | None = None, data: dict | None = None)[source]#

Class containing routines to handle pre-processing of data.

The purpose of this class is to process and store photometry of a SN object in a pandas dataframe, containing shifted, logarithmic, linear, magnitude, and flux values, as well as metadata such as filter effective wavelengths and nondetections. This enables efficient loading, sorting, and mathematical operations on the data during the Gaussian Process Regression fitting routines.

Runs SN methods such as load_<>_data, shift_to_max, and convert_to_fluxes to initialize data set. Also optionally performs iterative warping on SED at each epoch to better match observed photometry. Constructs a pandas dataframe with this information to be saved, read, and manipulated as part of the fitting routine.

Initialize a DataCube object.

Store the photoemtry of a SN object in this DataCube instance. The SN can be passed directly, by name, or with a dictionary of data. If no data is found, this method attempts to load the data using the SN object methods.

Parameters:

sn (SN, optional) – The SN object. Defaults to None.
name (str | None, optional) – The name of a SN object, to load, if one exists. Defaults to None.
data (dict | None, optional) – A dictionary of data to load with the SN object. Defaults to None.

construct_cube()[source]#

Construct a data cube using the stored photometry.

A data cube is a pandas dataframe which stores the photometry of a SN object, in both magnitude and flux space as well as both linear and log-transformed values.

This method loads all photometry from the SN data dictionaries, redshifts it, shifts it relative to the light curve peak, and stores all associated values.

deconstruct_cube()[source]#: Takes as input a data cube and turns it into a dictionary of photometry to be used in GP fitting Assumes a data cube of size (n, 5). NOTE: This method is not currently implemented.

measure_flux_in_filter(niter: int = 100, convergence_threshold: float = 1.1, plot: bool = False, verbose: bool = False, save: bool = False, overwrite: bool = False)[source]#

Construct a “warped” data cube using the input photometry.

A “warped” data cube is one that has been iteratively mangled until the interpolated SED at a given epoch convolved with the filter functions of the filters at that epoch match the input flux values. This process shifts the effective wavelengths of the filters until the convolved flux (aka synthetic flux) matches the observed values, within some convergence threshold. This step is necessary to ensure that the shape of the input SED is true to the actual SN SED.

Parameters:

niter (int, optional) – The number of iterations to iteratively warp the SED at each phase. Defaults to 100.
convergence_threshold (float, optional) – The multiplicative factor up to which the convolved flux is considered “converged” with the input flux. Defaults to 1.1.
plot (bool, optional) – Plot the SED and interpolated photometry. Defaults to False.
verbose (bool, optional) – Optionally output statistics and values about the iterative mangling. This is to aid in debugging. Defaults to False.
save (bool, optional) – Save the final warped data cube to file. The file path is built automatically from the SN object. Defaults to False.
overwrite (bool, optional) – Overwrite any existing warped data cube if attempted to save. Defaults to False.

plot_cube()[source]#

Plots the photometry stored in the DataCube.

Plots in flux space by default.

class caat.Diagnostic[source]#

Class to implement a number of diagnostics to check quality of the GP fitting, including but not limited to plots and metrics.

This is a helper class to provide validation and support during the Gaussian Process Regression fitting process. These methods are not intended to be called outside the routines in the GP3D class.

check_gradient_between_filters(filt_wls, phase_grid, wl_grid, gp_grid, std_grid, phases_to_check)[source]#: Check that the gradient between adjacent filters at representative time slices is smooth, i.e. free from second-order (or higher) bumps and wiggles

check_late_time_slope(filt, gp_times, gp_prediction, phases)[source]#: Verify that the late-time slope of the GP fit for a given filter is negative, as expected for late-time SN light curves

identify_outlier_points(filt, gp_times, gp_prediction, gp_std_deviation, phases, mags, errs, nsigma=3)[source]#: Check the goodness of fit by finding any points more than N sigma away from the GP fit for each filter

class caat.Fitter[source]#

An AbstractBaseClass representing any Fitter object.

This is inherited by the GP and GP3D classes in this package. More generally, a user is free to design a custom Fitter class to support their specific use case that inherits the Fitter ABC.

Required Methods:#

_prepare_data:: Initializes the data set to be used as input in the fitting routine
_process_dataset:: Processes the initialized data into the form used in the fitting routine
predict:: Runs the fitting routine and produces a prediction using the inputted data

class caat.GP(sne_collection: SNCollection | SNType, kernel: Kernel, filtlist: list, phasemin: int, phasemax: int, log_transform: float)[source]#

Generate a GP fit for a single band.

Unlike GP3D, the GP class provides functionality to perform Gaussian Process Regression on photometry from a single filter. This class inherits the Fitter ABC and prepares all data for the input sample, processes the data to be used in the Gaussian process regression routine, and performs the fitting.

Initialize a GP object.

Provides methods to perform Gaussian Process Regression on photometry from a single filter for a collection of SN objects. NOTE: This method is not used frequently within the base GOPREAUX package. Instead, it is used as a building block for the GP3D class, and to provides backwards support for more traditional Gaussian Process fitting routines.

Parameters:

sne_collection (SNCollection | SNType) – A collection of SN objects to fit.
kernel (Kernel) – A Kernel object used in the Gaussian Process Regression.
filtlist (list) – The filter of the photometry to fit.
phasemin (int) – The minimum phase, relative to peak brightness, to be fit.
phasemax (int) – The maximum phase, relative to peak brightness, to be fit.
log_transform (float) – The offset in the log transform. Must be larger than phasemin. Effectively controls the light curve “stretch” in log space.

predict(filt: str, test_size: float, plot=False)[source]#

Run the Gaussian Process Regression and use it to predict a light curve for the input filter.

Calls the run method and uses the trained, outputted GaussianProcessRegressor object to produce a predicted light curve.

Parameters:

filt (str) – The filter of the photometry to fit.
test_size (float) – The fraction of the input dataset to fit with the Gaussian process. Must be between 0 and 1.
plot (bool, optional) – Plot the predicted light curve. Defaults to False.

run(filt: str, test_size: float)[source]#

Run the Gaussian Process Regression.

This method runs the _prepare_data and _process_dataset methods to prepare the data for fitting.

A random sample of the input photometry is chosen via the sklearn train_test_split function. The GaussianProcessRegressor object is returned along with the input photometry.

Parameters:

filt (str) – The filter of the photometry to fit.
test_size (float) – The fraction of the input dataset to fit with the Gaussian process. Must be between 0 and 1.

Returns:

The trained Gaussian process fit np.ndarray: The input phases in the fit np.ndarray: The input magnitudes in the fit np.ndarray: The uncertainties on the input magnitudes.

Return type:

GaussianProcessRegressor

class caat.GP3D(collection: SNCollection | SNType, kernel: Kernel, filtlist: list, phasemin: int, phasemax: int, log_transform: float, set_to_normalize: SNCollection | SNType | None = None, mangle_sed: bool = False)[source]#

Class to perform GP fitting simultaneously across wavelength and phase for a given collection of SNe. Reads in a list of SNe to fit, as well as a collection of SNe to normalize that sample against, along with a set of optional flags for different fitting routines and parameters. Each SN in the science and comparison samples should already have its photometric data pre-processed using the routines available in the SN class, run within the DataCube class, and read directly from the SN datacube files created by the latter.

Initialize a GP3D object with the following arguments.

Parameters:

collection (SNCollection | SNType) – A collection of SN objects to fit
kernel (Kernel) – A Kernel object used in the Gaussian Process Regression.
filtlist (list) – A list of filters to fit.
phasemin (int) – The minimum phase, relative to peak brightness, to be fit.
phasemax (int) – The maximum phase, relative to peak brightness, to be fit.
log_transform (float) – The offset in the log transform. Must be larger than phasemin. Effectively controls the light curve “stretch” in log space.
set_to_normalize (SNCollection | SNType | None, optional) – The colleciton of transients to normalize collection to. If None, will use collection. Defaults to None.
mangle_sed (bool, optional) – Use the calculated mangled DataCube for each SN object in collection and set_to_normalize. If True, will exclude SN objects without a mangled DataCube. Defaults to False.

static interpolate_grid(grid, interp_array, filter_window=171)[source]#: Function to remove NaNs by interpolating between actual measurements in a phase/wl grid Takes as input a grid to interpolate over, an array containing values of the grid along the interpolation dimension, as well as a filter window for smoothing using a Savitsky-Golay filter

optimize_hyperparams(subtract_median=False, subtract_polynomial=False)[source]#

Optimize the Gaussian Process Regression kernel hyperparameters by fitting each transient in the sample individually. This is normally run before the predict method to retrieve the optimized kernel hyperparameters for the input sample. These hyperparameters are normally then fixed in the kernel, and the predict method is run using the fixed kernel.

Parameters:

subtract_median (bool, optional) – Fit and subtract off a median function to calculate residuals. Defaults to False.
subtract_polynomial (bool, optional) – Fit and subtract off a polynomial function to calculate residuals. One of subtract_median and subtract_polynomial must be True. Defaults to False.

Raises:

Exception – Must toggle either subtract_median or subtract_polynomial as True
to run GP3D. –

Returns:

List of optimized kernel hyperparameters.

Return type:

list

predict(plot=False, subtract_median=False, subtract_polynomial=False, run_diagnostics=False, fit_separately=True)[source]#

Generate a Gaussian Process Regression model of the input transient sample. Uses the specified normalization sample and all other initialized parameters to process and fit the data to produce the model.

Parameters:

plot (bool, optional) – Show intermediate plots. Defaults to False.
subtract_median (bool, optional) – Fit and subtract off a median function to calculate residuals. Defaults to False.
subtract_polynomial (bool, optional) – Fit and subtract off a polynomial function to calculate residuals. One of subtract_median and subtract_polynomial must be True. Defaults to False.
run_diagnostics (bool, optional) – Run diagnostic tests on the fitting to identify data points or regions of poor fit quality. Defaults to False.
fit_separately (bol, optional) – Fit each transient separately, or together as a group. Controls whether run_gp_individually or run_gp_on_full_sample is called to generate the predictive Gaussian Process Regression model. Defaults to True.

Returns:

An SNModel object containing the final, 3-dimensional Gaussian Process: Regression template model of the input transient sample.

Return type:

SNModel

run_gp_individually(plot=False, subtract_median=False, subtract_polynomial=False, interactive=False, run_diagnostics=False, save_individual_fits=False)[source]#

Run the Gaussian Process Regression fitting routine on each transient in the full sample individually. This produces a bespoke Gaussian process model for each transient, constructing a full 3-dimension SED surface. These surfaces are then randomly sampled and to be used in the construction of the final template model surface.

Parameters:

plot (bool, optional) – Show intermediate plots. Defaults to False.
subtract_median (bool, optional) – Fit and subtract off a median function to calculate residuals. Defaults to False.
subtract_polynomial (bool, optional) – Fit and subtract off a polynomial function to calculate residuals. One of subtract_median and subtract_polynomial must be True. Defaults to False.
interactive (bool, optional) – Interactively choose which fits to use in the creation of the final Gaussian process model. If True, sets plot to True as well. Defaults to False.
run_diagnostics (bool, optional) – Run diagnostic tests on the fitting to identify data points or regions of poor fit quality. Defaults to False.
save_individual_fits (bool, optional) – Save the GP fits to each individual SN object separately. If True, will save the models to the default location. WARNING: This can be a lot of data. Defualts to False.

Raises:

Exception – Must toggle either subtract_median or subtract_polynomial as True
to run GP3D. –

Returns:

A list of random samples from the Gaussian process distribution. Used to: construct final 3-dimensional templates.
np.ndarray: An array containing the processed magnitudes from: the template grid

np.ndarray: An array containing the log-transformed phases np.ndarray: An array containing the log-transformed wavelengths

Return type:

list

run_gp_on_full_sample(plot=False, subtract_median=False, subtract_polynomial=False)[source]#

Run the Gaussian Process Regression fitting routine on the full sample at once. Does not individually fit each transient, but instead fits all photometry in the input sample simultaneously.

Parameters:

plot (bool, optional) – Show intermediate plots. Defaults to False.
subtract_median (bool, optional) – Fit and subtract off a median function to calculate residuals. Defaults to False.
subtract_polynomial (bool, optional) – Fit and subtract off a polynomial function to calculate residuals. One of subtract_median and subtract_polynomial must be True. Defaults to False.

Raises:

Exception – Must toggle either subtract_median or subtract_polynomial as True
to run GP3D. –

Returns:

A list containing the Gaussian process model and its: uncertainty, both as an mxn array
np.ndarray: An array containing the processed magnitudes from: the template grid

np.ndarray: An array containing the log-transformed phases np.ndarray: An array containing the log-transformed wavelengths

Return type:

list

class caat.Kernel(kernel: Kernel)[source]#

A custom Kernel class used to store kernel hyperparameters and use them in the sklearn GaussianProcessRegression class. This is intended to be used to produce linear combinations of the basic Sklearn kernels.

This class inherits the sklearn Kernel object and overwrites some of its methods to maintain compatibility with the base class and the GaussianProcessRegressor class while enabling users to input custom kernels.

Initialize a Kernel object with an sklearn Kernel.

Parameters:: kernel (SklearnKernel) – The sklearn Kernel object.

diag(X)[source]#

Returns the diagonal of the kernel k(X, X).

The result of this method is identical to np.diag(self(X)); however, it can be evaluated more efficiently since only the diagonal is evaluated.

Parameters:: X (array-like of shape (n_samples,)) – Left argument of the returned kernel k(X, Y)
Returns:: K_diag – Diagonal of kernel k(X, X)
Return type:: ndarray of shape (n_samples_X,)

is_stationary()[source]#: Returns whether the kernel is stationary.

recursively_set_params(values: list, bounds: list | str, kernel=None)[source]#

Recursively set parameters for all component kernels. Gets the valid param keywords for the kernel and uses them to set the values of the correct parameters. If Kernel is a product or sum of kernels, assumes the input values and bounds are in the same order as the kernels.

Parameters:

values (list) – The kernel parameters
bounds (list | str) – The kernel parameter bounds
kernel (_type_, optional) – The kernel to set parameters of. Defaults to None.

class caat.Plot[source]#

Plot class allowing any number of diagnostic / step-by-step plots to be created and displayed across the SN, SNCollection, GP, and GP3D classes.

This is a helper class called in the different classes to provide optional plotting support. These methods are not intended to be called outside of the routines in the other classes.

plot_all_lcs(sn_class, filts=['all'], log_transform=False, plot_fluxes=False, ax=None, show=True)[source]#: plot all light curves of given subtype/collection can plot single, multiple or all bands

plot_construct_grid(gp_class, X, Y, Z, ax=None, Z_lower=None, Z_upper=None, grid_type=None, phase_grid=None, mag_grid=None, wl_grid=None, err_grid=None, filtlist=None)[source]#

Input grid_type:: takes str object ‘median’ or ‘poly’, default=None

plot_fit_for_max(sn_class, mjd_array, mag_array, err_array, fit_mjds, fit_mags, fit_errs, inds_to_fit)[source]#: Takes as input arrays for MJD, mag, and err for a filter as well as the guess for the MJD of maximum and an array to shift the lightcurve over, and returns estimates of the peak MJD and mag at peak

class caat.SN(name: str, data: dict = None, type: str = None, subtype: str = None, info: dict = {})[source]#

A Supernova object, taking a classification (i.e. SN II, SESNe, FBOT, etc.), a subtype (i.e., SN IIP, SN IIb, SN Ibn, etc.), and a name (i.e. SN2022acko). Provides routines for the extraction and transformation of photometric data that are uniformly run and saved within the DataCube class.

Initialize a SN object. Can initialize through either a name or through a dictionary of data.

Parameters:

name (str) – The name of the SN. If it exists in the CAAT file, the data will automatically be searched for and loaded.
data (dict, optional) – A dictionary of data. Allows for loading a new SN object that has not already been saved. Defaults to None.
type (str, optional) – The type (or classification) of the object. If one is not provided, it will be searched for within the CAAT database file and data directory automatically. Defaults to None.
subtype (str, optional) – The subtype of the object. If one is not provided, it will be searched for within the CAAT database file and data directory automatically. Defaults to None.
info (dict, optional) – A dictionary containing metadata of the transient. This is useful if a SN object is initialized before it has been added to the CAAT file. Users can pass information such as coordinates, redshift, and light curve peak information directly, which can then later be saved back to the CAAT file for easy re-initialization. Defaults to {}.

Raises:

Exception – If name is given, but is not found in the CAAT archive.

convert_all_mags_to_fluxes()[source]#: Converts all photometry in magnitudes to the corresponding flux values. Uses AB zeropoints. Runs on both shifted and unshifted photometry, relative to light curve peak.

correct_for_galactic_extinction()[source]#: Uses the coordinates of the SN from the CAAT file to find and correct for MW extinction. NOTE: Must be run before convert_to_fluxes() is ran.

fit_for_max(filt, shift_array=[-3, -2, -1, 0, 1, 2, 3], plot=False, offset=0)[source]#

Fit for the light curve peak. This method identifies a preliminary light curve peak, selects photometry within a 30 day window of the preliminary peak, and iteratively fits a third-order polynomial to a random subset of that data. This process only runs if more than 4 light curve points are within the preliminary peak in the given filter. Writes the peak info the info attribute on this class.

Parameters:

filt (_type_) – The filter of the photometry to fit.
shift_array (list, optional) – An array of phases to shift the selected photometry by, during the iterative peak fitting. Defaults to [-3, -2, -1, 0, 1, 2, 3].
plot (bool, optional) – Plot the fit to the peak. Defaults to False.
offset (int, optional) – A number of days relative to the preliminary peak to fit. Useful if the identified preliminary peak is not close to the true light curve peak. Defaults to 0.

interactively_fit_for_max(filt='', shift_array=[-3, -2, -1, 0, 1, 2, 3], plot=True, offset=0, save_to_caat=False, force=False)[source]#

Iteratively fit for the SN light curve peak. This method will load the SN photometry automatically. At each step of the fitting process, a plot is generated and the user is prompted to supply the filter to fit, an offset, whether to accept the fit, or refit with new parameters.

Parameters:

filt (str, optional) – The fiter to fit. If one is not passed, the user is shown the full light curve and prompted to pick a filter. Defaults to “”.
shift_array (list, optional) – An array of phases to shift the selected photometry by, during the iterative peak fitting. Defaults to [-3, -2, -1, 0, 1, 2, 3].
plot (bool, optional) – Plot the fit to the peak and all intermediate plots. Defaults to True.
offset (int, optional) – A number of days relative to the preliminary peak to fit. Useful if the identified preliminary peak is not close to the true light curve peak. Defaults to 0.
save_to_caat (bool, optional) – Save the best-fit peak information to the CAAT file. Defaults to False.
force (bool, optional) – Overwrite the existing peak information in the CAAT file. Defaults to False.

load_json_data()[source]#: Load data saved as a JSON file. This applies to data from ZTF, ATLAS, OpenSN, and ASAS-SN>. This method searches for .json data files and loads the photometry from any that it finds. Loaded photometry is saved as a dictionary attribute to this class.

load_shifted_data()[source]#: Loads any photometry for this SN object that has been shifted relative to light curve peak and saved to file.

load_swift_data()[source]#: Load Swift data for this object. Searches for the corresponding SOUSA output .dat file. If one is found, reads the file as a pandas dataframe, extracts detection and nondetection information, and transforms the magnitudes to the Vega system. Loaded photometry is saved as a dictionary attribute to this class.

log_transform_time(phases, phase_start=30)[source]#

Natural log-transform an array of phases, given an offset value to avoid numerical errors.

Parameters:

phases (np.ndarray) – A numpy array of phases.
phase_start (int, optional) – An offset to apply to the phase values, to avoid numerical errors.. Defaults to 30.

Returns:

The log-transformed phase values.

Return type:

np.ndarray

plot_data(filts_to_plot=['all'], shifted_data_exists=False, view_shifted_data=False, offset=0, plot_fluxes=False)[source]#

Plot photometry for this SN object. A user may control the type of photometry that is plotted (e.g., filters, magnitudes or fluxes, shifted or unshifted). If no data is found, this method will attempt to load data first.

Parameters:

filts_to_plot (list, optional) – A list of the filters to plot. Defaults to [“all”].
shifted_data_exists (bool, optional) – Flag to control whether or not to load new shifted data. Defaults to False.
view_shifted_data (bool, optional) – Flag to control plotting data shifted relative to light curve peak. Defaults to False.
offset (int, optional) – An offset to pass to the shift_to_max method used for fitting the light curve peak. Defaults to 0.
plot_fluxes (bool, optional) – Flag used to control plotting photometry in magnitude or flux space. Defaults to False.

read_info_from_caat_file()[source]#: Load information about the SN object from the CAAT file. Will search by name for the SN object in the CAAT file. If it is found, the redshift, coordinates, and light curve peak information are loaded as a dictionary attribute.

shift_to_max(filt: str, shift_array=[-3, -2, -1, 0, 1, 2, 3], plot=False, offset=0, shift_fluxes=False, try_other_filts=True, return_wls=False)[source]#

Shift the SN photometry relative to the light curve peak. This method will load the SN photometry if it is not already loaded. If no peak info is found, this method will attempt to fit for the light curve peak.

Parameters:

filt (_type_) – The filter of the photometry to fit.
shift_array (list, optional) – An array of phases to shift the selected photometry by, during the iterative peak fitting. Defaults to [-3, -2, -1, 0, 1, 2, 3].
plot (bool, optional) – Plot the fit to the peak. Defaults to False.
offset (int, optional) – A number of days relative to the preliminary peak to fit. Useful if the identified preliminary peak is not close to the true light curve peak. Defaults to 0.
shift_fluxes (bool, optional) – Shift the photometry in flux units relative to light curve peak. Defaults to False.
try_other_filts (bool, optional) – If the light curve peak cannot be found for the input filt, try fitting for the peak in a predefined list of filters. Defaults to True.
return_wls (bool, optional) – Return wavelength information for the photometry. Defaults to False.

Returns:

Lists of shifted: time, magnitudes, error, nondetections, and optional wavelengths.

Return type:

list, list, list, list, list (optional)

write_info_to_caat_file(force=False)[source]#

Save light curve peak information to the CAAT file. This method is usually run after the light curve peak is fit manually or automatically.

Parameters:: force (bool, optional) – Overwrite the peak info, if it already exists in the CAAT file. Defaults to False.

write_json_data(dry_run=True)[source]#

Writes photometry that has not been shifted relative to light curve peak to a .json file. Runs before the photometry has been shifted.

Parameters:: dry_run (bool, optional) – Run the method by logging what new directories and files would be created or saved, without actually doing so. Defaults to True.

A SNCollection object, which holds an arbitrary number of SNe.

The SNCollection object is the primary way of storing and passing a number of SN objects to the fitting routines in this package. SNCollection objects can be initialized with either a list of names, each corresponding to a SN recorded in the CAAT file, a list of SN objects, or a type and subtype. In the latter case, the corresponding SN objects are automatically found and instantiated.

Initialize a SNCollection object to store a collection of SNe. Can be initalized with either a list of names or SNe objects, or with a type and subtype.

Parameters:

names (str | list | None, optional) – A list of names, each corresponding to a SN object described in the CAAT file. Defaults to None.
sntype (str | None, optional) – The classification of SNe to instantiate. Defaults to None.
snsubtype (str | None, optional) – The subtype of SNe to instantiate. Must be a valid subtype of sntype. Defaults to None.
SNe (list[SN] | None, optional) – The SN or SNe to store. Defaults to None.

plot_all_lcs(filts=['all'], log_transform=False, plot_fluxes=False, ax=None, show=True)[source]#

Plot all light curves for the SNe in this SNCollection object. Can choose a subset of filters to plot, or to plot all filter data. Can plot log-transformed or natural light curves, fluxes or magnitudes.

Parameters:

filts (list, optional) – The filter(s) to plot. Defaults to [“all”].
log_transform (bool, optional) – Log transform the time axis. Defaults to False.
plot_fluxes (bool, optional) – Plot photometry in flux space, instead of magnitude space. Defaults to False.
ax (_type_, optional) – Provide an existing matplotlib.axes object. Used to customize plotting. Defaults to None.
show (bool, optional) – Show the light curves. Defaults to True.

A Supernova Model object. Saves the outputted 3D SED surface from the Gaussian process regression routine for a SN object or a collection of SNe. Provides routines for saving and loading the final GP fits, as well as for extracting 2D light curves or SEDs from the interpolated surfaces.

Initialize an SNModel object from a number of arguments.

Parameters:

surface (GaussianProcessRegressor | str | SurfaceArray | None, optional) – The final SED surface model. Can be either an initialized and fit GaussianProcessRegressor object, a SurfaceArray object, or filepath to a saved model. Defaults to None.
template_mags (np.ndarray | None, optional) – The magnitudes used to normalize the input photometry prior to fitting. Defaults to None.
phase_grid (np.ndarray | None, optional) – The phase grid used to produce the final SED surface model. Defaults to None.
phase_bounds (tuple | None, optional) – The minimum and maximum phase values provided to the fitting. Defaults to None.
wl_grid (np.ndarray | None, optional) – The wavelength grid used to produce the final SED surface model. Defaults to None.
filters_fit (list[str] | None, optional) – The specified filters of the photometry used in the fitting. Defaults to None.
sn (SN | None, optional) – The SN object to which this model belongs. Defaults to None.
sncollection (SNType | SNCollection | None, optional) – The collection of SN objects to which this model belongs. Defaults to None.
norm_set (SNType | SNCollection | None, optional) – The set of SN objects used in the normalization process during the fitting. Defaults to None.
log_transform (int | float | bool, optional) – The value of log_transform used in the fitting, if one was used. Defaults to False.

Raises:

ValueError – Must initialize an SNModel object by passing in either an SN or SNCollection, to which this model belongs.

compare_lightcurve_with_photometry(sn: SN, filt: str, show: bool = True)[source]#

Compare a predicted light curve with observed photometry. Useful when validating the accuracy of a model’s predicted light curve.

Parameters:

sn (SN) – A SN object with observed photometry.
filt (str) – The filter of the light curve to compare.
show (bool, optional) – Plot the resulting comparison. Defaults to True.

fit_photometry(sn_to_fit: SN | None = None, photometry: dict | DataFrame = None, filters_to_fit: list | None = None, phase_min: float | None = None, phase_max: float | None = None, show: bool = False, nsamples: int = 1, keep_new_fit: bool = False)[source]#

Fit photometry of an input SN using the GaussianProcessRegressor model. If a phase min or phase max is specified, extrapolates the fit to those bounds.

Parameters:

sn_to_fit (SN, optional) – A SN object containing the photometry to fit. Defaults to None.
photometry (dict | pd.DataFrame, optional) – The input photometry to fit, if one does not specify a sn_to_fit. Must be a dict or DataFrame that contains these columns: Filter, Phase, Mag, and MagErr, where “Mag” values are calculated relative to the light curve peak. For example passing in a “Mag” value of -2.0 means that point is 2 magnitudes fainter than the light curve peak, a.k.a “Mag” = peak_mag - each_observed_mag. Defaults to None.
filters_to_fit (list, optional) – The filters to fit. If none are provided, all filters will be fit. Defaults to None.
phase_min (float, optional) – The minimum phase to constrain our GP prediction. Defaults to None.
phase_max (float, optional) – The maximum phase to constrain our GP prediction. Defaults to None.
show (bool, optional) – Plot the resulting fit. Defaults to False.
nsamples (int, optional) – Number of samples to draw from the GP for the fit. If 1, plots the usual GP prediction with error bars If >1, plots nsamples of randomly drawn GP fits. Defaults to 1.
keep_new_fit (bool, optional) – Overwrite self.surface with the new GPR fit generated from the input photometry. If set to True, this allows class-based functionality (e.g., predict_lightcurve) to use the newly generated fit. Note that this does not overwrite any of the fit information that is saved to disk. Defaults to False.

load_from_fits(filename: str)[source]#

Load a specified .fits file as an SNModel object. This is used during the initialization of the object, if a string is passed as the surface argument. Loading the saved .fits file will initialize the underlying SED surface model and load all associated metadata.

Parameters:: filename (str) – The path to and name of the .fits file.

predict_lightcurve(phase_min: float | int, phase_max: float | int, wavelength: float | int, show=True)[source]#

Predict a light curve using the stored surface model. Utilizes the predict() method on self.surface to predict relative magnitudes given phase bounds and wavelength. Works for both stored and initialized GaussianProcessRegressor objects as well as SurfaceArray objects.

Parameters:

phase_min (float | int) – The minimum phase to predict, i.e. the first point of the light curve.
phase_max (float | int) – The maximum phase to predict, i.e. the last point of the light curve.
wavelength (float | int) – The wavelength at which to predict the light curve.
show (bool, optional) – Plot the predicted light curve. Defaults to True.

Raises:

ValueError – If the input phase_min or phase_max are outside the fitted bounds of the Gaussian process.
ValueError – If the input wavelength is outside the fitted bounds of the Gaussian Process.

predict_photometry_points(wavelengths: ndarray, phases: ndarray, show: bool = False, **kwargs)[source]#

Predict a series of photometry points given arrays of wavelength and phase. Utilizes the predict() method on self.surface to predict relative magnitudes at discrete points of wavelength and phase. Works for both stored and initialized GaussianProcessRegressor objects as well as SurfaceArray objects.

Example

To predict points in two filters at each of three phases, wavelengths and phases must be length 6 arrays, e.g. wavelengths = [3500, 3500, 3500, 5000, 5000, 5000] phases = [-10, 0, 10, -10, 0, 10]

Parameters:

wavelengths (np.ndarray) – array of wavelengths, in Angstroms.
phases (np.ndarray) – array of phases, in days.
show (bool, optional) – Plot the predicted photometry points. Defaults to False.

Raises:

ValueError – If any input wavelength values are outside the bounds of the Gaussian process fit.
ValueError – If any input phase values are outside the bounds of the Gaussian process fit.

Returns:

The predicted phases,: magnitudes, and uncertainties of the photometry points.

Return type:

tuple[np.ndarray, np.ndarray, np.ndarray]

predict_sed(wavelength_min, wavelength_max, phase, show=True)[source]#

Predict a spectral energy distribution (SED) using the stored surface model. Utilizes the predict() method on self.surface to predict relative magnitudes given wavelength bounds and phase. Works for both stored and initialized GaussianProcessRegressor objects as well as SurfaceArray objects.

Parameters:

wavelength_min (float | int) – The minimum wavelength to predict, i.e. the first point of the SED.
phase_max (float | int) – The maximum wavelength to predict, i.e. the last point of the SED.
phase (float | int) – The phase at which to predict the SED.
show (bool, optional) – Plot the predicted light curve. Defaults to True.

Raises:

ValueError – If the input wavelength_min or wavelength_max are outside the fitted bounds of the Gaussian process.
ValueError – If the input phase is outside the fitted bounds of the Gaussian Process.

save_fits(filename: str = None, force: bool = False)[source]#

Save the SNModel as a .fits file. The .fits file will store the pickled SED surface model, the associated uncertainties, and all metadata passed in through the initialization. This format allows it to be easily loaded and used without redoing the fitting process.

Parameters:

filename (str, optional) – The name of the file to be saved. Defaults to None.
force (bool, optional) – Overwrite an existing file, if one already exists with the same filename. Defaults to False.

class caat.SNType(type)[source]#

A SNType object, building a collection of all SNe of a given type (classification).

SNType inherits SNCollection and provides more tailored methods for all objects of a given classification.

Initialize a SNType object.

Parameters:: type (str) – The classification of the objects to load. Will automatically retrieve all subtypes of the given type and load the correct SN objects.

build_object_list()[source]#: Load all objects of the given type from the CAAT file. First finds all subtypes, then loads all SN objects of those type/subtypes.

get_subtypes()[source]#: Get all subtypes of the given type from the CAAT file.

class caat.CAAT(filename: str = 'caat.csv')[source]#

The CAAT class stores and retrieves metadata about the transients in this repository.

Parameters:

filename (str, optional) – The name of the caat .csv file.
"caat.csv". (Defaults to)

Raises:

Warning – No CAAT database file could be found.

classmethod combine_db_files(file1: str, file2: str, outfile: str)[source]#

Combine multiple CAAT database files into one. Assumes that the second file passed has the same columns as the first and in the same order.

Parameters:

file1 (str) – The filepath of the first database file.
file2 (str) – The filepath of the second database file.
outfile (str) – The filepath of the output database file.

classmethod create_db_file(type_list: list | None = None, base_db_name='caat.csv', tns_file='', force=False)[source]#

Create a CAAT database file given a TNS csv file. Optionally provide a list of transient types to limit the database file to.

Parameters:

type_list (list, optional) – An optional list of transient types to load. If none are provided, a preset set of types will be loaded. Defaults to None.
base_db_name (str, optional) – The name of the file to save. Defaults to “caat.csv”
tns_file (str, optional) – The name of the TNS file to parse for transient metadata, if one exists. Defaults to “”.
force (bool, optional) – Overwrite an existing CAAT database file, if one exists by the same name. Defaults to False.

get_sne_by_type(sntype: str, snsubtype: str | None = None)[source]#

Return a list of all the transients of a given type and subtype.

Parameters:

sntype (str) – The type of the objects to load.
snsubtype (str, optional) – The optional subtype of the objects to load. Should be a valid subtype of sntype. Defaults to None.

Returns:

A list of the names of the filtered transients.

Return type:

list

static read_info_from_tns_file(tns_file: str, sn_names: list, col_names: list)[source]#

Parameters:

tns_file (str) – The file path to a TNS .csv file.
sn_names (list) – The list of names of transients to search for in the TNS file.
col_names (list) – The names of the columns to extract from the TNS file.

Returns:

A dictionary of the retrieved column values.

Return type:

dict

static save_db_file(db_loc: str, sndb: DataFrame, force=False)[source]#

Save the CAAT database file to disk.

Parameters:

db_loc (str) – The filepath to save the new CAAT database file.
sndb (pd.DataFrame) – The CAAT database file, as a pandas DataFrame.
force (bool, optional) – Overwrite an existing file. Defaults to False.

class caat.DataCube(sn: <module 'caat.SN' from '/home/runner/work/gopreaux/gopreaux/src/caat/SN.py'> = None, name: str | None = None, data: dict | None = None)[source]#

Class containing routines to handle pre-processing of data.

Initialize a DataCube object.

Parameters:

sn (SN, optional) – The SN object. Defaults to None.
name (str | None, optional) – The name of a SN object, to load, if one exists. Defaults to None.
data (dict | None, optional) – A dictionary of data to load with the SN object. Defaults to None.

construct_cube()[source]#

Construct a data cube using the stored photometry.

A data cube is a pandas dataframe which stores the photometry of a SN object, in both magnitude and flux space as well as both linear and log-transformed values.

This method loads all photometry from the SN data dictionaries, redshifts it, shifts it relative to the light curve peak, and stores all associated values.

deconstruct_cube()[source]#: Takes as input a data cube and turns it into a dictionary of photometry to be used in GP fitting Assumes a data cube of size (n, 5). NOTE: This method is not currently implemented.

measure_flux_in_filter(niter: int = 100, convergence_threshold: float = 1.1, plot: bool = False, verbose: bool = False, save: bool = False, overwrite: bool = False)[source]#

Construct a “warped” data cube using the input photometry.

Parameters:

niter (int, optional) – The number of iterations to iteratively warp the SED at each phase. Defaults to 100.
convergence_threshold (float, optional) – The multiplicative factor up to which the convolved flux is considered “converged” with the input flux. Defaults to 1.1.
plot (bool, optional) – Plot the SED and interpolated photometry. Defaults to False.
verbose (bool, optional) – Optionally output statistics and values about the iterative mangling. This is to aid in debugging. Defaults to False.
save (bool, optional) – Save the final warped data cube to file. The file path is built automatically from the SN object. Defaults to False.
overwrite (bool, optional) – Overwrite any existing warped data cube if attempted to save. Defaults to False.

plot_cube()[source]#

Plots the photometry stored in the DataCube.

Plots in flux space by default.

caat.Diagnostics#: alias of <module ‘caat.Diagnostics’ from ‘/home/runner/work/gopreaux/gopreaux/src/caat/Diagnostics.py’>

class caat.GP(sne_collection: SNCollection | SNType, kernel: Kernel, filtlist: list, phasemin: int, phasemax: int, log_transform: float)[source]#

Generate a GP fit for a single band.

Initialize a GP object.

Parameters:

sne_collection (SNCollection | SNType) – A collection of SN objects to fit.
kernel (Kernel) – A Kernel object used in the Gaussian Process Regression.
filtlist (list) – The filter of the photometry to fit.
phasemin (int) – The minimum phase, relative to peak brightness, to be fit.
phasemax (int) – The maximum phase, relative to peak brightness, to be fit.
log_transform (float) – The offset in the log transform. Must be larger than phasemin. Effectively controls the light curve “stretch” in log space.

predict(filt: str, test_size: float, plot=False)[source]#

Run the Gaussian Process Regression and use it to predict a light curve for the input filter.

Calls the run method and uses the trained, outputted GaussianProcessRegressor object to produce a predicted light curve.

Parameters:

filt (str) – The filter of the photometry to fit.
test_size (float) – The fraction of the input dataset to fit with the Gaussian process. Must be between 0 and 1.
plot (bool, optional) – Plot the predicted light curve. Defaults to False.

run(filt: str, test_size: float)[source]#

Run the Gaussian Process Regression.

This method runs the _prepare_data and _process_dataset methods to prepare the data for fitting.

A random sample of the input photometry is chosen via the sklearn train_test_split function. The GaussianProcessRegressor object is returned along with the input photometry.

Parameters:

filt (str) – The filter of the photometry to fit.
test_size (float) – The fraction of the input dataset to fit with the Gaussian process. Must be between 0 and 1.

Returns:

The trained Gaussian process fit np.ndarray: The input phases in the fit np.ndarray: The input magnitudes in the fit np.ndarray: The uncertainties on the input magnitudes.

Return type:

GaussianProcessRegressor

Initialize a GP3D object with the following arguments.

Parameters:

collection (SNCollection | SNType) – A collection of SN objects to fit
kernel (Kernel) – A Kernel object used in the Gaussian Process Regression.
filtlist (list) – A list of filters to fit.
phasemin (int) – The minimum phase, relative to peak brightness, to be fit.
phasemax (int) – The maximum phase, relative to peak brightness, to be fit.
log_transform (float) – The offset in the log transform. Must be larger than phasemin. Effectively controls the light curve “stretch” in log space.
set_to_normalize (SNCollection | SNType | None, optional) – The colleciton of transients to normalize collection to. If None, will use collection. Defaults to None.
mangle_sed (bool, optional) – Use the calculated mangled DataCube for each SN object in collection and set_to_normalize. If True, will exclude SN objects without a mangled DataCube. Defaults to False.

static interpolate_grid(grid, interp_array, filter_window=171)[source]#: Function to remove NaNs by interpolating between actual measurements in a phase/wl grid Takes as input a grid to interpolate over, an array containing values of the grid along the interpolation dimension, as well as a filter window for smoothing using a Savitsky-Golay filter

optimize_hyperparams(subtract_median=False, subtract_polynomial=False)[source]#

Parameters:

subtract_median (bool, optional) – Fit and subtract off a median function to calculate residuals. Defaults to False.
subtract_polynomial (bool, optional) – Fit and subtract off a polynomial function to calculate residuals. One of subtract_median and subtract_polynomial must be True. Defaults to False.

Raises:

Exception – Must toggle either subtract_median or subtract_polynomial as True
to run GP3D. –

Returns:

List of optimized kernel hyperparameters.

Return type:

list

predict(plot=False, subtract_median=False, subtract_polynomial=False, run_diagnostics=False, fit_separately=True)[source]#

Parameters:

plot (bool, optional) – Show intermediate plots. Defaults to False.
subtract_median (bool, optional) – Fit and subtract off a median function to calculate residuals. Defaults to False.
subtract_polynomial (bool, optional) – Fit and subtract off a polynomial function to calculate residuals. One of subtract_median and subtract_polynomial must be True. Defaults to False.
run_diagnostics (bool, optional) – Run diagnostic tests on the fitting to identify data points or regions of poor fit quality. Defaults to False.
fit_separately (bol, optional) – Fit each transient separately, or together as a group. Controls whether run_gp_individually or run_gp_on_full_sample is called to generate the predictive Gaussian Process Regression model. Defaults to True.

Returns:

An SNModel object containing the final, 3-dimensional Gaussian Process: Regression template model of the input transient sample.

Return type:

SNModel

run_gp_individually(plot=False, subtract_median=False, subtract_polynomial=False, interactive=False, run_diagnostics=False, save_individual_fits=False)[source]#

Parameters:

plot (bool, optional) – Show intermediate plots. Defaults to False.
subtract_median (bool, optional) – Fit and subtract off a median function to calculate residuals. Defaults to False.
subtract_polynomial (bool, optional) – Fit and subtract off a polynomial function to calculate residuals. One of subtract_median and subtract_polynomial must be True. Defaults to False.
interactive (bool, optional) – Interactively choose which fits to use in the creation of the final Gaussian process model. If True, sets plot to True as well. Defaults to False.
run_diagnostics (bool, optional) – Run diagnostic tests on the fitting to identify data points or regions of poor fit quality. Defaults to False.
save_individual_fits (bool, optional) – Save the GP fits to each individual SN object separately. If True, will save the models to the default location. WARNING: This can be a lot of data. Defualts to False.

Raises:

Exception – Must toggle either subtract_median or subtract_polynomial as True
to run GP3D. –

Returns:

A list of random samples from the Gaussian process distribution. Used to: construct final 3-dimensional templates.
np.ndarray: An array containing the processed magnitudes from: the template grid

np.ndarray: An array containing the log-transformed phases np.ndarray: An array containing the log-transformed wavelengths

Return type:

list

run_gp_on_full_sample(plot=False, subtract_median=False, subtract_polynomial=False)[source]#

Run the Gaussian Process Regression fitting routine on the full sample at once. Does not individually fit each transient, but instead fits all photometry in the input sample simultaneously.

Parameters:

plot (bool, optional) – Show intermediate plots. Defaults to False.
subtract_median (bool, optional) – Fit and subtract off a median function to calculate residuals. Defaults to False.
subtract_polynomial (bool, optional) – Fit and subtract off a polynomial function to calculate residuals. One of subtract_median and subtract_polynomial must be True. Defaults to False.

Raises:

Exception – Must toggle either subtract_median or subtract_polynomial as True
to run GP3D. –

Returns:

A list containing the Gaussian process model and its: uncertainty, both as an mxn array
np.ndarray: An array containing the processed magnitudes from: the template grid

np.ndarray: An array containing the log-transformed phases np.ndarray: An array containing the log-transformed wavelengths

Return type:

list

Table of Contents

API#

Required Methods:#

This Page