Create README.md

README.md

@@ -0,0 +1,190 @@
+---
+license: apache-2.0
+---
+
+# TIC-FM
+
+**TIC-FM** is a time series classification foundation model that replaces the conventional classifier-fitting   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.
+
+## Benchmark Results
+
+TIC-FM is evaluated in the [TSC-FM time series classification foundation model benchmark](https://tsc-fm.dmirlab.com/). See its [model configurations and benchmark results](https://tsc-fm.dmirlab.com/methods/tic-fm), compare matching settings on the [time series classification leaderboard](https://tsc-fm.dmirlab.com/leaderboard), and consult the [Standard and few-shot evaluation protocol](https://tsc-fm.dmirlab.com/evaluation).
+
+
+
+## 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).