CITRAS-FM

CITRAS-FM (Covariate-Informed Transformer for time series Foundation Modeling) is a tiny (7M-parameter) time series foundation model for covariate-informed zero-shot forecasting. It supports zero-shot forecasting on a single target variable or multiple target variables, with optional support for observed covariates (past-only) and known covariates (available throughout the forecast horizon). It delivers sub-0.1-second CPU inference, making it suitable for real-time and resource-constrained environments.

For full technical details, please see the paper: CITRAS-FM: Tiny Time Series Foundation Model for Covariate-Informed Zero-Shot Forecasting

---

Problem Setting

CITRAS-FM handles three types of input variables:

Variable	Role	Count	Shape	Available range	Examples
Target	Variable to forecast	Ct (≥1)	(L, Ct)	Historical window [1, L]	Traffic amount
Observed covariate	Exogenous variable influencing the target, available up to the prediction point	Co (≥0)	(L, Co)	Historical window [1, L]	Weather
Known covariate	Exogenous variable influencing the target, available from the past through the forecast horizon	Ck (≥0)	(L+H, Ck)	Full window [1, L+H]	Calendar events

• L: length of historical context
• H: forecast horizon

Covariates are optional — the model works with targets only.

The table below compares supported variable types across open-source TSFMs. CITRAS-FM enables the most flexible variable usage among tiny TSFMs.

Model	Univariate	Multivariate	Observed cov¹	Known cov²
CITRAS-FM (ours)	✅	✅	✅	✅
Chronos-2 (Amazon)	✅	✅	✅	✅
Toto-1.0 (Datadog)	✅	✅	✅	✗
TabPFN-TS (Prior Labs)	✅	✗	✗	✅
COSMIC (Amazon)	✅	✗	✅	✅
TimesFM-2.5 (Google)	✅	✗	✗	✗
Sundial (Tsinghua Univ.)	✅	✗	✗	✗
Moirai-2.0 (Salesforce)	✅	✗	✗	✗
Chronos-Bolt (Amazon)	✅	✗	✗	✗
YINGLONG (Alibaba)	✅	✗	✗	✗
KAIROS (Ant Group)	✅	✗	✗	✗
TinyTimeMixer (IBM)	✅	✗	✗	✗

¹ Observed covariate has recorded values up to the prediction point.
² Known covariate has values from the past through to the forecast horizon.

---

Performance

Benchmark: fev-bench (100 tasks, zero-shot)

fev-bench is a standardized benchmark for zero-shot time series forecasting covering 100 tasks across diverse domains and frequencies.

• fev-all: all 100 tasks, including univariate, multivariate, and covariate-informed settings
• fev-cov: 42tasks with observed and/or known covariates
• fev-multi: 26 tasks with multivariate targets
• fev-uni: 32 tasks with univariate targets

Skill Score is computed relative to Scaled Quantile Loss of SeasonalNaive baseline (0% = SeasonalNaive, higher is better).

Models with < 10M parameters

Model	# Params (M)	fev-all (%) ↑	fev-cov (%) ↑	fev-multi (%) ↑	fev-uni (%) ↑
CITRAS-FM	7.2	41.2	39.0	54.2	31.3
KAIROS_mini (Ant Group)	9.9	37.7	35.4	50.9	27.9
Chronos-Bolt_Tiny (Amazon)	8.7	35.9	32.9	49.8	26.4
YINGLONG_6m (Alibaba)	7.3	25.1	26.5	49.7	-6.2
TinyTimeMixer_r2 (IBM)	0.8	-1.1	-4.6	28.2	-27.5
SeasonalNaive	0	0.0	0.0	0.0	0.0

Models with ≥ 10M parameters

Model	# Params (M)	fev-all (%) ↑	fev-cov (%) ↑	fev-multi (%) ↑	fev-uni (%) ↑
Chronos-2 (Amazon)	120	47.3	47.0	57.9	37.0
TiRex (NXAI)	35	42.6	38.7	55.7	35.0
TimesFM-2.5 (Google)	200	42.3	37.6	56.1	34.9
Toto-1.0 (Datadog)	151	40.7	35.1	57.1	31.6
TabPFN-TS (Prior Labs)	11	39.6	40.0	47.7	31.4
Chronos-Bolt_Base (Amazon)	205	38.9	35.9	52.1	30.1
COSMIC (Amazon)	200	39.0	36.0	52.3	29.8
Moirai-2.0 (Salesforce)	11	39.3	36.6	53.4	29.0
Sundial_Base (Tsinghua Univ.)	128	33.4	28.0	51.1	22.9

CITRAS-FM achieves the best accuracy among sub-10M tiny TSFMs on all splits, and outperforms models with 20× more parameters (TimesFM-2.5, COSMIC) in covariate-informed settings.

Installation

pip install git+https://github.com/hitachi-ais/citras-fm.git

(or clone and pip install -e . for development)

---

Quick Start

Load a pretrained model

Pretrained weights are distributed via the Hugging Face Hub at hitachi-nlp/citras-fm. The first call downloads the weights into ~/.cache/huggingface/hub/; subsequent calls hit the local cache.

from citras_fm import CitrasFM

model = CitrasFM.from_pretrained("hitachi-nlp/citras-fm")
print(model.pred_len)    # 24
print(model.quantiles)   # [0.1, 0.2, ..., 0.9]

To pin a specific checkpoint version, pass revision= (a commit hash or git tag on the HF repo):

model = CitrasFM.from_pretrained("hitachi-nlp/citras-fm", revision="ckpt-2026-06-26")

Forecast — ndarray (Ct=1, no covariates)

import numpy as np

target = np.random.randn(512)  # shape: (L,)

median, quantiles = model.forecast(target, horizon=24)
# median: np.ndarray, shape (H,) = (24,)
# quantiles: torch.Tensor, shape (H, Q) = (24, 9)

Forecast — Tensor (Ct=2, Co=1, Ck=2)

import torch

L, H = 512, 24

target = torch.randn(L, 2)              # (L, Ct)
observed_cov = torch.randn(L, 1)        # (L, Co)
known_cov = torch.randn(L + H, 2)       # (L+H, Ck)

median, quantiles = model.forecast(
    target, horizon=H,
    observed_cov=observed_cov,
    known_cov=known_cov,
)
# median: torch.Tensor, shape (H, Ct) = (24, 2)
# quantiles: torch.Tensor, shape (H, Ct, Q) = (24, 2, 9)

Forecast — Series / DataFrame (Ct=1, Co=2, Ck=2)

import pandas as pd
import numpy as np

L, H = 512, 24
dates = pd.date_range("2024-01-01", periods=L, freq="h")
dates_full = pd.date_range("2024-01-01", periods=L + H, freq="h")

target = pd.Series(np.random.randn(L), index=dates, name="demand")
observed_cov = pd.DataFrame(
    np.random.randn(L, 2), index=dates, columns=["temp", "humidity"]
)
known_cov = pd.DataFrame(
    np.random.randn(L + H, 2), index=dates_full, columns=["holiday", "promo"]
)

median, quantiles = model.forecast(
    target, horizon=H,
    observed_cov=observed_cov,
    known_cov=known_cov,
)
# median: pd.Series with DatetimeIndex, shape (H,) = (24,)
# quantiles: torch.Tensor, shape (H, Q) = (24, 9)

---

API Reference

CitrasFM.from_pretrained(model_id, revision=None, map_location="cpu", **kwargs)

Argument	Type	Description
model_id	str	HF Hub repo id (e.g. "hitachi-nlp/citras-fm") or a local directory containing model.safetensors + config.json
revision	str, optional	HF commit hash or git tag
map_location	str | torch.device	"cpu", "cuda", "cuda:0", etc.
cache_dir	str, optional	Override the default Hugging Face cache directory

CITRAS.forecast(...)

Argument	Type	Shape	Description
target	ndarray / Tensor / Series / DataFrame	(L, Ct) or (L,)	Historical target values
horizon	int	—	Steps to forecast (H)
observed_cov	ndarray / Tensor / Series / DataFrame, optional	(L, Co) or (L,)	Past-only covariates
known_cov	ndarray / Tensor / Series / DataFrame, optional	(L+H, Ck) or (L+H,)	Future-known covariates

Returns — (median, quantiles) tuple:

Return	Type	Shape	Condition
median	np.ndarray	(H, Ct) or (H,)	When input is np.ndarray
median	torch.Tensor	(H, Ct) or (H,)	When input is torch.Tensor
median	pd.Series	(H,) with DatetimeIndex	When input is pd.Series
median	pd.DataFrame	(H, Ct) with DatetimeIndex	When input is pd.DataFrame
quantiles	torch.Tensor	(H, Ct, Q) or (H, Q)	Always. Q = number of quantile levels

• When input is 1D (L,) or pd.Series, output dimensions are squeezed: (H,) and (H, Q).
• CITRAS-FM natively predicts model.pred_len (= 24) steps per iteration. When horizon > model.pred_len, recursive forecasting is applied automatically.

Properties

Property	Type	Description
model.pred_len	int	Native forecast length
model.quantiles	list[float]	Quantile levels (e.g. [0.1, 0.2, ..., 0.9])
model.max_context_length	int	Maximum context length (1032)

---

Example notebooks

• example_zeroshot.ipynb: Zero-shot forecasting walkthrough — install → data prep → inference → visualization.
• example_finetune.ipynb: Fine-tuning walkthrough — load pretrained model → prepare dataset → fine-tune with PyTorch Lightning → compare zero-shot vs fine-tuned results.

---

License

• Source code (this repository): PolyForm Noncommercial License 1.0.0 (see LICENSE).
• Pretrained weights (distributed on Hugging Face Hub): CC BY-NC-SA 4.0.

Bundled third-party components retain their original licenses; see each subdirectory under citras_fm/third_party/ for the LICENSE/NOTICE files.

Component	Vendor	License
citras_fm/third_party/amazon_chronos/	Amazon	Apache-2.0
citras_fm/third_party/google_timesfm/	Google	Apache-2.0
citras_fm/third_party/salesforce_uni2ts/	Salesforce	Apache-2.0
citras_fm/third_party/thuml_tslib/	THUML	MIT

Disclaimer

This software and its associated checkpoints are provided for research and non-commercial evaluation purposes only. The software is provided "AS IS", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, accuracy, reliability, and non-infringement of third-party rights.

In no event shall the authors, contributors, or Hitachi, Ltd. be liable for any claim, damages, or other liability — direct, indirect, incidental, special, exemplary, or consequential — arising from, out of, or in connection with the software or the use or other dealings in the software.

Forecasts produced by this model are probabilistic estimates and may be inaccurate. Do not use this software as the sole basis for safety-critical, mission-critical, life-critical, financial, or medical decisions. Users are solely responsible for evaluating the suitability of the software and checkpoints for their own use, and for compliance with applicable laws and regulations, including those governing the data they process.

Citation

If you find this repository or the associated paper useful, please cite:

Yamaguchi et al., "CITRAS-FM: Tiny Time Series Foundation Model for Covariate-Informed Zero-Shot Forecasting, "
34th European Signal Processing Conference (EUSIPCO), 2026 (to appear).

Releases

Code releases are tagged on GitHub. Checkpoint revisions are tracked separately on the Hugging Face Hub repo via commit hash and git tag — pin with revision="..." in from_pretrained.

Versions 1.x and 2.x were internal-only (research / pre-release). The first publicly distributed version is v3.0.0.

Code version	Description	Date
v3.0.0	Initial public release	2026/07/08