README.md

---
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}}
}
```