API Reference

Installation | Core concepts | Mechanisms | Patterns | Mathematical details | Benchmarking workflow | API reference

simulate_missingness

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:

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

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

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

from tsgap import MECHANISMS, PATTERNS

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

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