Upload Safecast radiation spatial regressor

README.md

@@ -0,0 +1,162 @@
+---
+language:
+- en
+license: cc0-1.0
+tags:
+- tabular-regression
+- spatial-ml
+- radiation
+- safecast
+- environmental-science
+- anomaly-detection
+- pytorch
+- safetensors
+- onnx
+datasets:
+- hsilvosa/safecast-radiation
+metrics:
+- r2
+- rmse
+- mae
+model-index:
+- name: safecast-spatial-harmonic-net
+  results:
+  - task:
+      type: tabular-regression
+      name: Global Radiation Spatial Regression
+    dataset:
+      type: hsilvosa/safecast-radiation
+      name: Safecast Historical Radiation Measurements
+    metrics:
+    - type: r2
+      value: 0.0785
+      name: R2 Score (log-scale)
+    - type: rmse
+      value: 3.11636
+      name: RMSE (uSv/h)
+    - type: mae
+      value: 0.67873
+      name: MAE (uSv/h)
+---
+
+# Global Radiation Anomaly Map & Spatial Regressor (Safecast)
+
+## Model Overview
+
+This repository provides **SpatialHarmonicNet**, a continuous spatial neural regression model that predicts environmental ambient radiation levels in microsieverts per hour (uSv/h) anywhere on Earth from geographic coordinates (latitude, longitude) and performs real-time radioactive anomaly detection.
+
+The model is trained on crowdsourced radiation sensor measurements from the [Safecast Historical Dataset](https://huggingface.co/datasets/hsilvosa/safecast-radiation), which spans over 265 million measurements collected worldwide from 2011 to 2026.
+
+## Architecture
+
+SpatialHarmonicNet is designed specifically for spherical planetary coordinates:
+
+1. **Unit Sphere Projection**: Longitude and latitude in degrees are mapped to 3D Cartesian coordinates on the unit sphere (x, y, z) = (cos(lat)*cos(lon), cos(lat)*sin(lon), sin(lat)), preventing meridian boundary discontinuity at +/-180 degrees and polar distortion.
+2. **Multi-Scale Spherical Fourier Feature Encoding**: Geometric frequency bands project the 3D unit coordinates across harmonic spatial frequencies ranging from planetary dimensions down to localized 1km neighborhoods.
+3. **Deep Residual Backbone**: Multi-layer residual MLP with LayerNorm, SiLU activations, and Dropout.
+4. **Heteroscedastic Gaussian Uncertainty Head**: Predicts both the expected mean log-radiation mu(x) and aleatoric variance sigma^2(x) via Negative Log-Likelihood (NLL) optimization.
+5. **Real-time Anomaly Detection**: Calculates statistical Z-scores and conformal prediction intervals to classify measurements into NORMAL, ELEVATED, ANOMALY_HIGH, and ANOMALY_CRITICAL.
+
+## Evaluation Results
+
+Evaluation performed on a holdout spatial test split (stratified across global 0.1-degree spatial grid cells):
+
+| Metric | SpatialHarmonicNet (PyTorch) |
+| --- | --- |
+| R2 Score (log-scale) | 0.0785 |
+| RMSE (uSv/h) | 3.11636 uSv/h |
+| MAE (uSv/h) | 0.67873 uSv/h |
+| 95% Confidence Interval Coverage (PICP) | 94.3% |
+
+### Reference Landmark Verification
+
+| Location | Category | Expected / Measured Baseline | Anomaly Trigger (at 5.0 uSv/h) |
+| --- | --- | --- | --- |
+| Chernobyl Reactor 4 Shelter | Nuclear Exclusion Zone | Elevated | ANOMALY_HIGH / CRITICAL |
+| Pripyat Red Forest | Nuclear Exclusion Zone | Elevated | ANOMALY_HIGH / CRITICAL |
+| Fukushima Daiichi | Nuclear Exclusion Zone | Elevated | ANOMALY_HIGH / CRITICAL |
+| Tokyo Metropolitan Area | Urban Background | ~0.05 - 0.08 uSv/h | ANOMALY_CRITICAL (Z > 12) |
+| Paris, France | Urban Background | ~0.06 - 0.09 uSv/h | ANOMALY_CRITICAL (Z > 12) |
+| New York City, USA | Urban Background | ~0.07 - 0.10 uSv/h | ANOMALY_CRITICAL (Z > 12) |
+| Denver, USA (Mile-High) | Elevated Cosmic Background | ~0.12 - 0.16 uSv/h | ANOMALY_CRITICAL (Z > 10) |
+
+## Quickstart & Usage
+
+### 1. Installation
+
+```bash
+pip install torch safetensors numpy pandas scipy
+```
+
+### 2. Python Inference Example
+
+```python
+import json
+import torch
+from safetensors.torch import load_file
+from radiation_map.models.spatial_net import SpatialHarmonicNet
+from radiation_map.models.anomaly_detector import RadiationAnomalyDetector
+
+# 1. Initialize model
+model = SpatialHarmonicNet(num_frequencies=32, max_frequency_log=4.5, hidden_dims=(256, 256, 128, 64))
+state_dict = load_file("model.safetensors")
+model.load_state_dict(state_dict)
+model.eval()
+
+# 2. Predict baseline radiation at a coordinate
+# Coordinates for Tokyo (35.6895 N, 139.6917 E)
+pred = model.predict_radiation(latitudes=35.6895, longitudes=139.6917)
+print(f"Predicted baseline: {pred['radiation_usv']:.4f} uSv/h")
+print(f"95% Confidence Interval: [{pred['ci_lower_usv']:.4f}, {pred['ci_upper_usv']:.4f}] uSv/h")
+
+# 3. Real-time Anomaly Detection
+detector = RadiationAnomalyDetector(model)
+result = detector.detect(
+    latitude=35.6895,
+    longitude=139.6917,
+    observed_value=2.50, # hypothetical spike in uSv/h
+    unit="usv"
+)
+
+print(f"Severity: {result.severity.value}")
+print(f"Z-score: {result.z_score:.2f}")
+print(f"Fold increase: {result.fold_increase:.1f}x")
+print(f"Description: {result.description}")
+```
+
+### 3. ONNX Runtime Inference
+
+```python
+import numpy as np
+import onnxruntime as ort
+
+session = ort.InferenceSession("spatial_regressor.onnx")
+
+# Project lat/lon to 3D Cartesian coordinates
+lat, lon = np.radians(35.6895), np.radians(139.6917)
+xyz = np.array([[np.cos(lat)*np.cos(lon), np.cos(lat)*np.sin(lon), np.sin(lat)]], dtype=np.float32)
+
+inputs = {"coords_cartesian": xyz}
+mu_log, log_var = session.run(None, inputs)
+
+# Inverse log transform to get uSv/h
+pred_usv = np.expm1(mu_log[0][0]) / 10.0
+print(f"ONNX Predicted uSv/h: {pred_usv:.4f}")
+```
+
+## Intended Use & Limitations
+
+- **Intended Use**: Environmental baseline modeling, spatial regression research, citizen-science data exploration, and screening for radioactive anomalies.
+- **Limitations**: Safecast data is crowdsourced and collected with mobile bGeigie Geiger-Muller counters. It is not official regulatory or government monitoring data. Geiger counters measure dose equivalents with Cs-137 calibration approximations.
+
+## Citation & Attribution
+
+```bibtex
+@misc{safecast_spatial_radiation,
+  author = {Safecast Contributors and Project Authors},
+  title = {Global Radiation Anomaly Map and Spatial Regressor},
+  year = {2026},
+  publisher = {Hugging Face},
+  howpublished = {\url{https://huggingface.co/models}}
+}
+```

config.json

@@ -0,0 +1,33 @@
+{
+  "model_type": "spatial_harmonic_net",
+  "task": "tabular-regression",
+  "domain": "spatial-ml",
+  "in_dim": 3,
+  "coordinate_system": "WGS84_spherical_cartesian",
+  "num_frequencies": 32,
+  "max_frequency_log": 4.5,
+  "hidden_dims": [
+    256,
+    256,
+    128,
+    64
+  ],
+  "cpm_to_usv_factor": 0.002994,
+  "target_transform": "log1p_10x",
+  "metrics": {
+    "r2": 0.0785,
+    "rmse_usv": 3.11636,
+    "mae_usv": 0.67873,
+    "medae_usv": 0.04192,
+    "rmse_log": 0.90007,
+    "mae_log": 0.43391,
+    "picp_95": 0.9434,
+    "mpiw_usv": 0.98325,
+    "sample_count": 64258
+  },
+  "anomaly_thresholds": {
+    "normal_z_max": 2.0,
+    "elevated_z_max": 4.0,
+    "anomaly_high_z_max": 8.0
+  }
+}

model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:dd5fe75af43c739b7cb278ad5516a8e52e2276d12f1ed06032c3767c4d6d79dd
+size 1584800

pytorch_model.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:00e9822883374fdba9ccae0e8274502b820938263007acee4ee79be0d779b8ed
+size 1594958

reference_hotspots.json

@@ -0,0 +1,79 @@
+{
+  "Chernobyl_Reactor_4": {
+    "latitude": 51.3896,
+    "longitude": 30.0999,
+    "expected_min_usv": 1.5,
+    "category": "hotspot",
+    "description": "Chernobyl Nuclear Power Plant Shelter"
+  },
+  "Pripyat_Red_Forest": {
+    "latitude": 51.3833,
+    "longitude": 30.05,
+    "expected_min_usv": 1.0,
+    "category": "hotspot",
+    "description": "Pripyat Red Forest Exclusion Zone"
+  },
+  "Fukushima_Daiichi": {
+    "latitude": 37.4211,
+    "longitude": 141.0328,
+    "expected_min_usv": 0.8,
+    "category": "hotspot",
+    "description": "Fukushima Daiichi Nuclear Power Station"
+  },
+  "Futaba_Town_Fukushima": {
+    "latitude": 37.4549,
+    "longitude": 141.0101,
+    "expected_min_usv": 0.4,
+    "category": "hotspot",
+    "description": "Futaba Exclusion Zone, Fukushima Prefecture"
+  },
+  "Ramsar_Talesh_Mahalleh": {
+    "latitude": 36.9011,
+    "longitude": 50.6558,
+    "expected_min_usv": 0.5,
+    "category": "natural_high",
+    "description": "Ramsar, Iran (high natural radioactivity from radium-rich hot springs)"
+  },
+  "Guarapari_Beach": {
+    "latitude": -20.6714,
+    "longitude": -40.4981,
+    "expected_min_usv": 0.3,
+    "category": "natural_high",
+    "description": "Guarapari, Brazil (monazite sand background)"
+  },
+  "Tokyo_Shinjuku": {
+    "latitude": 35.6938,
+    "longitude": 139.7034,
+    "expected_min_usv": 0.05,
+    "category": "background",
+    "description": "Tokyo Metropolitan Area"
+  },
+  "Paris_Eiffel": {
+    "latitude": 48.8584,
+    "longitude": 2.2945,
+    "expected_min_usv": 0.06,
+    "category": "background",
+    "description": "Paris, France"
+  },
+  "New_York_Manhattan": {
+    "latitude": 40.7831,
+    "longitude": -73.9712,
+    "expected_min_usv": 0.07,
+    "category": "background",
+    "description": "New York City, USA"
+  },
+  "London_Trafalgar": {
+    "latitude": 51.508,
+    "longitude": -0.1281,
+    "expected_min_usv": 0.06,
+    "category": "background",
+    "description": "London, UK"
+  },
+  "Denver_High_Altitude": {
+    "latitude": 39.7392,
+    "longitude": -104.9903,
+    "expected_min_usv": 0.12,
+    "category": "background_elevated",
+    "description": "Denver, Colorado (mile-high altitude cosmic ray contribution)"
+  }
+}

spatial_ensemble_regressor.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d892d2b36087e0985d4be51f471beef1d9739a505d284a9739da538dc8c5d8ff
+size 7032362

spatial_regressor.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3fddaf53b89b8e12ecdfdc1a0f96071db5507c3e8bcde1bcec0d5821a8af4939
+size 1607085