Skip to content

Latest commit

 

History

1,283 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

r2darts2 Banner

Python Version    Darts Version    PyTorch    License

A time series forecasting package for conflict prediction within the VIEWS (Violence and Impacts Early-Warning System) ecosystem. Built on Darts and PyTorch Lightning, it provides deep learning models, domain-specific loss functions, and reproducibility infrastructure tuned for zero-inflated, heavy-tailed conflict fatality data.


Key Features

  • 🚀 Production-Ready Integration: Seamlessly integrates with the VIEWS pipeline ecosystem via the Genomic Firewall and DNA manifest validation
  • ⚡ Zero-Inflated Data Handling: Specialized loss functions (SpotlightLoss family) and scalers (AsinhTransform chains) purpose-built for conflict fatality distributions
  • 🧠 10 Model Architectures: TFT, N-BEATS, N-HiTS, TiDE, TCN, BlockRNN, Transformer, NLinear, DLinear, TSMixer
  • 📊 Static Covariate Fingerprints: Per-entity conflict statistics (µ, σ, max, trend, sparsity) — implemented in transformers/static_covariates.py but not currently wired into the dataset; see reports/technical_risk_register.md C-36
  • 🔗 Chained Scalers: Arrow-syntax pipelines (AsinhTransform->MaxAbsScaler) for multi-stage feature normalization
  • 🛡️ Fortress Architecture: ADR-governed reproducibility, NaN detection, gradient health monitoring, and training stability callbacks throughout
  • 🧮 GPU Acceleration: Optimized for single- and multi-GPU training via PyTorch Lightning

📦 Installation

git clone https://github.com/views-platform/views-r2darts2.git
cd views-r2darts2
pip install -e .

Requires darts==0.40.0 and pandas 1.x — the newest versions the VIEWS platform can host (its viewser / views-transformation-library dependencies pin pandas<2, views-datafactory caps xarray<2026 and zarr<3). views-pipeline-core>=3.0.0,<4.0.0 is an optional extra: pip install -e ".[manager]". It is imported lazily by DartsForecastingModelManager and by the four ViewsDataset persistence methods (save_predstore, save_appwrite, from_predstore_latest, from_appwrite_latest); everything else works without it. For GPU support, install the appropriate PyTorch version for your CUDA setup first. See the PyTorch installation guide.


🧠 Supported Models

Model Static Covariates Description Ideal For
TFT (Temporal Fusion Transformer) ✅ VSN+GRN gating Hybrid LSTM + multi-head attention. Variable Selection Networks gate static covariate influence per time step. Interpretable multivariate forecasting; best when entity identity strongly conditions the forecast.
TSMixer ✅ Concatenation Alternating time-mixing and feature-mixing MLP blocks. Static covariates are concatenated at each block (no gating). Large-scale multivariate; fast training. Requires AsinhTransform->MaxAbsScaler on static cov stats due to blunt concat.
TiDE ✅ Concatenation MLP encoder-decoder for long-horizon forecasting. Efficient and scalable. Resource-constrained environments, long input horizons.
BlockRNN ✅ Concatenation Stacked RNN/LSTM/GRU with optional static covariate injection. Sequential dependency modeling; autoregressive forecasting.
NLinear ✅ Concatenation Lightweight linear model with optional trend/seasonality decomposition. Baseline modeling; rapid prototyping.
DLinear ✅ Concatenation Decomposition-Linear — separate linear layers for trend and seasonal components. Trend/seasonality separation; fast inference.
N-HiTS ❌ Not consumed Hierarchical interpolation with per-stack pooling→FC→theta pipelines. Flag accepted but not passed to the Darts constructor — the entity-id static covariate is attached but ignored by the model. Multi-scale temporal pattern extraction; long-term forecasting.
Transformer ❌ Not consumed Self-attention encoder with positional encoding. Flag accepted but silently ignored — no use_static_covariates is passed to the Darts constructor. Long-range temporal dependency modeling.
N-BEATS ❌ Not supported Fully-connected stacks with basis expansions for trend/seasonality. Static covariates are architecturally incompatible. Do not configure use_static_covariates=True. Interpretable decomposition; univariate/multivariate forecasting.
TCN (Temporal Convolutional Network) ❌ Not consumed Dilated causal convolutions with residual connections. High-frequency series; long-range dependencies.

Important: Models marked ❌ will silently drop static covariate fingerprints even if use_static_covariates=True is set in the config. This is a Darts library constraint, not a bug in this package. On 0.2.x no fingerprint is computed for any model (see Static Covariate Fingerprints below); only the entity id is attached, and for N-HiTS and Transformer even that is never seen by the model weights.


📊 Scalers

Proper data scaling is critical for neural network training. For conflict data — zero-inflated, heavily right-skewed, spanning four orders of magnitude — the choice of transform directly determines whether models converge.

Available Scalers

Scaler Formula Best For Notes
AsinhTransform $y = \text{asinh}(x)$ Zero-inflated counts, data with negatives ⭐ Recommended for all fatality data. Handles zeros and extreme outliers. Near-linear below 1.
MaxAbsScaler $y = x / \max(|x|)$ Cross-entity normalization after element-wise transform Maps to $[-1,1]$. Preserves ordinal rank. Required after AsinhTransform for static covariate injection in concatenation-based models.
StandardScaler $y = (x - \mu)/\sigma$ Roughly normal data Zero-mean, unit-variance. Poor choice for zero-inflated distributions.
MinMaxScaler $y = (x - x_{\min})/(x_{\max} - x_{\min})$ Bounded data (0–1, 0–100) Best for V-Dem indices and WDI percentages.
SqrtTransform $y = \sqrt{x}$ Moderate skew, count data Gentler compression than asinh; undefined for negatives.
LogTransform $y = \log(1 + x)$ Strictly positive skewed data Undefined for negatives. Prefer AsinhTransform for conflict data.
RobustScaler Median + IQR Outlier-heavy data Resistant to extreme values.
QuantileNormal Maps to $\mathcal{N}(0,1)$ Any distribution Forces Gaussian marginal.
QuantileUniform Maps to $U(0,1)$ Any distribution Forces uniform marginal.
YeoJohnsonTransform Power transform Mixed positive/negative Makes data more Gaussian-like.

AsinhTransform vs LogTransform

            Log(1+x)       AsinhTransform
x = -50     ❌ undefined    ✓ asinh(-50) = -4.61
x = 0       0.00            0.00
x = 1       0.69            0.88  (non-zero threshold in asinh space: 0.88 ≈ 1 death)
x = 100     4.62            5.30
x = 10000   9.21            9.90

The non_zero_threshold in SpotlightLoss is set to 0.88 because asinh(1) ≈ 0.88 — this exactly corresponds to the boundary of "at least 1 battle death" in raw space.

🔗 Chained Scalers

Use the -> operator to compose transforms sequentially. This is the production standard for all conflict and covariate features:

# Target: suppress zeros + bound output
"target_scaler": "AsinhTransform"

# Features: element-wise compression then cross-entity normalization
"feature_scaler_map": {
    "AsinhTransform->MaxAbsScaler": [
        "lr_splag_1_ged_sb", "lr_ged_ns", "lr_ged_os",
        "lr_acled_sb", "lr_wdi_ny_gdp_mktp_kd",
        # ... all conflict and macro features
    ],
}

# Static covariate statistics — INERT on 0.2.x: forwarded to a forecaster parameter its own
# docstring marks unused; nothing computes the fingerprint (register C-36)
"static_covariate_stats": {"transform": "AsinhTransform->MaxAbsScaler"}

Why MaxAbsScaler after AsinhTransform for features?
AsinhTransform is element-wise: it compresses Syria's ged_sb ≈ 5000 and Chad's ged_sb ≈ 3 independently. After asinh, Syria is at ~8.5 and Chad at ~1.8 — a 4.7× gap persists. MaxAbsScaler maps the entire feature column to [-1, 1] across all 180+ countries, collapsing cross-entity scale while preserving ordinal rank. Without this, concatenation-based models (TSMixer, TiDE) inject raw magnitude bias at every block.

Forward / inverse chain direction:

Forward:  X → Scaler₁.fit_transform(X) → Scaler₂.fit_transform(X') → X_scaled
Inverse:  X_scaled → Scaler₂.inverse_transform → Scaler₁.inverse_transform → X_original

Static Covariate Fingerprints

Designed, not wired (register C-36). The fingerprint below is implemented in views_r2darts2/transformers/static_covariates.py and fully tested, but nothing in the package calls it on 0.2.x — ViewsDataset.to_darts_timeseries attaches only the entity id as a static covariate. The table describes what the module computes, not what models currently receive.

For models that consume static covariates (TFT, TSMixer, TiDE, BlockRNN, NLinear, DLinear), five per-entity statistics are computed from the training partition only (via stat_time_range) and would be injected as TimeSeries.static_covariates metadata:

Statistic Meaning Transform Recommendation
target_mu Mean conflict level AsinhTransform->MaxAbsScaler
target_sigma Volatility / spread AsinhTransform->MaxAbsScaler
target_max Peak value (spike extremity) AsinhTransform->MaxAbsScaler
target_trend OLS slope over training window AsinhTransform->MaxAbsScaler
target_sparsity Fraction of zero months No transform (already in [0,1])

If the module is wired, stat_time_range must be the training window to prevent test-period leakage:

from views_r2darts2.transformers.static_covariates import compute_static_covariates, StaticCovariateConfig

stats = compute_static_covariates(
    time=time_arr, entity=entity_arr, values=values_2d,
    target_columns=["ged_sb"], column_order=column_names,
    stat_time_range=(training_start_month_id, training_end_month_id),
    config=StaticCovariateConfig(transform="AsinhTransform->MaxAbsScaler"),
)

Recommended Scaler by Data Source

Data Source Feature Type Recommended Chain Rationale
UCDP / ACLED Fatality counts AsinhTransform->MaxAbsScaler Zero-inflated; cross-entity normalization required
WDI GDP, population, aid flows AsinhTransform->MaxAbsScaler Spans many orders of magnitude; can be negative (net migration)
WDI Percentages (_zs suffix) AsinhTransform->MaxAbsScaler Handles near-zero values; consistent with other features
V-Dem Democracy indices (0–1 bounded) AsinhTransform->MaxAbsScaler or MinMaxScaler Already bounded; either works
Static cov stats µ, σ, max, trend AsinhTransform->MaxAbsScaler Required for concatenation-based models
Static cov stats Sparsity None (raw) Already in [0,1]

⚡ Loss Functions

All loss functions target zero-inflated conflict data: ~90% zeros, ~10% events spanning four orders of magnitude. The loss function family has evolved substantially — the table below shows the current production-recommended functions and the full catalog.

Loss Function Catalog

Loss Function Status Base Cell Loss Key Mechanism Use When
SpotlightLossLogcosh ⭐ Production log_cosh Event-gated shape + event-only level + dead-cell anchor (three components) Default for all models in production
SpotlightLoss ⭐ Production Barron(α=1.5) Same three-component structure on a heavier-tailed base; single gene non_zero_threshold; spectral term hard-disabled (_STFT = False) When log_cosh gradient is too aggressive on large errors
PrismLoss Research MSE (= MSLE in log space) KL-DRO + compound weights, no DC/AC decomp, no level anchor MSLE-aligned optimization without RevIN
SpotlightFocalLoss Research log_cosh Focal weighting by difficulty (1−exp(−|e|))^γ, no DRO Models without RevIN; exploration
SentinelLoss Research Generalised Charbonnier Power-law magnitude weights + SiLU symmetry + temporal gradient Alternative robust base when Barron α needs tuning
WeightedPenaltyHuberLoss Legacy Huber FP/FN multiplicative penalties Simple baselines; not recommended for production
WeightedHuberLoss Legacy Huber Non-zero reweighting Simple baselines
TimeAwareWeightedHuberLoss Legacy Huber Temporal decay + event weights Time-sensitive ablations
TweedieLoss Legacy Tweedie (p≈1.5) Compound Poisson-Gamma Count data without asinh transform
AsymmetricQuantileLoss Legacy Quantile Asymmetric τ-penalty When underestimation cost >> overestimation
ZeroInflatedLoss Legacy Huber (two-part) Explicit binary + count split Explicit zero-inflation modeling
SpikeFocalLoss Legacy MSE Focal on absolute magnitude Predates KL-DRO; superseded by Spotlight family
ShrinkageLoss Legacy Shrinkage Suppresses easy samples via sigmoid gate Exploratory; not validated for conflict

SpotlightLossLogcosh — Architecture Deep Dive

The production loss for all current VIEWS models. Operates entirely in asinh space; the target scaler must be AsinhTransform.

Note (2026-09-10): both production classes — views_r2darts2/math/spotlight_loss_logcosh.py and views_r2darts2/math/spotlight_loss.py — are three-component losses with a single gene, non_zero_threshold (LOSS_GENOMES): shape — base cell loss on demeaned per-cell errors, gated by an event mask, DRO-weighted; level — T-scaled loss on the event-only mean gap; anchor — loss on the dead-cell sum. Neither accepts delta; SpotlightLoss carries a spectral branch behind a hard-coded _STFT = False. A configured delta is silently dropped by the genome filter. The five-component design (DC/AC decomposition, compound weights, KL-DRO, level anchor, spectral) described in views_r2darts2/math/README.md is the Gen-5 design lineage; that file's configuration block still advertises delta and is stale (register C-15).

Configuration (SpotlightLossLogcosh):

"loss_function": "SpotlightLossLogcosh",
"non_zero_threshold": 0.88,  # asinh(1) ≈ 0.88 (= 1 battle death in raw space) — the only gene

Loss Function Evolution

The loss function development followed a clear progression as each failure mode was identified and addressed:

Generation Loss Problem It Solved Limitation Discovered
Gen 1 WeightedPenaltyHuberLoss Basic non-zero reweighting Huber is symmetric; no handling of RevIN bias; manually tuned FP/FN parameters
Gen 2 TweedieLoss, SpikeFocalLoss Compound Poisson structure; focal weighting No DRO; focal exponent γ is a fragile hyperparameter
Gen 3 PrismLoss KL-DRO replaces χ²-DRO; compound weighting is parameter-free No DC/AC decomposition; RevIN bias accumulates; no level anchor
Gen 4 SpotlightFocalLoss Focal mechanism adapted for regression, no class-specific logic No DRO; still requires γ tuning
Gen 5 SpotlightLossLogcosh DC/AC decomp + compound + KL-DRO + level anchor (+ spectral, since removed); parameter-free weighting log_cosh gradient can clip large errors aggressively
Gen 5b SpotlightLoss Barron(α=1.5) base cell loss — heavier tail than log_cosh Same three-component structure as current Logcosh; spectral branch disabled

🏗️ Multi-Stack Model Configuration

N-HiTS and TSMixer are multi-stack architectures where residuals are passed between stacks. Layer width ordering is critical and non-obvious.

The Layer Widths Trap

Both N-HiTS and TSMixer use a residual stacking pipeline:

Stack 0 (coarse) → absorbs easy patterns (trend, long cycles)
        ↓ residual
Stack 1 (mid)    → absorbs medium-frequency patterns
        ↓ residual  
Stack 2 (fine)   → must absorb ALL remaining residuals, including spike patterns

The fine stack always has the hardest job. Under SpotlightLoss (DRO weighting), high-conflict country residuals (e.g., Sudan) dominate gradients. If the fine stack has minimal capacity, it cannot model these spikes, producing erratic theta coefficients that cause:

  • Explosion on high-conflict countries (Sudan, Syria): fine stack theta blows up
  • Flatline on peaceful countries: coarse stack weights drift toward dominant loss signal, collapsing peaceful predictions to near-zero

Correct configuration:

# WRONG — coarse gets most capacity, fine gets least
"layer_widths": [256, 128, 64]   # ← Sudan explosion + flatline

# CORRECT — fine stack gets most capacity for residual absorption
"layer_widths": [64, 128, 256]   # ← stable, fine stack can handle spikes

N-HiTS Pooling / Frequency Alignment

N-HiTS pools the input sequence before each stack's FC block. The pooling_kernel_sizes and n_freq_downsample must be aligned:

pool_k = 4  →  input compressed to ceil(36/4) = 9 time steps → FC input dim = 9
n_freq = 4  →  theta output has 4 frequency coefficients, interpolated to 36 steps

If pool_k=4 but n_freq=3, there are 9 FC inputs but only 3 theta points — implicit upsampling by 9→36 via 3 basis functions creates a 3:1 gap. This forces the interpolation to guess intermediate values, introducing artificial smoothing that conflicts with spike reconstruction.

Correct alignment:

"pooling_kernel_sizes": [[4, 2, 1]],     # coarse: 9 steps, mid: 18 steps, fine: 36 steps
"n_freq_downsample": [[4, 2, 1]],        # 4 theta / 2 theta / 1 theta, interpolated to 36

The fine stack (pool_k=1, n_freq=1) sees all 36 time steps and produces 36 theta coefficients — effectively identity interpolation. This is correct: the fine stack should not impose any temporal compression on spike signals.

Also use max_pool_1d=True in the coarse stack to preserve spike maxima during pooling (average pooling dilutes spike information that should be routed to the coarse trend stack, not the fine detail stack).


🛡️ Fortress Architecture & Governance

This repository adheres to the Fortress Architecture: strict engineering and mathematical standards designed to guarantee scientific integrity and reproducibility in conflict forecasting.

The repository is governed by:

  • Architectural Decision Records (ADRs): Sequential, authoritative records of every major design choice.
  • Class Intent Contracts (CICs): Explicit declarations of purpose and responsibility for every critical class.
  • Reproducibility Manifest: The mandatory DNA genome that every experiment must declare before execution.
  • Technical Risk Register: Every known, unfixed concern, tiered and triggered (ADR-014); and the ADR-vs-code disagreements D-01..D-07 (each filed as a GitHub issue, #39–#45; D-05 ruled and closed via #40).
  • bash docs/validate_docs.sh checks the documentation set against itself and against the code tree — every views_r2darts2/…py or tests/…py path a live doc (this README included) names must exist. It is run by hand, not by CI (register C-55).

Training Stability Callbacks

Every training run is monitored by mandatory Fortress callbacks configured in ModelCatalog (8 of the 14 attached are shown; the others are TrainingStepPatchCallback, ValMetricsCallback, InputBatchMonitorCallback, LossComponentCallback, RichLossDiagnosticsCallback, LossGradientDiagnosticsCallbackV2, plus Lightning's EarlyStopping, LearningRateMonitor and ModelCheckpoint):

Callback Purpose
NaNDetectionCallback Halts training immediately on NaN in loss or weights
GradientHealthCallback Monitors gradient norm; warns on explosion/vanishing
WeightNormCallback Tracks parameter norm evolution across epochs
LossStabilityCallback Detects loss spikes and plateau regimes
RevINMonitorCallback Monitors RevIN affine parameters for drift
PredictionSanityCallback Validates output shape and value range each epoch
YHatBarCallback Tracks per-series mean predictions (ŷ bar) against targets
EpochTimingCallback Logs wall-clock time per epoch for performance tracking

🔧 API Reference

Most core classes follow the 1-Class-1-File standard; three homogeneous families (dataset/converters.py, dataset/subclasses.py, transformers/static_covariates.py) do not — register D-04 / issue #44.

ScalerSelector

from views_r2darts2.transformers.scaler_selector import ScalerSelector

scaler = ScalerSelector.get_scaler("AsinhTransform")
pipeline = ScalerSelector.instantiate_darts_scaler("AsinhTransform->MaxAbsScaler")  # Darts Pipeline; a single name returns a Darts Scaler

FeatureScalerManager

from views_r2darts2.transformers.feature_scaler_manager import FeatureScalerManager

manager = FeatureScalerManager(
    feature_scaler_map={"AsinhTransform->MaxAbsScaler": ["lr_ged_sb", "lr_ged_ns"]},
    default_scaler=None,
)

Catalogs (Genomic Firewall)

from views_r2darts2.catalogs.model_catalog import ModelCatalog
from views_r2darts2.catalogs.loss_catalog import LossCatalog
from views_r2darts2.catalogs.optimizer_catalog import OptimizerCatalog
from views_r2darts2.catalogs.scheduler_catalog import SchedulerCatalog

# Catalogs validate the DNA manifest on initialization
loss_fn = LossCatalog(config).get_loss()
model   = ModelCatalog(config).get_model("NHiTSModel")

ViewsDataset

from views_r2darts2 import ViewsDataset

# Zarr-backed, lazy; accepts parquet, DataFrame, FeatureFrame, PredictionFrame or Zarr
with ViewsDataset(source="cm_features.parquet", targets=["ged_sb"]) as ds:
    # scalers are fitted on the training window and owned by the dataset
    targets, past_cov = ds.fit_scalers(
        target_scaler="AsinhTransform",
        feature_scaler_map={"AsinhTransform->MaxAbsScaler": ["lr_ged_sb"]},
        time_ids=range(training_start_id, training_end_id + 1),   # fit on the training window only
        return_series=True,
    )
    ts_list = ds.to_darts_timeseries()

The dataset is the single source of truth for all data operations — see docs/CICs/views_dataset.md. For level-specific validation use ViewsDataset.for_loa("cm", source=...).

ReproducibilityGate

from views_r2darts2.infrastructure.reproducibility_gate import ReproducibilityGate

ReproducibilityGate.Config.audit_manifest(config)
ReproducibilityGate.Data.lock_entropy(config["random_state"])   # seeds torch/numpy/random; not full GPU determinism (C-24)
ReproducibilityGate.Temporal.audit_continuity(partition)

📐 Production Configuration Template

Minimal validated configuration for a new model:

def get_hp_config():
    return {
        # Forecast horizon
        "steps": [*range(1, 37)],
        "input_chunk_length": 36,
        "output_chunk_length": 36,
        "output_chunk_shift": 0,

        # Scaling — production standard
        "target_scaler": "AsinhTransform",
        "feature_scaler": None,
        "feature_scaler_map": {
            "AsinhTransform": [
                # All conflict counts, macro indicators, and lagged features
            ],
        },
        "static_covariate_stats": {"transform": "AsinhTransform->MaxAbsScaler"},   # inert on 0.2.x (C-36)

        # Loss — production standard
        "loss_function": "SpotlightLossLogcosh",
        "non_zero_threshold": 0.88, # asinh(1): boundary of 1 battle death

        # Optimizer
        "optimizer_cls": "AdamW",
        "lr": 0.0005,
        "weight_decay": 0.0002,
        "gradient_clip_val": 3,
        "optimizer_kwargs": {
            "betas": (0.9, 0.95), "lr": 0.0005, "weight_decay": 0.0002},

        # Scheduler
        "lr_scheduler_cls": "ReduceLROnPlateau",
        "lr_scheduler_factor": 0.5,
        "lr_scheduler_patience": 12,
        "lr_scheduler_min_lr": 1e-6,
        "lr_scheduler_kwargs": {
            "mode": "min", "factor": 0.5, "patience": 12,
            "min_lr": 1e-6, "cooldown": 3,
            "threshold": 0.01, "threshold_mode": "rel",
        },

        # Training
        "batch_size": 128,
        "n_epochs": 300,
        "early_stopping_patience": 35,
        "early_stopping_min_delta": 0.001,
        "force_reset": True,

        # Normalization
        "use_reversible_instance_norm": True,
        "use_cyclic_encoders": False,
        "use_static_covariates": True,  # Set False for N-BEATS, N-HiTS, Transformer

        # Reproducibility
        "random_state": 67,
        "time_steps": 36,               # not read by views_r2darts2; consumed (if at all) by views-pipeline-core (C-57)
        "rolling_origin_stride": 1,     # not read by views_r2darts2 (C-57)
        "prediction_format": "dataframe",

        # Prediction
        "likelihood": None,
        "num_samples": 1,
        "mc_dropout": False,
        "n_jobs": -1,                   # not read by views_r2darts2 (C-57)
    }

📚 References

About

A time series deep learning suite designed for conflict forecasting within the VIEWS (Violence and Impacts Early-Warning System) ecosystem.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Contributors

Languages