# API Reference

[Installation](installation.md) |
[Core concepts](concepts.md) |
[Mechanisms](mechanisms.md) |
[Patterns](patterns.md) |
[Mathematical details](mathematical_details.md) |
[Benchmarking workflow](benchmarking.md) |
[API reference](api.md)

## `simulate_missingness`

```python
simulate_missingness(
    X,
    mechanism,
    missing_rate,
    seed=None,
    pattern="pointwise",
    **kwargs,
)
```

Simulate missingness in a 2D `(time, features)` or 3D
`(samples, time, features)` NumPy array.

Returns:

```python
X_missing, mask
```

where `X_missing` is a copy of `X` with NaNs inserted and `mask` is a boolean
array with `True` for observed values and `False` for missing values.

Core parameters:

| Parameter | Type | Description |
|-----------|------|-------------|
| `X` | `np.ndarray` | Input data, shape `(T, D)` or `(N, T, D)` |
| `mechanism` | `str` | `"mcar"`, `"mar"`, or `"mnar"` |
| `missing_rate` | `float` | Target fraction missing, clipped to `[0, 1]` |
| `seed` | `int \| None` | Random seed |
| `pattern` | `str` | Missingness pattern |

Mechanism parameters:

| Parameter | Mechanisms | Default | Description |
|-----------|------------|---------|-------------|
| `target` | all | `"all"` | Dimensions to mask |
| `driver_dims` | MAR | `[0]` | Driver dimensions |
| `driver_weights` | MAR | `None` | Per-driver weights |
| `strength` | MAR, MNAR | `2.0` | Dependency strength |
| `base_rate` | MAR | `0.01` | Minimum probability floor |
| `direction` | MAR | `"positive"` | Driver direction |
| `mnar_mode` | MNAR | `"extreme"` | MNAR scoring mode |

Pattern parameters:

| Parameter | Patterns | Default | Description |
|-----------|----------|---------|-------------|
| `block_len` | block | `10` | Block length in timesteps |
| `block_frac` | block | `None` | Relative block length as a fraction of the time axis, or `(min_frac, max_frac)` for variable-length blocks. Recommended for long time series. |
| `block_density` | block | `1.0` | Fraction of missingness in blocks. Set below `1.0` to retain some pointwise missingness. |
| `decay_rate` | decay | `3.0` | Decay ramp steepness |
| `decay_center` | decay | `0.7` | Normalized ramp center |
| `persist` | markov, gilbert_elliott | `0.8` | Missing/bad-state persistence. For `gilbert_elliott`, MCAR only. |
| `bad_loss` | gilbert_elliott | `1.0` | Loss probability in the bad state. MCAR only. |
| `good_loss` | gilbert_elliott | `0.0` | Loss probability in the good state. MCAR only. For partial rates, `good_loss <= missing_rate < bad_loss`. |

`gilbert_elliott` supports only `mechanism="mcar"`. `missing_rate=0` adds no
artificial missingness and `missing_rate=1` masks all eligible entries. Partial
rates outside the feasible range defined by `good_loss` and `bad_loss` raise
`ValueError`.

## `simulate_many_rates`

```python
from tsgap import simulate_many_rates

rates = [0.05, 0.15, 0.25]
results = simulate_many_rates(X, "mcar", rates, seed=42)
```

Returns a dictionary mapping each rate to `(X_missing, mask)`. When a seed is
provided, each rate gets a deterministic offset from the base seed.

## `MissingnessSimulator`

```python
from tsgap import MissingnessSimulator

sim = MissingnessSimulator(
    "mar", missing_rate=0.25, seed=42,
    driver_dims=[0], pattern="block", block_len=10
)

X_missing, mask = sim.generate(X)
```

This object-oriented wrapper is useful when the same missingness configuration
is applied to multiple arrays.

## Registries

```python
from tsgap import MECHANISMS, PATTERNS

print(MECHANISMS.keys())
print(PATTERNS.keys())
```

The registries expose the currently available mechanism and pattern names,
including aliases.