pitcp.models.CONTRA

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

Fits inverse-flow images calibrated by the latent Euclidean norm.

CONTRA maps targets into a conditional flow’s latent coordinates and calibrates the values \(\lVert z \rVert_2\), where z is the transformed target.

Density estimation settings:

  • estimator: Conditional zuko flow mapping targets to latent coordinates. Although construction accepts a Gaussian mixture model for scikit-learn compatibility, fit rejects it because it has no invertible transform.

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

Training settings:

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

  • batch_size: Positive mini-batch size used during training and scoring. 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) – Conditional normalizing flow.

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

  • n_epochs (int) – Number of training epochs.

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

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

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

  • scores (np.ndarray) – Calibrated values of \(\lVert z \rVert_2\).

Parameters:

  • estimator (Flow | GMM)

  • optimizer (Optimizer)

  • n_epochs (int)

  • batch_size (int | None)

  • verbose (bool | int)

  • random_state (int | None)

Examples

>>> import torch
>>> import zuko
>>> from pitcp import CONTRA
>>> flow = zuko.flows.SOSPF(features=1, context=1, hidden_features=(4, 4))
>>> optimizer = torch.optim.Adam(flow.parameters())
>>> model = CONTRA(flow, optimizer, n_epochs=1, verbose=False)
__init__(estimator, optimizer, *, n_epochs=10, batch_size=None, verbose=True, random_state=None)[source]

Initializes CONTRA.

Parameters:

  • estimator (Flow | GMM) – Conditional density estimator. GMM instances are rejected by fit because they have no invertible transform.

  • optimizer (Optimizer) – Torch optimizer for density training.

  • n_epochs (int, optional) – Training epochs. Defaults to 10.

  • batch_size (int | None, optional) – Training batch size. Defaults to None.

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

  • random_state (int | None, optional) – DataLoader seed. Defaults to None.

fit(X, y)[source]

Fits the conditional flow to targets.

Parameters:

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

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

Returns:

The fitted regressor.

Return type:

Self

conformalize(X, y)[source]

Calibrates latent Euclidean norms using a fitted density estimator.

Parameters:

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

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

Returns:

The calibrated regressor.

Return type:

Self

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

Tests whether targets lie inside calibrated latent balls.

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 (CONTRA)

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 (CONTRA)

Returns:

self – The updated object.

Return type:

object