API reference#

Use background for normal workflows. It returns a Background with aligned rows, weights, reference indices, stored predictions, and diagnostics. weighting="equal" defaults to 100 rows; weighted modes reject size. Additional keyword arguments go to the corresponding advanced constructor.

cbaseline.background(predictions: ndarray, f0: ndarray | float, features: ndarray, *, weighting: Literal['equal', 'kernel', 'calibrated'] = 'equal', size: int | None = None, **kwargs: Any) → Background#

Construct a prediction-neutral empirical background.

Parameters:

  • predictions – Model outputs on the reference sample. Use scalar scores for regression or binary classification and centered-logit vectors for multiclass classification.

  • f0 – User-specified reference output.

  • features – Observed reference rows aligned with predictions.

  • weighting – "equal" (the default) selects a deterministic fixed-size equal-weight background. "kernel" returns direct localization weights. "calibrated" exponentially calibrates the kernel weights to the requested reference output.

  • size – Number of rows for weighting="equal". If omitted, defaults to 100. Invalid for weighted modes.

  • **kwargs – Additional options passed to the selected construction.

Returns:

A common interface exposing rows, weights, index, predictions, and diagnostics.

Return type:

Background

class cbaseline.Background(result: UniformBackground | WeightedBackground, weighting: Literal['equal', 'kernel', 'calibrated'])#

Common user-facing view of an equal- or weighted background.

Instances are created by background(). The underlying construction remains available through result for users who need method-specific details.

property diagnostics: dict#

Construction diagnostics from the underlying method.

property f0: ndarray | float#

Requested reference output.

property index: ndarray#

Indices of rows in the original reference sample.

property metric#

Prediction-space metric used by the construction.

property predictions: ndarray#

Model outputs associated with rows.

resampled(n_draws: int, *, random_state: int | None = None) → ndarray#

Draw an equal-weight Monte Carlo sample from a weighted background.

This method is available only for weighting='kernel' or weighting='calibrated'. For weight-blind software, prefer weighting='equal' unless an approximation to the weighted distribution is specifically required.

property rows: ndarray#

Observed feature rows in the constructed background.

property weights: ndarray#

Weights aligned with rows.

cbaseline.fit_prediction_metric(predictions: ndarray, *, covariance: ndarray | None = None, ridge: float = 1e-06, eigen_tol: float = 1e-10) → PredictionMetric#

Fit a whitening metric and remove redundant output directions.

class cbaseline.PredictionMetric(center: ndarray, eigenvectors: ndarray, eigenvalues: ndarray, discarded_eigenvectors: ndarray, discarded_eigenvalues: ndarray, ridge: float, original_dimension: int, eigen_threshold: float)#

Nonredundant whitening map for prediction gaps.

Advanced construction options#

uniform_background is the constructor behind equal-weight mode. kernel_weighted_background is the constructor behind kernel and calibrated modes. Their method-specific result objects remain available through Background.result. Prefer the common interface for integration code.

cbaseline.uniform_background(predictions: ndarray, f0: ndarray | float, features: ndarray, *, size: int, metric: PredictionMetric | None = None, covariance: ndarray | None = None, metric_ridge: float = 1e-06, eigen_tol: float = 1e-10, affine_support_atol: float = 1e-10, affine_support_rtol: float = 1e-08, tolerance: float | None = None, n_grid: int = 801, refinement_rounds: int = 3, max_shift: float | None = None, max_shift_multiplier: float = 3.0, min_direction_norm: float = 1e-12, max_pool_size: int | None = None) → UniformBackground#

Construct a fixed-size equal-weight background near f0.

Parameters:

  • predictions – Model outputs on the reference sample. Shape (n,) for scalar output or (n, k) for vector output. Multiclass use should pass centered logits.

  • f0 – Required reference output.

  • features – Observed feature rows aligned with predictions.

  • size – Exact number of rows in the equal-weight background. This fixes the downstream attribution budget.

  • metric – Optional precomputed PredictionMetric.

  • covariance – Optional covariance used when fitting the prediction-space metric.

  • affine_support_atol – Tolerances used to verify that f0 belongs to the affine output support of the reference predictions after redundant directions are removed.

  • affine_support_rtol – Tolerances used to verify that f0 belongs to the affine output support of the reference predictions after redundant directions are removed.

  • tolerance – Optional tolerance for the whitened norm of the selected background’s mean prediction gap. The construction always returns the best searched set. tolerance_met is None when no tolerance is supplied and a Boolean otherwise.

  • max_pool_size – Optional safety limit on the exact certified candidate pool. Exceeding the limit raises an error rather than silently approximating the slide.

Notes

A fixed size is a finite-sample computational choice, not an asymptotic bandwidth rule. For asymptotic localization, size can increase with the reference sample while the implied nearest-neighborhood radius shrinks.

cbaseline.kernel_weighted_background(predictions: ndarray, f0: ndarray | float, features: ndarray, *, kernel: Literal['gaussian', 'epanechnikov', 'uniform'] = 'gaussian', bandwidth: float | None = None, quantile: float | None = None, shrinking_count_constant: float = 0.5, metric: PredictionMetric | None = None, candidate_size: int | None = None, covariance: ndarray | None = None, metric_ridge: float = 1e-06, eigen_tol: float = 1e-10, affine_support_atol: float = 1e-10, affine_support_rtol: float = 1e-08, calibrate: bool = True, calibration_tolerance: float = 1e-10, calibration_raw_tolerance: float | None = None, calibration_maxiter: int = 2000, adaptive_widen: bool = True, widening_factor: float = 1.5, max_bandwidth: float | None = None, max_widening_steps: int = 12, gaussian_cutoff: float = 5.0) → WeightedBackground#

Construct a kernel-weighted background near a reference output.

See background constructions for mode selection and tuning, and diagnostics for success and failure semantics.