> ## Documentation Index > Fetch the complete documentation index at: https://nixtlaverse.nixtla.io/llms.txt > Use this file to discover all available pages before exploring further. # Domain-Specific Generators > IntermittentDemand, IoTSensor, EnergyLoad, StateSpace, DailyActiveUsers, VitalSigns, and Clickstream generators ### `IntermittentDemandGenerator` Bases: [BaseGenerator](#synforecast.base.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).
Occurrence patterns * 'random': i.i.d. Bernoulli(demand\_probability) per period, so the long-run fraction of non-zero periods equals demand\_probability. * 'clustered': runs of `cluster_size` consecutive demand periods separated by Geometric(demand\_probability) gaps. The overall demand fraction is cluster\_size / (1/demand\_probability + cluster\_size), not demand\_probability. demand\_probability == 0 means infinite gaps, i.e. an all-zero series. * 'seasonal': per-period Bernoulli with probability p(t) = demand\_probability + (seasonal\_peak\_prob - demand\_probability) \* (cos(2*pi*(t mod P)/P) + 1) / 2, which peaks at seasonal\_peak\_prob at the start of each cycle (t mod P == 0) and falls to demand\_probability mid-cycle.
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](#int) | Minimum length of each series | *required* | | `max_length` | [int](#int) | Maximum length of each series | *required* | | `freq` | [str](#str) \| [int](#int) | Frequency of the data (e.g. 'D', 'h', '5min') or int | *required* | | `demand_probability` | [float](#float) | Probability of non-zero demand per period (occurrence-pattern dependent, see above) (default: 0.2) | *required* | | `demand_distribution` | [str](#str) | Distribution for non-zero demand sizes (default: 'poisson') | *required* | | `demand_mean` | [float](#float) | Mean of demand when non-zero (default: 5.0) | *required* | | `demand_std` | [float](#float) | Std of demand when non-zero (default: 2.0) | *required* | | `intermittent_pattern` | [str](#str) | Occurrence pattern: 'random', 'clustered' or 'seasonal' (default: 'random') | *required* | | `cluster_size` | [int](#int) | Size of demand clusters (default: 3) | *required* | | `seasonal_period` | [int](#int) | Period for seasonal intermittency (default: 12) | *required* | | `seasonal_peak_prob` | [float](#float) | Peak occurrence probability at the start of each seasonal cycle (default: 0.4) | *required* | | `min_demand` | [int](#int) | Minimum non-zero demand value (default: 1) | *required* | | `seed` | [int](#int) \| None | Random seed for reproducibility (default: None) | *required* | #### `IntermittentDemandGenerator.generate_single_series` ```python theme={null} generate_single_series(length) ``` Generate values for a single intermittent demand time series. **Parameters:** | Name | Type | Description | Default | | -------- | ------------------------ | ------------------------------------ | ---------- | | `length` | [int](#int) | The length of the series to generate | *required* | **Returns:** | Type | Description | | -------------------------------------- | ------------------------------------------------------- | | [ndarray](#numpy.ndarray) | Array of values (mostly zeros with intermittent demand) | ### `IoTSensorGenerator` Bases: [BaseGenerator](#synforecast.base.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](#int) | Minimum length of each series. | *required* | | `max_length` | [int](#int) | Maximum length of each series. | *required* | | `freq` | [str](#str) \| [int](#int) | Frequency of the data, e.g. 's', 'min', 'h'. | *required* | | `n_sensors` | [int](#int) | Sensors per network (default: 1). | *required* | | `sensor_type` | [str](#str) | 'temperature', 'humidity', 'pressure', 'light', 'motion' or 'generic' (default: 'temperature'). | *required* | | `base_value` | [float](#float) \| None | Base sensor reading (default: typical value for sensor\_type). | *required* | | `trend` | [float](#float) | Linear trend per time step (default: 0.0). | *required* | | `seasonal_period` | [int](#int) | Seasonal cycle length in steps, 0 disables (default: 0). | *required* | | `seasonal_amplitude` | [float](#float) | Amplitude of seasonal variation (default: 0.0). | *required* | | `measurement_noise` | [float](#float) | Std of measurement noise (default: 0.1). | *required* | | `drift_rate` | [float](#float) | Deterministic sensor drift per step (default: 0.0). | *required* | | `drift_noise` | [float](#float) | Std of the random drift component (default: 0.01). | *required* | | `calibration_error` | [float](#float) | Constant calibration offset (default: 0.0). | *required* | | `battery_life` | [int](#int) \| None | Steps until battery degradation starts, None disables (default: None). | *required* | | `battery_degradation_rate` | [float](#float) | Rate of quality loss per step after battery\_life (default: 0.001). | *required* | | `failure_probability` | [float](#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](#str) | 'intermittent', 'complete' or 'stuck' (default: 'intermittent'). | *required* | | `failure_duration` | [int](#int) | Length of intermittent/stuck episodes (default: 10). | *required* | | `stuck_value` | [float](#float) \| None | Reading during 'stuck' failures (default: the reading at episode start). | *required* | | `spatial_correlation` | [float](#float) | Noise correlation between adjacent sensors in a network (default: 0.5). | *required* | | `seed` | [int](#int) \| None | Random seed for reproducibility (default: None). | *required* | #### `IoTSensorGenerator.generate_single_series` ```python theme={null} generate_single_series(length) ``` Generate values for a single sensor. **Parameters:** | Name | Type | Description | Default | | -------- | ------------------------ | ------------------------------------- | ---------- | | `length` | [int](#int) | The length of the series to generate. | *required* | **Returns:** | Type | Description | | -------------------------------------- | ----------------------------------------------- | | [ndarray](#numpy.ndarray) | Array of sensor readings (NaN during failures). | #### `IoTSensorGenerator.generate` ```python theme={null} 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](#int) | Number of series/networks to generate. | *required* | | `start_id` | [int](#int) | Starting ID for the series numbering (default: 0). | 0 | | `n_jobs` | [int](#int) | Ignored; generation is sequential. | -1 | **Returns:** | Type | Description | | ------------------------------------------------------------------------ | ------------------------------------------------------------------------- | | [IntoDataFrameT](#narwhals.stable.v2.typing.IntoDataFrameT) | DataFrame in long format with columns \[id\_col, time\_col, target\_col]. | ### `EnergyLoadGenerator` Bases: [BaseGenerator](#synforecast.base.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](#int) | Minimum length of each series. | *required* | | `max_length` | [int](#int) | Maximum length of each series. | *required* | | `freq` | [str](#str) \| [int](#int) | Frequency of the data, e.g. 'h', '15min', 'D'. | *required* | | `base_load` | [float](#float) | Base load in kW or MW (default: 100.0). | *required* | | `load_type` | [str](#str) | 'residential', 'commercial' or 'industrial' (default: 'residential'). | *required* | | `daily_pattern` | [bool](#bool) | Enable the daily cycle (default: True). | *required* | | `daily_amplitude` | [float](#float) | Amplitude of the daily variation (default: 30.0). | *required* | | `weekly_pattern` | [bool](#bool) | Enable the weekly cycle (default: True). | *required* | | `weekly_amplitude` | [float](#float) | Amplitude of the weekly variation (default: 15.0). | *required* | | `yearly_pattern` | [bool](#bool) | Enable the yearly cycle (default: True). | *required* | | `yearly_amplitude` | [float](#float) | Amplitude of the yearly variation (default: 20.0). | *required* | | `temperature_sensitive` | [bool](#bool) | Enable temperature effects (default: True). | *required* | | `temperature_sensitivity` | [float](#float) | Load change per degree of deviation from base\_temperature (default: 2.0). | *required* | | `base_temperature` | [float](#float) | Reference temperature in Celsius (default: 20.0). | *required* | | `morning_peak_hour` | [int](#int) | Hour of the residential morning peak (default: 8). | *required* | | `evening_peak_hour` | [int](#int) | Hour of the residential evening peak (default: 19). | *required* | | `peak_amplitude` | [float](#float) | Additional load at the residential peaks (default: 40.0). | *required* | | `holiday_effect` | [float](#float) | Fractional load reduction on holidays (default: 0.3). | *required* | | `holiday_days` | [list](#list)\[[int](#int)] | Day-of-year indices (0-364) that are holidays (default: \[]). | *required* | | `extreme_weather_prob` | [float](#float) | Per-step probability of extreme weather (default: 0.0). | *required* | | `extreme_weather_impact` | [float](#float) | Load multiplier during extreme weather (default: 1.5). | *required* | | `noise_std` | [float](#float) | Standard deviation of additive noise (default: 5.0). | *required* | | `seed` | [int](#int) \| None | Random seed for reproducibility (default: None). | *required* | #### `EnergyLoadGenerator.generate_single_series` ```python theme={null} generate_single_series(length) ``` Generate values for a single energy load series. **Parameters:** | Name | Type | Description | Default | | -------- | ------------------------ | ------------------------------------- | ---------- | | `length` | [int](#int) | The length of the series to generate. | *required* | **Returns:** | Type | Description | | -------------------------------------- | ---------------------------- | | [ndarray](#numpy.ndarray) | Array of energy load values. | ### `StateSpaceGenerator` Bases: [BaseGenerator](#synforecast.base.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](#int) | Minimum length of each series. | *required* | | `max_length` | [int](#int) | Maximum length of each series. | *required* | | `freq` | [str](#str) \| [int](#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](#int) | Dimension of the hidden state vector (default: 1). | *required* | | `obs_dim` | [int](#int) | Dimension of the observation vector (default: 1). | *required* | | `transition_matrix` | [list](#list)\[[list](#list)\[[float](#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)\[[list](#list)\[[float](#float)]] \| None | Observation matrix H, shape (obs\_dim, state\_dim). Default observes the first state. | *required* | | `state_covariance` | [list](#list)\[[list](#list)\[[float](#float)]] \| None | State noise covariance Q, symmetric PSD (default: 0.1 \* I). | *required* | | `obs_covariance` | [list](#list)\[[list](#list)\[[float](#float)]] \| None | Observation noise covariance R, symmetric PSD (default: 0.1 \* I). | *required* | | `transition_fn` | [Callable](#collections.abc.Callable) \| None | Custom state transition function. | *required* | | `observation_fn` | [Callable](#collections.abc.Callable) \| None | Custom observation function. | *required* | | `initial_state` | [list](#list)\[[float](#float)] \| None | Initial state mean (default: zeros). | *required* | | `initial_state_covariance` | [list](#list)\[[list](#list)\[[float](#float)]] \| None | Initial state covariance, symmetric PSD (default: identity). | *required* | | `seed` | [int](#int) \| None | Random seed for reproducibility (default: None). | *required* | | `id_col` | [str](#str) | Name of the ID column (default: 'unique\_id'). | *required* | | `time_col` | [str](#str) | Name of the timestamp column (default: 'ds'). | *required* | | `target_col` | [str](#str) | Name of the value column (default: 'y'). | *required* | | `start_datetime` | [str](#str) | First timestamp (default: '2000-01-01'). | *required* | #### `StateSpaceGenerator.generate_single_series` ```python theme={null} generate_single_series(length) ``` Generate values for a single state space series. **Parameters:** | Name | Type | Description | Default | | -------- | ------------------------ | ------------------------------------- | ---------- | | `length` | [int](#int) | The length of the series to generate. | *required* | **Returns:** | Type | Description | | -------------------------------------- | ---------------------------------------------- | | [ndarray](#numpy.ndarray) | Observed values (first observation dimension). | #### `StateSpaceGenerator.generate_with_states` ```python theme={null} 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](#int) | Number of series to generate (default: 1). | 1 | | `start_id` | [int](#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](#synforecast.base.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](#int) | Minimum length of each series. | *required* | | `max_length` | [int](#int) | Maximum length of each series. | *required* | | `freq` | [str](#str) \| [int](#int) | Frequency of the data, e.g. 'D', 'h'. | *required* | | `base_users` | [float](#float) | Base number of daily active users (default: 10000.0). | *required* | | `growth_rate` | [float](#float) | Daily organic growth rate (default: 0.0005). | *required* | | `growth_rate_std` | [float](#float) | Std dev of a per-series perturbation of growth\_rate (default: 0.0). | *required* | | `app_type` | [str](#str) | 'consumer', 'business' or 'gaming' (default: 'consumer'). | *required* | | `weekly_pattern` | [bool](#bool) | Enable weekly seasonality (default: True). | *required* | | `weekend_factor` | [float](#float) \| None | Multiplier for weekend activity (default: 1.2 for gaming, 0.8 otherwise). | *required* | | `event_probability` | [float](#float) | Per-step probability of an event (default: 0.02). | *required* | | `event_impact_min` | [float](#float) | Minimum event impact multiplier (default: 1.2). | *required* | | `event_impact_max` | [float](#float) | Maximum event impact multiplier (default: 2.0). | *required* | | `event_decay_rate` | [float](#float) | Per-step decay rate of the event boost (default: 0.1). | *required* | | `noise_std` | [float](#float) | Std of noise relative to the current level (default: 0.05). | *required* | | `event_col` | [str](#str) | Name of the event indicator column (default: 'event'). | *required* | | `seed` | [int](#int) \| None | Random seed for reproducibility (default: None). | *required* | #### `DailyActiveUsersGenerator.generate_single_series` ```python theme={null} 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](#int) | The length of the series to generate. | *required* | **Returns:** | Type | Description | | -------------------------------------- | -------------------- | | [ndarray](#numpy.ndarray) | Array of DAU values. | #### `DailyActiveUsersGenerator.generate` ```python theme={null} 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](#int) | Number of time series to generate. | *required* | | `start_id` | [int](#int) | Starting ID for the series numbering (default: 0). | 0 | | `n_jobs` | [int](#int) | Ignored; generation is sequential. | -1 | **Returns:** | Type | Description | | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | [IntoDataFrameT](#narwhals.stable.v2.typing.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](#synforecast.base.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.
Note Circadian and HRV components assume one time step = 1 minute (freq='min'); other frequencies distort those cycle periods.
**Parameters:** | Name | Type | Description | Default | | ------------------- | --------------------------------------- | ------------------------------------------------------------------------------------- | ---------- | | `min_length` | [int](#int) | Minimum length of each series. | *required* | | `max_length` | [int](#int) | Maximum length of each series. | *required* | | `freq` | [str](#str) \| [int](#int) | Frequency of the data; use 'min' for correct circadian/HRV periods. | *required* | | `patient_type` | [str](#str) | 'healthy', 'cardiac', 'sepsis', 'respiratory' or 'hypertensive' (default: 'healthy'). | *required* | | `vital_sign` | [str](#str) | Which vital sign to output (default: 'heart\_rate'). | *required* | | `include_circadian` | [bool](#bool) | Include circadian rhythm effects (default: True). | *required* | | `include_hrv` | [bool](#bool) | Include heart rate variability (default: True). | *required* | | `include_events` | [bool](#bool) | Include random physiological events (default: True). | *required* | | `event_probability` | [float](#float) | Per-step probability of an event (default: 0.01). | *required* | | `seed` | [int](#int) \| None | Random seed for reproducibility (default: None). | *required* |
Example > > > gen = VitalSignsGenerator( > > > ... min\_length=1440, # 24 hours of per-minute data > > > ... max\_length=1440, > > > ... freq="min", > > > ... patient\_type="healthy", > > > ... vital\_sign="heart\_rate", > > > ... seed=42, > > > ... ) > > > df = gen.generate(n\_series=10)
#### `VitalSignsGenerator.generate_single_series` ```python theme={null} generate_single_series(length) ``` Generate values for a single vital signs time series. **Parameters:** | Name | Type | Description | Default | | -------- | ------------------------ | ------------------------------------- | ---------- | | `length` | [int](#int) | The length of the series to generate. | *required* | **Returns:** | Type | Description | | -------------------------------------- | --------------------------- | | [ndarray](#numpy.ndarray) | Array of vital sign values. | #### `VitalSignsGenerator.generate_all_vitals` ```python theme={null} 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](#int) | Number of patients/series to generate. | 1 | | `start_id` | [int](#int) | Starting ID for the series numbering. | 0 | **Returns:** | Type | Description | | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | | [IntoDataFrameT](#narwhals.stable.v2.typing.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` ```python theme={null} get_model_info() ``` Get information about the vital signs model. **Returns:** | Type | Description | | -------------------------- | --------------------------------------------- | | [dict](#dict) | Model parameters and patient characteristics. | ### `ClickstreamGenerator` Bases: [BaseGenerator](#synforecast.base.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
Note Seasonality assumes hourly frequency (freq='h'). Other frequencies produce incorrect day/night and weekday patterns.
**Parameters:** | Name | Type | Description | Default | | --------------------- | --------------------------------------- | ---------------------------------------------------------------------- | ---------- | | `min_length` | [int](#int) | Minimum length of each series. | *required* | | `max_length` | [int](#int) | Maximum length of each series. | *required* | | `freq` | [str](#str) \| [int](#int) | Frequency of the data; use 'h' for correct seasonality patterns. | *required* | | `base_sessions` | [float](#float) | Baseline sessions per time bin (default: 100). | *required* | | `traffic_source` | [str](#str) | 'organic', 'paid', 'direct', 'referral' or 'mixed' (default: 'mixed'). | *required* | | `conversion_rate` | [float](#float) | Base conversion rate for engaged sessions (default: 0.03). | *required* | | `bounce_rate` | [float](#float) | Base rate of single-page sessions (default: 0.40). | *required* | | `avg_session_depth` | [float](#float) | Average pages per engaged session (default: 3.5). | *required* | | `include_seasonality` | [bool](#bool) | Include time-of-day and day-of-week patterns (default: True). | *required* | | `include_bots` | [bool](#bool) | Include bot traffic (default: True). | *required* | | `bot_fraction` | [float](#float) | Fraction of traffic from bots, \< 1.0 (default: 0.15). | *required* | | `output_type` | [str](#str) | Metric to output (default: 'sessions'). | *required* | | `seed` | [int](#int) \| None | Random seed for reproducibility (default: None). | *required* |
Example > > > gen = ClickstreamGenerator( > > > ... min\_length=168, # 1 week of hourly data > > > ... max\_length=168, > > > ... freq="h", > > > ... base\_sessions=500, > > > ... output\_type="sessions", > > > ... seed=42, > > > ... ) > > > df = gen.generate(n\_series=10)
#### `ClickstreamGenerator.generate_single_series` ```python theme={null} generate_single_series(length) ``` Generate values for a single clickstream time series. **Parameters:** | Name | Type | Description | Default | | -------- | ------------------------ | ------------------------------------- | ---------- | | `length` | [int](#int) | The length of the series to generate. | *required* | **Returns:** | Type | Description | | -------------------------------------- | ----------------------- | | [ndarray](#numpy.ndarray) | Array of metric values. | #### `ClickstreamGenerator.generate_full_metrics` ```python theme={null} generate_full_metrics(n_series=1, start_id=0) ``` Generate all clickstream metrics for complete analytics. **Parameters:** | Name | Type | Description | Default | | ---------- | ------------------------ | ------------------------------ | -------------- | | `n_series` | [int](#int) | Number of series to generate. | 1 | | `start_id` | [int](#int) | Starting ID for series naming. | 0 | **Returns:** | Type | Description | | ------------------------------------------------------------------- | ------------------------------------------------------------------- | | [dict](#dict)\[[str](#str), [ndarray](#numpy.ndarray)] | All metrics as flat arrays, keyed by metric name plus 'series\_id'. | #### `ClickstreamGenerator.generate_funnel` ```python theme={null} 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](#int) | Number of sessions entering the funnel. | 1000 | | `stages` | [list](#list)\[[str](#str)] \| None | Funnel stage names (default: standard e-commerce funnel). | None | **Returns:** | Type | Description | | ----------------------------------------------------- | ------------------------------------------ | | [dict](#dict)\[[str](#str), [int](#int)] | Stage name -> session count at that stage. | #### `ClickstreamGenerator.get_model_info` ```python theme={null} get_model_info() ``` Get information about the clickstream model. **Returns:** | Type | Description | | -------------------------- | --------------------------------------------- | | [dict](#dict) | Model parameters and traffic characteristics. |