frostie.retrieval

Classes

solo_retrieval

nested_retrieval

Functions

load_simulated_data([snr, del_wav, f_h2o])

Generate and return a simulated noisy spectrum of a water & CO2 ice mixture,

Module Contents

frostie.retrieval.load_simulated_data(snr=50, del_wav=0.01, f_h2o=0.5)

Generate and return a simulated noisy spectrum of a water & CO2 ice mixture, at a specified signal-to-noise ratio (SNR) and spectral resolution.

Parameters:

  • snr (float) – Desired signal-to-noise ratio of the simulated data.

  • del_wav (float) – Spectral resolution (wavelength bin size in microns) to which the model spectrum will be downsampled.

Returns:

data_all – Dictionary containing: - ‘wavelengths’ : ndarray

Binned wavelength array (microns)

  • ’reflectance’ndarray

    Simulated reflectance data with Gaussian noise

  • ’uncertainty’ndarray

    1-sigma uncertainty array corresponding to SNR

  • ’model_true’ndarray

    Noiseless model reflectance values

  • ’wav_model’ndarray

    Wavelengths corresponding to model_true

Return type:

dict

class frostie.retrieval.solo_retrieval
initialized = False
initialize(fixed_params, free_params, components, data, instrument_response=None)

Initialize the retrieval setup.

Parameters:

  • fixed_params (dict) – Dictionary of fixed model parameters (i, e, g, B, s, etc.)

  • free_params (list) – List of [parameter_name, (min, max)] tuples for sampling

  • components (dict) – Dictionary of {component_name: [wav, n, k]} entries

  • data (list) – [wavelengths, reflectance, uncertainty]

  • instrument_response (ndarray or None) – Optional response function array (must match wavelength grid)

_make_model(theta)

Generate model spectrum for a given theta vector (free parameter values). Handles abundance logic, fixed + free parameter resolution, and builds the Hapke model.

_loglike(theta, norm_log)

Compute log-likelihood from model and data. Assumes model and data are already matched in wavelength.

_dirichlet_prior_transform(theta_unit, prior_bounds, n_species)
_prior_transform(theta_unit)
run(save_dir='.', nlive=512, dlogz=0.1, sample='rwalk', bound='multi', bootstrap=0, use_multicore=False, nproc=None)

Run nested sampling and save the results to disk.

Parameters:

  • save_dir (str, optional) – Directory to store output samples and results.

  • nlive (int, optional) – Number of live points for the nested sampler.

  • dlogz (float, optional) – Convergence threshold for dynesty.

  • sample (str, optional) – Sampling method for dynesty (‘rwalk’, ‘auto’, etc.).

  • bound (str, optional) – Bounding method for dynesty (‘multi’, etc.).

  • bootstrap (int, optional) – Number of bootstrap iterations for ellipsoid bounding.

  • use_multicore (bool, optional) – Whether to run dynesty in parallel.

  • nproc (int or None, optional) – Number of cores to use if multiprocessing is enabled.

plot_solutions(plot_residuals=True, plot_uncertainty=False)

Plot posterior model fit with optional residuals and uncertainty shading.

Parameters:

  • plot_residuals (bool) – If True, show residuals below the model plot.

  • plot_uncertainty (bool) – If True, shade 1σ and 2σ confidence intervals.

plot_posteriors(truths=None, n_sigma=2)

Plot posterior distributions of the retrieved parameters.

Parameters:

  • truths (list or None, optional) – True values to overlay on the posterior plots (e.g., for simulated data).

  • n_sigma (int or float, optional) – Width of the confidence interval to annotate (default is 1σ).

print_retrieval_summary(n_sigma=2)

Print median values and confidence intervals for all retrieved parameters.

Uses equal-weighted posterior resampling to compute summary statistics.

Parameters:

n_sigma (float, optional) – Width of confidence interval to display (default is 2σ).

class frostie.retrieval.nested_retrieval
results_dict
model_logZs
model_names = []
best_model_name = None
initialize(fixed_params, free_params, components, data, instrument_response=None)

Initialize a nested_retrieval object with model and data settings.

Parameters:

  • fixed_params (dict) – Dictionary of fixed model parameters (e.g., geometry, phase function type).

  • free_params (list of [str, tuple]) – List of free parameters and their bounds.

  • components (dict) – Dictionary of optical constants keyed by component name.

  • data (list of ndarray) – List containing wavelength, reflectance, and uncertainty arrays.

  • instrument_response (ndarray, optional) – Optional instrument convolution kernel (default is None).

_build_model_case(include_components)

Dynamically build model-specific free parameter list.

run_all_models(use_multicore=False, nproc=None, save_dir='nested_results', nlive=512, dlogz=0.1, sample='rwalk', bound='multi', bootstrap=0)

Run N+1 retrievals (where N is the number of components in the model) to evaluate the evidence for each model combination.

Parameters:

  • use_multicore (bool, optional) – Whether to use multiprocessing (default is False).

  • nproc (int or None, optional) – Number of processor cores to use if multiprocessing is enabled.

  • save_dir (str, optional) – Directory to store samples and results.

  • nlive (int, optional) – Number of live points for nested sampling.

  • dlogz (float, optional) – Convergence criterion for nested sampling.

  • sample (str, optional) – Sampling method for dynesty.

  • bound (str, optional) – Bound-setting method for dynesty.

  • bootstrap (int, optional) – Number of bootstrap iterations for bounding ellipsoids.

compare_evidences(max_display_sigma=10.0, max_display_logz=100.0)

Compare log-evidences for all retrieval models and print sigma-level support.

Parameters:

  • max_display_sigma (float, optional) – Maximum sigma value to display in printed output.

  • max_display_logz (float, optional) – Maximum ΔlogZ value to display in printed output.

plot_best_model_solutions(plot_residuals=True, plot_uncertainty=False)

Plot the median spectrum and uncertainty region for the best-fit model.

Parameters:

  • plot_residuals (bool, optional) – Whether to show a residual panel below the main plot.

  • plot_uncertainty (bool, optional) – Whether to shade the 1σ and 2σ confidence intervals.

plot_best_model_posteriors(n_sigma=2, truths=None)

Plot posterior distributions for the best model’s parameters.

Parameters:

  • n_sigma (int or float, optional) – Width of the confidence interval to annotate.

  • truths (list or None, optional) – Ground truth values to mark on the plot.

print_best_model_summary(n_sigma=2)

Print the median and uncertainty bounds for each parameter in the best-fit model.

Parameters:

n_sigma (int, optional) – Confidence interval width (default is 2σ).

plot_model(name, plot_residuals=True, plot_uncertainty=False)

Plot solutions for any named model in the comparison set.

Parameters:

  • name (str) – Model name (e.g. ‘h2o’, ‘co2’, ‘h2o_co2’).

  • plot_residuals (bool) – Whether to show residual panel.

  • plot_uncertainty (bool) – Whether to shade 1σ/2σ confidence bounds.

plot_model_posteriors(name, n_sigma=2, truths=None)

Plot posterior distributions for any named model.

Parameters:

  • name (str) – Model name to plot.

  • n_sigma (float) – Confidence interval width.

  • truths (list or None) – True values to overlay.