pitcp.models.HPD

class HPD(estimator, optimizer, *, n_epochs=10, n_samples=1000, batch_size=None, verbose=True, random_state=None)[source]

Calibrates conditional highest-density scores by Monte Carlo sampling.

A conditional Zuko distribution models raw scalar scores. Monte Carlo density ranks turn observations into highest-predictive-density nonconformity scores, which are then calibrated by the shared split-conformal threshold.

Density estimation settings:

  • estimator: Conditional zuko flow or Gaussian mixture model used to model the score distribution given the features.

  • optimizer: PyTorch optimizer bound to estimator.parameters() and used to minimize the negative conditional log-likelihood.

Training and sampling settings:

  • n_epochs: Positive number of full passes over the training data. Defaults to 10.

  • n_samples: Positive number of Monte Carlo draws used to estimate each highest-density rank. Defaults to 1000.

  • batch_size: Positive mini-batch size used during training and inference. None uses the full dataset. Defaults to None.

  • verbose: Boolean or integer controlling the tqdm training progress bar. Defaults to True.

  • random_state: Seed controlling mini-batch shuffling during fit. None uses PyTorch’s current random state. Defaults to None.

Variables:

  • estimator (Flow | GMM) – Conditional score-density estimator.

  • optimizer (torch.optim.Optimizer) – Optimizer used for density training.

  • n_epochs (int) – Number of training epochs.

  • n_samples (int) – Monte Carlo sample count used for density ranks.

  • batch_size (int | None) – Training batch size or None for full batches.

  • verbose (bool | int) – Whether to display the training progress bar.

  • random_state (int | None) – Mini-batch shuffling seed.

  • scores (np.ndarray) – HPD calibration scores with shape (n_samples,).

Parameters:

  • estimator (Flow | GMM)

  • optimizer (Optimizer)

  • n_epochs (int)

  • n_samples (int)

  • batch_size (int | None)

  • verbose (bool | int)

  • random_state (int | None)

Examples

>>> import torch
>>> import zuko
>>> from pitcp import HPD
>>> density = zuko.mixtures.GMM(features=1, context=1, components=2)
>>> optimizer = torch.optim.Adam(density.parameters())
>>> model = HPD(density, optimizer, n_epochs=1, verbose=False)
__init__(estimator, optimizer, *, n_epochs=10, n_samples=1000, batch_size=None, verbose=True, random_state=None)[source]

Initializes the HPD conformal regressor.

Parameters:

  • estimator (Flow | GMM) – Conditional score-density estimator.

  • optimizer (torch.optim.Optimizer) – Optimizer for density training.

  • n_epochs (int, optional) – Number of training epochs. Defaults to 10.

  • n_samples (int, optional) – Monte Carlo density-rank sample count. Defaults to 1000.

  • batch_size (int | None, optional) – Mini-batch size. None uses full batches. Defaults to None.

  • verbose (bool | int, optional) – Whether to show a progress bar. Defaults to True.

  • random_state (int | None, optional) – Mini-batch shuffling seed. Defaults to None.

fit(X, y)[source]

Fits the conditional density estimator to raw scores.

Parameters:

  • X (np.typing.ArrayLike) – Score-training features with shape (n_samples, n_features).

  • y (np.typing.ArrayLike) – Targets with shape (n_samples,) or (n_samples, n_outputs).

Returns:

The fitted estimator.

Return type:

Self

conformalize(X, y)[source]

Stores held-out HPD-rank calibration scores.

Parameters:

  • X (np.typing.ArrayLike) – Calibration features with shape (n_samples, n_features).

  • y (np.typing.ArrayLike) – Targets with shape (n_samples,) or (n_samples, n_outputs).

Returns:

The calibrated estimator.

Return type:

Self

predict(X, *, confidence_level=0.9)[source]

Predicts calibrated highest-density rank thresholds.

Parameters:

  • X (np.typing.ArrayLike) – Test features with shape (n_samples, n_features).

  • confidence_level (float | Sequence[float], optional) – Target marginal coverage level or levels. Defaults to 0.9.

Returns:

Thresholds, with the level axis omitted for one level.

Return type:

np.ndarray

contains(X, y, *, confidence_level=0.9)[source]

Tests whether scores lie inside calibrated HPD sets.

Parameters:

  • X (np.typing.ArrayLike) – Test features with shape (n_samples, n_features).

  • y (np.typing.ArrayLike) – Test targets with shape (n_samples,) or (n_samples, n_outputs).

  • confidence_level (float | Sequence[float], optional) – Requested coverage levels. Defaults to 0.9.

Returns:

Coverage indicators with shape (n_samples,) or ``(n_samples,

n_levels)``.

Return type:

np.ndarray

set_fit_request()

No-op.

Calling this method has no effect.

Returns:

self – The updated object.

Return type:

object

Parameters:

self (HPD)

set_predict_request(*, confidence_level='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the predict method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

  • True: metadata is requested, and passed to predict if provided. The request is ignored if metadata is not provided.

  • False: metadata is not requested and the meta-estimator will not pass it to predict.

  • None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

  • str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:

  • confidence_level (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for confidence_level parameter in predict.

  • self (HPD)

Returns:

self – The updated object.

Return type:

object