integration.compute_multi_dim_pod

compute_multi_dim_pod(
    poi_grid,
    nuisance_ranges,
    model,
    X_train,
    residuals,
    bandwidth,
    dist_info,
    thresholds,
    n_mc_samples=3000,
    feature_names=None,
    poi_names=None,
)

Calculates the marginal Probability of Detection (PoD) across a grid of Parameters of Interest (PoI).

This function determines the probability that a signal will exceed a given threshold. It features a dual-path architecture for maximum efficiency:

Fast Path (Vectorized): If there are no active nuisance parameters (i.e., all extra variables are held constant as ‘slices’), it calculates the probabilities for the entire grid and all threshold vectors simultaneously in a single array operation.
Slow Path (Monte Carlo): If there are active nuisance parameters (ranges where min != max), it performs Monte Carlo integration to marginalize out the nuisance variance, running thousands of samples per grid point.

Parameters

Name	Type	Description	Default
poi_grid	np.ndarray	A 2D array of shape (N_grid_points, n_pois) containing the evaluation coordinates.	required
nuisance_ranges	Dict[str, Tuple[float, float]]	The min and max bounds for each nuisance parameter. If min == max, the parameter is treated as a constant slice.	required
model	Any	A fitted scikit-learn surrogate model (predicts the mean response).	required
X_train	np.ndarray	Original training data matrix (N_train, n_total_vars).	required
residuals	np.ndarray	Residuals from the model fit, used for local noise estimation.	required
bandwidth	float	The local kernel smoothing bandwidth for the variance model.	required
dist_info	Tuple[str, Tuple]	The (name, parameters) of the residual error distribution.	required
thresholds	Union[float, np.ndarray, list]	One or more signal detection thresholds. Providing an array triggers vectorized multi-threshold calculation.	required
n_mc_samples	int	Number of Monte Carlo draws per PoI grid point when evaluating active nuisances. Defaults to 3000.	`3000`
feature_names	list	Names of all feature columns in `X_train`, in the exact same order as the columns appear. Used to correctly map PoIs and nuisances to their physical array indices.	`None`
poi_names	list	Names of the parameters of interest (PoIs). Each entry must correspond to a name in `feature_names`.	`None`

Returns

Name	Type	Description
	Tuple[np.ndarray, np.ndarray]	Tuple[np.ndarray, np.ndarray]: - pod_integrated (np.ndarray): The PoD values. Shape is `(N_grid_points,)` if a single threshold is provided, or `(N_grid_points, N_thresholds)` if an array of thresholds is provided. - mean_integrated (np.ndarray): The expected mean signal response across the PoI grid.

Examples

# Calculate a PoD spectrum for 100 thresholds instantly (Fast Path)
pod_matrix, mean_curve = compute_multi_dim_pod(
    poi_grid=X_eval,
    nuisance_ranges={'Angle': (45.0, 45.0)}, # Constant slice
    model=kriging_model,
    X_train=X, residuals=resids, bandwidth=1.5,
    dist_info=('norm', (0, 1)),
    thresholds=np.linspace(10, 50, 100)
)