lf2i.simulator package

class lf2i.simulator.Simulator(poi_dim: int, data_dim: int, batch_size: int, nuisance_dim: int | None = None)

Bases: ABC

Base class for simulators. This is a template from which every simulator should inherit.

Parameters:

• poi_dim (int) – Dimensionality of the space of parameters of interest.

• data_dim (int) – Dimensionality of a single datapoint X.

• batch_size (int) – Size of data batches from a specific parameter configuration. Must be the same for observations and simulations. A simulated/observed sample batch from a specific parameter configuration will have dimensions (batch_size, data_dim).

• nuisance_dim (Optional[int], optional) – Dimensionality of the space of nuisance parameters (systematics), by default 0.

abstractmethod simulate_for_test_statistic(size: int, estimation_method: str) → Tuple[ndarray | Tensor]

Simulate a training set used to estimate the test statistic.

Parameters:

• size (int) – Number of simulations.

• estimation_method (str) – The method with which the test statistic is estimated. If likelihood-based test statistics are used, such as ACORE and BFF, then ‘likelihood’. If prediction/posterior-based test statistics are used, such as WALDO, then ‘prediction’ or ‘posterior’.

Returns:

Tuple[Union[np.ndarray, torch.Tensor]] – Y, parameters, samples (depending on the specific needs of the test statistic).

abstractmethod simulate_for_critical_values(size: int) → Tuple[ndarray | Tensor, ndarray | Tensor]

Simulate a training set used to estimate the critical values via quantile regression.

Parameters:

size (int) – Number of simulations. Note that each simulation will be a batch with dimensions (batch_size, data_dim).

Returns:

Tuple[Union[np.ndarray, torch.Tensor], Union[np.ndarray, torch.Tensor]] – Parameters, samples.

abstractmethod simulate_for_diagnostics(size: int) → Tuple[ndarray | Tensor, ndarray | Tensor]

Simulate a training set used to estimate conditional coverage via the diagnostics branch.

Parameters:

size (int) – Number of simulations. Note that each simulation will be a batch with dimensions (batch_size, data_dim).

Returns:

Tuple[Union[np.ndarray, torch.Tensor], Union[np.ndarray, torch.Tensor]] – Parameters, samples.

Submodules

lf2i.simulator.gaussian module

class lf2i.simulator.gaussian.GaussianMean(likelihood_cov: float | Tensor, prior: str, poi_space_bounds: Dict[str, float], poi_grid_size: int, poi_dim: int, data_dim: int, batch_size: int, prior_kwargs: Dict[str, float | Tensor] | None = None)

Bases: Simulator

Gaussian simulator with fixed covariance structure. Supports any parameter dimensionality and batch size. Assumes diagonal covariance matrix.

Parameter of interest: mean.

Parameters:

• likelihood_cov (Union[float, torch.Tensor]) – Covariance structure of the likelihood. If float or Tensor with only one value, it is interpreted as the (equal) variance for each component. If Tensor with poi_dim values, the i-th one is the variance of the i-th component.

• prior (str) – Either gaussian or uniform.

• poi_space_bounds (Dict[str, float]) – Bounds of the space of parameters of interest. Used to construct the parameter grid, which contains the evaluation points for the confidence regions. Must contain low and high. Assumes that each dimension of the parameter has the same bounds.

• poi_grid_size (int) – Number of points in the parameter grid. If (poi_grid_size)**(1/poi_dim) is not an integer, the closest larger number is chosen. E.g., if poi_grid_size == 1000 and poi_dim == 2, then the grid will have 32 x 32 = 1024 points.

• poi_dim (int) – Dimensionality of the parameter of interest.

• data_dim (int) – Dimensionality of the data.

• batch_size (int) – Size of each batch of samples generated from a specific parameter value.

• prior_kwargs (Optional[Dict[Union[float, torch.Tensor]]], optional) – If prior == ‘gaussian’, must contain loc and cov. These can be scalars or tensors, as specified for likelihood_cov. If prior == ‘uniform’, must contain ‘low’ and ‘high’. Assumes that each dimension of the parameter has the same bounds. If None, parameter_space_bounds is used.

simulate_for_test_statistic(size: int, estimation_method: str) → Tuple[Tensor]

Simulate a training set used to estimate the test statistic.

Parameters:

• size (int) – Number of simulations.

• estimation_method (str) – The method with which the test statistic is estimated. If likelihood-based test statistics are used, such as ACORE and BFF, then ‘likelihood’. If prediction/posterior-based test statistics are used, such as WALDO, then ‘prediction’ or ‘posterior’.

Returns:

Tuple[Union[np.ndarray, torch.Tensor]] – Y, parameters, samples (depending on the specific needs of the test statistic).

simulate_for_critical_values(size: int) → Tuple[Tensor]

Simulate a training set used to estimate the critical values via quantile regression.

Parameters:

size (int) – Number of simulations. Note that each simulation will be a batch with dimensions (batch_size, data_dim).

Returns:

Tuple[Union[np.ndarray, torch.Tensor], Union[np.ndarray, torch.Tensor]] – Parameters, samples.

simulate_for_diagnostics(size: int) → Tuple[Tensor]

Simulate a training set used to estimate conditional coverage via the diagnostics branch.

Parameters:

size (int) – Number of simulations. Note that each simulation will be a batch with dimensions (batch_size, data_dim).

Returns:

Tuple[Union[np.ndarray, torch.Tensor], Union[np.ndarray, torch.Tensor]] – Parameters, samples.

lf2i.simulator.gmm module

class lf2i.simulator.gmm.GaussianMixtureLocation(poi_space_bounds: Dict[str, float], poi_grid_size: int, poi_dim: int, data_dim: int, batch_size: int, mixture_weights: Tensor | None = None, mixture_scales: Tensor | None = None, prior_kwargs: Dict[str, float | Tensor] | None = None)

Bases: Simulator

Gaussian mixture simulator for inference of a location parameter.

The likelihood is a two-component Gaussian mixture:

X | theta ~ w_0 * N(theta, sigma_0^2 I) + w_1 * N(theta, sigma_1^2 I)

where the mixture weights and component scales are fixed.

The prior over theta is an isotropic Gaussian: theta ~ N(prior_loc, prior_cov * I).

Parameters:

• poi_space_bounds (Dict[str, float]) – Bounds for the parameter grid (‘low’ and ‘high’). Each dimension shares the same bounds.

• poi_grid_size (int) – Number of points in the parameter grid. For poi_dim > 1 the actual grid size may be slightly larger (rounded up per dimension).

• poi_dim (int) – Dimensionality of the location parameter theta.

• data_dim (int) – Dimensionality of each observation (must equal poi_dim).

• batch_size (int) – Number of observations drawn for each parameter value.

• mixture_weights (torch.Tensor, optional) – Two-element tensor of mixture weights. Defaults to [0.5, 0.5].

• mixture_scales (torch.Tensor, optional) – Two-element tensor of per-component standard deviations. Defaults to [1.0, 0.1].

• prior_kwargs (Dict[str, Union[float, torch.Tensor]], optional) – Must contain ‘loc’ (scalar or Tensor) and ‘cov’ (scalar) for the isotropic Gaussian prior. Defaults to standard normal: loc=0, cov=1.

likelihood(loc: Tensor) → MixtureSameFamily

Return the mixture likelihood distribution at a given location parameter.

Parameters:

loc (torch.Tensor) – Shape (poi_dim,) — a single parameter value.

Returns:

torch.distributions.MixtureSameFamily – The mixture distribution X | theta = loc.

simulate_for_test_statistic(size: int, estimation_method: str) → Tuple[Tensor, Tensor]

Simulate a training set used to estimate the test statistic.

Parameters:

• size (int) – Number of simulations.

• estimation_method (str) – The method with which the test statistic is estimated. If likelihood-based test statistics are used, such as ACORE and BFF, then ‘likelihood’. If prediction/posterior-based test statistics are used, such as WALDO, then ‘prediction’ or ‘posterior’.

Returns:

Tuple[Union[np.ndarray, torch.Tensor]] – Y, parameters, samples (depending on the specific needs of the test statistic).

simulate_for_critical_values(size: int) → Tuple[Tensor, Tensor]

Simulate a training set used to estimate the critical values via quantile regression.

Parameters:

size (int) – Number of simulations. Note that each simulation will be a batch with dimensions (batch_size, data_dim).

Returns:

Tuple[Union[np.ndarray, torch.Tensor], Union[np.ndarray, torch.Tensor]] – Parameters, samples.

simulate_for_diagnostics(size: int) → Tuple[Tensor, Tensor]

Simulate a training set used to estimate conditional coverage via the diagnostics branch.

Parameters:

size (int) – Number of simulations. Note that each simulation will be a batch with dimensions (batch_size, data_dim).

Returns:

Tuple[Union[np.ndarray, torch.Tensor], Union[np.ndarray, torch.Tensor]] – Parameters, samples.

lf2i.simulator.hep module

class lf2i.simulator.hep.OnOff(poi_grid_size: int, batch_size: int, poi_space_bounds: Dict[str, float] | None = None, nuisance_space_bounds: Dict[str, float] | None = None, s: float | None = None, b: float | None = None, tau: float | None = None)

Bases: Simulator

Poisson counting experiment (“on-off” problem), as described in https://arxiv.org/abs/2107.03920.

Parameter of interest is signal strength mu. Nuisance is background scaling factor nu. In addition, the following are treated as fixed hyperparameters:

• Nominally expected signal and background counts s and b.

• Relationship in measurement time between the two processes tau.

Parameters:

• poi_grid_size (int) – Number of points in the parameter grid over mu.

• batch_size (int) – Size of each batch of samples generated from a specific parameter value.

• poi_space_bounds (Optional[Dict[str, float]], optional) – Bounds of mu. Must contain ‘low’ and ‘high’. Defaults to {‘low’: 0, ‘high’: 5}.

• nuisance_space_bounds (Optional[Dict[str, float]], optional) – Bounds of nu. Must contain ‘low’ and ‘high’. Defaults to {‘low’: 0.6, ‘high’: 1.4}.

• s (Optional[float], optional) – Nominally expected signal count. Defaults to 15.

• b (Optional[float], optional) – Nominally expected background count. Defaults to 70.

• tau (Optional[float], optional) – Relationship in measurement time between the two processes. Defaults to 1.

property param_space_bounds: Dict[str, List[float]]

simulate_for_test_statistic(size: int, estimation_method: str) → Tuple[Tensor]

Simulate a training set used to estimate the test statistic.

Parameters:

• size (int) – Number of simulations.

• estimation_method (str) – The method with which the test statistic is estimated. If likelihood-based test statistics are used, such as ACORE and BFF, then ‘likelihood’. If prediction/posterior-based test statistics are used, such as WALDO, then ‘prediction’ or ‘posterior’.

Returns:

Tuple[Union[np.ndarray, torch.Tensor]] – Y, parameters, samples (depending on the specific needs of the test statistic).

simulate_for_critical_values(size: int) → Tuple[Tensor]

Simulate a training set used to estimate the critical values via quantile regression.

Parameters:

size (int) – Number of simulations. Note that each simulation will be a batch with dimensions (batch_size, data_dim).

Returns:

Tuple[Union[np.ndarray, torch.Tensor], Union[np.ndarray, torch.Tensor]] – Parameters, samples.

simulate_for_diagnostics(size: int) → Tuple[Tensor]

Simulate a training set used to estimate conditional coverage via the diagnostics branch.

Parameters:

size (int) – Number of simulations. Note that each simulation will be a batch with dimensions (batch_size, data_dim).

Returns:

Tuple[Union[np.ndarray, torch.Tensor], Union[np.ndarray, torch.Tensor]] – Parameters, samples.