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

}

```