Part of the VIEWS Platform ecosystem for large-scale conflict forecasting.
- Overview
- Role in the VIEWS Pipeline
- Architecture
- Features
- Installation
- Running Tests
- Project Structure
- Governance
- Contributing
- Acknowledgements
VIEWS Reporting provides the visualization, statistical analysis, reconciliation, and report generation layer for the VIEWS conflict forecasting pipeline. It produces HTML evaluation reports, interactive choropleth maps, posterior distribution analyses, and hierarchical forecast reconciliation.
All incoming data is expected on its original measurement scale -- this library does not infer or reverse mathematical transformations from column names (ADR-011, Architecture Decision Record).
Key Capabilities:
- Bayesian posterior analysis -- MAP (Maximum A Posteriori) estimation, HDI (Highest Density Interval) computation, and credible interval reporting
- Hierarchical forecast reconciliation -- proportional scaling to ensure country-grid consistency
- HTML report generation -- Tailwind CSS-styled evaluation and forecast reports with XSS-safe content
- Interactive mapping -- choropleth maps at country and PRIO-GRID (Peace Research Institute Oslo grid) resolution via GeoPandas and Mapclassify
VIEWS Reporting sits at the output end of the forecasting pipeline, consuming model predictions and producing human-readable reports, maps, and statistical summaries.
- views-pipeline-core: Pipeline infrastructure -- provides orchestration, configuration, and the queryset/partition framework that reporting consumes.
- views-models: Model outputs -- predictions and posterior samples evaluated and visualized by this library.
- views-evaluation: Evaluation metrics -- scoring and calibration results displayed in evaluation reports.
- views-stepshifter: Stepshift model predictions consumed for reconciliation and visualization.
- docs: Organization/pipeline level documentation.
- Data Input: Receives evaluated predictions and posterior samples from the pipeline.
- Analysis: Computes MAP estimates, HDI intervals, and reconciles hierarchical forecasts.
- Output: Generates HTML reports, distribution plots, historical line graphs, and choropleth maps.
The repository follows a five-layer dependency model (ADR-002):
| Layer | Package | Purpose |
|---|---|---|
| Ingestion | loaders |
Declared-format prediction loaders (parquet / numpy PredictionFrame) → datasets (ADR-012) |
| Compute | statistics |
Bayesian posterior analysis (MAP, HDI), forecast reconciliation |
| Compute | transformations |
Log transform lifecycle (legacy per ADR-011) |
| Compute | reconciliation |
Hierarchical country-grid forecast reconciliation |
| Compute | metadata |
Entity metadata accessors via viewser (30 functions) |
| Render | visualizations |
Distribution plots, historical line graphs |
| Render | mapping |
Interactive/static choropleth maps |
| Compose | reports |
HTML report builder with Tailwind CSS |
| Compose | templates |
EvaluationReportTemplate, ForecastReportTemplate |
| Assets | assets |
Shapefiles (country, priogrid), header images |
Data flows upward: ingestion -> compute -> render -> compose. No downward dependencies (ADR-002).
- Posterior Distribution Analysis: MAP via histogram density peak, HDI via shortest-interval on sorted samples, configurable credible masses and zero-mass thresholds.
- Forecast Reconciliation: Proportional scaling that preserves zeros, clamps non-negative, and ensures country totals match grid sums. Parallel execution via ProcessPoolExecutor.
- HTML Reports: Content accumulation API (headings, paragraphs, tables, images, footers) with
html.escape()on all user-facing text. Tailwind CSS styling. Export to standalone HTML files. - Choropleth Mapping: Country and PRIO-GRID level maps with bundled shapefiles, configurable classification schemes, and interactive Folium output.
- Historical Line Graphs: Plotly-based time series with HDI bands, forecast cutoff markers, and entity dropdown navigation.
- Distribution Plots: HDI and MAP overlays on posterior sample histograms.
- Python 3.11 — 3.12+ is not yet supported: an upstream transitive dependency
(
views-pipeline-core → ingester3 → levenshtein) has no 3.12/3.13 build. See ADR-014 and risk register C-36. The package is resolved for Linux and macOS. - uv for development (hatchling + uv per ADR-014).
For development (recommended):
git clone https://github.com/views-platform/views-reporting
cd views-reporting
uv sync # creates .venv from uv.lockOr install the published package into an existing environment:
pip install views-reportingSee the organization/pipeline level docs for full environment setup.
uv run pytest tests/ -q # full suite
uv run pytest tests/ -q -m "not slow" # skip slow integration testsFixture-dependent tests skip automatically when their data is absent.
views-reporting/
├── README.md # Documentation
├── tests/ # 85–161 tests depending on environment
├── views_reporting/ # Main source code
│ ├── assets/ # Shapefiles and header images
│ ├── mapping/ # Choropleth map generation
│ ├── metadata/ # Entity metadata accessors
│ ├── reconciliation/ # Hierarchical forecast reconciliation
│ ├── reports/ # HTML report builder + Tailwind CSS
│ ├── statistics/ # Posterior analysis (MAP, HDI)
│ ├── templates/ # Report templates (evaluation, forecast)
│ ├── transformations/ # Log transform lifecycle (legacy)
│ ├── visualizations/ # Distribution and historical plots
│ └── __init__.py # Package initialization
├── documentation/
│ ├── ADRs/ # 18 Architecture Decision Records
│ ├── CICs/ # 13 Class Intent Contracts
│ └── guides/ # Operational runbooks (e.g. publishing to PyPI)
├── reports/ # Technical risk register
├── .github/workflows/ # CI configuration
└── pyproject.toml # Project metadata (PEP 621) + hatchling/uv
This repository uses structured governance documented in documentation/:
- 18 ADRs (000-017) -- architectural decisions, from foundational principles to data ingestion, build tooling, release automation, configuration, and evaluation-report standards
- 13 CICs -- intent contracts covering every non-trivial class plus the full Ingestion-layer loader surface (ADR-006)
- Risk register --
reports/technical_risk_register.md(ADR-010) - Testing doctrine -- red/green/beige team taxonomy (ADR-005)
- Guides -- operational runbooks in
documentation/guides/(e.g. publishing to PyPI)
Start with documentation/ADRs/README.md for the governance map.
| ADR | Title | Impact |
|---|---|---|
| ADR-002 | Topology and dependency rules | Four-layer architecture, no downward deps |
| ADR-003 | Authority of declarations over inference | Fail-loud, no semantic inference |
| ADR-005 | Testing as mandatory critical infrastructure | Red/green/beige test categories |
| ADR-011 | Data arrives on original measurement scale | No transform detection from column names |
We welcome contributions! Please follow the contribution guidelines outlined in the VIEWS Documentation. See also documentation/contributor_protocols/ for repo-specific protocols.
All contributions must comply with the constitutional ADRs in documentation/ADRs/, including:
- ADR-003 -- Explicit declarations over inference; fail loud on semantic ambiguity
- ADR-005 -- Testing is mandatory (red / beige / green taxonomy)
- ADR-006 -- Non-trivial classes require intent contracts
- ADR-007 -- Silicon-based agents are untrusted contributors
Special thanks to the VIEWS MD&D Team for their collaboration and support.