curepy package

curepy package#

Bases: object

calculate_b_cov() → ndarray | None[source]#

Calculate the full covariance matrix for all ancillary parameters.

Constructs per-parameter correlation matrices, flattens and combines them with corr_between_b (if set) using comet_maths.calculate_flattened_corr. Returns None if insufficient data is available and emits a warning.

Returns:: Combined covariance matrix for all ancillary parameters, or None if it cannot be computed.

generate_b_samples()[source]#

Generate Monte Carlo samples for the ancillary parameters.

Uses punpy.MCPropagation to draw samples from the joint distribution defined by b, u_b, corr_b, and corr_between_b. If b is None the resulting b_samples attribute is set to None. If b_samples has already been provided it is left unchanged.

class curepy.MCMC(nwalkers: int, steps: int, burn_in: int, progress: bool = True, parallel_cores: int = 1)[source]#

Bases: BaseRetrieval

MCMC retrieval object.

analyse_samples(samples: ndarray, b_samples: ndarray | None, return_samples: bool, return_corr: bool, return_b_samples: bool, reshape_results: bool, corr_dims: int | Sequence[int] | None = -99) → RetrievalResult[source]#

Summarise MCMC samples into a RetrievalResult.

Computes the median, symmetric uncertainty (average of upper and lower 1-sigma percentiles), and optionally the correlation matrix.

Parameters:

samples – Post-burn-in MCMC samples.
b_samples – Ancillary parameter samples.
return_samples – If True, include the raw samples in the result.
return_corr – If True, compute and include the correlation matrix.
return_b_samples – If True, include ancillary samples.
reshape_results – If True, reshape outputs to the initial-guess shape.
corr_dims – int or List of ints, axis to calculate correlation matrix along.

Returns:

Retrieved values, uncertainties, and optional extras.

generate_theta_i(theta_0: ndarray, factor_std: float = 0.1) → ndarray[source]#

Generate a single walker starting position from theta_0.

Perturbs theta_0 by a Gaussian factor and recursively reduces the perturbation magnitude until the resulting position lies within the support of the prior.

Parameters:

theta_0 – Initial state vector.
factor_std – Standard deviation of the multiplicative Gaussian perturbation.

Returns:

Perturbed starting position that is within the prior support.

run_MCMC(theta_0: ndarray, nwalkers: int, steps: int, burn_in: int) → ndarray[source]#

Run emcee.EnsembleSampler and return the post-burn-in chain.

Parameters:

theta_0 – Initial state vector around which walkers are initialised.
nwalkers – Number of ensemble walkers.
steps – Total number of sampling steps.
burn_in – Number of initial samples to discard.

Returns:

Array of post-burn-in samples with shape (nwalkers * steps - burn_in, ndim).

Bases: object

static calculate_inv_cov(unc: ndarray, corr: ndarray) → ndarray[source]#

Calculate the inverse covariance matrix.

Parameters:

unc – Uncertainty (standard deviation) array.
corr – Correlation matrix.

Returns:

Inverse of the covariance matrix.

static return_corr_cholesky_whitening(corr: ndarray | None) → tuple[source]#

Return the correlation matrix, its Cholesky decomposition, and the whitening matrix.

Parameters:: corr – Correlation matrix, or None.
Returns:: Tuple of (corr, cholesky, W) where cholesky is the Cholesky decomposition of the correlation matrix, or None if corr is None, and W is the whitening matrix.

class curepy.MeasurementFunction(measurement_func: Callable, initial_guess: Any, multiple_guess_measurements: bool = False, measurement_name: str = None, input_quantities_names: str | List[str] = None)[source]#

Bases: object

make_x_tuple(theta: ndarray) → tuple[source]#

Build the input-quantity tuple from the flattened state vector.

Fills a deep copy of initial_guess with values from theta in order, supporting up to three levels of nesting.

Parameters:: theta – Flattened state vector whose values are inserted into the initial-guess structure.
Returns:: Tuple of input quantities ready to be passed to the measurement function.

measurement_function_flattened_b(theta: ndarray, b_flat: ndarray, b_shape_list: List[tuple]) → ndarray[source]#

Evaluate the measurement function with a flat ancillary-parameter vector.

Reconstructs the original ancillary parameter arrays from the flat vector b_flat using the shapes in b_shape_list, then calls the measurement function and returns a flattened result.

Parameters:

theta – Flattened retrieval state vector.
b_flat – Concatenated, flattened ancillary parameter values.
b_shape_list – Shapes used to reconstruct each ancillary parameter array.

Returns:

Flattened output of the measurement function.

measurement_function_flattened_output(theta: ndarray, b: ndarray | None) → ndarray[source]#

Evaluate the measurement function and return a flattened output array.

Parameters:

theta – Flattened retrieval state vector.
b – Ancillary parameter values, or None if not used.

Returns:

Flattened output of the measurement function.

measurement_function_x(theta: ndarray, b: ndarray | None) → ndarray[source]#

Evaluate the measurement function at state vector theta.

Unpacks theta into the input-quantity tuple expected by the underlying measurement function and calls it, optionally passing ancillary parameters b.

Parameters:

theta – Flattened retrieval state vector.
b – Ancillary parameter values, or None if not used.

Returns:

Output of the measurement function.

class curepy.OE(Jx: ndarray | None = None)[source]#

Bases: BaseRetrieval

Optimal Estimation (OE) retrieval object.

calculate_Jb(x: ndarray) → ndarray[source]#

Numerically compute the Jacobian of the measurement function with respect to the flattened ancillary parameters.

Parameters:: x – State vector at which the Jacobian is evaluated.
Returns:: Jacobian matrix.

calculate_Jx(x: ndarray) → ndarray[source]#

Numerically compute the Jacobian of the measurement function with respect to the state vector.

Parameters:: x – State vector at which the Jacobian is evaluated.
Returns:: Jacobian matrix.

calculate_measurand_covariance(x: ndarray, J: ndarray, Sy_inv: ndarray | None, Sa_inv: ndarray | None = None, Sb_inv: ndarray | None = None) → ndarray[source]#

Calculate the posterior state-vector covariance matrix.

Uses the Gauss–Newton / LPU formula combining measurement, ancillary, and prior uncertainty contributions.

Parameters:

x – Retrieved state vector.
J – Jacobian with respect to the state vector.
Sy_inv – Inverse measurement covariance. Must not be None unless Sb_inv is also provided.
Sa_inv – Inverse prior covariance, or None if no prior is used.
Sb_inv – Pre-computed inverse ancillary-parameter covariance mapped to measurement space. If None, the covariance is computed from the ancillary object.

Returns:

Posterior state-vector covariance matrix.

process_inverse_jacobian(J: ndarray, x: ndarray) → tuple[source]#

Derive state-vector uncertainties from the Jacobian via LPU.

Parameters:

J – Jacobian of the measurement function with respect to the state vector, evaluated at x.
x – Retrieved state vector.

Returns:

Tuple of (u_func, corr_x) where u_func is the 1-sigma uncertainty array and corr_x is the correlation matrix.

class curepy.Prior(prior_shape: List[str] = None, prior_params: List[dict] = [{}], prior_correlation: ndarray | None = None)[source]#

Bases: object

combine_dist_functions(xs: ndarray)[source]#

Evaluate each individual prior distribution at the corresponding value.

Parameters:: xs – Sequence of parameter values, one per retrieval parameter.
Returns:: Callable that, when invoked, returns a list of log-prior values from each individual distribution.

return_Sa_inv() → ndarray | None[source]#

Compute the inverse of the prior covariance matrix.

Constructs the prior covariance from the "sigma" entries in prior_params and the (optionally formatted) correlation matrix, then returns its inverse. Returns None if no correlation matrix is available.

Returns:: Inverse of the prior covariance matrix, or None if the correlation matrix is undefined.

class curepy.RetrievalFactory[source]#

Bases: object

make_retrieval_object(name: str | BaseRetrieval, *args, **kwargs) → BaseRetrieval[source]#

Return the specified retrieval object.

Parameters:: name – Retrieval method identifier. May be a string key (e.g. "mcmc", "oe") or a BaseRetrieval subclass.
Returns:: Instantiated retrieval method object.

class curepy.RetrievalInput(measurement_function_obj: MeasurementFunction | None = None, measurement_obj: Measurement | None = None, ancillary_obj: AncillaryParameter | None = None, prior_obj: Prior | None = None)[source]#

Bases: object

Construct ancillary_obj from ancillary parameter data.

Parameters:

b – Ancillary parameter values.
u_b – Uncertainties for the ancillary parameters.
corr_b – Correlation specification for each ancillary parameter.
corr_between_b – Correlation matrix between ancillary parameters.
b_samples – Pre-generated MC samples for ancillary parameters.
b_MC_steps – Number of MC steps for ancillary parameter sampling.

build_from_obsarray(obs_ds: Any, y_name: str, measurement_func: Callable, initial_guess: Any, b_name: List[str] | None = None, multiple_guess_measurements: bool = False, input_quantities_names: str | List[str] = None, prior_shape: List[str] = None, prior_params: List[dict] = [{}], prior_correlation: Any | None = None, b_samples: Any | None = None, b_MC_steps: int | None = None) → None[source]#

Construct all retrieval input sub-objects from an obsarray dataset.

The measurement variable, uncertainty, and error-correlation are read directly from the dataset. Ancillary parameters are optionally sourced from the same dataset by name.

Parameters:

obs_ds – obsarray dataset containing measurement and ancillary variables with associated uncertainty information.
y_name – Name of the measurement variable in obs_ds.
measurement_func – Callable measurement/forward-model function.
initial_guess – Initial values for the retrieval parameters.
b_name – List of ancillary parameter variable names in obs_ds, or None if no ancillary parameters are used.
multiple_guess_measurements – If True, the initial guess contains multiple measurements per parameter.
input_quantities_names – Optional name(s) for input quantities.
prior_shape – List of prior distribution shape names.
prior_params – List of prior parameter dictionaries.
prior_correlation – Correlation matrix for the prior.
b_samples – Pre-generated MC samples for ancillary parameters.
b_MC_steps – Number of MC steps for ancillary parameter sampling.

Construct measurement_obj from measurement data.

Parameters:

y – Measurement variable.
u_y_total – Total uncertainty of the measurement variable.
u_y_rand – Random uncertainty of the measurement variable.
u_y_syst – Systematic uncertainty of the measurement variable.
corr_y – Error-correlation of the measurement variable (None, "rand", "syst", or a square matrix).

build_measurement_function(measurement_func: Callable, initial_guess: Any, multiple_guess_measurements: bool = False, measurement_name: str = None, input_quantities_names: str | List[str] = None) → None[source]#

Construct measurement_function_obj from individual components.

Parameters:

measurement_func – Callable measurement/forward-model function.
initial_guess – Initial values for the retrieval parameters.
multiple_guess_measurements – If True, the initial guess contains multiple measurements per parameter.
measurement_name – Optional name for the measured quantity.
input_quantities_names – Optional name(s) for input quantities.

build_prior(prior_shape: List[str] = None, prior_params: List[dict] = [{}], prior_correlation: Any | None = None) → None[source]#

Construct prior_obj from prior distribution specifications.

Parameters:

prior_shape – List of prior distribution shape names.
prior_params – List of prior parameter dictionaries.
prior_correlation – Correlation matrix for the prior.

build_retrieval_inputs(measurement_func: Callable, initial_guess: Any, y: Any, u_y_total: Any | None = None, u_y_rand: Any | None = None, u_y_syst: Any | None = None, corr_y: str | Any | None = None, multiple_guess_measurements: bool = False, measurement_name: str = None, input_quantities_names: str | List[str] = None, prior_shape: List[str] = None, prior_params: List[dict] = [{}], prior_correlation: Any | None = None, b: list | None = None, u_b: list | None = None, corr_b: list | None = None, corr_between_b: Any | None = None, b_samples: Any | None = None, b_MC_steps: int | None = None) → None[source]#

Construct all retrieval input sub-objects in a single call.

Parameters:

measurement_func – Callable measurement/forward-model function.
initial_guess – Initial values for the retrieval parameters.
y – Measurement variable.
u_y_total – Total uncertainty of the measurement variable.
u_y_rand – Random uncertainty of the measurement variable.
u_y_syst – Systematic uncertainty of the measurement variable.
corr_y – Error-correlation of the measurement variable (None, "rand", "syst", or a square matrix).
multiple_guess_measurements – If True, the initial guess contains multiple measurements per parameter.
measurement_name – Optional name for the measured quantity.
input_quantities_names – Optional name(s) for input quantities.
prior_shape – List of prior distribution shape names.
prior_params – List of prior parameter dictionaries.
prior_correlation – Correlation matrix for the prior.
b – Ancillary parameter values.
u_b – Uncertainties for the ancillary parameters.
corr_b – Correlation specification for each ancillary parameter.
corr_between_b – Correlation matrix between ancillary parameters.
b_samples – Pre-generated MC samples for ancillary parameters.
b_MC_steps – Number of MC steps for ancillary parameter sampling.

Bases: object

build_obsarray() → None[source]#: Build an obsarray dataset from the retrieval results.

Note

Not yet implemented.

get_chisq() → float[source]#: Get the chi-squared value of the retrieval.

Note

Not yet implemented.

curepy.flatten_array(A: ndarray) → tuple[source]#

Flatten array and return the flattened array and the original shape.

Parameters:: A – Array to be flattened.
Returns:: Tuple of (A_flat, shape).

curepy.format_correlation(y: ndarray | list, corr: ndarray | str | None) → ndarray | None[source]#

Format a correlation matrix from user-provided inputs.

Parameters:

y – Reference variable used to determine the length of the correlation matrix.
corr –
Correlation specification. Accepted values:
- None — no correlation (returns None).
- "rand" — random (diagonal identity matrix).
- "syst" — fully systematic (all-ones matrix).
- Custom square numpy.ndarray.

Returns:

Formatted correlation matrix, or None.

curepy.ln_multi_normal(theta: ndarray, mu: ndarray, Sa_inv: ndarray) → float[source]#

Evaluate the log of an unnormalised multivariate normal prior.

Parameters:

theta – Current parameter vector to evaluate.
mu – Mean vector of the multivariate Gaussian.
Sa_inv – Inverse of the prior covariance matrix.

Returns:

Log probability proportional to the multivariate Gaussian log-density.

curepy.ln_normal(theta: float | ndarray, mu: float | ndarray, sigma: float | ndarray) → float | ndarray[source]#

Evaluate the log of an unnormalised normal (Gaussian) prior distribution.

Parameters:

theta – Current parameter value(s) to evaluate.
mu – Mean of the Gaussian distribution.
sigma – Standard deviation of the Gaussian distribution.

Returns:

Log probability proportional to the Gaussian log-density.

Evaluate the log of a truncated normal prior distribution.

Parameters:

theta – Current parameter value(s) to evaluate.
mu – Mean of the normal distribution.
sigma – Standard deviation of the normal distribution.
minimum – Lower bound of the truncation.
maximum – Upper bound of the truncation.

Returns:

Log probability proportional to the truncated normal log-density.

curepy.ln_uniform(theta: float | ndarray, minimum: float | ndarray, maximum: float | ndarray) → float[source]#

Evaluate the log of a uniform prior distribution.

Returns 0 when all elements of theta are strictly within [minimum, maximum], and -inf otherwise.

Parameters:

theta – Current parameter value(s) to evaluate.
minimum – Lower bound(s) of the uniform distribution.
maximum – Upper bound(s) of the uniform distribution.

Returns:

Log probability: 0 if in-bounds, -numpy.inf otherwise.

curepy.lnlike(cost_function: float | ndarray) → float | ndarray[source]#

Convert a chi-squared cost to a log likelihood.

Parameters:: cost_function – Chi-squared cost value(s).
Returns:: Log likelihood, equal to -0.5 * cost_function.

curepy.plot_corner(xs, bins: int = 20, range=None, weights=None, color: str = 'k', smooth=None, smooth1d=None, ticks=None, ticklabels=None, labels=None, label_kwargs: dict = None, show_titles: bool = False, title_fmt: str = '.2f', title_kwargs: dict = None, truths=None, truth_color: str = '#4682b4', scale_hist: bool = False, quantiles=None, verbose: bool = False, fig=None, max_n_ticks: int = 5, top_ticks: bool = False, use_math_text: bool = False, hist_kwargs: dict = None, **hist2d_kwargs)[source]#

Make a corner plot showing the projections of a data set in a multi-dimensional space. Remaining keyword arguments are forwarded to hist2d() or used for matplotlib styling.

Parameters:

xs – The samples. Must be a 1-D or 2-D array where the zeroth axis is the list of samples and the next axis are the dimensions of the space.
bins – Number of bins to use in histograms, either as a fixed value for all dimensions or as a list of integers for each dimension.
range – A list where each element is either a length-2 tuple containing lower and upper bounds, or a float in (0, 1) giving the fraction of samples to include in the bounds.
weights – The weight of each sample. If None (default), samples are given equal weight.
color – A matplotlib colour for all histograms.
smooth – Standard deviation for Gaussian kernel smoothing of the 2-D histograms. None disables smoothing.
smooth1d – Standard deviation for Gaussian kernel smoothing of the 1-D histograms. None disables smoothing.
ticks – Custom tick positions for each dimension.
ticklabels – Custom tick labels for each dimension.
labels – A list of names for the dimensions. Defaults to DataFrame column names when xs is a pandas.DataFrame.
label_kwargs – Extra keyword arguments passed to set_xlabel / set_ylabel.
show_titles – If True, display the 0.5 quantile with 1-sigma errors as a title above each 1-D histogram.
title_fmt – Format string for quantile values in titles.
title_kwargs – Extra keyword arguments passed to set_title.
truths – Reference values to indicate on the plots. Individual values may be None.
truth_color – matplotlib colour for the truth markers.
scale_hist – If True, scale 1-D histograms so the zero line is visible.
quantiles – Fractional quantiles to show as vertical dashed lines on 1-D histograms.
verbose – If True, print the computed quantile values.
fig – Existing matplotlib.Figure to overplot onto.
max_n_ticks – Maximum number of axis ticks per axis.
top_ticks – If True, label ticks at the top of each axis.
use_math_text – If True, render very large or small axis tick exponents as powers of 10.
hist_kwargs – Extra keyword arguments forwarded to the 1-D histogram plots.

Returns:

The matplotlib.Figure containing the corner plot.

curepy.reshape_array(A_flat: ndarray, shape: tuple) → ndarray[source]#

Reshape a flattened array to a given shape.

Parameters:

A_flat – Flattened array.
shape – Target shape.

Returns:

Reshaped array.

curepy package

Contents

curepy package#

Subpackages#