views-hydranet 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. views_hydranet-0.1.0/LICENSE +21 -0
  2. views_hydranet-0.1.0/PKG-INFO +211 -0
  3. views_hydranet-0.1.0/README.md +184 -0
  4. views_hydranet-0.1.0/pyproject.toml +58 -0
  5. views_hydranet-0.1.0/views_hydranet/__init__.py +36 -0
  6. views_hydranet-0.1.0/views_hydranet/architectures/HydraBNrecurrentUnet_06_LSTM4.py +778 -0
  7. views_hydranet-0.1.0/views_hydranet/architectures/anti_aliased_pool.py +78 -0
  8. views_hydranet-0.1.0/views_hydranet/architectures/dual_stream.py +55 -0
  9. views_hydranet-0.1.0/views_hydranet/architectures/dynamic_skip.py +89 -0
  10. views_hydranet-0.1.0/views_hydranet/architectures/locked_dropout.py +77 -0
  11. views_hydranet-0.1.0/views_hydranet/architectures/registry.py +75 -0
  12. views_hydranet-0.1.0/views_hydranet/architectures/shallow_pool.py +61 -0
  13. views_hydranet-0.1.0/views_hydranet/architectures/wide_memory.py +40 -0
  14. views_hydranet-0.1.0/views_hydranet/distributions/__init__.py +16 -0
  15. views_hydranet-0.1.0/views_hydranet/distributions/base.py +135 -0
  16. views_hydranet-0.1.0/views_hydranet/distributions/composition.py +78 -0
  17. views_hydranet-0.1.0/views_hydranet/distributions/family_loss.py +42 -0
  18. views_hydranet-0.1.0/views_hydranet/distributions/mixture_negative_binomial.py +150 -0
  19. views_hydranet-0.1.0/views_hydranet/distributions/nb_core.py +165 -0
  20. views_hydranet-0.1.0/views_hydranet/distributions/negative_binomial.py +105 -0
  21. views_hydranet-0.1.0/views_hydranet/distributions/registry.py +82 -0
  22. views_hydranet-0.1.0/views_hydranet/distributions/sampling.py +106 -0
  23. views_hydranet-0.1.0/views_hydranet/distributions/truncated_negative_binomial.py +159 -0
  24. views_hydranet-0.1.0/views_hydranet/distributions/zero_inflated_negative_binomial.py +177 -0
  25. views_hydranet-0.1.0/views_hydranet/infrastructure/__init__.py +0 -0
  26. views_hydranet-0.1.0/views_hydranet/infrastructure/reproducibility_gate.py +160 -0
  27. views_hydranet-0.1.0/views_hydranet/manager/hydranet_manager.py +413 -0
  28. views_hydranet-0.1.0/views_hydranet/train/train_model.py +150 -0
  29. views_hydranet-0.1.0/views_hydranet/train/training_engine.py +1674 -0
  30. views_hydranet-0.1.0/views_hydranet/utils/body_supervision.py +94 -0
  31. views_hydranet-0.1.0/views_hydranet/utils/config_initializer.py +1497 -0
  32. views_hydranet-0.1.0/views_hydranet/utils/correlated_bernoulli.py +141 -0
  33. views_hydranet-0.1.0/views_hydranet/utils/count_mean_loss.py +53 -0
  34. views_hydranet-0.1.0/views_hydranet/utils/count_target_bridge.py +54 -0
  35. views_hydranet-0.1.0/views_hydranet/utils/curriculum.py +113 -0
  36. views_hydranet-0.1.0/views_hydranet/utils/data_fetcher.py +205 -0
  37. views_hydranet-0.1.0/views_hydranet/utils/data_sniffer.py +465 -0
  38. views_hydranet-0.1.0/views_hydranet/utils/dense_nb_loss.py +86 -0
  39. views_hydranet-0.1.0/views_hydranet/utils/disk_guard.py +121 -0
  40. views_hydranet-0.1.0/views_hydranet/utils/feature_scaler.py +262 -0
  41. views_hydranet-0.1.0/views_hydranet/utils/feedback_field_transforms.py +291 -0
  42. views_hydranet-0.1.0/views_hydranet/utils/focal_loss.py +64 -0
  43. views_hydranet-0.1.0/views_hydranet/utils/gate_field_structure.py +155 -0
  44. views_hydranet-0.1.0/views_hydranet/utils/grid_naming.py +62 -0
  45. views_hydranet-0.1.0/views_hydranet/utils/hurdle_nb.py +85 -0
  46. views_hydranet-0.1.0/views_hydranet/utils/hydranet_inference.py +1748 -0
  47. views_hydranet-0.1.0/views_hydranet/utils/inference_orchestrator.py +339 -0
  48. views_hydranet-0.1.0/views_hydranet/utils/integrity_guardian.py +89 -0
  49. views_hydranet-0.1.0/views_hydranet/utils/lognormal_nll_loss.py +77 -0
  50. views_hydranet-0.1.0/views_hydranet/utils/model_artifact_fetcher.py +139 -0
  51. views_hydranet-0.1.0/views_hydranet/utils/mtloss.py +73 -0
  52. views_hydranet-0.1.0/views_hydranet/utils/pareto_loss.py +52 -0
  53. views_hydranet-0.1.0/views_hydranet/utils/prediction_frame_assembler.py +189 -0
  54. views_hydranet-0.1.0/views_hydranet/utils/quantile_head.py +157 -0
  55. views_hydranet-0.1.0/views_hydranet/utils/rollout_diagnostics.py +77 -0
  56. views_hydranet-0.1.0/views_hydranet/utils/sampling_strategies.py +106 -0
  57. views_hydranet-0.1.0/views_hydranet/utils/scheduled_sampling.py +101 -0
  58. views_hydranet-0.1.0/views_hydranet/utils/shrinkage_loss.py +49 -0
  59. views_hydranet-0.1.0/views_hydranet/utils/static_channels.py +69 -0
  60. views_hydranet-0.1.0/views_hydranet/utils/tobit_loss.py +112 -0
  61. views_hydranet-0.1.0/views_hydranet/utils/training_forensics.py +371 -0
  62. views_hydranet-0.1.0/views_hydranet/utils/truncated_nb_loss.py +92 -0
  63. views_hydranet-0.1.0/views_hydranet/utils/utils.py +315 -0
  64. views_hydranet-0.1.0/views_hydranet/utils/utils_device.py +23 -0
  65. views_hydranet-0.1.0/views_hydranet/utils/utils_logging.py +172 -0
  66. views_hydranet-0.1.0/views_hydranet/utils/utils_orchestration.py +41 -0
  67. views_hydranet-0.1.0/views_hydranet/utils/visual_diagnostics.py +1251 -0
  68. views_hydranet-0.1.0/views_hydranet/utils/volume_handler.py +876 -0
  69. views_hydranet-0.1.0/views_hydranet/utils/volume_sampler.py +144 -0
  70. views_hydranet-0.1.0/views_hydranet/utils/warmup_decay_lr_scheduler.py +14 -0
  71. views_hydranet-0.1.0/views_hydranet/utils/weighted_bce_loss.py +51 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Simon Polichinel von der Maase
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,211 @@
1
+ Metadata-Version: 2.4
2
+ Name: views-hydranet
3
+ Version: 0.1.0
4
+ Summary: views-hydranet is a package that contains modeling procedure, evaluation and forecasting using HydraNet implemented in PyTorch
5
+ License: MIT
6
+ License-File: LICENSE
7
+ Author: Dylan
8
+ Author-email: 52908667+smellycloud@users.noreply.github.com
9
+ Requires-Python: >=3.11,<3.15
10
+ Classifier: License :: OSI Approved :: MIT License
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Programming Language :: Python :: 3.11
13
+ Classifier: Programming Language :: Python :: 3.12
14
+ Classifier: Programming Language :: Python :: 3.13
15
+ Classifier: Programming Language :: Python :: 3.14
16
+ Provides-Extra: viz
17
+ Requires-Dist: matplotlib (>=3.8,<4) ; extra == "viz"
18
+ Requires-Dist: torch (>=2.2.1,<3.0.0)
19
+ Requires-Dist: views-frames (>=1.10.2,<2)
20
+ Requires-Dist: views-pipeline-core (>=3.0.0,<4.0.0)
21
+ Project-URL: Changelog, https://github.com/views-platform/views-hydranet/releases
22
+ Project-URL: Homepage, https://github.com/views-platform/views-hydranet
23
+ Project-URL: Issues, https://github.com/views-platform/views-hydranet/issues
24
+ Project-URL: Repository, https://github.com/views-platform/views-hydranet
25
+ Description-Content-Type: text/markdown
26
+
27
+ <div style="width: 100%; max-width: 1500px; height: 400px; overflow: hidden; position: relative;">
28
+ <img src="https://github.com/user-attachments/assets/1ec9e217-508d-4b10-a41a-08dface269c7" alt="VIEWS Twitter Header" style="position: absolute; top: -50px; width: 100%; height: auto;">
29
+ </div>
30
+
31
+
32
+ # **HydraNet**: Spatiotemporal Conflict Forecasting Model 👾
33
+
34
+ > **Part of the [VIEWS Platform](https://github.com/views-platform) ecosystem for large-scale conflict forecasting.**
35
+
36
+ ---
37
+
38
+ ## 📚 Table of Contents
39
+
40
+ 1. [Overview](#overview)
41
+ 2. [Role in the VIEWS Pipeline](#role-in-the-views-pipeline)
42
+ 3. [Features](#features)
43
+ 4. [Installation](#installation)
44
+ 5. [Usage](#usage)
45
+ 6. [Configuration & Stability](#configuration--stability)
46
+ 7. [Architecture](#architecture)
47
+ 8. [Project Structure](#project-structure)
48
+ 9. [Contributing](#contributing)
49
+ 10. [License](#license)
50
+ 11. [Acknowledgements](#acknowledgements)
51
+
52
+ ---
53
+
54
+ ## 🧠 Overview
55
+
56
+ **HydraNet** is an advanced machine learning model designed for **spatiotemporal forecasting of violent conflict** at high granularity. It predicts three types of violence—state-based, non-state-based, and one-sided—by solving regression and classification tasks concurrently.
57
+
58
+ The model provides:
59
+ - **Probabilistic Outputs**: Enables uncertainty quantification through posterior distributions.
60
+ - **Temporospatial Learning**: Leverages convolutional layers for spatial dependencies and LSTMs for temporal patterns.
61
+ - **Multi-Tasking**: Simultaneously predicts probabilities and magnitudes of conflict.
62
+
63
+ HydraNet is **FAIR-compliant** (Findable, Accessible, Interoperable, Reusable), ensuring transparency and ease of use for researchers and policymakers.
64
+
65
+ ---
66
+
67
+ ## 🌍 Role in the VIEWS Pipeline
68
+
69
+ HydraNet is a core component of the **Violence & Impacts Early Warning System (VIEWS)** pipeline, working alongside other repositories:
70
+
71
+ - **[views-pipeline-core](https://github.com/views-platform/views-pipeline-core):** Manages data ingestion, preprocessing, and pipeline orchestration.
72
+ - **[views-models](https://github.com/views-platform/views-models):** Provides interfaces to train, test, and deploy HydraNet.
73
+ - **[views-evaluation](https://github.com/views-platform/views-evaluation):** Evaluates model predictions and performs calibration tasks.
74
+ - **[docs](https://github.com/views-platform/docs):** Organization/pipeline level documentation.
75
+
76
+ ### Integration Workflow
77
+
78
+ HydraNet fits into the VIEWS pipeline as follows:
79
+ 1. **Data Input:** Preprocessed PRIO grid-cell-level conflict data is retrieved from **views-pipeline-core**.
80
+ 2. **Model Execution:** HydraNet generates probabilistic forecasts for multiple violence types across a 36-month horizon.
81
+ 3. **Evaluation and Calibration:** Outputs are passed to **views-evaluation** for ensembling and alignment with other models.
82
+
83
+ ---
84
+
85
+ ## ✨ Features
86
+
87
+ - **Multi-Task Learning:** Simultaneous prediction of probabilities and magnitudes for three conflict types.
88
+ - **Uncertainty Quantification:** Generates posterior distributions for robust decision-making.
89
+ - **Hybrid Architecture:** Combines CNNs for spatial dependencies, LSTMs for temporal patterns, and U-net for precision.
90
+ - **Minimal Manual Engineering:** Relies solely on past conflict history, simplifying input requirements.
91
+ - **Scalable Design:** Adaptable for new features and forecasting tasks.
92
+
93
+ ---
94
+
95
+ ## ⚙️ Installation
96
+
97
+ ### Prerequisites
98
+
99
+ - Python >= 3.8
100
+ - GPU support recommended (e.g., NVIDIA CUDA).
101
+
102
+ ### Steps
103
+
104
+ See the organization/pipeline level [docs](https://github.com/views-platform/docs)
105
+
106
+ ---
107
+
108
+ ## 🚀 Usage
109
+
110
+ ### 1. Run Training Locally
111
+
112
+ See the organization/pipeline level [docs](https://github.com/views-platform/docs)
113
+
114
+ ### 2. Use in the VIEWS Pipeline
115
+
116
+ HydraNet seamlessly integrates into the broader VIEWS pipeline. After training and prediction, the outputs can be passed into the **views-evaluation** repository for further analysis and calibration.
117
+
118
+ ---
119
+
120
+ ## ⚙️ Configuration & Stability
121
+
122
+ HydraNet uses a **Strict Handshake** protocol to ensure production predictability. All hyperparameters are validated against a Pydantic schema (`HydraNetConfig`) at the start of every task.
123
+
124
+ - **Fail-Fast:** If a required field is missing or a value is invalid (e.g., a typo in `transform`), the program will halt immediately with a detailed error report.
125
+ - **Safe-Mode:** The system uses internal state protection to ensure that critical paths (like model saving and data loading) are robust against partial initializations or mocked environments.
126
+
127
+ ### Feature Lifecycle (ADR 046)
128
+ HydraNet employs a **Symmetric Feature Lifecycle** governed by an "Instructional Blueprint."
129
+ - **Transformations:** Mathematical scaling (e.g., `log1p`) applied to raw inputs.
130
+ - **Derivations:** Manufacturing instructions for targets (e.g., `binary` thresholding) applied consistently during training and evaluation.
131
+ - **Handshake:** The model manager "sanctifies" ground-truth data for evaluation, ensuring that targets like `by_sb_best` are derived on-the-fly and bit-perfect with training logic.
132
+
133
+ ### Prediction Output Format (ADR 047)
134
+ HydraNet adopts the **PredictionFrame** interface mandated by `views-pipeline-core` (ADR-033).
135
+
136
+ - **What:** `_evaluate_model_artifact()` returns `dict[str, list[PredictionFrame]]` and `_forecast_model_artifact()` returns `dict[str, PredictionFrame]` — one entry per target signal.
137
+ - **Why:** Target-keyed output enables multi-target dispatch, enforces a validated `(N, S)` shape contract, and unlocks automatic parity auditing between the PF and legacy DataFrame paths.
138
+ - **How:** The config declares `"prediction_format": "prediction_frame"`. The manager converts its internal DataFrames via `_to_pf_dict()` before returning. The upstream pipeline reads the flag and routes through `PredictionFrameDispatcher`.
139
+ - **Guide:** See [`reports/guides/prediction_frame.md`](reports/guides/prediction_frame.md) for a self-contained implementation guide, including how to adopt this pattern in other model repos.
140
+
141
+ ---
142
+
143
+ ## 🏗 Architecture
144
+
145
+ HydraNet employs a **probabilistic recurrent U-net** architecture optimized for spatiotemporal conflict forecasting.
146
+
147
+ ### Key Components
148
+
149
+ - **CNNs (Convolutional Neural Networks):** Capture intricate spatial patterns in grid-cell data.
150
+ - **LSTMs (Long Short-Term Memory networks):** Model temporal dependencies and trends.
151
+ - **Dropout Layers:** Enable Monte Carlo sampling to quantify model uncertainty.
152
+ - **Multi-Decoder Design:** Outputs six distinct forecasts (probabilities and magnitudes for three violence types).
153
+
154
+ ### Workflow
155
+
156
+ 1. **Input:** Historical conflict fatalities categorized as state-based, non-state, and one-sided.
157
+ 2. **Data Processing:** Converts historical data into z-stacks of monthly grids with three channels (one for each violence type).
158
+ 3. **Prediction:** Generates six outputs: probabilities and magnitudes for each type of violence.
159
+
160
+ For a detailed explanation of the architecture, refer to the **[HydraNet Paper](link-to-paper)**.
161
+
162
+ ---
163
+
164
+ ## 🗂 Project Structure
165
+
166
+ ```plaintext
167
+ views_hydranet/
168
+ ├── README.md # Documentation
169
+ ├── tests # Unit and integration tests
170
+ ├── views_hydranet # Main source code
171
+ │ ├── architecture # Model definitions (CNN + LSTM + U-net)
172
+ │ ├── evaluate # Evaluation scripts
173
+ │ ├── forecast # Forecasting utilities
174
+ │ ├── manager # Workflow management
175
+ │ ├── train # Training logic
176
+ │ ├── utils # Helper functions (logging, metrics, etc.)
177
+ │ ├── __init__.py # Package initialization
178
+ ├── .gitignore # Git ignore rules
179
+ ├── pyproject.toml # Poetry project file
180
+ ├── poetry.lock # Dependency lock file
181
+ ```
182
+
183
+ ---
184
+
185
+ ## 🤝 Contributing
186
+
187
+ We welcome contributions to HydraNet! Please follow the contribution guidelines outlined in the [organization-level documentation](https://github.com/views-platform/docs).
188
+
189
+ ---
190
+
191
+ ## 📜 License
192
+
193
+ ...
194
+
195
+ ---
196
+
197
+ ## 💬 Acknowledgements
198
+
199
+ <p align="center">
200
+ <img src="https://raw.githubusercontent.com/views-platform/docs/main/images/views_funders.png" alt="Views Funders" width="80%">
201
+ </p>
202
+
203
+ HydraNet builds upon:
204
+
205
+ - [UCDP Georeferenced Event Dataset (GED)](https://ucdp.uu.se/) for conflict data.
206
+ - [PRIO Grid](https://grid.prio.org/#/) for spatial resolution.
207
+ - Concepts from Hegre et al. (2019), Hegre et al. (2021), and Vesco et al. (2022).
208
+ - Funding from the **European Research Council** and the **Danish Research Council**.
209
+
210
+ Special thanks to the **VIEWS MD&D Team** for their collaboration, guidance, and efforts.
211
+
@@ -0,0 +1,184 @@
1
+ <div style="width: 100%; max-width: 1500px; height: 400px; overflow: hidden; position: relative;">
2
+ <img src="https://github.com/user-attachments/assets/1ec9e217-508d-4b10-a41a-08dface269c7" alt="VIEWS Twitter Header" style="position: absolute; top: -50px; width: 100%; height: auto;">
3
+ </div>
4
+
5
+
6
+ # **HydraNet**: Spatiotemporal Conflict Forecasting Model 👾
7
+
8
+ > **Part of the [VIEWS Platform](https://github.com/views-platform) ecosystem for large-scale conflict forecasting.**
9
+
10
+ ---
11
+
12
+ ## 📚 Table of Contents
13
+
14
+ 1. [Overview](#overview)
15
+ 2. [Role in the VIEWS Pipeline](#role-in-the-views-pipeline)
16
+ 3. [Features](#features)
17
+ 4. [Installation](#installation)
18
+ 5. [Usage](#usage)
19
+ 6. [Configuration & Stability](#configuration--stability)
20
+ 7. [Architecture](#architecture)
21
+ 8. [Project Structure](#project-structure)
22
+ 9. [Contributing](#contributing)
23
+ 10. [License](#license)
24
+ 11. [Acknowledgements](#acknowledgements)
25
+
26
+ ---
27
+
28
+ ## 🧠 Overview
29
+
30
+ **HydraNet** is an advanced machine learning model designed for **spatiotemporal forecasting of violent conflict** at high granularity. It predicts three types of violence—state-based, non-state-based, and one-sided—by solving regression and classification tasks concurrently.
31
+
32
+ The model provides:
33
+ - **Probabilistic Outputs**: Enables uncertainty quantification through posterior distributions.
34
+ - **Temporospatial Learning**: Leverages convolutional layers for spatial dependencies and LSTMs for temporal patterns.
35
+ - **Multi-Tasking**: Simultaneously predicts probabilities and magnitudes of conflict.
36
+
37
+ HydraNet is **FAIR-compliant** (Findable, Accessible, Interoperable, Reusable), ensuring transparency and ease of use for researchers and policymakers.
38
+
39
+ ---
40
+
41
+ ## 🌍 Role in the VIEWS Pipeline
42
+
43
+ HydraNet is a core component of the **Violence & Impacts Early Warning System (VIEWS)** pipeline, working alongside other repositories:
44
+
45
+ - **[views-pipeline-core](https://github.com/views-platform/views-pipeline-core):** Manages data ingestion, preprocessing, and pipeline orchestration.
46
+ - **[views-models](https://github.com/views-platform/views-models):** Provides interfaces to train, test, and deploy HydraNet.
47
+ - **[views-evaluation](https://github.com/views-platform/views-evaluation):** Evaluates model predictions and performs calibration tasks.
48
+ - **[docs](https://github.com/views-platform/docs):** Organization/pipeline level documentation.
49
+
50
+ ### Integration Workflow
51
+
52
+ HydraNet fits into the VIEWS pipeline as follows:
53
+ 1. **Data Input:** Preprocessed PRIO grid-cell-level conflict data is retrieved from **views-pipeline-core**.
54
+ 2. **Model Execution:** HydraNet generates probabilistic forecasts for multiple violence types across a 36-month horizon.
55
+ 3. **Evaluation and Calibration:** Outputs are passed to **views-evaluation** for ensembling and alignment with other models.
56
+
57
+ ---
58
+
59
+ ## ✨ Features
60
+
61
+ - **Multi-Task Learning:** Simultaneous prediction of probabilities and magnitudes for three conflict types.
62
+ - **Uncertainty Quantification:** Generates posterior distributions for robust decision-making.
63
+ - **Hybrid Architecture:** Combines CNNs for spatial dependencies, LSTMs for temporal patterns, and U-net for precision.
64
+ - **Minimal Manual Engineering:** Relies solely on past conflict history, simplifying input requirements.
65
+ - **Scalable Design:** Adaptable for new features and forecasting tasks.
66
+
67
+ ---
68
+
69
+ ## ⚙️ Installation
70
+
71
+ ### Prerequisites
72
+
73
+ - Python >= 3.8
74
+ - GPU support recommended (e.g., NVIDIA CUDA).
75
+
76
+ ### Steps
77
+
78
+ See the organization/pipeline level [docs](https://github.com/views-platform/docs)
79
+
80
+ ---
81
+
82
+ ## 🚀 Usage
83
+
84
+ ### 1. Run Training Locally
85
+
86
+ See the organization/pipeline level [docs](https://github.com/views-platform/docs)
87
+
88
+ ### 2. Use in the VIEWS Pipeline
89
+
90
+ HydraNet seamlessly integrates into the broader VIEWS pipeline. After training and prediction, the outputs can be passed into the **views-evaluation** repository for further analysis and calibration.
91
+
92
+ ---
93
+
94
+ ## ⚙️ Configuration & Stability
95
+
96
+ HydraNet uses a **Strict Handshake** protocol to ensure production predictability. All hyperparameters are validated against a Pydantic schema (`HydraNetConfig`) at the start of every task.
97
+
98
+ - **Fail-Fast:** If a required field is missing or a value is invalid (e.g., a typo in `transform`), the program will halt immediately with a detailed error report.
99
+ - **Safe-Mode:** The system uses internal state protection to ensure that critical paths (like model saving and data loading) are robust against partial initializations or mocked environments.
100
+
101
+ ### Feature Lifecycle (ADR 046)
102
+ HydraNet employs a **Symmetric Feature Lifecycle** governed by an "Instructional Blueprint."
103
+ - **Transformations:** Mathematical scaling (e.g., `log1p`) applied to raw inputs.
104
+ - **Derivations:** Manufacturing instructions for targets (e.g., `binary` thresholding) applied consistently during training and evaluation.
105
+ - **Handshake:** The model manager "sanctifies" ground-truth data for evaluation, ensuring that targets like `by_sb_best` are derived on-the-fly and bit-perfect with training logic.
106
+
107
+ ### Prediction Output Format (ADR 047)
108
+ HydraNet adopts the **PredictionFrame** interface mandated by `views-pipeline-core` (ADR-033).
109
+
110
+ - **What:** `_evaluate_model_artifact()` returns `dict[str, list[PredictionFrame]]` and `_forecast_model_artifact()` returns `dict[str, PredictionFrame]` — one entry per target signal.
111
+ - **Why:** Target-keyed output enables multi-target dispatch, enforces a validated `(N, S)` shape contract, and unlocks automatic parity auditing between the PF and legacy DataFrame paths.
112
+ - **How:** The config declares `"prediction_format": "prediction_frame"`. The manager converts its internal DataFrames via `_to_pf_dict()` before returning. The upstream pipeline reads the flag and routes through `PredictionFrameDispatcher`.
113
+ - **Guide:** See [`reports/guides/prediction_frame.md`](reports/guides/prediction_frame.md) for a self-contained implementation guide, including how to adopt this pattern in other model repos.
114
+
115
+ ---
116
+
117
+ ## 🏗 Architecture
118
+
119
+ HydraNet employs a **probabilistic recurrent U-net** architecture optimized for spatiotemporal conflict forecasting.
120
+
121
+ ### Key Components
122
+
123
+ - **CNNs (Convolutional Neural Networks):** Capture intricate spatial patterns in grid-cell data.
124
+ - **LSTMs (Long Short-Term Memory networks):** Model temporal dependencies and trends.
125
+ - **Dropout Layers:** Enable Monte Carlo sampling to quantify model uncertainty.
126
+ - **Multi-Decoder Design:** Outputs six distinct forecasts (probabilities and magnitudes for three violence types).
127
+
128
+ ### Workflow
129
+
130
+ 1. **Input:** Historical conflict fatalities categorized as state-based, non-state, and one-sided.
131
+ 2. **Data Processing:** Converts historical data into z-stacks of monthly grids with three channels (one for each violence type).
132
+ 3. **Prediction:** Generates six outputs: probabilities and magnitudes for each type of violence.
133
+
134
+ For a detailed explanation of the architecture, refer to the **[HydraNet Paper](link-to-paper)**.
135
+
136
+ ---
137
+
138
+ ## 🗂 Project Structure
139
+
140
+ ```plaintext
141
+ views_hydranet/
142
+ ├── README.md # Documentation
143
+ ├── tests # Unit and integration tests
144
+ ├── views_hydranet # Main source code
145
+ │ ├── architecture # Model definitions (CNN + LSTM + U-net)
146
+ │ ├── evaluate # Evaluation scripts
147
+ │ ├── forecast # Forecasting utilities
148
+ │ ├── manager # Workflow management
149
+ │ ├── train # Training logic
150
+ │ ├── utils # Helper functions (logging, metrics, etc.)
151
+ │ ├── __init__.py # Package initialization
152
+ ├── .gitignore # Git ignore rules
153
+ ├── pyproject.toml # Poetry project file
154
+ ├── poetry.lock # Dependency lock file
155
+ ```
156
+
157
+ ---
158
+
159
+ ## 🤝 Contributing
160
+
161
+ We welcome contributions to HydraNet! Please follow the contribution guidelines outlined in the [organization-level documentation](https://github.com/views-platform/docs).
162
+
163
+ ---
164
+
165
+ ## 📜 License
166
+
167
+ ...
168
+
169
+ ---
170
+
171
+ ## 💬 Acknowledgements
172
+
173
+ <p align="center">
174
+ <img src="https://raw.githubusercontent.com/views-platform/docs/main/images/views_funders.png" alt="Views Funders" width="80%">
175
+ </p>
176
+
177
+ HydraNet builds upon:
178
+
179
+ - [UCDP Georeferenced Event Dataset (GED)](https://ucdp.uu.se/) for conflict data.
180
+ - [PRIO Grid](https://grid.prio.org/#/) for spatial resolution.
181
+ - Concepts from Hegre et al. (2019), Hegre et al. (2021), and Vesco et al. (2022).
182
+ - Funding from the **European Research Council** and the **Danish Research Council**.
183
+
184
+ Special thanks to the **VIEWS MD&D Team** for their collaboration, guidance, and efforts.
@@ -0,0 +1,58 @@
1
+ [project]
2
+ name = "views-hydranet"
3
+ version = "0.1.0"
4
+ description = "views-hydranet is a package that contains modeling procedure, evaluation and forecasting using HydraNet implemented in PyTorch"
5
+ authors = [
6
+ {name = "Dylan",email = "52908667+smellycloud@users.noreply.github.com"}
7
+ ]
8
+ license = {text = "MIT"}
9
+ readme = "README.md"
10
+ requires-python = ">=3.11,<3.15"
11
+ dependencies = [
12
+ "views-pipeline-core (>=3.0.0,<4.0.0)",
13
+ "views-frames (>=1.10.2,<2)",
14
+ "torch>=2.2.1,<3.0.0"
15
+ ]
16
+
17
+ # issue #215: matplotlib is imported lazily by VisualDiagnostics (optional plotting stack). Declare it
18
+ # as an OPTIONAL extra so models that enable diagnostics (diagnostic_visualizations=True) can pin it via
19
+ # `views-hydranet[viz]`; the default headless run path needs no plotting stack.
20
+ [project.urls]
21
+ Homepage = "https://github.com/views-platform/views-hydranet"
22
+ Repository = "https://github.com/views-platform/views-hydranet"
23
+ Issues = "https://github.com/views-platform/views-hydranet/issues"
24
+ Changelog = "https://github.com/views-platform/views-hydranet/releases"
25
+
26
+ [project.optional-dependencies]
27
+ viz = ["matplotlib>=3.8,<4"]
28
+
29
+ [build-system]
30
+ requires = ["poetry-core>=2.0.0,<3.0.0"]
31
+ build-backend = "poetry.core.masonry.api"
32
+
33
+ [tool.poetry.group.dev.dependencies]
34
+ ruff = ">=0.14.14,<0.15.0"
35
+ mypy = ">=1.19.1,<2.0.0"
36
+ pytest = "<9.0.0"
37
+ pre-commit = ">=4.5.1,<5.0.0"
38
+ pytest-cov = ">=5.0.0,<6.0.0"
39
+ # #215: the test suite renders diagnostics + imports matplotlib at module top (test_visual_diagnostics,
40
+ # test_memory_fingerprint), and conftest fails the run if collection drops below the min count — so
41
+ # matplotlib must be present in the test env even though it's a runtime-optional 'viz' extra.
42
+ matplotlib = ">=3.8,<4"
43
+
44
+
45
+ [tool.ruff]
46
+ line-length = 99
47
+
48
+ [tool.ruff.lint]
49
+ # Enable Pyflakes (F), pycodestyle errors (E) & warnings (W), and isort (I)
50
+ select = ["E", "F", "W", "I"]
51
+
52
+ [tool.ruff.format]
53
+ # Use double quotes for strings
54
+ quote-style = "double"
55
+
56
+ [tool.mypy]
57
+ # Ignore errors from libraries that don't have type hints
58
+ ignore_missing_imports = true
@@ -0,0 +1,36 @@
1
+ """views-hydranet — the HydraNet conflict-forecasting model for the VIEWS platform.
2
+
3
+ The public API of this package is **`HydranetManager`, and nothing else.**
4
+
5
+ That is not an aspiration; it is what the consumers do. All eight models in `views-models`
6
+ that constitute the `rusty_bucket` ensemble import exactly one name, and it is this one::
7
+
8
+ from views_hydranet import HydranetManager
9
+
10
+ Everything else — `views_hydranet.utils`, `.train`, `.architectures`, `.distributions`,
11
+ `.infrastructure` — is **internal**. It is importable, because Python has no way to prevent it,
12
+ but it carries no stability promise and may be renamed or moved without a major version bump.
13
+
14
+ Why this file says so at all: publishing to PyPI makes every module in the wheel reachable by
15
+ strangers, and anything reachable can be depended upon. Without this declaration, all 67 modules
16
+ would look equally official, and #181 — reorganising `utils/`, which is 42 of them — would become
17
+ a breaking change for anyone who had imported from it. With it, that reorganisation stays free.
18
+
19
+ See `docs/guides/publishing-to-pypi.md`, and #181 / #279.
20
+
21
+ ⚠️ The import below is LAZY, and must stay lazy. `HydranetManager` pulls in torch, and this
22
+ package has two tests — `test_importing_config_initializer_does_not_import_torch` and
23
+ `test_importing_the_registry_does_not_import_torch` — that guarantee the light modules stay light.
24
+ An eager import here breaks both, because importing ANY submodule runs this file first. PEP 562's
25
+ module-level `__getattr__` gives the short public path without that cost.
26
+ """
27
+
28
+ __all__ = ["HydranetManager"]
29
+
30
+
31
+ def __getattr__(name: str):
32
+ if name == "HydranetManager":
33
+ from views_hydranet.manager.hydranet_manager import HydranetManager
34
+
35
+ return HydranetManager
36
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")