Skip to content
BranchesTags

Repository files navigation

VIEWS Twitter Header

GitHub License    GitHub branch check runs    GitHub Issues or Pull Requests    GitHub Release

A modular Python framework for end‑to‑end conflict forecasting: data ingestion, transformation, drift monitoring, model and ensemble management, evaluation, reconciliation, mapping, reporting, packaging, and artifact governance.

Acknowledgements

Views Funders

Caution

🚨 ATTENTION: MANDATORY EXPLICIT CONFIGURATION (Tier 3)

As of February 2026, the pipeline enforces Explicit Intent Declaration. Legacy keys (targets, metrics) are deprecated and will trigger large warning banners.

1. Targets are MANDATORY: You must declare at least one target or the pipeline will hard-stop. 2. Be Explicit: Use task-specific prefixes (regression_ or classification_). 3. Split Metrics: Clearly separate Point metrics from Sample-based (Uncertainty) metrics.

Category Tier 3: Best Practice (Explicit) Legacy (Deprecated)
Targets regression_targets, classification_targets targets
Metrics regression_point_metrics
regression_sample_metrics
classification_point_metrics
classification_sample_metrics		 regression_metrics
classification_metrics
metrics

Misspelled or unrecognized keys (e.g., regression_target without the 's') will trigger a hard stop with helpful hints.

Table of Contents

  1. Conceptual Overview
  2. High‑Level Architecture
  3. Core Pipeline Stages
  4. Managers (Orchestration Layer)
  5. Modules (Functional Layer)
  6. Data Layer & Querysets
  7. Evaluation & Metrics
  8. Reconciliation (Hierarchical Consistency)
  9. Reporting & Mapping
  10. CLI & Argument System
  11. Configuration & Partitioning
  12. Package Management
  13. Logging & Monitoring
  14. Development Workflow
  15. Quick Start
  16. FAQ

1. Conceptual Overview

The pipeline transforms raw geo‑temporal data into validated, reconciled, and documented forecasts. Key features include:

  • Deterministic data preparation (queryset + transformation replay)
  • Strict naming & artifact conventions
  • Partition-aware evaluation (calibration/validation/forecasting)
  • Multi-model ensembling & hierarchical reconciliation
  • Automated HTML reporting and spatial visualization
  • Reproducible configuration merging and logging
  • Optional integration with Weights & Biases (WandB) and prediction store

2. High‑Level Architecture

         ┌────────────────────────────────────────┐
         │            ConfigurationManager        │
         │  (deployment + hyperparameters + meta) │
         └───────────────┬────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────┐
│                 ViewsDataLoader                  │
│  Queryset → Raw Fetch → Drift Check → Update     │
│  → Transformation Replay → Partition Slice       │
└───────────────┬──────────────────────────────────┘
                │  DataFrame (month_id, entity_id)
                ▼
      ┌─────────────────────────────────────────┐
      │   ForecastingModelManager (thin façade)  │
      │   Routes to independently testable stages│
      │                                         │
      │   ┌─────────────┐  ┌──────────────────┐ │
      │   │TrainingStage│  │ EvaluationStage  │ │
      │   └─────────────┘  └──────────────────┘ │
      │   ┌───────────────┐ ┌────────────────┐  │
      │   │ForecastingStage│ │ReportingStage │  │
      │   └───────────────┘ └────────────────┘  │
      │   ┌───────────────────────┐              │
      │   │  PredictionIOManager  │              │
      │   └───────────────────────┘              │
      └────────────┬────────────────────────────┘
                   │ Predictions
                   ▼
         ┌────────────────────────┐
         │ ReconciliationModule   │
         │ (Country ↔ Priogrid)   │
         └────────────┬───────────┘
                      │ Reconciled Predictions
                      ▼
         ┌───────────────────────────┐
         │ Reporting & Mapping       │
         │ HTML, Tables, Choropleths │
         └───────────────────────────┘

Architecture note (April 2026): ForecastingModelManager has been decomposed from a 3049-LOC monolith into a ~1960-LOC thin façade that delegates to 5 independently testable stage classes. Each stage receives a frozen context object (immutable dataclass) rather than reaching into the manager's internals. ModelPathManager has been relocated from managers/ to data/ to fix dependency inversion. All existing import paths continue to work via re-export shims. See ADR-045 for the full design rationale.

3. Core Pipeline Stages

Stage Output Key Component
Data Fetch Partitioned feature/target frame ViewsDataLoader
Train Artifact (model file) TrainingStage (via ForecastingModelManager / EnsembleManager)
Evaluate Metrics + eval predictions EvaluationStage (via ForecastingModelManager)
Forecast Future horizon predictions ForecastingStage (via ForecastingModelManager)
Reconcile Grid ↔ country consistency ReconciliationModule
Report HTML summaries ReportingStage (via ForecastingModelManager)
Package Poetry-compliant project PackageManager

4. Managers (Orchestration Layer)

Manager / Stage Purpose
ModelPathManager Path + artifact resolution for a model (canonical location: data/)
ModelManager Abstract training/evaluation/forecast flow control
ForecastingModelManager Thin façade — routes to pipeline stages below
EvaluationStage Metrics orchestration (DF + PF paths, step mappings, evaluator integration)
ReportingStage Forecast + evaluation HTML report generation
ForecastingStage Post-processing, validation, and persistence of forecast predictions
TrainingStage Training log creation and WandB alerts
PredictionIOManager Save/load predictions, evaluations, and evaluation tables
EnsemblePathManager Paths for multi-model ensemble
EnsembleManager Aggregation + optional reconciliation
ExtractorPathManager External raw data ingestion paths
ExtractorManager Download → preprocess → save for external datasets
PostprocessorPathManager Downstream transformation stage paths
PostprocessorManager Read → transform → validate → save
PackageManager Create/validate Poetry packages
ConfigurationManager Merge + validate layered configuration

Each stage receives an immutable frozen context object and is independently unit-testable. See ADR-045 for architecture details.

5. Modules (Functional Layer)

Module Role
dataloaders Partition-aware data retrieval + drift detection + incremental update
transformations Dataset transformation undo/management (extracted to views-reporting, ADR-054)
reconciliation Hierarchical grid ↔ country alignment (extracted to views-reporting, ADR-054)
reports Tailwind-styled HTML evaluation/forecast report generation (extracted to views-reporting, ADR-054)
mapping Static + interactive choropleth maps (extracted to views-reporting, ADR-054)
visualizations Historical line graphs & distribution plots (extracted to views-reporting, ADR-054)
logging Central logging configuration injection
statistics Posterior distribution analysis & forecast reconciliation (extracted to views-reporting, ADR-054)
wandb Alerts, artifact logging, run lifecycle
model validation Structural & logical integrity checks (sniffer pattern, ADR-041)
ensemble validation Structural & logical integrity checks

5.1 Intermediate Modules

Module Role
cli CLI parsing and validation
dataset Spatio-temporal dataset handler with country and priogrid level support

6. Data Layer & Querysets

  • Querysets define feature/target extraction logic + transformation chains.
  • Incremental updates replace raw slices (GED / ACLED) and replay transformations (UpdateViewser).
  • MultiIndex structure: (month_id, entity_id) for time-spatial operations.
  • Data types normalized (float64 for numeric integrity).
  • Partitions defined via month ranges (train/test or forecast horizon).

7. Evaluation & Metrics

Evaluation produces:

  • Step-wise metrics (per forecast horizon)
  • Month-wise metrics (temporal slices)
  • Time-series metrics (sequence performance trajectory)

Conflict type auto-inferred from target tokens (sb / ns / os). Files named per ADR conventions (artifact/output naming).

8. Reconciliation (Hierarchical Consistency)

Ensures priogrid sums align with authoritative country totals while preserving relative spatial pattern and zero inflation. Parallelizable across countries × time × targets. Integrated into ensembles or model forecast postprocessing.

9. Reporting & Mapping

Component Feature
ReportModule Headings, paragraphs, Markdown, tables, images, grids
MappingModule Country & priogrid choropleths (static + interactive animation)
Templates Forecast + evaluation report skeletons
CSS Tailwind subset embedded for portability

Reports embed:

  • Metrics tables
  • Key–value configuration summaries
  • Spatial animations (Plotly)
  • Artifact provenance (timestamps, versions)

10. CLI & Argument System

Dataclass-driven (ForecastingModelArgs):

  • Flags: --train, --evaluate, --forecast, --report, --sweep, --prediction_store, --monthly
  • Validation prevents illegal combinations (e.g., evaluate with forecasting run type).
  • Monthly shortcut auto-configures production cycle.

11. Configuration & Partitioning

ConfigurationManager merges:

  1. Deployment
  2. Hyperparameters
  3. Meta
  4. Partition dictionary
  5. Runtime overrides (highest priority)

Forecast partitions dynamically adjusted by override_timestep. Validation enforces structural integrity and target specification.

12. Package Management

PackageManager:

  • Validates naming (organization-prefix-*)
  • Creates Poetry skeleton (Python version constraint)
  • Adds dependencies (including views-pipeline-core)
  • Fetches latest release (tags or GitHub API)
  • Runs poetry check

13. Logging & Monitoring

  • YAML-driven configuration (handlers, levels, formatters).
  • Dedicated model/ensemble logging directories.
  • Standard separation: main log, error log.
  • WandB alerts for stage transitions, failures, reconciliation completeness.

14. Development Workflow

Task Command
Run model ./run.sh --run_type calibration --train --evaluate --report --saved
Run ensemble ./run.sh --ensemble hybrid_lynx --forecast --report
Update raw data Use --update_viewser
Generate report only Use --evaluate --report or --forecast --report

Refer to documentation/development_guidelines.md for coding standards and docstring_guidelines.md for formatting.

15. Quick Start

  1. Run build_model_scaffold.py or build_ensemble_scaffold.py found in the views-models repository.

  2. Update config_deployment.py, config_hyperparameters.py, config_queryset.py, config_meta.py.

  3. Run calibration:

    python main.py --run_type calibration --train --evaluate --report

  4. Run forecasting:

    python main.py --run_type forecasting --train --forecast --report

  5. View artifacts: models/<name>/artifacts/

16. FAQ

Question Answer
Do I need WandB? Optional; disable notifications to run offline.
Can I reconcile single-model forecasts? Yes—apply ReconciliationModule manually after forecast stage.
How do I add a new transformation? Register callable in transformation mapping and ensure replay compatibility.
Are forecasts stored transformed or raw? Temporarily reversed to raw scale before saving (pending ADR finalization).
Can I aggregate probabilistic outputs? Current ensemble aggregation expects scalar or single-element lists.

About

VIEWS Pipeline Core is a comprehensive machine learning pipeline designed to produce monthly predictions of future violent conflict at both country and sub-country levels.

viewsforecasting.org

Resources

Readme
MIT license
Activity
Custom properties

Stars

3 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

Used by

Contributors

Languages