Govisha/TelecomTS

1---2license: mit3---4# 📡 TelecomTS: A Multi-Modal Telecom Dataset5<p align="center">6  <a href="https://icml.cc/Conferences/2026"><img alt="ICML 2026" src="https://img.shields.io/badge/ICML-2026-blue.svg"></a>7  <a href="https://arxiv.org/abs/2510.06063"><img alt="arXiv" src="https://img.shields.io/badge/arXiv-2510.06063-b31b1b.svg"></a>8  <a href="https://github.com/Ali-maatouk/TelecomTS">9  <img alt="GitHub" src="https://img.shields.io/badge/GitHub-TelecomTS-181717?logo=github">10  </a>11  <img alt="License" src="https://img.shields.io/badge/license-MIT-green.svg">12</p>13 14**TelecomTS** is a large-scale, high-resolution, multi-modal dataset derived from a **5G telecommunications testbed**. It is the first public observability dataset to preserve **deanonymized** observability metrics with **absolute scale information**, encompassing by design various downstream tasks beyond forecasting such as **anomaly detection, root-cause analysis, and multi-modal reasoning**.15 16Observability data, particularly in telecommunications, differs fundamentally from conventional time series (e.g., weather, finance) by being:17- **Zero-inflated**18- **Highly stochastic and bursty**19- **Structurally noisy with minimal discernible temporal patterns**20 21## 🚀 Key Features22- **32k Data Samples**23- **1M+ Observations** from a live 5G network24- **Multi-modal inputs**:25  - Time series KPIs across PHY, MAC, and network layers26  - Environment descriptions and natural-language Q&A pairs27- **Absolute scale preserved** (no normalization/anonymization)28- **Real and synthetic anomalies**: 10 synthetic types grounded in telecom literature plus one real anomaly (jamming) collected over the air29- **Reasoning traces**: explicit chain-of-thought traces attached to `network` and `anomalies` Q&A entries, for reasoning-aware fine-tuning and RL30- **Downstream tasks supported**:31  - 🔎 **Anomaly detection** 32  - 🛠️ **Root-cause analysis** 33  - ⏱️ **Anomaly duration localization** 34  - 📈 **Forecasting / reconstruction** 35  - 🤖 **Time series and network-level Q&A** 36- **Labels provided**: zone, application, mobility, congestion state, anomaly presence37 38## 📊 Statistics39 40| Statistic                | Description                  | Count                                      |41|:-------------------------|:-----------------------------|:-------------------------------------------|42| **Time Series Samples**  | Total samples                | 32,000                                     |43|                          | Sample length                | 128                                        |44| **Channels**             | Total channels               | 18                                         |45|                          | Channel types                | 10 float, 6 integer, 2 categorical         |46| **Anomalies**            | Anomaly types                | 11                                         |47| **Q&A Categories**       | Time Series Q&A categories   | 64                                         |48|                          | Network-Level Q&A categories | 4                                          |49|                          | Anomalies Q&A categories     | 3                                          |50| **Total QA Size**        | Total QA instances           | **2,210,185**                              |51 52## 📂 Dataset Structure53 54The main dataset consists of JSONL files containing chunked time series (128 timesteps each) along with multi-modal information. Each sample within the JSONL files includes:55 56- **start_time / end_time** — temporal boundaries of the chunk57- **sampling_rate_hz** — number of timesteps per second 58- **description** — natural-language summary of the network environment and time series behaviors59- **KPIs** — key performance indicator names and values60- **anomalies** — existence, type, duration, affected KPIs, and troubleshooting tickets61- **statistics** — mean, variance, trend, and periodicity for each KPI62- **labels** — contextual metadata (zone, application, mobility, congestion, anomaly presence)63- **QnA** — natural-language Q&A over the sample, grouped into `timeseries`, `network`, and `anomalies` subcategories. Each entry of has the following structure:64 65  ```json66  { "q": "What activity was the user engaged in?",67    "a": "Twitch",68    "reasoning": "Sustained downlink throughput in the 2–4 Mbps range with periodic UDP bursts and stable RSRP is consistent with live video streaming..." }69  ```70 71  The `reasoning` field, present in the last two subcategories, contains an explicit reasoning trace that reveals the intermediate decision-making steps used to derive the final answer. 72 73Beyond the main dataset, each scenario also includes:74 75- **`description.txt`** – textual description of the network environment76- **`metrics.csv`** – raw observations for the scenario77 78## 🧪 Installation & Usage79 80### Install 🤗 Datasets81```bash82pip install datasets83```84 85### Load the Dataset86```python87from datasets import load_dataset88 89# Load the full dataset90dataset = load_dataset(91          "AliMaatouk/TelecomTS",92          data_files={"full": "**/chunked.jsonl"}93)94 95print(dataset)96```97 98### Inspect a Sample99```python100sample = dataset["full"][0]101print(sample.keys())102# dict_keys(['start_time', 'end_time', 'sampling_rate', 'KPIs', 'description', 'anomalies', 'statistics', 'labels', 'QnA'])103```104 105 106## Citation107 108You can find the paper with all details at https://arxiv.org/abs/2510.06063. Please cite it as follows:109 110```bib111@misc{feng2025telecomtsmultimodalobservabilitydataset,112      title={TelecomTS: A Multi-Modal Observability Dataset for Time Series and Language Analysis}, 113      author={Austin Feng and Andreas Varvarigos and Ioannis Panitsas and Daniela Fernandez and Jinbiao Wei and Yuwei Guo and Jialin Chen and Ali Maatouk and Leandros Tassiulas and Rex Ying},114      year={2025},115      eprint={2510.06063},116      archivePrefix={arXiv},117      primaryClass={cs.AI},118      url={https://arxiv.org/abs/2510.06063}, 119}120```121