HMIS-Chronos / README.md
sakasurya's picture
Access note: verified organisation email
ef733d6 verified
|
Raw History Blame Contribute Delete
10.9 kB
---
license: cc-by-nc-sa-4.0
base_model: amazon/chronos-2
pipeline_tag: time-series-forecasting
library_name: chronos-forecasting
language:
- en
tags:
- time-series
- forecasting
- chronos
- chronos-2
- health
- india
- hmis
datasets:
- judicialmind/HMIS-Bench
extra_gated_prompt: 'This model is released under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 licence (CC
BY-NC-SA 4.0): research, academic, personal and other non-commercial use is permitted with attribution; adaptations must
be shared under the same licence; commercial use is not permitted. The original public source data remains under the Government
Open Data License - India (GODL-India). Commercial use: contact surya@judicialmind.ai or hello@judicialmind.ai.'
extra_gated_fields:
Name: text
Email: text
Organization: text
I accept the CC BY-NC-SA licence terms (research and non-commercial use only): checkbox
extra_gated_button_content: Accept and request access
---
# HMIS-Chronos
<!-- jm:top -->
Licence: CC BY-NC-SA 4.0 — research and non-commercial use only; derivatives must be shared under the same licence. Commercial use: contact surya@judicialmind.ai or hello@judicialmind.ai
Access is approved automatically when the email you enter matches your Hugging Face account email and belongs to the organisation you name; other requests are reviewed manually.
<!-- /jm:top -->
HMIS-Chronos is [Chronos-2](https://huggingface.co/amazon/chronos-2) (120M parameters) fine-tuned to forecast
monthly health-service counts that Indian sub-districts report to the Health Management Information System
(HMIS): antenatal registrations, deliveries, vaccinations, family planning, disease cases, outpatient and
inpatient attendance. It forecasts all indicators of a sub-district together, with Chronos-2 group attention
across them, and returns quantiles 1 to 3 months ahead. It is scored on the
[HMIS-Bench](https://huggingface.co/datasets/judicialmind/HMIS-Bench) benchmark, where its median forecasts have
the lowest MASE of the nine models at every horizon.
## Quickstart
```bash
pip install -r requirements.txt # chronos-forecasting 2.3.2, torch, pandas, pyarrow
```
```python
import pandas as pd
import torch
from chronos import Chronos2Pipeline
pipe = Chronos2Pipeline.from_pretrained("judicialmind/HMIS-Chronos", device_map="cpu", dtype=torch.float32)
# all HMIS-Bench series of one sub-district (Narpatganj, Araria, Bihar), up to July 2021
df = pd.read_parquet("hf://datasets/judicialmind/HMIS-Bench/series/bench.parquet",
columns=["series_id", "ts", "target", "subdistrict", "headline"])
df["ts"] = pd.to_datetime(df["ts"])
sub = df[(df.subdistrict == 1112) & (df.ts < "2021-08-01")]
months = pd.period_range(end="2021-07", periods=36, freq="M") # 36-month context, NaN = not reported
wide = (sub.assign(m=sub.ts.dt.to_period("M"))
.pivot(index="headline", columns="m", values="target").reindex(columns=months))
inputs = [torch.tensor(row, dtype=torch.float32) for row in wide.to_numpy()]
q, _ = pipe.predict_quantiles(inputs, prediction_length=3, quantile_levels=[0.1, 0.5, 0.9],
cross_learning=True) # group attention across the sub-district
for name, qi in list(zip(wide.index, q))[:2]:
print(name, "Aug-Oct 2021 median:", qi[0, :, 1].round().tolist(),
"80% band:", list(zip(qi[0, :, 0].round().tolist(), qi[0, :, 2].round().tolist())))
```
```
anc_registered Aug-Oct 2021 median: [986.0, 984.0, 970.0] 80% band: [(844.0, 1148.0), (804.0, 1183.0), (759.0, 1191.0)]
condoms Aug-Oct 2021 median: [1365.0, 1351.0, 1333.0] 80% band: [(1080.0, 1609.0), (976.0, 1669.0), (855.0, 1713.0)]
```
**Input.** One 1-D float tensor per series: the monthly counts before the forecast origin on a regular monthly
grid, oldest first, `NaN` for months that were not reported. The model was evaluated with 36 months of context
(shorter series are fine). Pass all series of one sub-district in one call with `cross_learning=True`; series in
the same call share information.
**Output.** `predict_quantiles` returns one tensor per input series of shape `(1, prediction_length,
n_quantiles)` (the leading 1 is the target dimension) and the median. Counts can come out slightly negative near
zero; clip at 0 if needed.
### Helper for long tables
`hmis_chronos.py` (in this repository) does the windowing and grouping for a long table with one row per
(series, month):
```python
import sys
from huggingface_hub import snapshot_download
sys.path.insert(0, snapshot_download("judicialmind/HMIS-Chronos"))
from hmis_chronos import load, forecast
pipe = load("judicialmind/HMIS-Chronos") # bfloat16 on GPU, float32 on CPU
three = df[df.subdistrict.isin([1112, 1113, 1114])] # df: series_id, ts, target, subdistrict (as above)
fc = forecast(pipe, three, origin="2021-08-01", horizon=3)
print(fc[["series_id", "h", "q0.1", "q0.5", "q0.9"]].head(3).round(1).to_string(index=False))
```
```
series_id h q0.1 q0.5 q0.9
hmis|10|188|1112|1.1|total 1 843.6 986.4 1148.2
hmis|10|188|1112|1.1|total 2 803.8 984.5 1182.8
hmis|10|188|1112|1.1|total 3 758.6 970.3 1191.1
```
`forecast` groups by `subdistrict` (set `group_col=None` to forecast each series alone), uses the 36 months before
`origin` and skips series with fewer than 8 reported months in them, which is the HMIS-Bench window rule. The same
module runs from the shell:
```bash
python hmis_chronos.py my_series.parquet --origin 2021-08-01 --horizon 3 --out forecasts.csv
```
Its forecasts match the HMIS-Bench forecast files of this model (computed on GPU in bfloat16) to a median
relative difference of 0.07% on CPU in float32.
## Files
| file | content |
|---|---|
| `model.safetensors`, `config.json` | Chronos-2 weights and configuration (12 layers, d_model 768, 21 quantile heads) |
| `hmis_chronos.py` | `load`, `forecast` and a CLI for long monthly tables |
| `requirements.txt` | pinned runtime dependencies |
## Results
HMIS-Bench, averaged over six monthly origins (August 2021 to January 2022), on the same 599,714 windows for every
model. `chronos2_ft_hmis_s0` is this model. Lower WQL and MASE are better; a calibrated 80% interval covers 0.80;
win rate = share of windows with lower MASE than zero-shot Chronos-2.
All series:
| h | model | WQL | MASE | cov_80 | win rate vs chronos2 |
|---|---|---|---|---|---|
| 1 | **HMIS-Chronos** (`chronos2_ft_hmis_s0`) | 0.1553 | **0.8224** | 0.8019 | 0.4985 |
| 1 | `chronos2` (zero-shot) | 0.1458 | 0.8380 | 0.8267 | – |
| 1 | `tirex` | 0.1435 | 0.8348 | 0.8278 | 0.5175 |
| 1 | `timesfm25` | 0.1459 | 0.8378 | 0.7568 | 0.5193 |
| 1 | `lightgbm` | 0.1473 | 0.8349 | 0.7989 | 0.5070 |
| 1 | `naive` | 0.1540 | 0.9081 | 0.7441 | 0.4833 |
| 2 | **HMIS-Chronos** (`chronos2_ft_hmis_s0`) | 0.1671 | **0.8738** | 0.8013 | 0.5073 |
| 2 | `chronos2` (zero-shot) | 0.1594 | 0.8949 | 0.8363 | – |
| 2 | `tirex` | 0.1575 | 0.8893 | 0.8404 | 0.5222 |
| 2 | `timesfm25` | 0.1582 | 0.8944 | 0.7521 | 0.5217 |
| 2 | `lightgbm` | 0.1574 | 0.8917 | 0.7959 | 0.5050 |
| 2 | `naive` | 0.1709 | 0.9823 | 0.7683 | 0.4674 |
| 3 | **HMIS-Chronos** (`chronos2_ft_hmis_s0`) | 0.1770 | **0.9153** | 0.8022 | 0.5094 |
| 3 | `chronos2` (zero-shot) | 0.1683 | 0.9376 | 0.8409 | – |
| 3 | `tirex` | 0.1665 | 0.9291 | 0.8476 | 0.5305 |
| 3 | `timesfm25` | 0.1662 | 0.9359 | 0.7472 | 0.5247 |
| 3 | `lightgbm` | 0.1634 | 0.9326 | 0.7923 | 0.5099 |
| 3 | `naive` | 0.1821 | 1.0405 | 0.7854 | 0.4570 |
Held-out states (Uttar Pradesh, Bihar, Odisha, Andhra Pradesh; not seen in fine-tuning):
| h | model | WQL | MASE | cov_80 | win rate vs chronos2 |
|---|---|---|---|---|---|
| 1 | **HMIS-Chronos** | 0.1740 | 0.8543 | 0.8112 | 0.4782 |
| 1 | `chronos2` (zero-shot) | 0.1698 | 0.8530 | 0.8335 | – |
| 2 | **HMIS-Chronos** | 0.1888 | 0.9248 | 0.8069 | 0.4816 |
| 2 | `chronos2` (zero-shot) | 0.1862 | 0.9252 | 0.8395 | – |
| 3 | **HMIS-Chronos** | 0.2048 | 0.9848 | 0.8045 | 0.4804 |
| 3 | `chronos2` (zero-shot) | 0.2006 | 0.9838 | 0.8410 | – |
HMIS-Chronos gives the most accurate median forecasts on the states it was tuned on (MASE 0.8224 vs 0.8380 at one
month); its quantile bands are narrower than zero-shot Chronos-2, so WQL and 80% coverage favour the zero-shot
model. On the held-out states the two are level on MASE. For calibrated intervals use zero-shot Chronos-2 or
widen the HMIS-Chronos band; for point forecasts in the states covered by HMIS-Bench use HMIS-Chronos. The
full leaderboard, with per-indicator slices, is in the
[HMIS-Bench-Leaderboard](https://huggingface.co/spaces/judicialmind/HMIS-Bench-Leaderboard) Space.
## Coverage
Fine-tuned on HMIS-Bench sub-district series from April 2020 to July 2021 for 48 headline HMIS indicators in 28
States/UTs (Uttar Pradesh, Bihar, Odisha and Andhra Pradesh held out). Monthly frequency; forecasts 1 to 3 months.
## Source data
Fine-tuned and evaluated on HMIS-Bench, derived from the HMIS sub-district monthly reports (FY2020-21 and
FY2021-22) of the Ministry of Health and Family Welfare, published on the Open Government Data Platform India
([data.gov.in](https://data.gov.in)), snapshot May 2026, under the
[Government Open Data License - India](https://data.gov.in/government-open-data-license-india).
Base model: [`amazon/chronos-2`](https://huggingface.co/amazon/chronos-2) (Apache-2.0).
<!-- jm:source -->
Original data: published by Ministry of Health and Family Welfare (Health Management Information System, HMIS) on the Open Government Data Platform India ([data.gov.in](https://data.gov.in)) and, where marked, NITI Aayog's National Data and Analytics Platform ([NDAP](https://ndap.niti.gov.in)), under the [Government Open Data License - India](https://data.gov.in/government-open-data-license-india) (GODL-India). The original public data remains under GODL-India; the CC BY-NC-SA 4.0 licence of this repository covers JudicialMind's compilation, derived fields, annotations, benchmarks and models.
<!-- /jm:source -->
## Citation
```bibtex
@misc{judicialmind2026hmischronos,
title={HMIS-Chronos: Chronos-2 Fine-tuned for Indian Sub-district Health Service Forecasting},
author={JudicialMind},
year={2026},
publisher={Hugging Face},
howpublished={\url{https://huggingface.co/judicialmind/HMIS-Chronos}}
}
```
<!-- jm:license -->
## License
[CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) (see `LICENSE`): research, academic, personal and other non-commercial use, with attribution to JudicialMind and to the original data publishers; adaptations must be shared under the same licence. Commercial use requires a separate licence.
Commercial use: contact surya@judicialmind.ai or hello@judicialmind.ai.
Base model(s): `amazon/chronos-2` (apache-2.0). Their licence terms and notices continue to apply to the upstream components; see `THIRD_PARTY_NOTICES.md`.
<!-- /jm:license -->