lf2i.estimators package

Subpackages

• lf2i.estimators.torch_utils package
  • Submodules
  • lf2i.estimators.torch_utils.cdf module
    • BrierScoreLoss
      • BrierScoreLoss.forward()
    • QuantileWeightedCRPSLoss
      • QuantileWeightedCRPSLoss.forward()
    • SigmoidCDF
      • SigmoidCDF.forward()
      • SigmoidCDF.quantile()
    • BetaNetwork
      • BetaNetwork.forward()
    • ParametricCDFEstimator
      • ParametricCDFEstimator.fit()
      • ParametricCDFEstimator.predict_proba()
  • lf2i.estimators.torch_utils.quantile_regressor module
    • QuantileLoss
      • QuantileLoss.forward()
    • FeedForwardNN
      • FeedForwardNN.build_model()
      • FeedForwardNN.forward()
    • Learner
      • Learner.fit()
      • Learner.predict()
    • LearnerRegression
      • LearnerRegression.predict()
    • LearnerClassification
      • LearnerClassification.predict_proba()

Submodules

lf2i.estimators.base_cdf module

class lf2i.estimators.base_cdf.AbstractCDFEstimator(*args, **kwargs)

Bases: Protocol

Protocol for parametric CDF estimators that model F(λ | θ).

Unlike probabilistic classifiers, these receive test statistics and parameters of interest as separate arrays at fit time rather than a single combined matrix. At predict time they follow the same predict_proba(X) convention so that downstream p-value computation is uniform across both algorithm categories.

This interface is satisfied by ParametricCDFEstimator and any custom estimator that models the conditional CDF of the test statistic directly.

Implement this Protocol to provide a custom CDF estimator to estimate_rejection_proba as the algorithm argument.

fit(X: ndarray | Tensor, **kwargs) → AbstractCDFEstimator

Fit the CDF estimator to calibration data.

Parameters:

X (Union[np.ndarray, torch.Tensor]) – Shape (n, 1 + poi_dim). Column 0 is the test statistic λ(x_i; θ_i), columns 1: are the corresponding parameters of interest θ_i.

Returns:

self

predict_proba(X: ndarray | Tensor, **kwargs) → ndarray

Compute p-values from the fitted CDF.

Parameters:

X (Union[np.ndarray, torch.Tensor]) – Shape (n, 1 + poi_dim). Column 0 is the test statistic λ, columns 1: are the parameters of interest θ.

Returns:

np.ndarray – Shape (n, 2). - [:, 0] = P(reject=0 | cutoff, θ) - [:, 1] = P(reject=1 | cutoff, θ) Rows sum to 1.

lf2i.estimators.base_likelihoods module

class lf2i.estimators.base_likelihoods.AbstractClassifier(*args, **kwargs)

Bases: Protocol

Protocol for basic likelihood ratio estimators via classification.

predict_proba(X: Tensor | ndarray, **kwargs) → Tensor

For X containing x and θ, predict p(y=1 | x, θ) where y is the class label indicating whether the data was generated from the model with parameter θ or from a reference distribution. Evaluates likelihood ratio p(x; θ) / [int p(x; θ’) r(θ’) dθ’].

Parameters:

X (Union[torch.Tensor, np.ndarray]) – Observed test statistic values and parameter values at which to evaluate

Returns:

Union[torch.Tensor, np.ndarray] – Probabilities with shape (n_samples, 2) where: - [:, 0] contains p(y=0 | x, θ) - [:, 1] contains p(y=1 | x, θ) Both columns must sum to 1.0 for each sample.

class lf2i.estimators.base_likelihoods.AbstractClassifierTrainer(*args, **kwargs)

Bases: AbstractClassifier, Protocol

fit(X: Tensor | ndarray, y: Tensor | ndarray, **kwargs) → None

Fit the classifier to data.

Parameters:

• X (Union[torch.Tensor, np.ndarray]) – Training data containing x and θ

• y (Union[torch.Tensor, np.ndarray]) – Class labels indicating whether each row of X was generated from the model with parameter θ or from a reference distribution.

lf2i.estimators.base_posteriors module

class lf2i.estimators.base_posteriors.AbstractPosterior(*args, **kwargs)

Bases: Protocol

Protocol for basic posterior distributions. Compatible with sbi.utils.kde.KDEWrapper and similar simple posteriors.

log_prob(theta: Tensor | ndarray, x: Tensor | ndarray | None = None, **kwargs) → Tensor

Evaluate log posterior probability log p(θ|x).

Parameters:

• theta (Union[torch.Tensor, np.ndarray]) – Parameter values at which to evaluate

• x (Optional[Union[torch.Tensor, np.ndarray]]) – Observed data (optional, some posteriors may have this pre-set)

Returns:

torch.Tensor – Log probabilities

class lf2i.estimators.base_posteriors.AbstractNeuralPosterior(*args, **kwargs)

Bases: Protocol

Protocol for neural posterior estimators that require training. Compatible with sbi.inference.posteriors.base_posterior.NeuralPosterior.

Note: This extends AbstractPosterior’s interface by including training methods.

sample(sample_shape: tuple, x: Tensor | ndarray, show_progress_bars: bool = True, **kwargs) → Tensor

Sample from the posterior p(θ|x).

Parameters:

• sample_shape (tuple) – Shape of samples to draw, e.g., (1000,) for 1000 samples

• x (Union[torch.Tensor, np.ndarray]) – Observed data

• show_progress_bars (bool) – Whether to show progress bars during sampling

Returns:

torch.Tensor – Samples from posterior with shape (sample_shape, theta_dim)

log_prob(theta: Tensor | ndarray, x: Tensor | ndarray | None = None, **kwargs) → Tensor

Evaluate log posterior probability log p(θ|x).

Parameters:

• theta (Union[torch.Tensor, np.ndarray]) – Parameter values at which to evaluate

• x (Optional[Union[torch.Tensor, np.ndarray]]) – Observed data

Returns:

torch.Tensor – Log probabilities

class lf2i.estimators.base_posteriors.AbstractKDE(*args, **kwargs)

Bases: Protocol

Protocol for KDE wrappers. Compatible with sbi.utils.kde.KDEWrapper.

Note: KDE typically doesn’t need the ‘x’ parameter since it’s fit to samples.

log_prob(theta: Tensor | ndarray, **kwargs) → Tensor

Evaluate log probability under the KDE.

Parameters:

theta (Union[torch.Tensor, np.ndarray]) – Points at which to evaluate density

Returns:

torch.Tensor – Log probabilities

class lf2i.estimators.base_posteriors.AbstractNeuralPosteriorTrainer(*args, **kwargs)

Bases: Protocol

Protocol for neural posterior estimators that require training. Compatible with sbi.inference.posteriors.base_posterior.NeuralPosterior.

Note: This extends AbstractPosterior’s interface by including training methods.

append_simulations(theta: Tensor | ndarray, x: Tensor | ndarray, **kwargs) → AbstractNeuralPosterior

Append training data (simulations) to the estimator.

Parameters:

• theta (Union[torch.Tensor, np.ndarray]) – Simulated parameters

• x (Union[torch.Tensor, np.ndarray]) – Simulated data corresponding to theta

Returns:

AbstractNeuralPosterior – Returns self for method chaining

train(**kwargs) → AbstractNeuralPosterior

Train the neural posterior estimator on appended simulations.

Returns:

AbstractNeuralPosterior – Returns self for method chaining

build_posterior(**kwargs) → AbstractNeuralPosterior

Build the posterior distribution after training.

Returns:

AbstractNeuralPosterior – The trained posterior object ready for inference

lf2i.estimators.base_probabilistic_classifier module

class lf2i.estimators.base_probabilistic_classifier.AbstractProbabilisticClassifier(*args, **kwargs)

Bases: Protocol

Protocol for probabilistic classifiers that estimate P(reject | cutoff, θ).

X has shape (n, 1 + poi_dim): column 0 is the resampled cutoff (test statistic threshold), remaining columns are parameters of interest θ. This interface is satisfied by sklearn-style classifiers such as CatBoostClassifier, LogisticRegression, and TabICLClassifier, as well as any custom estimator that follows the same convention.

Implement this Protocol to provide a custom probabilistic classifier to estimate_rejection_proba as the algorithm argument.

fit(X: ndarray | Tensor, y: ndarray | Tensor, **kwargs) → None

Fit the classifier to augmented calibration data.

Parameters:

• X (Union[np.ndarray, torch.Tensor]) – Shape (n, 1 + poi_dim). Column 0 is the resampled cutoff, columns 1: are the parameters of interest θ. Produced by lf2i.calibration.p_values.augment_calibration_set.

• y (Union[np.ndarray, torch.Tensor]) – Shape (n,). Binary rejection indicators (0 or 1). Produced by lf2i.calibration.p_values.augment_calibration_set.

predict_proba(X: ndarray | Tensor, **kwargs) → ndarray

Predict class probabilities for each row of X.

Parameters:

X (Union[np.ndarray, torch.Tensor]) – Shape (n, 1 + poi_dim). Column 0 is the resampled cutoff, columns 1: are the parameters of interest θ.

Returns:

np.ndarray – Shape (n, 2). - [:, 0] = P(reject=0 | cutoff, θ) - [:, 1] = P(reject=1 | cutoff, θ) Rows sum to 1.

lf2i.estimators.base_quantile_regressor module

class lf2i.estimators.base_quantile_regressor.AbstractQuantileRegressor(*args, **kwargs)

Bases: Protocol

Protocol for quantile regressors that estimate critical values.

X has shape (n, param_dim): the parameters of interest θ. y has shape (n,): the test statistics λ(x; θ).

This interface is satisfied by CatBoostRegressor, the FeedForwardNN LearnerRegression wrapper, and any custom estimator that follows the same fit/predict convention expected by lf2i.calibration.critical_values.train_qr_algorithm.

Implement this Protocol to provide a custom quantile regressor to train_qr_algorithm as the algorithm argument.

fit(X: ndarray | Tensor, y: ndarray | Tensor, **kwargs) → None

Fit the quantile regressor to calibration data.

Parameters:

• X (Union[np.ndarray, torch.Tensor]) – Shape (n, param_dim). Parameters of interest θ.

• y (Union[np.ndarray, torch.Tensor]) – Shape (n,). Test statistics λ(x_i; θ_i).

predict(X: ndarray | Tensor, **kwargs) → ndarray

Predict quantile(s) of the test statistic at each parameter value.

Parameters:

X (Union[np.ndarray, torch.Tensor]) – Shape (n, param_dim). Parameters of interest θ.

Returns:

np.ndarray – Shape (n,) for a single quantile, or (n, k) for k quantiles.