README.md

---
license: mit
---

# TIC-FM

**TIC-FM** is a time series classification foundation model that replaces the conventional frozen-encoder-plus-task-specific-classifier pipeline with **in-context inference**. At deployment, TIC-FM treats the labeled training split as context and predicts labels for the query/test split without fitting a new classifier or updating model parameters.


[Paper](https://arxiv.org/abs/2602.00620) · [Code](https://github.com/fangjuntao/TIC-FM) · [ICML FMSD 2026 workshop paper](https://openreview.net/forum?id=HVvARHEA9M)

## Model description

TIC-FM contains three main components:

1. A ViT-based time series encoder that converts each series into an instance embedding using raw values, first-order differences, and patch-level statistics.
2. A lightweight projection adapter that maps time series embeddings into the token space of the in-context classifier.
3. A latent-memory, split-masked Transformer that conditions each query on labeled context examples while preventing information flow among query examples.

The released checkpoint supports parallel context–query inference and cyclic label-permutation ensembling. Its main configuration is summarized below.

| Component | Configuration |
| --- | --- |
| Input length | 512 |
| Time series embedding dimension | 512 |
| Time series encoder | 6 Transformer layers |
| Projection adapter | 512 → 1024 → 512 |
| In-context Transformer | 12 blocks, 4 attention heads |
| Latent memory | 32 latent tokens; 2 write and 2 read layers |
| Direct class capacity | Up to 10 classes |

Tasks with more than 10 classes are handled by the hierarchical class-extension procedure implemented in the evaluation pipeline.

## Repository files

| File | Description |
| --- | --- |
| `TSEncoder_orion_icl_full.pt` | TIC-FM model checkpoint |
| `TSEncoder_orion_icl_model_hparams.json` | Architecture and checkpoint configuration |

This repository contains model weights and configuration only. Model definitions, data loading, preprocessing, and evaluation scripts are provided in the [official code repository](https://github.com/fangjuntao/TIC-FM).

## Quick start

### 1. Set up the code

```bash
git clone https://github.com/fangjuntao/TIC-FM.git
cd TIC-FM

conda env create -f environment.yml
conda activate TICFS

pip install -U huggingface_hub
```

### 2. Download the checkpoint

```bash
hf download Jwpqkh/TIC-FM \
  TSEncoder_orion_icl_full.pt \
  TSEncoder_orion_icl_model_hparams.json \
  --local-dir checkpoints
```

The same files can be downloaded in Python:

```python
from huggingface_hub import hf_hub_download

checkpoint_path = hf_hub_download(
    repo_id="Jwpqkh/TIC-FM",
    filename="TSEncoder_orion_icl_full.pt",
)
hparams_path = hf_hub_download(
    repo_id="Jwpqkh/TIC-FM",
    filename="TSEncoder_orion_icl_model_hparams.json",
)

print(checkpoint_path)
print(hparams_path)
```

### 3. Evaluate on UCR

Download the UCR archive and run the evaluation script from the project root:

```bash
python scripts/eval_TSEncoder_orion_icl_classifier_ucr_full.py \
  --suite ucr \
  --mode classifier_v2 \
  --ucr_path /path/to/UCRdata/ \
  --full_ckpt checkpoints/TSEncoder_orion_icl_full.pt \
  --model_hparams_json checkpoints/TSEncoder_orion_icl_model_hparams.json
```

To evaluate a single dataset:

```bash
python scripts/eval_TSEncoder_orion_icl_classifier_ucr_full.py \
  --suite ucr \
  --dataset ECG200 \
  --mode classifier_v2 \
  --ucr_path /path/to/UCRdata/ \
  --full_ckpt checkpoints/TSEncoder_orion_icl_full.pt \
  --model_hparams_json checkpoints/TSEncoder_orion_icl_model_hparams.json
```

Useful arguments include `--support_size`, `--query_batch_size`, and `--softmax_temperature`. See the code repository for the complete evaluation interface.

## Training data and procedure

TIC-FM is trained in three stages:

1. The time series encoder is pretrained for 100 epochs with a contrastive objective on 100,000 synthetic time series generated by CauKer.
2. The in-context classifier is pretrained on synthetic classification tasks sampled from a structural causal model prior.
3. The encoder and in-context classifier are frozen, and only the projection adapter is trained for five epochs on the training splits of the UCR archive.

No UCR test split is used for checkpoint training. Therefore, this released checkpoint corresponds to the main **TIC-FM** model rather than the fully synthetic **TIC-FM (Syn.)** variant.

## Evaluation

The model is evaluated on all 128 datasets in the UCR archive using the official train/test splits. The official training split is supplied as labeled context, and the test split is treated as unlabeled queries. TIC-FM performs inference without fitting a dataset-specific classifier.

| Model | Target-specific classifier fitting | Average accuracy | Mean rank |
| --- | ---: | ---: | ---: |
| TIC-FM | No | 80.01% | 3.59 |

These results are taken from version 2 of the accompanying arXiv paper. Refer to the paper for baselines, per-dataset results, low-label protocols, statistical analysis, and complete experimental settings.

## Intended use

TIC-FM is intended for:

- Research on training-free and in-context time series classification.
- Evaluation on univariate classification datasets with labeled context examples.
- Reproduction and extension of the experiments reported in the accompanying papers.

## Limitations

- The released checkpoint is primarily evaluated on the univariate UCR archive; performance on other domains, multichannel datasets, irregularly sampled data, or distribution shifts is not guaranteed.
- Predictions depend on the quality and class coverage of the labeled context set. Query classes absent from the context cannot be inferred reliably.
- Inputs are processed at a fixed length of 512 by the provided evaluation pipeline; alternative preprocessing may change performance.
- The checkpoint uses custom PyTorch modules and is not directly compatible with `transformers.pipeline`.
- The model is a research artifact and should be independently validated before use in high-stakes applications.

## Citation

If you use this checkpoint, please cite the following papers.

```bibtex
@article{fang2026rethinking,
  title   = {Rethinking Zero-Shot Time Series Classification:
             From Task-specific Classifiers to In-Context Inference},
  author  = {Fang, Juntao and Xie, Shifeng and Nie, Shengbin and
             Ling, Yuhui and Liu, Yuming and Li, Zijian and Zhang, Keli and
             Pan, Lujia and Palpanas, Themis and Cai, Ruichu},
  journal = {arXiv preprint arXiv:2602.00620},
  year    = {2026}
}

@inproceedings{fang2026beyond,
  title     = {Beyond Task-Specific Classifiers:
               In-Context Inference for Time Series Classification
               Foundation Models},
  author    = {Fang, Juntao and Xie, Shifeng and Nie, Shengbin and
               Ling, Yuhui and Liu, Yuming and Li, Zijian and Zhang, Keli and
               Pan, Lujia and Palpanas, Themis and Cai, Ruichu},
  booktitle = {2nd ICML Workshop on Foundation Models for Structured Data},
  year      = {2026},
  url       = {https://openreview.net/forum?id=HVvARHEA9M}
}
```

## License

The TIC-FM model checkpoint is released under the MIT License. Third-party
components remain subject to their respective licenses.

## Contact

For questions or issues, please open an issue in the [official code repository](https://github.com/fangjuntao/TIC-FM/issues).