raccoon package

Submodules

raccoon.util module

class raccoon.util.Util

Bases: object

classmethod find_extrema(curve, init_peak_detection_proximity_threshold=50, is_peak=True)

Find peaks or troughs of a curve.

Parameters:

• curve (np.ndarray) – 1D numpy array

• init_peak_detection_proximity_threshold (int) – Minimum distance between two extrema in pixels

• is_peak (bool) – If True, find peaks, otherwise find troughs

Returns:

Indices of the extrema

Return type:

np.ndarray

classmethod find_init_peaks_troughs_mids(curve, init_peak_detection_proximity_threshold=50)

Find initial peaks, troughs, and midpoints of a curve.

Parameters:

• curve (np.ndarray) – 1D numpy array

• init_peak_detection_proximity_threshold (int) – Minimum distance between two extrema in pixels

Returns:

Peaks, troughs, and midpoints

Return type:

Tuple[np.ndarray, np.ndarray, np.ndarray]

classmethod fit_sine_function_to_extrema_polynomial(extrema_positions, extrema_vals, is_peak, n_amplitude, n_offset, n_frequency, phi_0=None)

Fit a wiggly function to the peaks and troughs of a curve.

Parameters:

• extrema_positions (np.ndarray) – Positions of the extrema

• extrema_vals (np.ndarray) – Values of the extrema

• is_peak (np.ndarray) – If True, the extrema are peaks, otherwise they are troughs

• n_amplitude (int) – Degree of the polynomial for the amplitude

• n_offset (int) – Degree of the polynomial for the offset

• n_frequency (int) – Degree of the polynomial for the frequency

• phi_0 (float) – Phase offset

Returns:

amplitude coefficients, offset coefficients, frequency coefficients, phase offset

classmethod fit_sine_function_to_extrema_spline(extrema_positions, extrema_vals, is_peak, n_amplitude, n_frequency, phi_0=None)

Fit a wiggly function to the peaks and troughs of a curve using splines for amplitude and frequency.

Parameters:

• extrema_positions (np.ndarray) – Positions of the extrema

• extrema_vals (np.ndarray) – Values of the extrema

• is_peak (np.ndarray) – If True, the extrema are peaks, otherwise they are troughs

• n_amplitude (int) – Degree of the polynomial for the amplitude

• n_offset (int) – Degree of the polynomial for the offset

• n_frequency (int) – Degree of the polynomial for the frequency

• phi_0 (float) – Phase offset

Returns:

amplitude spline, frequency spline, phase offset

Return type:

tuple

classmethod fitted_sine_function_polynomial(xs, amplitude_coeffs, offset_coeffs, frequency_coeffs, phi_0)

Evaluate the fitted sine function at x.

Parameters:

• xs (np.ndarray) – x values

• amplitude_coeffs (np.ndarray) – Amplitude coefficients

• offset_coeffs (np.ndarray) – Offset coefficients

• frequency_coeffs (np.ndarray) – Frequency coefficients

• phi_0 (float) – Phase offset

Returns:

Fitted sine function values

Return type:

np.ndarray

classmethod fitted_sine_function_spline(xs, amp_spline, frequency_spline, phi_0)

Evaluate the fitted sine function at x.

Parameters:

• xs (np.ndarray) – x values

• amplitude_coeffs (np.ndarray) – Amplitude coefficients

• offset_coeffs (np.ndarray) – Offset coefficients

• frequency_coeffs (np.ndarray) – Frequency coefficients

• phi_0 (float) – Phase offset

Returns:

Fitted sine function values

Return type:

np.ndarray

classmethod get_init_params_polynomial(curve, scaled_wavelengths, n_amplitude=2, n_offset=7, n_frequency=1, init_peak_detection_proximity_threshold=50, plot=False)

Get initial parameters for the curve fitting.

Parameters:

• curve (np.ndarray) – 1D numpy array

• n_amplitude (int) – Degree of the polynomial for the amplitude

• n_frequency (int) – Degree of the polynomial for the frequency

• n_offset (int) – Degree of the polynomial for the offset

• plot (bool) – If True, plot the initial parameters

Returns:

Initial amplitude, frequency, offset, and phase

Return type:

Tuple[np.ndarray, np.ndarray, np.ndarray, float]

classmethod get_init_params_spline(curve, scaled_wavelengths, n_amplitude=2, n_frequency=1, init_peak_detection_proximity_threshold=50, plot=False)

Get initial parameters for curve fitting using spline-based amplitude and frequency.

Parameters:

• curve – 1D numpy array of spectral values

• scaled_wavelengths – Corresponding wavelength values

• n_amplitude – Number of knots for amplitude spline

• n_frequency – Number of knots for frequency spline

• init_peak_detection_proximity_threshold – Minimum distance between extrema (in indices)

• plot – Whether to show diagnostic plots

Returns:

Tuple containing (amplitude_spline, frequency_spline, phase_offset)

classmethod get_linear_freq_coeffs_from_extrema(extrema, scaled_wavelengths)

Get the linear frequency coefficients from the extrema.

Parameters:

• extrema (np.ndarray) – Extrema

• scaled_wavelengths (np.ndarray) – Scaled wavelengths

Returns:

Linear frequency coefficients

Return type:

np.ndarray

static lighter_smooth_curve(curve)

Smooth a curve using Savitzky-Golay filter.

Parameters:

curve (np.ndarray) – 1D numpy array

Returns:

Smoothed curve

Return type:

np.ndarray

static smooth_curve(curve)

Smooth a curve using Savitzky-Golay filter.

Parameters:

curve (np.ndarray) – 1D numpy array

Returns:

Smoothed curve

Return type:

np.ndarray

raccoon.util.polyfit(x, y, deg, w=None)

Fit a polynomial to the data. The signature is the same as numpy.polyfit.

Parameters:

• x (np.ndarray) – x values

• y (np.ndarray) – y values

• deg (int) – Degree of the polynomial

Returns:

Coefficients of the polynomial

Return type:

np.ndarray

raccoon.util.polyval(coeffs, x)

Evaluate a polynomial at a point. The signature is the same as numpy.polyval.

Parameters:

• coeffs (np.ndarray) – Coefficients of the polynomial

• x (float) – Point to evaluate the polynomial

Returns:

Value of the polynomial at x

Return type:

float

raccoon.wiggle_cleaner module

class raccoon.wiggle_cleaner.WiggleCleaner(wavelengths, datacube, noise_cube, gaps=None, symmetric_sharpening=False, asymmetric_sharpening=False, continuum_diff_polynomial_order=2)

Bases: object

WiggleCleaner class for cleaning modulation/wiggles in spectral data.

BLUE = '#377eb8'

GREEN = '#4daf4a'

GREY = '#999999'

ORANGE = '#ff7f00'

PURPLE = '#984ea3'

RED = '#e41a1c'

property asymmetric_sharpening

Get the asymmetric sharpening flag.

Returns:

Asymmetric sharpening flag

Return type:

bool

clean_cube(wiggle_detection_sigma_threshold=3, wiggle_detection_variance_ratio_threshold=0.8, n_amplitude=10, n_frequency=1, min_n_amplitude=None, min_n_frequency=None, n_amplitude_for_detection=None, n_frequency_for_detection=None, specified_noise_level=0, cleaning_mask=None, init_peak_detection_proximity_threshold=200, aperture_radius=4, annulus_outer_radius=0, annulus_inner_radius=0, conserve_flux=True, outlier_rejection_method='fdr', fdr_alpha=0.01, fdr_outlier_max_fraction=0.1, use_huber_loss=False, huber_delta=1.35, sigma_clip_sigma=5, sigma_clip_max_iterations=5, extract_uncertainty=True, symmetric_sharpening=False, asymmetric_sharpening=False, selection_criteria='bic', min_selection_difference=None, num_samples_uncertainty_region=1000, verbose=True, plot=True, fit_full_model=True)

Clean the datacube.

Parameters:

• sigma_threshold (float) – Sigma threshold

• n_amplitude (int) – Number of amplitude parameters

• n_frequency (int) – Number of frequency parameters

• min_n_amplitude (int) – Minimum number of amplitude parameters

• min_n_frequency (int) – Minimum number of frequency parameters

• specified_noise_level (float) – Artificial noise level in fraction of the spectrum

• init_peak_detection_proximity_threshold (float) – Proximity lower limit in Angstrom for initial identifaction of peaks and troughs

• aperture_size (int) – Aperture size. Spaxels at the edges with width less than this value will not be cleaned.

• min_x (int) – Minimum spaxel x to set lower limit for the cleaning process

• max_x (int) – Maximum spaxel x to set upper limit for the cleaning process

• min_y (int) – Minimum spaxel y to set lower limit for the cleaning process

• max_y (int) – Maximum spaxel y to set upper limit for the cleaning process

• conserve_flux (bool) – If True, conserve flux in each spaxel

• cleaning_mask (np.ndarray) – Mask for cleaning, if None, clean all spaxels

• outlier_rejection_method (str) – Outlier rejection method, “fdr” or “sigma_clip”, set None to disable

• use_huber_loss (bool) – If True, use Huber loss function

• huber_delta (float) – Delta for Huber loss function

• fdr_alpha (float) – False discovery rate (FDR) correction threshold, smaller value will reject less outliers

• fdr_outlier_max_fraction (float) – Maximum fraction of outliers to reject using FDR

• sigma_clip_sigma (float) – Sigma threshold for sigma clipping

• sigma_clip_max_iterations (int) – Number of sigma clip iterations

• extract_uncertainty (bool) – If True, extract the uncertainties

• symmetric_sharpening (bool) – If True, use symmetric sharpening

• asymmetric_sharpening (bool) – If True, use asymmetric sharpening

• selection_criteria (str) – Selection criteria for model selection, “bic” or “chi2”

• min_selection_difference (float) – Minimum difference between the best and the next best model selection criteria

• verbose (bool) – If True, print the results

• plot (bool) – If True, plot the results

Returns:

Cleaned datacube

Return type:

np.ndarray

Returns:

Cleaned datacube

Return type:

np.ndarray

configure_noise(wiggle_signal, wiggle_noise, specified_noise_level)

Configure the noise.

Parameters:

• wiggle_signal (np.ndarray) – wiggle_signal

• wiggle_noise (np.ndarray) – wiggle noise

• specified_noise_level (float) – User-defined noise level to be used instead of the actual noise. Set to 0 to disable.

Returns:

modified wiggle noise

Return type:

np.ndarray

configure_polynomial_ns(n_amplitude=None, n_frequency=None)

Configure the number of parameters.

Parameters:

• n_amplitude (int) – Number of amplitude parameters

• n_frequency (int) – Number of frequency parameters

Returns:

Number of amplitude and frequency parameters

Return type:

Tuple

cost_function(params, wiggle_signal, wiggle_noise)

Compute the cost function (sum of squared residuals).

Parameters:

• params (np.ndarray) – Parameters

• wiggle_signal (np.ndarray) – wiggle data

• wiggle_noise (np.ndarray) – wiggle_noise

Returns:

cost

Return type:

float

fit_wiggle(x, y, aperture_radius=4, annulus_outer_radius=5, annulus_inner_radius=3, n_amplitude=None, n_frequency=None, specified_noise_level=0, init_peak_detection_proximity_threshold=200, do_interim_fit_phase_only=False, extract_covariance=True, outlier_rejection_method=None, fdr_alpha=0.01, fdr_outlier_max_fraction=0.1, use_huber_loss=False, huber_delta=1.35, sigma_clip_sigma=5, sigma_clip_max_iterations=5, symmetric_sharpening=False, asymmetric_sharpening=False, plot=True, verbose=True, fit_full_model=True, save_figure_dir=None)

Fit the wiggle data.

Parameters:

• wiggle_signal (np.ndarray) – Wiggle data

• wiggle_noise (np.ndarray) – wiggle noise

• n_amplitude (int) – Number of amplitude parameters

• n_frequency (int) – Number of frequency parameters

• specified_noise_level (float) – User-defined noise level to be used instead of the actual noise. Set to 0 to disable.

• init_peak_detection_proximity_threshold (float) – Proximity lower limit in Angstrom for initial identifaction of peaks and troughs

• plot (bool) – If True, plot the results

• verbose (bool) – If True, print the results

• do_interim_fit_phase_only (bool) – If True, do an interim fit with phase only

• outlier_rejection_method (str) – Outlier rejection method, “fdr” or “sigma_clip”, set None to disable

• fdr_alpha (float) – False discovery rate (FDR) correction threshold, smaller value will reject less outliers

• fdr_outlier_max_fraction (float) – Maximum fraction of outliers to reject using FDR

• use_huber_loss (bool) – If True, use Huber loss function for outlier rejection with FDR

• huber_delta (float) – Delta for Huber loss function

• sigma_clip_sigma (float) – Sigma threshold for sigma clipping

• sigma_clip_max_iterations (int) – Number of sigma clip iterations

• extract_uncertainty (bool) – If True, extract the uncertainties

Returns:

Fitted parameters

Return type:

np.ndarray

fit_wiggle_with_model_selection(x, y, aperture_radius=4, annulus_outer_radius=0, annulus_inner_radius=0, n_amplitude=10, n_frequency=1, min_n_amplitude=None, min_n_frequency=None, specified_noise_level=0, init_peak_detection_proximity_threshold=200, plot=False, selection_criteria='bic', min_selection_difference=None, extract_covariance=True, outlier_rejection_method=None, fdr_alpha=0.01, fdr_outlier_max_fraction=0.1, use_huber_loss=False, huber_delta=1.35, sigma_clip_sigma=5, sigma_clip_max_iterations=3, symmetric_sharpening=False, asymmetric_sharpening=False, fit_full_model=False)

Fit the wiggle signal with selecting amplitude polynomial order based on BIC.

Parameters:

• x (int) – x coordinate

• y (int) – y coordinate

• aperture_radius (int) – Aperture radius

• annulus_outer_radius (int) – Annulus outer radius

• annulus_inner_radius (int) – Annulus inner radius

• n_amplitude (int) – Maximum number of amplitude parameters

• n_frequency (int) – Number of frequency parameters

• min_n_amplitude (int) – Minimum number of amplitude parameters

• min_n_frequency (int) – Minimum number of frequency parameters

• specified_noise_level (float) – Artificial noise level

• init_peak_detection_proximity_threshold (float) – Proximity lower limit in Angstrom for initial identifaction of peaks and troughs

• plot (bool) – If True, plot the results

• selection_criteria (str) – Selection criteria, “bic” or “chi2”

• sigma_clip_sigma (float) – Sigma clip threshold

• sigma_clip_max_iterations (int) – Number of sigma clip iterations

• combine_bic_weighted (bool) – If True, combine the BIC weighted by the number of parameters

• extract_uncertainty (bool) – If True, extract the uncertainties

• outlier_rejection_method (str) – Outlier rejection method, “fdr” or “sigma_clip”, set None to disable

• huber_delta (float) – Delta for Huber loss function

• fdr_alpha (float) – False discovery rate (FDR) correction threshold, smaller value will reject less outliers

• fdr_outlier_max_fraction (float) – Maximum fraction of outliers to reject using FDR

• sigma_clip_sigma – Sigma threshold for sigma clipping

• sigma_clip_max_iterations – Number of sigma clip iterations

• extract_uncertainty – If True, extract the uncertainties

• symmetric_sharpening (bool) – If True, use symmetric sharpening

• asymmetric_sharpening (bool) – If True, use asymmetric sharpening

• selection_criteria – Selection criteria for model selection, “bic” or “chi2”

• min_selection_difference (float) – Minimum difference between the best and the next best model selection criteria

• verbose (bool) – If True, print the results

• plot – If True, plot the results

Returns:

Fitted parameters

Return type:

np.ndarray

get_a1_a2(params)

Get the a_1 and a_2 parameters for asymmetric and symmetric sharpening from the params array.

Parameters:

params (np.ndarray) – Parameters

Returns:

a_1 and a_2 parameters

Return type:

Tuple[float, float]

get_design_matrix(aperture_spectra, annulus_spectra, annulus_outer_radius, a, wavelengths)

Get the design matrix for the full model fit.

Parameters:

• a (float) – Non-linear parameter, the exponent for the wavelength term in power- law component of the continuum

• annulus_outer_radius (float) – Outer radius of the annulus

• aperture_spectra (np.ndarray) – Aperture spectra

• annulus_spectra (np.ndarray) – Annulus spectra

• wavelengths (np.ndarray) – Wavelengths

Returns:

Design matrix

Return type:

np.ndarray

get_exponent_param(params)

Get the exponent parameter for the wavelength term in the power-law component of the continuum.

Parameters:

params (np.ndarray) – Parameters

Returns:

Exponent parameter

Return type:

float

get_model_selection_metric(wiggle_signal, wiggle_noise, result_params, selection_criteria='bic')

Get the fit metric: BIC or chi^2.

Parameters:

• wiggle_signal (np.ndarray) – wiggle_signal

• wiggle_noise (np.ndarray) – wiggle noise

• result_params (np.ndarray) – Fitted parameters

• selection_criteria (str) – Selection criteria, “bic” or “chi2”

Returns:

Fit metric

Return type:

float

get_model_uncertainty(result_params, cov_matrix, num_samples_uncertainty_region=1000)

Get the model uncertainty.

Parameters:

• result_params (np.ndarray) – Fitted parameters

• cov_matrix (np.ndarray) – Covariance matrix

• num_samples_uncertainty_region (int) – Number of samples for uncertainty region

Returns:

Model uncertainty at each wavelength

Return type:

np.ndarray

get_residual_func(wiggle_signal, wiggle_noise)

Get the residual function.

Parameters:

• wiggle_signal (np.ndarray) – wiggle data

• wiggle_noise (np.ndarray) – wiggle noise

Returns:

Residual function

Return type:

Callable

get_residual_func_phase_only(init_params, wiggle_signal, wiggle_noise)

Get the residual function with phase only.

Parameters:

• params (np.ndarray) – Parameters

• init_params (np.ndarray) – Initial parameters

• wiggle_signal (np.ndarray) – wiggle_signal

• wiggle_noise (np.ndarray) – wiggle noise

Returns:

Residual function

Return type:

Callable

get_spectra_set(x, y, aperture_radius, annulus_outer_radius, annulus_inner_radius)

Get the spectra set.

Parameters:

• x (int) – x coordinate

• y (int) – y coordinate

• aperture_radius (int) – Aperture radius

• annulus_outer_radius (int) – annulus outer radius

• annulus_inner_radius (int) – annulus inner radius

Returns:

spectra, noise, aperture_spectra, aperture_noise, annulus_spectra, annulus_noise

Return type:

Tuple of np.ndarray

get_wiggle_signal(x, y, aperture_radius=4, annulus_outer_radius=0, annulus_inner_radius=0, plot=False)

Get the wiggle signal for preliminary assessments.

Parameters:

• spaxel_x (int) – Spaxel x

• spaxel_y (int) – Spaxel y

• aperture (int) – aperture size to sum the spectra to average out the wiggles

Returns:

Modulation wiggle_signal and noise

Return type:

Tuple of np.ndarray

is_wiggle_detected(wiggle_signal, wiggle_noise, result_params, sigma_threshold=5, variance_ratio_threshold=0.8, verbose=True)

Check if wiggle is detected.

Parameters:

• wiggle_signal (np.ndarray) – wiggle_signal

• wiggle_noise (np.ndarray) – wiggle_noise

• sigma_threshold (float) – Sigma threshold

• variance_ratio_threshold (float) – Variance ratio threshold, set 0 to disable

• verbose (bool) – If True, print the results

Returns:

True if wiggle is detected

Return type:

bool

model_full_fit(params, x, y, aperture_radius, annulus_outer_radius=0, annulus_inner_radius=0)

Compute the full model fit.

Parameters:

• params (np.ndarray) – Parameters

• x (np.ndarray) – x coordinates

• y (np.ndarray) – y coordinates

• aperture_radius (float) – Aperture radius

• annulus_outer_radius (float) – Outer radius of the annulus

• annulus_inner_radius (float) – Inner radius of the annulus

Returns:

Full model, spectra, and total noise

Return type:

Tuple[np.ndarray, np.ndarray, np.ndarray]

plot_full_fit_model(bestfit_model, model_uncertainty, spectra, noise, wiggle_model=None, save_figure_info={'dir': None, 'x': None, 'y': None})

Plot the full fit model.

Parameters:

• bestfit_model (np.ndarray) – Best-fit model

• model_uncertainty (np.ndarray) – Model uncertainty

• spectra (np.ndarray) – Spectra

• noise (np.ndarray) – Noise

Returns:

None

Return type:

None

plot_wiggle_model(wiggle_signal, wiggle_noise, result_params, cov_matrix=None, num_samples_uncertainty_region=1000, save_figure_info={'dir': None, 'x': None, 'y': None})

Plot the model.

Parameters:

• wiggle_signal (np.ndarray) – wiggle_signal

• wiggle_noise (np.ndarray) – wiggle noise

• result_params (np.ndarray) – Fitted parameters

• cov_matrix (np.ndarray) – Covariance matrix

• num_samples_uncertainty_region (int) – Number of samples for uncertainty region

Returns:

None

Return type:

None

reject_outliers(residual, num_params=0, fdr_alpha=0.01, fdr_outlier_max_fraction=0.1, sigma_clip_sigma=5, sigma_clip_max_iterations=5)

Reject outliers using the selected method.

Parameters:

• residual (np.ndarray) – Residuals

• num_params (int) – Number of parameters

• fdr_q (float) – FDR correction threshold

• fdr_outlier_max_fraction (float) – Maximum fraction of outliers to reject

• huber_delta (float) – Delta for Huber loss function

• sigma (float) – Sigma threshold for sigma clipping

• sigma_clip_max_iterations (int) – Maximum number of iterations for sigma clipping

Returns:

Indices of outliers

Return type:

np.ndarray

residual_vector(params, wiggle_signal, wiggle_noise)

Get the residual vector.

Parameters:

• params (np.ndarray) – Parameters

• wiggle_signal (np.ndarray) – wiggle_signal

• wiggle_noise (np.ndarray) – wiggle_noise

Returns:

Residual vector

Return type:

np.ndarray

residual_vector_full_fit(params, x, y, aperture_radius, annulus_outer_radius=0, annulus_inner_radius=0)

Compute the residual vector for the full model fit.

Parameters:

• params (np.ndarray) – Parameters

• x (np.ndarray) – x coordinates

• y (np.ndarray) – t coordinates

• aperture_radius (float) – Aperture radius

• annulus_outer_radius (float) – Outer radius of the annulus

• annulus_inner_radius (float) – Inner radius of the annulus

Returns:

Residual vector

Return type:

np.ndarray

scale_wavelengths_negative1_to_1(w)

Scale the wavelengths to -1 to 1.

Parameters:

w (np.ndarray) – Wavelengths

Returns:

Scaled wavelengths

Return type:

np.ndarray

scale_wavelengths_to_0_1(w)

Scale the wavelengths to 0 to 1.

Parameters:

w (np.ndarray) – Wavelengths

Returns:

Scaled wavelengths

Return type:

np.ndarray

property scaled_w

Scaled wavelengths.

Returns:

Scaled wavelengths

Return type:

np.ndarray

set_gaps(gaps)

Set the gaps to be ignored during the fitting process.

Parameters:

gaps (list of tuples) – List of wavelength ranges to be ignored

Returns:

None

Return type:

None

set_params(amplitude_params, frequency_params, phi_0, n_amplitude=None, n_frequency=None)

Set the parameters. Opposite function of the split_params function.

Parameters:

• amplitude_params (np.ndarray) – Amplitude parameters

• frequency_params (np.ndarray) – Frequency parameters

• phi_0 (float) – Phase

• n_amplitude (int) – Number of amplitude parameters

• n_frequency (int) – Number of frequency parameters

Returns:

Parameters

Return type:

np.ndarray

static solve_ridge_regression(A, spectra)

Solve the ridge regression problem.

Parameters:

• A (np.ndarray) – Design matrix

• spectra (np.ndarray) – Target spectra

Returns:

Coefficients

Return type:

np.ndarray

split_params(params, n_amplitude=None, n_frequency=None)

Split the parameters. Opposite of the set_params function.

Parameters:

• params (np.ndarray) – Parameters

• n_amplitude (int) – Number of amplitude parameters

• n_frequency (int) – Number of frequency parameters

Returns:

amplitude parameters, frequency parameters, and phi_0

Return type:

Tuple

property symmetric_sharpening

Get the symmetric sharpening flag.

Returns:

Symmetric sharpening flag

Return type:

bool

wiggle_func(xs, amplitude_params, frequency_params, phi, a_1=0, a_2=0)

Get the wiggle function.

Parameters:

• xs (np.ndarray) – Scaled wavelengths

• frequency_params (np.ndarray) – Frequency parameters

• amplitude_params (np.ndarray) – Amplitude parameters

• phi (float) – Phase

Returns:

Wiggle function

Return type:

np.ndarray

wiggle_model(params)

Get the wiggle model given the parameters.

Parameters:

params (np.ndarray) – Parameters

Returns:

Model

Return type:

np.ndarray

Module contents

Top-level package for raccoon.

class raccoon.WiggleCleaner(wavelengths, datacube, noise_cube, gaps=None, symmetric_sharpening=False, asymmetric_sharpening=False, continuum_diff_polynomial_order=2)

Bases: object

WiggleCleaner class for cleaning modulation/wiggles in spectral data.

BLUE = '#377eb8'

GREEN = '#4daf4a'

GREY = '#999999'

ORANGE = '#ff7f00'

PURPLE = '#984ea3'

RED = '#e41a1c'

property asymmetric_sharpening

Get the asymmetric sharpening flag.

Returns:

Asymmetric sharpening flag

Return type:

bool

clean_cube(wiggle_detection_sigma_threshold=3, wiggle_detection_variance_ratio_threshold=0.8, n_amplitude=10, n_frequency=1, min_n_amplitude=None, min_n_frequency=None, n_amplitude_for_detection=None, n_frequency_for_detection=None, specified_noise_level=0, cleaning_mask=None, init_peak_detection_proximity_threshold=200, aperture_radius=4, annulus_outer_radius=0, annulus_inner_radius=0, conserve_flux=True, outlier_rejection_method='fdr', fdr_alpha=0.01, fdr_outlier_max_fraction=0.1, use_huber_loss=False, huber_delta=1.35, sigma_clip_sigma=5, sigma_clip_max_iterations=5, extract_uncertainty=True, symmetric_sharpening=False, asymmetric_sharpening=False, selection_criteria='bic', min_selection_difference=None, num_samples_uncertainty_region=1000, verbose=True, plot=True, fit_full_model=True)

Clean the datacube.

Parameters:

• sigma_threshold (float) – Sigma threshold

• n_amplitude (int) – Number of amplitude parameters

• n_frequency (int) – Number of frequency parameters

• min_n_amplitude (int) – Minimum number of amplitude parameters

• min_n_frequency (int) – Minimum number of frequency parameters

• specified_noise_level (float) – Artificial noise level in fraction of the spectrum

• init_peak_detection_proximity_threshold (float) – Proximity lower limit in Angstrom for initial identifaction of peaks and troughs

• aperture_size (int) – Aperture size. Spaxels at the edges with width less than this value will not be cleaned.

• min_x (int) – Minimum spaxel x to set lower limit for the cleaning process

• max_x (int) – Maximum spaxel x to set upper limit for the cleaning process

• min_y (int) – Minimum spaxel y to set lower limit for the cleaning process

• max_y (int) – Maximum spaxel y to set upper limit for the cleaning process

• conserve_flux (bool) – If True, conserve flux in each spaxel

• cleaning_mask (np.ndarray) – Mask for cleaning, if None, clean all spaxels

• outlier_rejection_method (str) – Outlier rejection method, “fdr” or “sigma_clip”, set None to disable

• use_huber_loss (bool) – If True, use Huber loss function

• huber_delta (float) – Delta for Huber loss function

• fdr_alpha (float) – False discovery rate (FDR) correction threshold, smaller value will reject less outliers

• fdr_outlier_max_fraction (float) – Maximum fraction of outliers to reject using FDR

• sigma_clip_sigma (float) – Sigma threshold for sigma clipping

• sigma_clip_max_iterations (int) – Number of sigma clip iterations

• extract_uncertainty (bool) – If True, extract the uncertainties

• symmetric_sharpening (bool) – If True, use symmetric sharpening

• asymmetric_sharpening (bool) – If True, use asymmetric sharpening

• selection_criteria (str) – Selection criteria for model selection, “bic” or “chi2”

• min_selection_difference (float) – Minimum difference between the best and the next best model selection criteria

• verbose (bool) – If True, print the results

• plot (bool) – If True, plot the results

Returns:

Cleaned datacube

Return type:

np.ndarray

Returns:

Cleaned datacube

Return type:

np.ndarray

configure_noise(wiggle_signal, wiggle_noise, specified_noise_level)

Configure the noise.

Parameters:

• wiggle_signal (np.ndarray) – wiggle_signal

• wiggle_noise (np.ndarray) – wiggle noise

• specified_noise_level (float) – User-defined noise level to be used instead of the actual noise. Set to 0 to disable.

Returns:

modified wiggle noise

Return type:

np.ndarray

configure_polynomial_ns(n_amplitude=None, n_frequency=None)

Configure the number of parameters.

Parameters:

• n_amplitude (int) – Number of amplitude parameters

• n_frequency (int) – Number of frequency parameters

Returns:

Number of amplitude and frequency parameters

Return type:

Tuple

cost_function(params, wiggle_signal, wiggle_noise)

Compute the cost function (sum of squared residuals).

Parameters:

• params (np.ndarray) – Parameters

• wiggle_signal (np.ndarray) – wiggle data

• wiggle_noise (np.ndarray) – wiggle_noise

Returns:

cost

Return type:

float

fit_wiggle(x, y, aperture_radius=4, annulus_outer_radius=5, annulus_inner_radius=3, n_amplitude=None, n_frequency=None, specified_noise_level=0, init_peak_detection_proximity_threshold=200, do_interim_fit_phase_only=False, extract_covariance=True, outlier_rejection_method=None, fdr_alpha=0.01, fdr_outlier_max_fraction=0.1, use_huber_loss=False, huber_delta=1.35, sigma_clip_sigma=5, sigma_clip_max_iterations=5, symmetric_sharpening=False, asymmetric_sharpening=False, plot=True, verbose=True, fit_full_model=True, save_figure_dir=None)

Fit the wiggle data.

Parameters:

• wiggle_signal (np.ndarray) – Wiggle data

• wiggle_noise (np.ndarray) – wiggle noise

• n_amplitude (int) – Number of amplitude parameters

• n_frequency (int) – Number of frequency parameters

• specified_noise_level (float) – User-defined noise level to be used instead of the actual noise. Set to 0 to disable.

• init_peak_detection_proximity_threshold (float) – Proximity lower limit in Angstrom for initial identifaction of peaks and troughs

• plot (bool) – If True, plot the results

• verbose (bool) – If True, print the results

• do_interim_fit_phase_only (bool) – If True, do an interim fit with phase only

• outlier_rejection_method (str) – Outlier rejection method, “fdr” or “sigma_clip”, set None to disable

• fdr_alpha (float) – False discovery rate (FDR) correction threshold, smaller value will reject less outliers

• fdr_outlier_max_fraction (float) – Maximum fraction of outliers to reject using FDR

• use_huber_loss (bool) – If True, use Huber loss function for outlier rejection with FDR

• huber_delta (float) – Delta for Huber loss function

• sigma_clip_sigma (float) – Sigma threshold for sigma clipping

• sigma_clip_max_iterations (int) – Number of sigma clip iterations

• extract_uncertainty (bool) – If True, extract the uncertainties

Returns:

Fitted parameters

Return type:

np.ndarray

fit_wiggle_with_model_selection(x, y, aperture_radius=4, annulus_outer_radius=0, annulus_inner_radius=0, n_amplitude=10, n_frequency=1, min_n_amplitude=None, min_n_frequency=None, specified_noise_level=0, init_peak_detection_proximity_threshold=200, plot=False, selection_criteria='bic', min_selection_difference=None, extract_covariance=True, outlier_rejection_method=None, fdr_alpha=0.01, fdr_outlier_max_fraction=0.1, use_huber_loss=False, huber_delta=1.35, sigma_clip_sigma=5, sigma_clip_max_iterations=3, symmetric_sharpening=False, asymmetric_sharpening=False, fit_full_model=False)

Fit the wiggle signal with selecting amplitude polynomial order based on BIC.

Parameters:

• x (int) – x coordinate

• y (int) – y coordinate

• aperture_radius (int) – Aperture radius

• annulus_outer_radius (int) – Annulus outer radius

• annulus_inner_radius (int) – Annulus inner radius

• n_amplitude (int) – Maximum number of amplitude parameters

• n_frequency (int) – Number of frequency parameters

• min_n_amplitude (int) – Minimum number of amplitude parameters

• min_n_frequency (int) – Minimum number of frequency parameters

• specified_noise_level (float) – Artificial noise level

• init_peak_detection_proximity_threshold (float) – Proximity lower limit in Angstrom for initial identifaction of peaks and troughs

• plot (bool) – If True, plot the results

• selection_criteria (str) – Selection criteria, “bic” or “chi2”

• sigma_clip_sigma (float) – Sigma clip threshold

• sigma_clip_max_iterations (int) – Number of sigma clip iterations

• combine_bic_weighted (bool) – If True, combine the BIC weighted by the number of parameters

• extract_uncertainty (bool) – If True, extract the uncertainties

• outlier_rejection_method (str) – Outlier rejection method, “fdr” or “sigma_clip”, set None to disable

• huber_delta (float) – Delta for Huber loss function

• fdr_alpha (float) – False discovery rate (FDR) correction threshold, smaller value will reject less outliers

• fdr_outlier_max_fraction (float) – Maximum fraction of outliers to reject using FDR

• sigma_clip_sigma – Sigma threshold for sigma clipping

• sigma_clip_max_iterations – Number of sigma clip iterations

• extract_uncertainty – If True, extract the uncertainties

• symmetric_sharpening (bool) – If True, use symmetric sharpening

• asymmetric_sharpening (bool) – If True, use asymmetric sharpening

• selection_criteria – Selection criteria for model selection, “bic” or “chi2”

• min_selection_difference (float) – Minimum difference between the best and the next best model selection criteria

• verbose (bool) – If True, print the results

• plot – If True, plot the results

Returns:

Fitted parameters

Return type:

np.ndarray

get_a1_a2(params)

Get the a_1 and a_2 parameters for asymmetric and symmetric sharpening from the params array.

Parameters:

params (np.ndarray) – Parameters

Returns:

a_1 and a_2 parameters

Return type:

Tuple[float, float]

get_design_matrix(aperture_spectra, annulus_spectra, annulus_outer_radius, a, wavelengths)

Get the design matrix for the full model fit.

Parameters:

• a (float) – Non-linear parameter, the exponent for the wavelength term in power- law component of the continuum

• annulus_outer_radius (float) – Outer radius of the annulus

• aperture_spectra (np.ndarray) – Aperture spectra

• annulus_spectra (np.ndarray) – Annulus spectra

• wavelengths (np.ndarray) – Wavelengths

Returns:

Design matrix

Return type:

np.ndarray

get_exponent_param(params)

Get the exponent parameter for the wavelength term in the power-law component of the continuum.

Parameters:

params (np.ndarray) – Parameters

Returns:

Exponent parameter

Return type:

float

get_model_selection_metric(wiggle_signal, wiggle_noise, result_params, selection_criteria='bic')

Get the fit metric: BIC or chi^2.

Parameters:

• wiggle_signal (np.ndarray) – wiggle_signal

• wiggle_noise (np.ndarray) – wiggle noise

• result_params (np.ndarray) – Fitted parameters

• selection_criteria (str) – Selection criteria, “bic” or “chi2”

Returns:

Fit metric

Return type:

float

get_model_uncertainty(result_params, cov_matrix, num_samples_uncertainty_region=1000)

Get the model uncertainty.

Parameters:

• result_params (np.ndarray) – Fitted parameters

• cov_matrix (np.ndarray) – Covariance matrix

• num_samples_uncertainty_region (int) – Number of samples for uncertainty region

Returns:

Model uncertainty at each wavelength

Return type:

np.ndarray

get_residual_func(wiggle_signal, wiggle_noise)

Get the residual function.

Parameters:

• wiggle_signal (np.ndarray) – wiggle data

• wiggle_noise (np.ndarray) – wiggle noise

Returns:

Residual function

Return type:

Callable

get_residual_func_phase_only(init_params, wiggle_signal, wiggle_noise)

Get the residual function with phase only.

Parameters:

• params (np.ndarray) – Parameters

• init_params (np.ndarray) – Initial parameters

• wiggle_signal (np.ndarray) – wiggle_signal

• wiggle_noise (np.ndarray) – wiggle noise

Returns:

Residual function

Return type:

Callable

get_spectra_set(x, y, aperture_radius, annulus_outer_radius, annulus_inner_radius)

Get the spectra set.

Parameters:

• x (int) – x coordinate

• y (int) – y coordinate

• aperture_radius (int) – Aperture radius

• annulus_outer_radius (int) – annulus outer radius

• annulus_inner_radius (int) – annulus inner radius

Returns:

spectra, noise, aperture_spectra, aperture_noise, annulus_spectra, annulus_noise

Return type:

Tuple of np.ndarray

get_wiggle_signal(x, y, aperture_radius=4, annulus_outer_radius=0, annulus_inner_radius=0, plot=False)

Get the wiggle signal for preliminary assessments.

Parameters:

• spaxel_x (int) – Spaxel x

• spaxel_y (int) – Spaxel y

• aperture (int) – aperture size to sum the spectra to average out the wiggles

Returns:

Modulation wiggle_signal and noise

Return type:

Tuple of np.ndarray

is_wiggle_detected(wiggle_signal, wiggle_noise, result_params, sigma_threshold=5, variance_ratio_threshold=0.8, verbose=True)

Check if wiggle is detected.

Parameters:

• wiggle_signal (np.ndarray) – wiggle_signal

• wiggle_noise (np.ndarray) – wiggle_noise

• sigma_threshold (float) – Sigma threshold

• variance_ratio_threshold (float) – Variance ratio threshold, set 0 to disable

• verbose (bool) – If True, print the results

Returns:

True if wiggle is detected

Return type:

bool

model_full_fit(params, x, y, aperture_radius, annulus_outer_radius=0, annulus_inner_radius=0)

Compute the full model fit.

Parameters:

• params (np.ndarray) – Parameters

• x (np.ndarray) – x coordinates

• y (np.ndarray) – y coordinates

• aperture_radius (float) – Aperture radius

• annulus_outer_radius (float) – Outer radius of the annulus

• annulus_inner_radius (float) – Inner radius of the annulus

Returns:

Full model, spectra, and total noise

Return type:

Tuple[np.ndarray, np.ndarray, np.ndarray]

plot_full_fit_model(bestfit_model, model_uncertainty, spectra, noise, wiggle_model=None, save_figure_info={'dir': None, 'x': None, 'y': None})

Plot the full fit model.

Parameters:

• bestfit_model (np.ndarray) – Best-fit model

• model_uncertainty (np.ndarray) – Model uncertainty

• spectra (np.ndarray) – Spectra

• noise (np.ndarray) – Noise

Returns:

None

Return type:

None

plot_wiggle_model(wiggle_signal, wiggle_noise, result_params, cov_matrix=None, num_samples_uncertainty_region=1000, save_figure_info={'dir': None, 'x': None, 'y': None})

Plot the model.

Parameters:

• wiggle_signal (np.ndarray) – wiggle_signal

• wiggle_noise (np.ndarray) – wiggle noise

• result_params (np.ndarray) – Fitted parameters

• cov_matrix (np.ndarray) – Covariance matrix

• num_samples_uncertainty_region (int) – Number of samples for uncertainty region

Returns:

None

Return type:

None

reject_outliers(residual, num_params=0, fdr_alpha=0.01, fdr_outlier_max_fraction=0.1, sigma_clip_sigma=5, sigma_clip_max_iterations=5)

Reject outliers using the selected method.

Parameters:

• residual (np.ndarray) – Residuals

• num_params (int) – Number of parameters

• fdr_q (float) – FDR correction threshold

• fdr_outlier_max_fraction (float) – Maximum fraction of outliers to reject

• huber_delta (float) – Delta for Huber loss function

• sigma (float) – Sigma threshold for sigma clipping

• sigma_clip_max_iterations (int) – Maximum number of iterations for sigma clipping

Returns:

Indices of outliers

Return type:

np.ndarray

residual_vector(params, wiggle_signal, wiggle_noise)

Get the residual vector.

Parameters:

• params (np.ndarray) – Parameters

• wiggle_signal (np.ndarray) – wiggle_signal

• wiggle_noise (np.ndarray) – wiggle_noise

Returns:

Residual vector

Return type:

np.ndarray

residual_vector_full_fit(params, x, y, aperture_radius, annulus_outer_radius=0, annulus_inner_radius=0)

Compute the residual vector for the full model fit.

Parameters:

• params (np.ndarray) – Parameters

• x (np.ndarray) – x coordinates

• y (np.ndarray) – t coordinates

• aperture_radius (float) – Aperture radius

• annulus_outer_radius (float) – Outer radius of the annulus

• annulus_inner_radius (float) – Inner radius of the annulus

Returns:

Residual vector

Return type:

np.ndarray

scale_wavelengths_negative1_to_1(w)

Scale the wavelengths to -1 to 1.

Parameters:

w (np.ndarray) – Wavelengths

Returns:

Scaled wavelengths

Return type:

np.ndarray

scale_wavelengths_to_0_1(w)

Scale the wavelengths to 0 to 1.

Parameters:

w (np.ndarray) – Wavelengths

Returns:

Scaled wavelengths

Return type:

np.ndarray

property scaled_w

Scaled wavelengths.

Returns:

Scaled wavelengths

Return type:

np.ndarray

set_gaps(gaps)

Set the gaps to be ignored during the fitting process.

Parameters:

gaps (list of tuples) – List of wavelength ranges to be ignored

Returns:

None

Return type:

None

set_params(amplitude_params, frequency_params, phi_0, n_amplitude=None, n_frequency=None)

Set the parameters. Opposite function of the split_params function.

Parameters:

• amplitude_params (np.ndarray) – Amplitude parameters

• frequency_params (np.ndarray) – Frequency parameters

• phi_0 (float) – Phase

• n_amplitude (int) – Number of amplitude parameters

• n_frequency (int) – Number of frequency parameters

Returns:

Parameters

Return type:

np.ndarray

static solve_ridge_regression(A, spectra)

Solve the ridge regression problem.

Parameters:

• A (np.ndarray) – Design matrix

• spectra (np.ndarray) – Target spectra

Returns:

Coefficients

Return type:

np.ndarray

split_params(params, n_amplitude=None, n_frequency=None)

Split the parameters. Opposite of the set_params function.

Parameters:

• params (np.ndarray) – Parameters

• n_amplitude (int) – Number of amplitude parameters

• n_frequency (int) – Number of frequency parameters

Returns:

amplitude parameters, frequency parameters, and phi_0

Return type:

Tuple

property symmetric_sharpening

Get the symmetric sharpening flag.

Returns:

Symmetric sharpening flag

Return type:

bool

wiggle_func(xs, amplitude_params, frequency_params, phi, a_1=0, a_2=0)

Get the wiggle function.

Parameters:

• xs (np.ndarray) – Scaled wavelengths

• frequency_params (np.ndarray) – Frequency parameters

• amplitude_params (np.ndarray) – Amplitude parameters

• phi (float) – Phase

Returns:

Wiggle function

Return type:

np.ndarray

wiggle_model(params)

Get the wiggle model given the parameters.

Parameters:

params (np.ndarray) – Parameters

Returns:

Model

Return type:

np.ndarray