frostie.retrieval ================= .. py:module:: frostie.retrieval Classes ------- .. autoapisummary:: frostie.retrieval.solo_retrieval frostie.retrieval.nested_retrieval Functions --------- .. autoapisummary:: frostie.retrieval.load_simulated_data Module Contents --------------- .. py:function:: 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. :param snr: Desired signal-to-noise ratio of the simulated data. :type snr: float :param del_wav: Spectral resolution (wavelength bin size in microns) to which the model spectrum will be downsampled. :type del_wav: float :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 :rtype: dict .. py:class:: solo_retrieval .. py:attribute:: initialized :value: False .. py:method:: initialize(fixed_params, free_params, components, data, instrument_response=None) Initialize the retrieval setup. :param fixed_params: Dictionary of fixed model parameters (i, e, g, B, s, etc.) :type fixed_params: dict :param free_params: List of [parameter_name, (min, max)] tuples for sampling :type free_params: list :param components: Dictionary of {component_name: [wav, n, k]} entries :type components: dict :param data: [wavelengths, reflectance, uncertainty] :type data: list :param instrument_response: Optional response function array (must match wavelength grid) :type instrument_response: ndarray or None .. py:method:: _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. .. py:method:: _loglike(theta, norm_log) Compute log-likelihood from model and data. Assumes model and data are already matched in wavelength. .. py:method:: _dirichlet_prior_transform(theta_unit, prior_bounds, n_species) .. py:method:: _prior_transform(theta_unit) .. py:method:: 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. :param save_dir: Directory to store output samples and results. :type save_dir: str, optional :param nlive: Number of live points for the nested sampler. :type nlive: int, optional :param dlogz: Convergence threshold for dynesty. :type dlogz: float, optional :param sample: Sampling method for dynesty ('rwalk', 'auto', etc.). :type sample: str, optional :param bound: Bounding method for dynesty ('multi', etc.). :type bound: str, optional :param bootstrap: Number of bootstrap iterations for ellipsoid bounding. :type bootstrap: int, optional :param use_multicore: Whether to run dynesty in parallel. :type use_multicore: bool, optional :param nproc: Number of cores to use if multiprocessing is enabled. :type nproc: int or None, optional .. py:method:: plot_solutions(plot_residuals=True, plot_uncertainty=False) Plot posterior model fit with optional residuals and uncertainty shading. :param plot_residuals: If True, show residuals below the model plot. :type plot_residuals: bool :param plot_uncertainty: If True, shade 1σ and 2σ confidence intervals. :type plot_uncertainty: bool .. py:method:: plot_posteriors(truths=None, n_sigma=2) Plot posterior distributions of the retrieved parameters. :param truths: True values to overlay on the posterior plots (e.g., for simulated data). :type truths: list or None, optional :param n_sigma: Width of the confidence interval to annotate (default is 1σ). :type n_sigma: int or float, optional .. py:method:: 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. :param n_sigma: Width of confidence interval to display (default is 2σ). :type n_sigma: float, optional .. py:class:: nested_retrieval .. py:attribute:: results_dict .. py:attribute:: model_logZs .. py:attribute:: model_names :value: [] .. py:attribute:: best_model_name :value: None .. py:method:: initialize(fixed_params, free_params, components, data, instrument_response=None) Initialize a nested_retrieval object with model and data settings. :param fixed_params: Dictionary of fixed model parameters (e.g., geometry, phase function type). :type fixed_params: dict :param free_params: List of free parameters and their bounds. :type free_params: list of [str, tuple] :param components: Dictionary of optical constants keyed by component name. :type components: dict :param data: List containing wavelength, reflectance, and uncertainty arrays. :type data: list of ndarray :param instrument_response: Optional instrument convolution kernel (default is None). :type instrument_response: ndarray, optional .. py:method:: _build_model_case(include_components) Dynamically build model-specific free parameter list. .. py:method:: 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. :param use_multicore: Whether to use multiprocessing (default is False). :type use_multicore: bool, optional :param nproc: Number of processor cores to use if multiprocessing is enabled. :type nproc: int or None, optional :param save_dir: Directory to store samples and results. :type save_dir: str, optional :param nlive: Number of live points for nested sampling. :type nlive: int, optional :param dlogz: Convergence criterion for nested sampling. :type dlogz: float, optional :param sample: Sampling method for dynesty. :type sample: str, optional :param bound: Bound-setting method for dynesty. :type bound: str, optional :param bootstrap: Number of bootstrap iterations for bounding ellipsoids. :type bootstrap: int, optional .. py:method:: compare_evidences(max_display_sigma=10.0, max_display_logz=100.0) Compare log-evidences for all retrieval models and print sigma-level support. :param max_display_sigma: Maximum sigma value to display in printed output. :type max_display_sigma: float, optional :param max_display_logz: Maximum ΔlogZ value to display in printed output. :type max_display_logz: float, optional .. py:method:: plot_best_model_solutions(plot_residuals=True, plot_uncertainty=False) Plot the median spectrum and uncertainty region for the best-fit model. :param plot_residuals: Whether to show a residual panel below the main plot. :type plot_residuals: bool, optional :param plot_uncertainty: Whether to shade the 1σ and 2σ confidence intervals. :type plot_uncertainty: bool, optional .. py:method:: plot_best_model_posteriors(n_sigma=2, truths=None) Plot posterior distributions for the best model's parameters. :param n_sigma: Width of the confidence interval to annotate. :type n_sigma: int or float, optional :param truths: Ground truth values to mark on the plot. :type truths: list or None, optional .. py:method:: print_best_model_summary(n_sigma=2) Print the median and uncertainty bounds for each parameter in the best-fit model. :param n_sigma: Confidence interval width (default is 2σ). :type n_sigma: int, optional .. py:method:: plot_model(name, plot_residuals=True, plot_uncertainty=False) Plot solutions for any named model in the comparison set. :param name: Model name (e.g. 'h2o', 'co2', 'h2o_co2'). :type name: str :param plot_residuals: Whether to show residual panel. :type plot_residuals: bool :param plot_uncertainty: Whether to shade 1σ/2σ confidence bounds. :type plot_uncertainty: bool .. py:method:: plot_model_posteriors(name, n_sigma=2, truths=None) Plot posterior distributions for any named model. :param name: Model name to plot. :type name: str :param n_sigma: Confidence interval width. :type n_sigma: float :param truths: True values to overlay. :type truths: list or None