# Asimov Datasets

## What is an Asimov dataset?

An Asimov dataset is the expected observation under a specific hypothesis,
generated by `predict_fn(state)` at a chosen POI value (`mu_asimov`). It
provides a deterministic substitute for real data, giving the median expected
outcome under the assumed hypothesis.

## When is it needed?

The Asimov dataset is used to compute `q_asimov`, the test statistic evaluated
on Asimov data. Some asymptotic distributions need `q_asimov` for p-value
computation:

| Distribution | null p-value | alt p-value | expected bands |
|---|---|---|---|
| TMuAsymptotic | no Asimov needed | needs Asimov | needs Asimov |
| QMuAsymptotic | no Asimov needed | needs Asimov | needs Asimov |
| Q0Asymptotic | no Asimov needed | needs Asimov | needs Asimov |
| QTildeAsymptotic | **needs Asimov** | needs Asimov | needs Asimov |
| TMuTildeAsymptotic | **needs Asimov** | needs Asimov | needs Asimov |

## What happens without it?

When `predict_fn` is not provided and no `asimov_observation` is given,
`q_asimov` is `None`. Computations that need it issue a warning and return
`None`. Downstream effects:

- `CLs` returns `None` if `palt` is `None`
- `calc.expected()` returns `None`

**Practical summary**: If you only need `null_pval` with TMu/QMu/Q0
distributions, no Asimov is needed. For CLs limits or Brazil bands, you need it.

## How to provide Asimov data

There are two ways:

1. **`predict_fn`** (standard): Passed to `AsymptoticCalculator` or directly to
   the test statistic. The Asimov dataset is generated at `mu_asimov`.

   ```python
   calc = AsymptoticCalculator(
       nll_fn=nll,
       params=params,
       observation=observed,
       poi_key="mu",
       predict_fn=predict,
       mu_asimov=0.0,  # background-only Asimov
   )
   ```

2. **`asimov_observation`** (pre-computed): Pass a pre-computed Asimov dataset
   directly to the test statistic.

   ```python
   result = QTilde().compute(
       nll,
       params,
       observed,
       "mu",
       poi_test=1.0,
       asimov_observation={"n": 5.0},
   )
   ```

## Choosing `mu_asimov`

- **`mu_asimov=0.0`** (default): Background-only hypothesis. Use for exclusion
  tests and upper limits.
- **`mu_asimov=1.0`**: Signal+background hypothesis. Use for discovery tests.

## Asimov as observation proxy

Separately from variance estimation, passing an Asimov dataset as `observation`
to `fit()` or `calc.test()` gives expected results under a hypothesis. This is
useful for computing expected limits or expected significances without real data.