Domain-Specific Generators

`IntermittentDemandGenerator`

Bases: BaseGenerator Generate intermittent demand time series with sparse patterns. Demand is a two-part process: a binary occurrence process decides at which periods demand happens, and a size distribution draws the demand quantity for those periods (all other periods are zero). Common in retail, spare parts, and inventory contexts (Croston-style demand). Size distributions are moment-matched to (demand_mean, demand_std):

‘poisson’: Poisson(demand_mean); demand_std is ignored.
‘negative_binomial’: p = mean/var, n = mean*p/(1-p); falls back to Poisson when demand_std**2 <= demand_mean.
‘lognormal’: mu = ln(mean^2 / sqrt(var + mean^2)), sigma^2 = ln(1 + var/mean^2).
‘gamma’: shape = (mean/std)^2, scale = var/mean. Sizes are clipped from below at min_demand.

Parameters:

Name	Type	Description	Default
`min_length`	`int`	Minimum length of each series	required
`max_length`	`int`	Maximum length of each series	required
`freq`	`str \| int`	Frequency of the data (e.g. ‘D’, ‘h’, ‘5min’) or int	required
`demand_probability`	`float`	Probability of non-zero demand per period (occurrence-pattern dependent, see above) (default: 0.2)	required
`demand_distribution`	`str`	Distribution for non-zero demand sizes (default: ‘poisson’)	required
`demand_mean`	`float`	Mean of demand when non-zero (default: 5.0)	required
`demand_std`	`float`	Std of demand when non-zero (default: 2.0)	required
`intermittent_pattern`	`str`	Occurrence pattern: ‘random’, ‘clustered’ or ‘seasonal’ (default: ‘random’)	required
`cluster_size`	`int`	Size of demand clusters (default: 3)	required
`seasonal_period`	`int`	Period for seasonal intermittency (default: 12)	required
`seasonal_peak_prob`	`float`	Peak occurrence probability at the start of each seasonal cycle (default: 0.4)	required
`min_demand`	`int`	Minimum non-zero demand value (default: 1)	required
`seed`	`int \| None`	Random seed for reproducibility (default: None)	required

`IntermittentDemandGenerator.generate_single_series`

generate_single_series(length)

Generate values for a single intermittent demand time series. Parameters:

Name	Type	Description	Default
`length`	`int`	The length of the series to generate	required

Returns:

Type	Description
`ndarray`	Array of values (mostly zeros with intermittent demand)

`IoTSensorGenerator`

Bases: BaseGenerator Generate IoT sensor readings with realistic degradation patterns. The signal is base_value + trend * t plus optional sinusoidal seasonality, a calibration offset, a cumulative drift random walk (drift_rate per step with drift_noise variation), and Gaussian measurement noise. After battery_life steps, noise grows and the signal is attenuated at battery_degradation_rate. Failures can be injected as NaN gaps (‘intermittent’), a permanent NaN tail (‘complete’), or frozen readings (‘stuck’). With n_sensors > 1, each generated “series” is a network of sensors whose measurement noise is spatially correlated (corr[i, j] = spatial_correlation ** |i - j|); each sensor becomes a separate output series. Parameters:

Name	Type	Description	Default
`min_length`	`int`	Minimum length of each series.	required
`max_length`	`int`	Maximum length of each series.	required
`freq`	`str \| int`	Frequency of the data, e.g. ‘s’, ‘min’, ‘h’.	required
`n_sensors`	`int`	Sensors per network (default: 1).	required
`sensor_type`	`str`	’temperature’, ‘humidity’, ‘pressure’, ‘light’, ‘motion’ or ‘generic’ (default: ‘temperature’).	required
`base_value`	`float \| None`	Base sensor reading (default: typical value for sensor_type).	required
`trend`	`float`	Linear trend per time step (default: 0.0).	required
`seasonal_period`	`int`	Seasonal cycle length in steps, 0 disables (default: 0).	required
`seasonal_amplitude`	`float`	Amplitude of seasonal variation (default: 0.0).	required
`measurement_noise`	`float`	Std of measurement noise (default: 0.1).	required
`drift_rate`	`float`	Deterministic sensor drift per step (default: 0.0).	required
`drift_noise`	`float`	Std of the random drift component (default: 0.01).	required
`calibration_error`	`float`	Constant calibration offset (default: 0.0).	required
`battery_life`	`int \| None`	Steps until battery degradation starts, None disables (default: None).	required
`battery_degradation_rate`	`float`	Rate of quality loss per step after battery_life (default: 0.001).	required
`failure_probability`	`float`	Probability of sensor failure (default: 0.0). For ‘complete’: probability the series fails at all; for ‘intermittent’/‘stuck’: per-step probability of starting a failure episode.	required
`failure_type`	`str`	’intermittent’, ‘complete’ or ‘stuck’ (default: ‘intermittent’).	required
`failure_duration`	`int`	Length of intermittent/stuck episodes (default: 10).	required
`stuck_value`	`float \| None`	Reading during ‘stuck’ failures (default: the reading at episode start).	required
`spatial_correlation`	`float`	Noise correlation between adjacent sensors in a network (default: 0.5).	required
`seed`	`int \| None`	Random seed for reproducibility (default: None).	required

`IoTSensorGenerator.generate_single_series`

generate_single_series(length)

Generate values for a single sensor. Parameters:

Name	Type	Description	Default
`length`	`int`	The length of the series to generate.	required

Returns:

Type	Description
`ndarray`	Array of sensor readings (NaN during failures).

`IoTSensorGenerator.generate`

generate(n_series, start_id=0, n_jobs=-1)

Generate IoT sensor data. With n_sensors == 1, generates n_series independent sensors. With n_sensors > 1, generates n_series sensor networks, each contributing n_sensors correlated series. Parameters:

Name	Type	Description	Default
`n_series`	`int`	Number of series/networks to generate.	required
`start_id`	`int`	Starting ID for the series numbering (default: 0).	`0`
`n_jobs`	`int`	Ignored; generation is sequential.	`-1`

Returns:

Type	Description
`IntoDataFrameT`	DataFrame in long format with columns [id_col, time_col, target_col].

`EnergyLoadGenerator`

Bases: BaseGenerator Generate electricity demand with nested daily/weekly/yearly cycles. The load is a base level plus:

A daily profile depending on load_type: residential has Gaussian morning/evening peaks, commercial a broad midday peak, industrial a near-constant profile with a night dip.
A weekly cycle: weekend reduction for residential/commercial, a sinusoidal pattern for industrial.
A yearly cosine cycle peaking around the series start (winter).
Temperature-driven load: both heating (cold) and cooling (hot) increase demand proportionally to |temperature - base_temperature|.
Holiday reductions, random extreme-weather multipliers, and Gaussian noise. The result is clipped at zero.

Hour of day, day of week and day of year are derived from the step position relative to the series start using the step size implied by freq (an integer freq is treated as hourly). Parameters:

Name	Type	Description	Default
`min_length`	`int`	Minimum length of each series.	required
`max_length`	`int`	Maximum length of each series.	required
`freq`	`str \| int`	Frequency of the data, e.g. ‘h’, ‘15min’, ‘D’.	required
`base_load`	`float`	Base load in kW or MW (default: 100.0).	required
`load_type`	`str`	’residential’, ‘commercial’ or ‘industrial’ (default: ‘residential’).	required
`daily_pattern`	`bool`	Enable the daily cycle (default: True).	required
`daily_amplitude`	`float`	Amplitude of the daily variation (default: 30.0).	required
`weekly_pattern`	`bool`	Enable the weekly cycle (default: True).	required
`weekly_amplitude`	`float`	Amplitude of the weekly variation (default: 15.0).	required
`yearly_pattern`	`bool`	Enable the yearly cycle (default: True).	required
`yearly_amplitude`	`float`	Amplitude of the yearly variation (default: 20.0).	required
`temperature_sensitive`	`bool`	Enable temperature effects (default: True).	required
`temperature_sensitivity`	`float`	Load change per degree of deviation from base_temperature (default: 2.0).	required
`base_temperature`	`float`	Reference temperature in Celsius (default: 20.0).	required
`morning_peak_hour`	`int`	Hour of the residential morning peak (default: 8).	required
`evening_peak_hour`	`int`	Hour of the residential evening peak (default: 19).	required
`peak_amplitude`	`float`	Additional load at the residential peaks (default: 40.0).	required
`holiday_effect`	`float`	Fractional load reduction on holidays (default: 0.3).	required
`holiday_days`	`list[int]`	Day-of-year indices (0-364) that are holidays (default: []).	required
`extreme_weather_prob`	`float`	Per-step probability of extreme weather (default: 0.0).	required
`extreme_weather_impact`	`float`	Load multiplier during extreme weather (default: 1.5).	required
`noise_std`	`float`	Standard deviation of additive noise (default: 5.0).	required
`seed`	`int \| None`	Random seed for reproducibility (default: None).	required

`EnergyLoadGenerator.generate_single_series`

generate_single_series(length)

Generate values for a single energy load series. Parameters:

Name	Type	Description	Default
`length`	`int`	The length of the series to generate.	required

Returns:

Type	Description
`ndarray`	Array of energy load values.

`StateSpaceGenerator`

Bases: BaseGenerator Generate time series from a (linear-Gaussian or custom) state space model. The linear model is:

x[t] = F x[t-1] + w[t],  w[t] ~ (0, Q)   (state equation)
y[t] = H x[t] + v[t],    v[t] ~ N(0, R)  (observation equation)

with x[0] ~ N(initial_state, initial_state_covariance). State noise w follows the configured innovation distribution (scaled by the Cholesky/PSD factor of Q); observation noise v is Gaussian. The univariate output is the first observation dimension y[t][0], with y[0] observing the initial state. Custom nonlinear dynamics can be supplied via transition_fn / observation_fn, each called as fn(x, t, rng). Parameters:

Name	Type	Description	Default
`min_length`	`int`	Minimum length of each series.	required
`max_length`	`int`	Maximum length of each series.	required
`freq`	`str \| int`	Frequency of the data. A pandas offset alias (e.g. ‘D’, ‘h’, ‘5min’, ‘MS’) or an integer time index step.	required
`state_dim`	`int`	Dimension of the hidden state vector (default: 1).	required
`obs_dim`	`int`	Dimension of the observation vector (default: 1).	required
`transition_matrix`	`list[list[float]] \| None`	State transition matrix F, shape (state_dim, state_dim). When None (and no transition_fn), a random stable matrix is generated.	required
`observation_matrix`	`list[list[float]] \| None`	Observation matrix H, shape (obs_dim, state_dim). Default observes the first state.	required
`state_covariance`	`list[list[float]] \| None`	State noise covariance Q, symmetric PSD (default: 0.1 * I).	required
`obs_covariance`	`list[list[float]] \| None`	Observation noise covariance R, symmetric PSD (default: 0.1 * I).	required
`transition_fn`	`Callable \| None`	Custom state transition function.	required
`observation_fn`	`Callable \| None`	Custom observation function.	required
`initial_state`	`list[float] \| None`	Initial state mean (default: zeros).	required
`initial_state_covariance`	`list[list[float]] \| None`	Initial state covariance, symmetric PSD (default: identity).	required
`seed`	`int \| None`	Random seed for reproducibility (default: None).	required
`id_col`	`str`	Name of the ID column (default: ‘unique_id’).	required
`time_col`	`str`	Name of the timestamp column (default: ‘ds’).	required
`target_col`	`str`	Name of the value column (default: ‘y’).	required
`start_datetime`	`str`	First timestamp (default: ‘2000-01-01’).	required

`StateSpaceGenerator.generate_single_series`

generate_single_series(length)

Generate values for a single state space series. Parameters:

Name	Type	Description	Default
`length`	`int`	The length of the series to generate.	required

Returns:

Type	Description
`ndarray`	Observed values (first observation dimension).

`StateSpaceGenerator.generate_with_states`

generate_with_states(n_series=1, start_id=0)

Generate series and return both observations and hidden states. Only missingness is applied to the observations (changepoints and anomalies would desynchronize them from the returned states). Parameters:

Name	Type	Description	Default
`n_series`	`int`	Number of series to generate (default: 1).	`1`
`start_id`	`int`	Starting ID for series numbering (default: 0).	`0`

Returns: (observations DataFrame in long format, states DataFrame with one state_j column per state dimension).

`DailyActiveUsersGenerator`

Bases: BaseGenerator Generate Daily Active Users time series with event-driven jumps. The DAU level is base_users * (1 + growth_rate)^day with a weekend multiplier, plus a decaying boost from random events: with probability event_probability per step an event adds (impact - 1) * base to a boost that decays geometrically at rate event_decay_rate. Proportional Gaussian noise is added and the result is clipped at zero. The day index is derived from the step position relative to the series start using the step size implied by freq (an integer freq is treated as daily). Weekends are day indices 5 and 6 of each 7-day block. Also outputs an exogenous column marking the steps where events occur, usable as a feature for forecasting models. Parameters:

Name	Type	Description	Default
`min_length`	`int`	Minimum length of each series.	required
`max_length`	`int`	Maximum length of each series.	required
`freq`	`str \| int`	Frequency of the data, e.g. ‘D’, ‘h’.	required
`base_users`	`float`	Base number of daily active users (default: 10000.0).	required
`growth_rate`	`float`	Daily organic growth rate (default: 0.0005).	required
`growth_rate_std`	`float`	Std dev of a per-series perturbation of growth_rate (default: 0.0).	required
`app_type`	`str`	’consumer’, ‘business’ or ‘gaming’ (default: ‘consumer’).	required
`weekly_pattern`	`bool`	Enable weekly seasonality (default: True).	required
`weekend_factor`	`float \| None`	Multiplier for weekend activity (default: 1.2 for gaming, 0.8 otherwise).	required
`event_probability`	`float`	Per-step probability of an event (default: 0.02).	required
`event_impact_min`	`float`	Minimum event impact multiplier (default: 1.2).	required
`event_impact_max`	`float`	Maximum event impact multiplier (default: 2.0).	required
`event_decay_rate`	`float`	Per-step decay rate of the event boost (default: 0.1).	required
`noise_std`	`float`	Std of noise relative to the current level (default: 0.05).	required
`event_col`	`str`	Name of the event indicator column (default: ‘event’).	required
`seed`	`int \| None`	Random seed for reproducibility (default: None).	required

`DailyActiveUsersGenerator.generate_single_series`

generate_single_series(length)

Generate values for a single DAU time series. Also populates self._current_events with event indicators. Parameters:

Name	Type	Description	Default
`length`	`int`	The length of the series to generate.	required

Returns:

Type	Description
`ndarray`	Array of DAU values.

`DailyActiveUsersGenerator.generate`

generate(n_series, start_id=0, n_jobs=-1)

Generate synthetic DAU time series data with event indicators. Parameters:

Name	Type	Description	Default
`n_series`	`int`	Number of time series to generate.	required
`start_id`	`int`	Starting ID for the series numbering (default: 0).	`0`
`n_jobs`	`int`	Ignored; generation is sequential.	`-1`

Returns:

Type	Description
`IntoDataFrameT`	DataFrame in long format with columns [id_col, time_col, target_col, event_col], where event_col is 1 at steps where an event occurred.

`VitalSignsGenerator`

Bases: BaseGenerator Generate realistic vital signs time series for healthcare applications. Simulates one of six vital signs (heart rate, systolic/diastolic blood pressure, respiratory rate, SpO2, temperature) as a per-series baseline plus a slow random-walk drift, a circadian rhythm, heart rate variability (for HR and BP), random physiological events (activity bursts, rest periods, spikes), measurement noise, and cross-vital correlations with heart rate. Values are clipped to physiological bounds that depend on the patient archetype. Parameters:

Name	Type	Description	Default
`min_length`	`int`	Minimum length of each series.	required
`max_length`	`int`	Maximum length of each series.	required
`freq`	`str \| int`	Frequency of the data; use ‘min’ for correct circadian/HRV periods.	required
`patient_type`	`str`	’healthy’, ‘cardiac’, ‘sepsis’, ‘respiratory’ or ‘hypertensive’ (default: ‘healthy’).	required
`vital_sign`	`str`	Which vital sign to output (default: ‘heart_rate’).	required
`include_circadian`	`bool`	Include circadian rhythm effects (default: True).	required
`include_hrv`	`bool`	Include heart rate variability (default: True).	required
`include_events`	`bool`	Include random physiological events (default: True).	required
`event_probability`	`float`	Per-step probability of an event (default: 0.01).	required
`seed`	`int \| None`	Random seed for reproducibility (default: None).	required

`VitalSignsGenerator.generate_single_series`

generate_single_series(length)

Generate values for a single vital signs time series. Parameters:

Name	Type	Description	Default
`length`	`int`	The length of the series to generate.	required

Returns:

Type	Description
`ndarray`	Array of vital sign values.

`VitalSignsGenerator.generate_all_vitals`

generate_all_vitals(n_series=1, start_id=0)

Generate all six vital signs for complete patient monitoring. Parameters:

Name	Type	Description	Default
`n_series`	`int`	Number of patients/series to generate.	`1`
`start_id`	`int`	Starting ID for the series numbering.	`0`

Returns:

Type	Description
`IntoDataFrameT`	DataFrame with columns [id_col, time_col] plus one column per vital sign, aligned on the same timestamps per patient.

`VitalSignsGenerator.get_model_info`

get_model_info()

Get information about the vital signs model. Returns:

Type	Description
`dict`	Model parameters and patient characteristics.

`ClickstreamGenerator`

Bases: BaseGenerator Generate web clickstream/session time series for analytics applications. Human sessions per time bin are Poisson-distributed around base_sessions modulated by hour-of-day/day-of-week seasonality and a slow log-random-walk trend. Bot traffic (flatter profile plus occasional crawl spikes) can be added on top. Bounces, pageviews (geometric page depth for engaged sessions) and conversions are derived per bin from the human sessions, with multipliers depending on traffic_source. Output types:

‘sessions’: total session counts (human + bot) per time bin
‘pageviews’: total pageviews per time bin
‘conversions’: conversion counts per time bin
‘bounce_rate’: bounced fraction of total sessions per time bin

Parameters:

Name	Type	Description	Default
`min_length`	`int`	Minimum length of each series.	required
`max_length`	`int`	Maximum length of each series.	required
`freq`	`str \| int`	Frequency of the data; use ‘h’ for correct seasonality patterns.	required
`base_sessions`	`float`	Baseline sessions per time bin (default: 100).	required
`traffic_source`	`str`	’organic’, ‘paid’, ‘direct’, ‘referral’ or ‘mixed’ (default: ‘mixed’).	required
`conversion_rate`	`float`	Base conversion rate for engaged sessions (default: 0.03).	required
`bounce_rate`	`float`	Base rate of single-page sessions (default: 0.40).	required
`avg_session_depth`	`float`	Average pages per engaged session (default: 3.5).	required
`include_seasonality`	`bool`	Include time-of-day and day-of-week patterns (default: True).	required
`include_bots`	`bool`	Include bot traffic (default: True).	required
`bot_fraction`	`float`	Fraction of traffic from bots, < 1.0 (default: 0.15).	required
`output_type`	`str`	Metric to output (default: ‘sessions’).	required
`seed`	`int \| None`	Random seed for reproducibility (default: None).	required

`ClickstreamGenerator.generate_single_series`

generate_single_series(length)

Generate values for a single clickstream time series. Parameters:

Name	Type	Description	Default
`length`	`int`	The length of the series to generate.	required

Returns:

Type	Description
`ndarray`	Array of metric values.

`ClickstreamGenerator.generate_full_metrics`

generate_full_metrics(n_series=1, start_id=0)

Generate all clickstream metrics for complete analytics. Parameters:

Name	Type	Description	Default
`n_series`	`int`	Number of series to generate.	`1`
`start_id`	`int`	Starting ID for series naming.	`0`

Returns:

Type	Description
`dict[str, ndarray]`	All metrics as flat arrays, keyed by metric name plus ‘series_id’.

`ClickstreamGenerator.generate_funnel`

generate_funnel(n_sessions=1000, stages=None)

Generate a conversion funnel with stage-by-stage drop-off. Retention between stages rises from ~0.4 to ~0.7 (committed users drop off less), adjusted by the traffic source’s conversion multiplier. Parameters:

Name	Type	Description	Default
`n_sessions`	`int`	Number of sessions entering the funnel.	`1000`
`stages`	`list[str] \| None`	Funnel stage names (default: standard e-commerce funnel).	`None`

Returns:

Type	Description
`dict[str, int]`	Stage name -> session count at that stage.

`ClickstreamGenerator.get_model_info`

get_model_info()

Get information about the clickstream model. Returns:

Type	Description
`dict`	Model parameters and traffic characteristics.

Getting Started

Capabilities

Generators

Nixtlaverse

API Reference

Domain-Specific Generators

`IntermittentDemandGenerator`

`IntermittentDemandGenerator.generate_single_series`

`IoTSensorGenerator`

`IoTSensorGenerator.generate_single_series`

`IoTSensorGenerator.generate`

`EnergyLoadGenerator`

`EnergyLoadGenerator.generate_single_series`

`StateSpaceGenerator`

`StateSpaceGenerator.generate_single_series`

`StateSpaceGenerator.generate_with_states`

`DailyActiveUsersGenerator`

`DailyActiveUsersGenerator.generate_single_series`

`DailyActiveUsersGenerator.generate`

`VitalSignsGenerator`

`VitalSignsGenerator.generate_single_series`

`VitalSignsGenerator.generate_all_vitals`

`VitalSignsGenerator.get_model_info`

`ClickstreamGenerator`

`ClickstreamGenerator.generate_single_series`

`ClickstreamGenerator.generate_full_metrics`

`ClickstreamGenerator.generate_funnel`

`ClickstreamGenerator.get_model_info`

​IntermittentDemandGenerator

​IntermittentDemandGenerator.generate_single_series

​IoTSensorGenerator

​IoTSensorGenerator.generate_single_series

​IoTSensorGenerator.generate

​EnergyLoadGenerator

​EnergyLoadGenerator.generate_single_series

​StateSpaceGenerator

​StateSpaceGenerator.generate_single_series

​StateSpaceGenerator.generate_with_states

​DailyActiveUsersGenerator

​DailyActiveUsersGenerator.generate_single_series

​DailyActiveUsersGenerator.generate

​VitalSignsGenerator

​VitalSignsGenerator.generate_single_series

​VitalSignsGenerator.generate_all_vitals

​VitalSignsGenerator.get_model_info

​ClickstreamGenerator

​ClickstreamGenerator.generate_single_series

​ClickstreamGenerator.generate_full_metrics

​ClickstreamGenerator.generate_funnel

​ClickstreamGenerator.get_model_info

`IntermittentDemandGenerator`

`IntermittentDemandGenerator.generate_single_series`

`IoTSensorGenerator`

`IoTSensorGenerator.generate_single_series`

`IoTSensorGenerator.generate`

`EnergyLoadGenerator`

`EnergyLoadGenerator.generate_single_series`

`StateSpaceGenerator`

`StateSpaceGenerator.generate_single_series`

`StateSpaceGenerator.generate_with_states`

`DailyActiveUsersGenerator`

`DailyActiveUsersGenerator.generate_single_series`

`DailyActiveUsersGenerator.generate`

`VitalSignsGenerator`

`VitalSignsGenerator.generate_single_series`

`VitalSignsGenerator.generate_all_vitals`

`VitalSignsGenerator.get_model_info`

`ClickstreamGenerator`

`ClickstreamGenerator.generate_single_series`

`ClickstreamGenerator.generate_full_metrics`

`ClickstreamGenerator.generate_funnel`

`ClickstreamGenerator.get_model_info`