From bb07f880afdd2b33d7bbb0c1ad0cad96c600a2c8 Mon Sep 17 00:00:00 2001 From: Adrian Blumer Date: Mon, 16 Nov 2026 17:24:00 -0800 Subject: [PATCH 01/20] feat(connectors): add the OpenTSLM M4-Caption connector Add opentslm/m4-caption. It converts the M4-Caption release of OpenTSLM: the train part of the 100,000 M4 competition series, each with a caption that GPT-4o wrote. Each series becomes one Record and one AnswerTask without a prompt. The Record keeps the M4 id and the frequency. The values stay float32, because the release holds the M4 values rounded to float32. The series use an ordinal axis, because the release has no timestamps and a month has no fixed length. The release has no split. The OpenTSLM loader splits the series at load time with the datasets library. The connector computes the same 80/10/10 split with NumPy and stops with an error if the split does not match a pinned digest. generate_splits.py computed that digest with the datasets version from the OpenTSLM uv.lock. The M4 organizers state no license, so the card uses NONE. OpenTSLM releases the captions under MIT. --- .../datasets/opentslm/m4_caption/__init__.py | 6 + .../datasets/opentslm/m4_caption/connector.py | 279 ++++++++++++++++++ .../datasets/opentslm/m4_caption/dataset.yaml | 44 +++ .../opentslm/m4_caption/generate_splits.py | 83 ++++++ .../m4_caption/tests/test_connector.py | 154 ++++++++++ 5 files changed, 566 insertions(+) create mode 100644 packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/__init__.py create mode 100644 packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py create mode 100644 packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml create mode 100644 packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/generate_splits.py create mode 100644 packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/tests/test_connector.py diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/__init__.py b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/__init__.py new file mode 100644 index 000000000..210792a47 --- /dev/null +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/__init__.py @@ -0,0 +1,6 @@ +"""M4-Caption: the M4 competition series, each with a caption that GPT-4o wrote.""" + +from timenet_connectors.datasets.opentslm.m4_caption.connector import ( + CONNECTOR as CONNECTOR, + M4CaptionConnector as M4CaptionConnector, +) diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py new file mode 100644 index 000000000..1233e4be3 --- /dev/null +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py @@ -0,0 +1,279 @@ +"""The M4-Caption connector: M4 competition series, each with a caption that GPT-4o wrote. + +The OpenTSLM release holds the train part of all 100,000 M4 series, one CSV of series and one CSV of +captions for each of the six M4 frequencies. Each series becomes one Record and one AnswerTask. The +target is the caption. The release has no split, so the connector computes the split of OpenTSLM's +loader and checks it against a pinned digest. +""" + +from collections.abc import Iterator, Sequence +from dataclasses import dataclass +import hashlib +from math import ceil +from pathlib import Path +import re + +import numpy as np +from pydantic import FiniteFloat, Json + +from timenet.connectors import BaseConnector +from timenet.dataset import Record, Signal, Source, TimeFDataset +from timenet.dataset.axis import OrdinalAxis +from timenet.errors import TimeNetConnectorError +from timenet.types import Annotation, AnswerTask, Split, TimeSeriesSpec +from timenet_connectors.download import ensure_archive +from timenet_connectors.sources.readers import CsvDataReader, DataRow + + +M4_CAPTION_URL = "https://polybox.ethz.ch/index.php/s/MT3y9WdEebT8wfj/download/M4TimeSeriesCaptionDatasetV02.zip" +M4_CAPTION_SHA256 = "4acb748d94d7287fe58dbb5c3cf6314ea259010b7720f42506739269dec54edf" +RELEASE_FOLDER = "M4TimeSeriesCaptionDataset" +"""The folder in the archive that holds the CSV files.""" +FREQUENCIES = ("Daily", "Hourly", "Monthly", "Quarterly", "Weekly", "Yearly") +"""The M4 frequencies, in the order that OpenTSLM's loader reads them. The split depends on this order.""" +MAX_SERIES_CHARS = 1_000_000 +"""The largest series cell that the connector reads, in characters. The largest cell of the release +holds a daily series of 9,919 values in 169,126 characters.""" +OPENTSLM_SPLIT_SHA256 = "370cc2580bcdb912e13a546c1a84f3d52d7e2098db07cfe2873ffde8270f5256" +"""The digest of the split that OpenTSLM's loader gives the release, as generate_splits.py computed it.""" + +# The release states no unit, and the M4 series come from many domains. +M4_SERIES = TimeSeriesSpec(spec_type="m4_series", name="M4 series", unit_value=None, dtype="float32") + +_SERIES_ID = re.compile(r"series-(?P(?P[DHMQWY])[1-9][0-9]*)") +"""A release id: the M4 id, such as M1, after a ``series-`` prefix that OpenTSLM added.""" + + +class _SeriesRow(DataRow): + """A row of a series file: the release id and the values as a JSON list.""" + + id: str + series: Json[list[FiniteFloat]] + + +class _CaptionRow(DataRow): + """A row of a caption file: the release id and the caption.""" + + id: str + caption: str + + +def _parse_m4_id(series_id: str, frequency: str) -> str: + """Get the M4 id from a release id, and check that it belongs to the frequency of its file. + + Returns: + The M4 id, such as ``M1``. + + Raises: + TimeNetConnectorError: If the id is not an M4 series id of the frequency. + """ + match = _SERIES_ID.fullmatch(series_id) + if match is None or match["letter"] != frequency[0]: + raise TimeNetConnectorError(f"{series_id!r} is not a {frequency} M4 series id") + return match["m4_id"] + + +def _as_float32(values: Sequence[float]) -> np.ndarray: + """Convert the values to float32, and check that the conversion keeps every value exactly. + + The release holds M4 values that OpenTSLM rounded to float32, so float32 is lossless for it. + + Returns: + The values as float32. + + Raises: + TimeNetConnectorError: If a value is not exactly a float32 value. + """ + exact = np.array(values, dtype=np.float64) + rounded = exact.astype(np.float32) + if not np.array_equal(rounded.astype(np.float64), exact): + raise TimeNetConnectorError("the series holds a value that is not exactly float32") + return rounded + + +@dataclass(frozen=True) +class M4CaptionSeries: + """One M4 series of the release, with its frequency and caption.""" + + m4_id: str + frequency: str + values: np.ndarray + caption: str + + def create_record(self) -> Record: + """Create the Record of the series, with its M4 id and frequency. + + Returns: + The Record, not yet added to a dataset. + """ + signal = Signal.from_values(self.values, spec=M4_SERIES, name="value", time_axis=OrdinalAxis()) + frequency = Annotation(key="frequency", value=self.frequency) + return Record( + sources=(Source(name="M4", signals=(signal,)),), + annotations=(frequency,), + metadata={"m4_id": self.m4_id}, + ) + + def create_caption_task(self, record: Record, *, split: Split) -> AnswerTask: + """Create the task that asks for the caption of the series. + + Returns: + The task, not yet added to a dataset. + """ + return AnswerTask(inputs=(record,), targets=(self.caption,), split=split) + + +@dataclass(frozen=True) +class OpenTSLMSplit: + """The 80/10/10 split of ``create_combined_dataset`` in OpenTSLM's M4 loader. + + The loader calls ``train_test_split`` of the datasets library twice, without stratification. That + function shuffles the rows with ``numpy.random.default_rng(seed).permutation``: the first rows of the + permutation are the test part and the rest are the train part. NumPy does not promise the same + permutation in every version, so the split is checked against a digest. + """ + + sha256: str + """The digest that :meth:`digest` must give for the split.""" + + @staticmethod + def digest(m4_ids: Sequence[str], splits: Sequence[Split]) -> str: + """Compute the digest of a split. + + The digest is the SHA-256 of one line per series, in order. Each line is the M4 id, a tab, the + split, and a newline. + + Returns: + The digest in hexadecimal. + """ + lines = "".join(f"{m4_id}\t{split}\n" for m4_id, split in zip(m4_ids, splits, strict=True)) + return hashlib.sha256(lines.encode()).hexdigest() + + def assign_splits(self, m4_ids: Sequence[str]) -> list[Split]: + """Assign the split of OpenTSLM's loader to each series, in the order of the loader. + + Returns: + The split of each series. + + Raises: + TimeNetConnectorError: If the split does not match the pinned digest. + """ + splits = [Split.TRAIN] * len(m4_ids) + all_positions = np.arange(len(m4_ids)) + train_and_validation = self._split_off(all_positions, splits, Split.TEST, seed=42, size=0.1) + # The loader keeps the share of the validation part at 10 percent of all series. + self._split_off(train_and_validation, splits, Split.VALIDATION, seed=43, size=0.1 / (1.0 - 0.1)) + if self.digest(m4_ids, splits) != self.sha256: + raise TimeNetConnectorError( + f"the OpenTSLM split of {len(m4_ids)} series does not match the pinned digest {self.sha256}" + ) + return splits + + @staticmethod + def _split_off(positions: np.ndarray, splits: list[Split], split: Split, *, seed: int, size: float) -> np.ndarray: + """Do one ``train_test_split`` call of the datasets library on the series at ``positions``. + + The series of the part that the call names "test" get ``split``. + + Returns: + The positions of the part that the call names "train", in the order of the permutation. + """ + permutation = np.random.default_rng(seed).permutation(len(positions)) + n_split = ceil(size * len(positions)) + for position in positions[permutation[:n_split]]: + splits[position] = split + return positions[permutation[n_split:]] + + +@dataclass(frozen=True) +class M4CaptionRelease: + """The extracted release and the split that its series must get.""" + + directory: Path + split: OpenTSLMSplit + + def read_series(self) -> Iterator[M4CaptionSeries]: + """Read every series of the release, in the order of OpenTSLM's loader. + + The loader reads the files of each frequency, and skips ``m4_series.csv`` and ``m4_captions.csv``. + A malformed file raises a :class:`~timenet.errors.TimeNetConnectorError` that names the file and + its row. + + Yields: + Each series with its caption. + """ + for frequency in FREQUENCIES: + yield from self._read_frequency(frequency) + + def _read_frequency(self, frequency: str) -> Iterator[M4CaptionSeries]: + """Read the series of one frequency, paired with the caption in the same row of its caption file. + + Yields: + Each series with its caption. + + Raises: + TimeNetConnectorError: If the files do not pair one to one, or a series row is malformed. + """ + series_path = self.directory / f"m4_series_{frequency}.csv" + captions_path = self.directory / f"m4_captions_{frequency}.csv" + series_reader = CsvDataReader( + series_path, _SeriesRow, expected_columns=("id", "series"), max_field_chars=MAX_SERIES_CHARS + ) + series_rows = list(series_reader.iter_rows()) + caption_rows = list(CsvDataReader(captions_path, _CaptionRow, expected_columns=("id", "caption")).iter_rows()) + if len(series_rows) != len(caption_rows): + raise TimeNetConnectorError( + f"{series_path.name} has {len(series_rows)} series rows but {len(caption_rows)} caption rows" + ) + for number, (series_row, caption_row) in enumerate(zip(series_rows, caption_rows, strict=True), start=1): + try: + m4_id = _parse_m4_id(series_row.id, frequency) + if series_row.id != caption_row.id: + raise TimeNetConnectorError( + f"series id {series_row.id!r} does not match caption id {caption_row.id!r}" + ) + yield M4CaptionSeries( + m4_id=m4_id, + frequency=frequency, + values=_as_float32(series_row.series), + caption=caption_row.caption, + ) + except TimeNetConnectorError as exc: + raise TimeNetConnectorError(f"{series_path.name} data row {number}: {exc}") from exc + + +class M4CaptionConnector(BaseConnector[M4CaptionRelease]): + """Connector for the M4-Caption release of OpenTSLM.""" + + async def download_async(self, cache_dir: Path) -> list[M4CaptionRelease]: # ruff: ignore[no-self-use] + """Download and extract the release archive once. + + Args: + cache_dir: The directory that holds the extracted files. + + Returns: + The extracted release, with the pinned split. + """ + root = await ensure_archive(M4_CAPTION_URL, cache_dir, filename="m4_caption.zip", sha256=M4_CAPTION_SHA256) + return [M4CaptionRelease(directory=root / RELEASE_FOLDER, split=OpenTSLMSplit(sha256=OPENTSLM_SPLIT_SHA256))] + + def convert(self, raw_refs: list[M4CaptionRelease]) -> TimeFDataset: + """Create one Record and one AnswerTask for each series. + + Args: + raw_refs: The release from :meth:`download_async`. + + Returns: + The populated dataset. + """ + (release,) = raw_refs + all_series = list(release.read_series()) + splits = release.split.assign_splits([series.m4_id for series in all_series]) + dataset = TimeFDataset(metadata=self.metadata()) + for series, split in zip(all_series, splits, strict=True): + record = dataset.add_record(record=series.create_record()) + dataset.add_task(task=series.create_caption_task(record, split=split)) + return dataset + + +CONNECTOR = M4CaptionConnector diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml new file mode 100644 index 000000000..e2d5f73c8 --- /dev/null +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml @@ -0,0 +1,44 @@ +# yaml-language-server: $schema=https://docs.timenet.ai/schemas/dataset-card-v1.schema.json +yaml_schema_version: 1 +dataset_id: opentslm/m4-caption +dataset_version: 1.0.0 +name: M4-Caption +description: >- + 100,000 univariate series from the M4 forecasting competition (80,000 train, 10,000 validation, + 10,000 test). Each series has one caption in English. GPT-4o wrote each caption from a plot of the + series, with the prompt "Generate a detailed caption for the following time-series data:". The + series are the train part of M4, the history that the competitors received, without the forecast + horizon. There are 4,227 daily, 414 hourly, 48,000 monthly, 24,000 quarterly, 359 weekly and 23,000 + yearly series, with 13 to 9,919 values each. The OpenTSLM paper gives 64 to 512 values, but the + release has the full length. The release holds the M4 values rounded to float32, and the dataset + keeps them in float32 without a change. The release has no timestamps and states no unit. The M4 + series come + from the micro, industry, macro, finance, demographic and other domains, so the values have mixed + units. Each record states the M4 id, such as M1, and the M4 frequency. The release has no split + column, so the dataset gives each series the split of OpenTSLM's loader. That loader merges all + frequencies and makes a random 80/10/10 split with the datasets library. + + The release archive also holds m4_series.csv, a copy of the weekly series, and m4_captions.csv, + with 40 other captions of weekly series. OpenTSLM does not use these two files, and the dataset + does not keep them. + + The M4 organizers at the University of Nicosia state no license for the M4 data. OpenTSLM + releases the captions under MIT. +license: NONE +source_url: https://polybox.ethz.ch/index.php/s/MT3y9WdEebT8wfj +citation: >- + Langer, P., et al. (2025). OpenTSLM: Time-Series Language Models for Reasoning over Multivariate + Medical Text- and Time-Series Data. https://doi.org/10.48550/arXiv.2510.02410. M4 series: + Makridakis, S., Spiliotis, E., & Assimakopoulos, V. (2020). The M4 Competition: 100,000 time series + and 61 forecasting methods. International Journal of Forecasting, 36(1), 54-74. Makridakis, S., + Spiliotis, E., & Assimakopoulos, V. (2018). The M4 Competition: Results, findings, conclusion and + way forward. International Journal of Forecasting, 34(4), 802-808. +domains: + - economics + - finance + - general +tags: + - m4 + - forecasting + - captioning + - generated-supervision diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/generate_splits.py b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/generate_splits.py new file mode 100644 index 000000000..e4d5fd2e4 --- /dev/null +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/generate_splits.py @@ -0,0 +1,83 @@ +# /// script +# requires-python = ">=3.12" +# dependencies = [ +# # The versions that the OpenTSLM uv.lock pins. The split depends on datasets and numpy. +# "datasets==4.4.1", +# "numpy==2.3.5", +# "pandas==2.3.3", +# ] +# /// +"""Print OPENTSLM_SPLIT_SHA256, the digest of the train, validation and test split of m4-caption. + +The release does not store the split. OpenTSLM's loader makes it at load time with the datasets library +and a fixed seed. The connector computes the same split with NumPy and checks it against the digest that +this script prints. This script runs the calls of OpenTSLM's loader with the library versions of the +OpenTSLM uv.lock, so the digest comes from OpenTSLM's own code path and not from the connector. + +Run it once with the extracted release folder, from this directory:: + + uv run generate_splits.py +""" + +import hashlib +import json +from pathlib import Path +import sys + + +FREQUENCIES = ["Daily", "Hourly", "Monthly", "Quarterly", "Weekly", "Yearly"] + + +def load_samples(release: Path) -> list[dict[str, str]]: + """Read the samples in the order of load_all_m4_data and create_combined_dataset. + + Returns: + One sample with the release id and the frequency for each series. + """ + # Discovery imports every module beside the connectors, so the script imports its own dependencies + # only when it runs. + import pandas as pd # ruff: ignore[import-outside-top-level] + + all_samples = [] + for frequency in FREQUENCIES: + series_df = pd.read_csv(release / f"m4_series_{frequency}.csv") + captions_df = pd.read_csv(release / f"m4_captions_{frequency}.csv") + common_ids = set(series_df["id"]) & set(captions_df["id"]) + series_df = series_df[series_df["id"].isin(common_ids)].reset_index(drop=True) + captions_df = captions_df[captions_df["id"].isin(common_ids)].reset_index(drop=True) + merged_df = series_df.merge(captions_df, on="id", how="inner") + for _, row in merged_df.iterrows(): + # The loader skips a row whose series does not parse, so parse each one. The split depends + # only on the number and order of the rows, so the samples here hold no values. + json.loads(row["series"]) + all_samples.append({"id": row["id"], "frequency": frequency}) + return all_samples + + +def main() -> None: + """Split the release in the folder that the first argument names, and print the digest.""" + from datasets import Dataset # ruff: ignore[import-outside-top-level] # ty: ignore[unresolved-import] + + all_samples = load_samples(Path(sys.argv[1])) + + # The calls of create_combined_dataset, with their names and settings. + full_dataset = Dataset.from_list(all_samples) + test_frac = 0.1 + val_frac = 0.1 + seed = 42 + train_val, test = full_dataset.train_test_split(test_size=test_frac, seed=seed).values() + val_frac_adj = val_frac / (1.0 - test_frac) + train, val = train_val.train_test_split(test_size=val_frac_adj, seed=seed + 1).values() + + # The digest of OpenTSLMSplit.digest in connector.py: one "\t\n" line per series, in + # the order of the loader. The M4 id is the release id without its "series-" prefix. + split_of = dict.fromkeys(train["id"], "train") + split_of |= dict.fromkeys(val["id"], "validation") + split_of |= dict.fromkeys(test["id"], "test") + lines = "".join(f"{sample['id'].removeprefix('series-')}\t{split_of[sample['id']]}\n" for sample in all_samples) + print(f"train {len(train)}, validation {len(val)}, test {len(test)}") + print(f'OPENTSLM_SPLIT_SHA256 = "{hashlib.sha256(lines.encode()).hexdigest()}"') + + +if __name__ == "__main__": + main() diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/tests/test_connector.py b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/tests/test_connector.py new file mode 100644 index 000000000..39f13da60 --- /dev/null +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/tests/test_connector.py @@ -0,0 +1,154 @@ +import csv +import json +from pathlib import Path + +import numpy as np +import pytest + +from timenet.dataset import TimeFDataset +from timenet.dataset.axis import OrdinalAxis +from timenet.errors import TimeNetConnectorError +from timenet.reader import TimeFReader +from timenet.registry import open_local_version +from timenet.testing import assert_datasets_equal +from timenet.types import AnswerTask, Split +from timenet.types.text import read_value +from timenet_connectors.datasets.opentslm.m4_caption.connector import ( + M4CaptionConnector, + M4CaptionRelease, + OpenTSLMSplit, +) + + +_SERIES_IDS = { + "Daily": ["D1", "D2"], + "Hourly": ["H1"], + "Monthly": ["M1", "M2", "M3"], + "Quarterly": ["Q1", "Q2"], + "Weekly": ["W1"], + "Yearly": ["Y1"], +} +"""Ten series in the order that OpenTSLM's loader reads the frequencies.""" + +_OPENTSLM_SPLIT = {"M3": Split.TEST, "W1": Split.VALIDATION} +"""The split that create_combined_dataset of OpenTSLM gives these ten series. It was taken from a run of +datasets 4.4.1, the version in the OpenTSLM uv.lock. Every other series is in the train split.""" + +_FLOAT32_VALUES = [1089.199951171875, 1078.9100341796875, 8000.0, 195.92799377441406] +"""Values as the release writes them: M4 values rounded to float32, printed with every digit.""" + + +_LONGEST_SERIES = 9919 +"""The number of values of the longest series in the release, a daily one. Its CSV cell has more +characters than the default cell limit of the csv module.""" + + +def _values(m4_id: str) -> list[float]: + # A distinct length and offset for each series, so a mix-up of two series changes the values. The sum + # is in float32, so each value stays a float32 value, like in the release. + shift = np.float32(sum(map(ord, m4_id))) + values = np.array(_FLOAT32_VALUES, dtype=np.float32) + shift + if m4_id == "D1": + return np.resize(values, _LONGEST_SERIES).tolist() + return values.tolist()[: 2 + len(m4_id)] + + +def _write_csv(path: Path, columns: tuple[str, str], rows: list[tuple[str, str]]) -> None: + with path.open("w", newline="", encoding="utf-8") as stream: + writer = csv.writer(stream) + writer.writerow(columns) + writer.writerows(rows) + + +def _expected_split(m4_id: str) -> Split: + return _OPENTSLM_SPLIT.get(m4_id, Split.TRAIN) + + +def _write_release( + directory: Path, + *, + series_rows: dict[str, list[tuple[str, str]]] | None = None, + split_sha256: str | None = None, +) -> M4CaptionRelease: + # Like the archive, the files sit in a folder of their own, beside the files that the loader skips. + root = directory / "M4TimeSeriesCaptionDataset" + root.mkdir() + for frequency, m4_ids in _SERIES_IDS.items(): + default_rows = [(f"series-{m4_id}", json.dumps(_values(m4_id))) for m4_id in m4_ids] + caption_rows = [(f"series-{m4_id}", f"Caption of {m4_id}.\n\nA second paragraph.") for m4_id in m4_ids] + _write_csv( + root / f"m4_series_{frequency}.csv", ("id", "series"), (series_rows or {}).get(frequency, default_rows) + ) + _write_csv(root / f"m4_captions_{frequency}.csv", ("id", "caption"), caption_rows) + _write_csv(root / "m4_captions.csv", ("id", "caption"), [("series-W1", "A caption that OpenTSLM never used.")]) + all_ids = [m4_id for m4_ids in _SERIES_IDS.values() for m4_id in m4_ids] + if split_sha256 is None: + split_sha256 = OpenTSLMSplit.digest(all_ids, [_expected_split(m4_id) for m4_id in all_ids]) + return M4CaptionRelease(directory=root, split=OpenTSLMSplit(sha256=split_sha256)) + + +def _convert(directory: Path, **changes) -> TimeFDataset: + return M4CaptionConnector().convert([_write_release(directory, **changes)]) + + +def test_each_series_becomes_a_record_and_a_caption_task(tmp_path): + tasks = _convert(tmp_path).tasks_of(AnswerTask) + expected = [(frequency, m4_id) for frequency, m4_ids in _SERIES_IDS.items() for m4_id in m4_ids] + assert len(tasks) == len(expected) + for task, (frequency, m4_id) in zip(tasks, expected, strict=True): + (record,) = task.inputs + (signal,) = record.signals + # The release values are float32 values, so float32 keeps every digit. + assert signal.to_numpy().dtype == np.float32 + np.testing.assert_array_equal(signal.to_numpy(), np.array(_values(m4_id), dtype=np.float32)) + # The release has no timestamps, and a month or a year has no fixed length. + assert signal.time_axis == OrdinalAxis() + assert signal.spec.unit_value is None + assert record.metadata == {"m4_id": m4_id} + (annotation,) = record.annotations + assert (annotation.key, read_value(annotation.value)) == ("frequency", frequency) + assert task.targets is not None + assert [read_value(target) for target in task.targets] == [f"Caption of {m4_id}.\n\nA second paragraph."] + # A caption task has no prompt. The training prompt of OpenTSLM is not part of the release. + assert task.prompt is None + assert task.split == _expected_split(m4_id) + + +def test_a_split_that_differs_from_the_pinned_digest_raises(tmp_path): + with pytest.raises(TimeNetConnectorError, match=r"the OpenTSLM split .* does not match the pinned digest"): + _convert(tmp_path, split_sha256="0" * 64) + + +@pytest.mark.parametrize( + ("series_rows", "message"), + [ + ({"Daily": [("series-D1", json.dumps([0.1, 0.2])), ("series-D2", "[1.0]")]}, "not exactly float32"), + ({"Daily": [("series-D1", "[1.0, null]"), ("series-D2", "[1.0]")]}, "line 2: .*Input should be a valid number"), + ({"Daily": [("series-D1", "[1.0, NaN]"), ("series-D2", "[1.0]")]}, "line 2: .*Input should be a finite number"), + ({"Daily": [("series-D2", "[1.0]"), ("series-D1", "[1.0]")]}, "series id 'series-D2' does not match"), + ({"Daily": [("series-M9", "[1.0]"), ("series-D2", "[1.0]")]}, "is not a Daily M4 series id"), + ({"Daily": [("series-D1", "[1.0]")]}, "has 1 series rows but 2 caption rows"), + ], + ids=[ + "a value that is not float32", + "a null value", + "a NaN value", + "series and captions out of step", + "an id of another frequency", + "a series row too few", + ], +) +def test_a_malformed_series_file_raises_with_its_location(tmp_path, series_rows, message): + # The CSV reader rejects a null or NaN value itself, and names the line of the file. + with pytest.raises(TimeNetConnectorError, match=rf"(?s)m4_series_Daily\.csv.*{message}"): + _convert(tmp_path, series_rows=series_rows) + + +def test_the_dataset_round_trips_through_storage(tmp_path): + source = tmp_path / "source" + source.mkdir() + dataset = _convert(source) + version_dir = dataset.write(path=tmp_path / "registry") + with TimeFReader(open_local_version(version_dir)) as reader: + reader.verify() + assert_datasets_equal(dataset, reader.read()) From b5890639b7399f0dbb32f619b8d85110964cecb0 Mon Sep 17 00:00:00 2001 From: Adrian Blumer Date: Tue, 17 Nov 2026 09:07:22 -0800 Subject: [PATCH 02/20] docs(connectors): describe the M4-Caption connector and a parent dataset Add a README to the M4-Caption connector. It describes the records, the split, and how the release relates to the M4 data. It also describes future work: an M4 parent dataset that M4-Caption can import its Records from. --- .../datasets/opentslm/m4_caption/README.md | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/README.md diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/README.md b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/README.md new file mode 100644 index 000000000..36c6b64a5 --- /dev/null +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/README.md @@ -0,0 +1,38 @@ +# M4-Caption + +M4-Caption pairs each of the 100,000 series of the M4 forecasting competition with one caption that +GPT-4o wrote. OpenTSLM publishes it as a zip archive of CSV files, one series file and one caption +file for each M4 frequency. + +The connector converts each series into one Record and one `AnswerTask` without a prompt. The +Record holds the series as one float32 Signal on an ordinal axis, the M4 id in its metadata, and +the M4 frequency as an annotation. The task target is the caption. + +## Split + +The release has no split column. The OpenTSLM loader splits the series at load time with the +`train_test_split` function of the datasets library. The connector computes the same 80/10/10 split +with NumPy. If the result does not match `OPENTSLM_SPLIT_SHA256`, the build stops with an error. +`generate_splits.py` computed that digest with the OpenTSLM code path and the library versions of +the OpenTSLM `uv.lock`. + +## Relation to the M4 data + +Each series of the release is the train part of the M4 series with the same id, from the +`Dataset/Train` files of the M4-methods repository. The release does not hold the test horizon or +the series information of `M4-info.csv`. Each value is the float32 rounding of the M4 value. The +largest relative difference is 6e-8, and in 49,610 of the 100,000 series the values are equal bit +for bit. + +## Future work: an M4 parent dataset + +TimeNet can model this relation with a parent dataset. A connector for M4, for example +`mcompetitions/m4`, can convert the `Dataset/` folder of M4-methods: the train and test files and +`M4-info.csv`. M4-Caption can then declare that release under `parents` and import its Records, as +`physionet/ecg-qa-cot` imports PTB-XL. The caption task then names the train part of each series +with a `StepInterval` scope. + +With a parent, the 24 million values exist once, and a reader gets the M4 category, horizon and +test part. The values become the float64 M4 values, not the float32 values that OpenTSLM plotted +for GPT-4o. The card must document that difference. The connector must also make sure that each +release series equals the float32 rounding of the parent series. From 6217eec7a3058f9d679df82b7b5b6fbbd3fc8e0e Mon Sep 17 00:00:00 2001 From: Adrian Blumer Date: Tue, 17 Nov 2026 09:21:12 -0800 Subject: [PATCH 03/20] refactor(connectors): raise the CSV cell limit before M4-Caption reads Call CsvDataReader.raise_field_size_limit before the connector reads a series file, in place of the removed max_field_chars option. --- .../datasets/opentslm/m4_caption/connector.py | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py index 1233e4be3..2111967d4 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py @@ -216,10 +216,8 @@ def _read_frequency(self, frequency: str) -> Iterator[M4CaptionSeries]: """ series_path = self.directory / f"m4_series_{frequency}.csv" captions_path = self.directory / f"m4_captions_{frequency}.csv" - series_reader = CsvDataReader( - series_path, _SeriesRow, expected_columns=("id", "series"), max_field_chars=MAX_SERIES_CHARS - ) - series_rows = list(series_reader.iter_rows()) + CsvDataReader.raise_field_size_limit(MAX_SERIES_CHARS) + series_rows = list(CsvDataReader(series_path, _SeriesRow, expected_columns=("id", "series")).iter_rows()) caption_rows = list(CsvDataReader(captions_path, _CaptionRow, expected_columns=("id", "caption")).iter_rows()) if len(series_rows) != len(caption_rows): raise TimeNetConnectorError( From c6f426d5f37a496f17cc2cc49ef587b7acb2c2e5 Mon Sep 17 00:00:00 2001 From: Adrian Blumer Date: Tue, 17 Nov 2026 09:24:58 -0800 Subject: [PATCH 04/20] refactor(connectors): use the renamed CSV cell limit method Call CsvDataReader.set_field_size_limit, the new name of raise_field_size_limit. --- .../datasets/opentslm/m4_caption/connector.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py index 2111967d4..362d5b82c 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py @@ -216,7 +216,7 @@ def _read_frequency(self, frequency: str) -> Iterator[M4CaptionSeries]: """ series_path = self.directory / f"m4_series_{frequency}.csv" captions_path = self.directory / f"m4_captions_{frequency}.csv" - CsvDataReader.raise_field_size_limit(MAX_SERIES_CHARS) + CsvDataReader.set_field_size_limit(MAX_SERIES_CHARS) series_rows = list(CsvDataReader(series_path, _SeriesRow, expected_columns=("id", "series")).iter_rows()) caption_rows = list(CsvDataReader(captions_path, _CaptionRow, expected_columns=("id", "caption")).iter_rows()) if len(series_rows) != len(caption_rows): From 7bea0f0053466a646116916a62f1501c5f87ad7a Mon Sep 17 00:00:00 2001 From: Adrian Blumer Date: Tue, 17 Nov 2026 10:25:19 -0800 Subject: [PATCH 05/20] refactor(connectors): freeze the M4-Caption split in splits.json.xz The connector computed the OpenTSLM split with NumPy and compared it with a digest from generate_splits.py. That meant two implementations of one split. generate_splits.py now runs the calls of the OpenTSLM loader once and writes the 10,000 validation and 10,000 test series, by M4 id, to splits.json.xz. The file is 19 KB, and the connector reads it with the lzma module of the standard library. This is the frozen-file pattern of sleep-cot. The file gives the same split as the digest did. The README describes the frozen split. It also notes future work on the axis type, if calendar axes (#555) land. --- .../datasets/opentslm/m4_caption/README.md | 29 +++-- .../datasets/opentslm/m4_caption/connector.py | 123 ++++++++++-------- .../opentslm/m4_caption/generate_splits.py | 57 +++++--- .../opentslm/m4_caption/splits.json.xz | Bin 0 -> 19476 bytes .../m4_caption/tests/test_connector.py | 44 +++++-- 5 files changed, 151 insertions(+), 102 deletions(-) create mode 100644 packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/splits.json.xz diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/README.md b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/README.md index 36c6b64a5..8094607aa 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/README.md +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/README.md @@ -11,28 +11,35 @@ the M4 frequency as an annotation. The task target is the caption. ## Split The release has no split column. The OpenTSLM loader splits the series at load time with the -`train_test_split` function of the datasets library. The connector computes the same 80/10/10 split -with NumPy. If the result does not match `OPENTSLM_SPLIT_SHA256`, the build stops with an error. -`generate_splits.py` computed that digest with the OpenTSLM code path and the library versions of -the OpenTSLM `uv.lock`. +`train_test_split` function of the datasets library, so the split depends on the versions of +datasets and NumPy. `generate_splits.py` ran the calls of the loader once, with the library versions +of the OpenTSLM `uv.lock`. It wrote the 10,000 validation and 10,000 test series, by M4 id, to +`splits.json.xz`. The connector reads that file and puts every other series in the train split. + +The file is JSON compressed with xz, about 19 KB. Python reads it with the `lzma` module of the +standard library. To read it yourself, run `xz -dc splits.json.xz`. The file also states the SHA-256 +of the release archive. If it does not match the pinned archive, the build stops with an error. ## Relation to the M4 data Each series of the release is the train part of the M4 series with the same id, from the `Dataset/Train` files of the M4-methods repository. The release does not hold the test horizon or the series information of `M4-info.csv`. Each value is the float32 rounding of the M4 value. The -largest relative difference is 6e-8, and in 49,610 of the 100,000 series the values are equal bit -for bit. +largest relative difference is 6e-8. ## Future work: an M4 parent dataset TimeNet can model this relation with a parent dataset. A connector for M4, for example `mcompetitions/m4`, can convert the `Dataset/` folder of M4-methods: the train and test files and -`M4-info.csv`. M4-Caption can then declare that release under `parents` and import its Records, as -`physionet/ecg-qa-cot` imports PTB-XL. The caption task then names the train part of each series -with a `StepInterval` scope. +`M4-info.csv`. M4-Caption can then declare that release under `parents` and import its Records. +The caption task then names the train part of each series with a `StepInterval` scope. With a parent, the 24 million values exist once, and a reader gets the M4 category, horizon and test part. The values become the float64 M4 values, not the float32 values that OpenTSLM plotted -for GPT-4o. The card must document that difference. The connector must also make sure that each -release series equals the float32 rounding of the parent series. +for GPT-4o. + +## Future work: Change axis types + +We currently use ordinal axis for consistency, as some of the frequencies are only regular in +calendar terms, e.g. "monthly". If [Proposal: calendar axes, value cells and civil-date origins +](https://github.com/OpenTSLM/TimeNet/issues/555) lands we can reconsider this choice. diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py index 362d5b82c..934713a9d 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py @@ -2,19 +2,20 @@ The OpenTSLM release holds the train part of all 100,000 M4 series, one CSV of series and one CSV of captions for each of the six M4 frequencies. Each series becomes one Record and one AnswerTask. The -target is the caption. The release has no split, so the connector computes the split of OpenTSLM's -loader and checks it against a pinned digest. +target is the caption. The release has no split, so the connector reads the split of OpenTSLM's +loader from splits.json.xz, which generate_splits.py wrote. """ +from collections import Counter from collections.abc import Iterator, Sequence from dataclasses import dataclass -import hashlib -from math import ceil +import lzma from pathlib import Path import re +from typing import Self import numpy as np -from pydantic import FiniteFloat, Json +from pydantic import BaseModel, ConfigDict, FiniteFloat, Json, ValidationError, model_validator from timenet.connectors import BaseConnector from timenet.dataset import Record, Signal, Source, TimeFDataset @@ -30,12 +31,12 @@ RELEASE_FOLDER = "M4TimeSeriesCaptionDataset" """The folder in the archive that holds the CSV files.""" FREQUENCIES = ("Daily", "Hourly", "Monthly", "Quarterly", "Weekly", "Yearly") -"""The M4 frequencies, in the order that OpenTSLM's loader reads them. The split depends on this order.""" +"""The M4 frequencies, in the order that OpenTSLM's loader reads them.""" MAX_SERIES_CHARS = 1_000_000 """The largest series cell that the connector reads, in characters. The largest cell of the release holds a daily series of 9,919 values in 169,126 characters.""" -OPENTSLM_SPLIT_SHA256 = "370cc2580bcdb912e13a546c1a84f3d52d7e2098db07cfe2873ffde8270f5256" -"""The digest of the split that OpenTSLM's loader gives the release, as generate_splits.py computed it.""" +SPLITS_PATH = Path(__file__).with_name("splits.json.xz") +"""The split of OpenTSLM's loader for the release, as generate_splits.py wrote it.""" # The release states no unit, and the M4 series come from many domains. M4_SERIES = TimeSeriesSpec(spec_type="m4_series", name="M4 series", unit_value=None, dtype="float32") @@ -123,74 +124,74 @@ def create_caption_task(self, record: Record, *, split: Split) -> AnswerTask: return AnswerTask(inputs=(record,), targets=(self.caption,), split=split) -@dataclass(frozen=True) -class OpenTSLMSplit: - """The 80/10/10 split of ``create_combined_dataset`` in OpenTSLM's M4 loader. +class M4CaptionSplits(BaseModel): + """The validation and test series of OpenTSLM's split, by M4 id. - The loader calls ``train_test_split`` of the datasets library twice, without stratification. That - function shuffles the rows with ``numpy.random.default_rng(seed).permutation``: the first rows of the - permutation are the test part and the rest are the train part. NumPy does not promise the same - permutation in every version, so the split is checked against a digest. + The release has no split. generate_splits.py ran the calls of OpenTSLM's loader once and wrote this + split to splits.json.xz. Every series that the file does not name is in the train split. """ - sha256: str - """The digest that :meth:`digest` must give for the split.""" + model_config = ConfigDict(extra="forbid", frozen=True) - @staticmethod - def digest(m4_ids: Sequence[str], splits: Sequence[Split]) -> str: - """Compute the digest of a split. + source_sha256: str + """SHA-256 digest of the release archive that the split was made from.""" + validation: tuple[str, ...] + test: tuple[str, ...] - The digest is the SHA-256 of one line per series, in order. Each line is the M4 id, a tab, the - split, and a newline. + @model_validator(mode="after") + def _each_series_in_one_split(self) -> Self: + repeated = sorted(m4_id for m4_id, count in Counter(self.m4_ids).items() if count > 1) + if repeated: + raise ValueError(f"series {repeated} are named more than once") + return self - Returns: - The digest in hexadecimal. - """ - lines = "".join(f"{m4_id}\t{split}\n" for m4_id, split in zip(m4_ids, splits, strict=True)) - return hashlib.sha256(lines.encode()).hexdigest() + @property + def m4_ids(self) -> tuple[str, ...]: + """The validation and test series together.""" + return (*self.validation, *self.test) - def assign_splits(self, m4_ids: Sequence[str]) -> list[Split]: - """Assign the split of OpenTSLM's loader to each series, in the order of the loader. + @classmethod + def read_from_file(cls, path: Path) -> Self: + """Read the split from an xz-compressed JSON file. Returns: - The split of each series. + The split. Raises: - TimeNetConnectorError: If the split does not match the pinned digest. + TimeNetConnectorError: If the file does not hold a valid split. """ - splits = [Split.TRAIN] * len(m4_ids) - all_positions = np.arange(len(m4_ids)) - train_and_validation = self._split_off(all_positions, splits, Split.TEST, seed=42, size=0.1) - # The loader keeps the share of the validation part at 10 percent of all series. - self._split_off(train_and_validation, splits, Split.VALIDATION, seed=43, size=0.1 / (1.0 - 0.1)) - if self.digest(m4_ids, splits) != self.sha256: - raise TimeNetConnectorError( - f"the OpenTSLM split of {len(m4_ids)} series does not match the pinned digest {self.sha256}" - ) - return splits - - @staticmethod - def _split_off(positions: np.ndarray, splits: list[Split], split: Split, *, seed: int, size: float) -> np.ndarray: - """Do one ``train_test_split`` call of the datasets library on the series at ``positions``. + try: + return cls.model_validate_json(lzma.decompress(path.read_bytes())) + except (lzma.LZMAError, ValidationError) as exc: + raise TimeNetConnectorError(f"{path.name} does not hold a valid split: {exc}") from exc - The series of the part that the call names "test" get ``split``. + def assign_split_to_each_series(self, m4_ids: Sequence[str]) -> list[Split]: + """Assign a split to each series of the pinned release. Returns: - The positions of the part that the call names "train", in the order of the permutation. + The split of each series, in the order of ``m4_ids``. + + Raises: + TimeNetConnectorError: If the split was made from another release, or names a series that + the release does not have. """ - permutation = np.random.default_rng(seed).permutation(len(positions)) - n_split = ceil(size * len(positions)) - for position in positions[permutation[:n_split]]: - splits[position] = split - return positions[permutation[n_split:]] + if self.source_sha256 != M4_CAPTION_SHA256: + raise TimeNetConnectorError( + f"the split was made from the release {self.source_sha256}, not from the pinned {M4_CAPTION_SHA256}" + ) + unknown = sorted(set(self.m4_ids) - set(m4_ids)) + if unknown: + raise TimeNetConnectorError(f"the split names series {unknown} that the release does not have") + split_of = dict.fromkeys(self.validation, Split.VALIDATION) | dict.fromkeys(self.test, Split.TEST) + return [split_of.get(m4_id, Split.TRAIN) for m4_id in m4_ids] @dataclass(frozen=True) class M4CaptionRelease: - """The extracted release and the split that its series must get.""" + """The extracted release and the file that holds the split of its series.""" directory: Path - split: OpenTSLMSplit + splits_path: Path def read_series(self) -> Iterator[M4CaptionSeries]: """Read every series of the release, in the order of OpenTSLM's loader. @@ -205,6 +206,14 @@ def read_series(self) -> Iterator[M4CaptionSeries]: for frequency in FREQUENCIES: yield from self._read_frequency(frequency) + def read_splits(self, m4_ids: Sequence[str]) -> list[Split]: + """Read the split of each series from the split file. + + Returns: + The split of each series, in the order of ``m4_ids``. + """ + return M4CaptionSplits.read_from_file(self.splits_path).assign_split_to_each_series(m4_ids) + def _read_frequency(self, frequency: str) -> Iterator[M4CaptionSeries]: """Read the series of one frequency, paired with the caption in the same row of its caption file. @@ -250,10 +259,10 @@ async def download_async(self, cache_dir: Path) -> list[M4CaptionRelease]: # ru cache_dir: The directory that holds the extracted files. Returns: - The extracted release, with the pinned split. + The extracted release, with the frozen split of the connector. """ root = await ensure_archive(M4_CAPTION_URL, cache_dir, filename="m4_caption.zip", sha256=M4_CAPTION_SHA256) - return [M4CaptionRelease(directory=root / RELEASE_FOLDER, split=OpenTSLMSplit(sha256=OPENTSLM_SPLIT_SHA256))] + return [M4CaptionRelease(directory=root / RELEASE_FOLDER, splits_path=SPLITS_PATH)] def convert(self, raw_refs: list[M4CaptionRelease]) -> TimeFDataset: """Create one Record and one AnswerTask for each series. @@ -266,7 +275,7 @@ def convert(self, raw_refs: list[M4CaptionRelease]) -> TimeFDataset: """ (release,) = raw_refs all_series = list(release.read_series()) - splits = release.split.assign_splits([series.m4_id for series in all_series]) + splits = release.read_splits([series.m4_id for series in all_series]) dataset = TimeFDataset(metadata=self.metadata()) for series, split in zip(all_series, splits, strict=True): record = dataset.add_record(record=series.create_record()) diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/generate_splits.py b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/generate_splits.py index e4d5fd2e4..633bfc131 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/generate_splits.py +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/generate_splits.py @@ -7,28 +7,33 @@ # "pandas==2.3.3", # ] # /// -"""Print OPENTSLM_SPLIT_SHA256, the digest of the train, validation and test split of m4-caption. +"""Write splits.json.xz, the frozen train, validation and test split of m4-caption. The release does not store the split. OpenTSLM's loader makes it at load time with the datasets library -and a fixed seed. The connector computes the same split with NumPy and checks it against the digest that -this script prints. This script runs the calls of OpenTSLM's loader with the library versions of the -OpenTSLM uv.lock, so the digest comes from OpenTSLM's own code path and not from the connector. +and a fixed seed, so the split depends on the versions of datasets and NumPy. Instead of pinning these +libraries in the connector, this script ran the calls of the loader once, with the library versions of +the OpenTSLM uv.lock, and wrote the validation and test series to splits.json.xz. The connector reads +that file. xz keeps the file small, and Python reads it with the lzma module of the standard library. +The script is here for reference, so you can see how the file was made. -Run it once with the extracted release folder, from this directory:: +Run it once with the release archive, from this directory:: - uv run generate_splits.py + uv run generate_splits.py """ import hashlib import json +import lzma from pathlib import Path import sys +import zipfile FREQUENCIES = ["Daily", "Hourly", "Monthly", "Quarterly", "Weekly", "Yearly"] +SPLITS_PATH = Path(__file__).with_name("splits.json.xz") -def load_samples(release: Path) -> list[dict[str, str]]: +def load_samples(archive: zipfile.ZipFile) -> list[dict[str, str]]: """Read the samples in the order of load_all_m4_data and create_combined_dataset. Returns: @@ -40,8 +45,8 @@ def load_samples(release: Path) -> list[dict[str, str]]: all_samples = [] for frequency in FREQUENCIES: - series_df = pd.read_csv(release / f"m4_series_{frequency}.csv") - captions_df = pd.read_csv(release / f"m4_captions_{frequency}.csv") + series_df = pd.read_csv(archive.open(f"M4TimeSeriesCaptionDataset/m4_series_{frequency}.csv")) + captions_df = pd.read_csv(archive.open(f"M4TimeSeriesCaptionDataset/m4_captions_{frequency}.csv")) common_ids = set(series_df["id"]) & set(captions_df["id"]) series_df = series_df[series_df["id"].isin(common_ids)].reset_index(drop=True) captions_df = captions_df[captions_df["id"].isin(common_ids)].reset_index(drop=True) @@ -54,11 +59,22 @@ def load_samples(release: Path) -> list[dict[str, str]]: return all_samples +def m4_id_order(m4_id: str) -> tuple[str, int]: + """Sort M4 ids by frequency letter, then by number: M2 before M10. + + Returns: + The sort key. + """ + return m4_id[0], int(m4_id[1:]) + + def main() -> None: - """Split the release in the folder that the first argument names, and print the digest.""" + """Split the release archive that the first argument names, and write splits.json.xz.""" from datasets import Dataset # ruff: ignore[import-outside-top-level] # ty: ignore[unresolved-import] - all_samples = load_samples(Path(sys.argv[1])) + archive_path = Path(sys.argv[1]) + with zipfile.ZipFile(archive_path) as archive: + all_samples = load_samples(archive) # The calls of create_combined_dataset, with their names and settings. full_dataset = Dataset.from_list(all_samples) @@ -67,16 +83,15 @@ def main() -> None: seed = 42 train_val, test = full_dataset.train_test_split(test_size=test_frac, seed=seed).values() val_frac_adj = val_frac / (1.0 - test_frac) - train, val = train_val.train_test_split(test_size=val_frac_adj, seed=seed + 1).values() - - # The digest of OpenTSLMSplit.digest in connector.py: one "\t\n" line per series, in - # the order of the loader. The M4 id is the release id without its "series-" prefix. - split_of = dict.fromkeys(train["id"], "train") - split_of |= dict.fromkeys(val["id"], "validation") - split_of |= dict.fromkeys(test["id"], "test") - lines = "".join(f"{sample['id'].removeprefix('series-')}\t{split_of[sample['id']]}\n" for sample in all_samples) - print(f"train {len(train)}, validation {len(val)}, test {len(test)}") - print(f'OPENTSLM_SPLIT_SHA256 = "{hashlib.sha256(lines.encode()).hexdigest()}"') + _, val = train_val.train_test_split(test_size=val_frac_adj, seed=seed + 1).values() + + # The file names each series by its M4 id: the release id without its "series-" prefix. + splits = { + "source_sha256": hashlib.sha256(archive_path.read_bytes()).hexdigest(), + "validation": sorted((sample_id.removeprefix("series-") for sample_id in val["id"]), key=m4_id_order), + "test": sorted((sample_id.removeprefix("series-") for sample_id in test["id"]), key=m4_id_order), + } + SPLITS_PATH.write_bytes(lzma.compress((json.dumps(splits, indent=2) + "\n").encode())) if __name__ == "__main__": diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/splits.json.xz b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/splits.json.xz new file mode 100644 index 0000000000000000000000000000000000000000..0077df9176b204faefcbde8bdc9ff8ebe041e5f9 GIT binary patch literal 19476 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 literal 0 HcmV?d00001 diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/tests/test_connector.py b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/tests/test_connector.py index 39f13da60..51c5be379 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/tests/test_connector.py +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/tests/test_connector.py @@ -1,5 +1,6 @@ import csv import json +import lzma from pathlib import Path import numpy as np @@ -14,9 +15,11 @@ from timenet.types import AnswerTask, Split from timenet.types.text import read_value from timenet_connectors.datasets.opentslm.m4_caption.connector import ( + M4_CAPTION_SHA256, + SPLITS_PATH, M4CaptionConnector, M4CaptionRelease, - OpenTSLMSplit, + M4CaptionSplits, ) @@ -30,9 +33,9 @@ } """Ten series in the order that OpenTSLM's loader reads the frequencies.""" -_OPENTSLM_SPLIT = {"M3": Split.TEST, "W1": Split.VALIDATION} -"""The split that create_combined_dataset of OpenTSLM gives these ten series. It was taken from a run of -datasets 4.4.1, the version in the OpenTSLM uv.lock. Every other series is in the train split.""" +_SPLITS = {"source_sha256": M4_CAPTION_SHA256, "validation": ["W1"], "test": ["M3"]} +"""A split file for the ten series. Every series that it does not name is in the train split.""" +_EXPECTED_SPLIT = {"M3": Split.TEST, "W1": Split.VALIDATION} _FLOAT32_VALUES = [1089.199951171875, 1078.9100341796875, 8000.0, 195.92799377441406] """Values as the release writes them: M4 values rounded to float32, printed with every digit.""" @@ -61,14 +64,14 @@ def _write_csv(path: Path, columns: tuple[str, str], rows: list[tuple[str, str]] def _expected_split(m4_id: str) -> Split: - return _OPENTSLM_SPLIT.get(m4_id, Split.TRAIN) + return _EXPECTED_SPLIT.get(m4_id, Split.TRAIN) def _write_release( directory: Path, *, series_rows: dict[str, list[tuple[str, str]]] | None = None, - split_sha256: str | None = None, + splits: dict[str, str | list[str]] = _SPLITS, ) -> M4CaptionRelease: # Like the archive, the files sit in a folder of their own, beside the files that the loader skips. root = directory / "M4TimeSeriesCaptionDataset" @@ -81,10 +84,9 @@ def _write_release( ) _write_csv(root / f"m4_captions_{frequency}.csv", ("id", "caption"), caption_rows) _write_csv(root / "m4_captions.csv", ("id", "caption"), [("series-W1", "A caption that OpenTSLM never used.")]) - all_ids = [m4_id for m4_ids in _SERIES_IDS.values() for m4_id in m4_ids] - if split_sha256 is None: - split_sha256 = OpenTSLMSplit.digest(all_ids, [_expected_split(m4_id) for m4_id in all_ids]) - return M4CaptionRelease(directory=root, split=OpenTSLMSplit(sha256=split_sha256)) + splits_path = directory / "splits.json.xz" + splits_path.write_bytes(lzma.compress(json.dumps(splits).encode())) + return M4CaptionRelease(directory=root, splits_path=splits_path) def _convert(directory: Path, **changes) -> TimeFDataset: @@ -114,9 +116,25 @@ def test_each_series_becomes_a_record_and_a_caption_task(tmp_path): assert task.split == _expected_split(m4_id) -def test_a_split_that_differs_from_the_pinned_digest_raises(tmp_path): - with pytest.raises(TimeNetConnectorError, match=r"the OpenTSLM split .* does not match the pinned digest"): - _convert(tmp_path, split_sha256="0" * 64) +@pytest.mark.parametrize( + ("changes", "message"), + [ + ({"source_sha256": "0" * 64}, "the split was made from the release 0+, not from the pinned"), + ({"test": ["M3", "W1"]}, r"series \['W1'\] are named more than once"), + ({"test": ["M3", "M9"]}, r"names series \['M9'\] that the release does not have"), + ], + ids=["another release", "a series in two splits", "a series that the release does not have"], +) +def test_a_split_file_that_does_not_fit_the_release_raises(tmp_path, changes, message): + with pytest.raises(TimeNetConnectorError, match=message): + _convert(tmp_path, splits=_SPLITS | changes) + + +def test_the_frozen_split_holds_the_opentslm_split_of_the_pinned_release(): + splits = M4CaptionSplits.read_from_file(SPLITS_PATH) + assert splits.source_sha256 == M4_CAPTION_SHA256 + # The 80/10/10 split of 100,000 series that the OpenTSLM paper reports. + assert (len(splits.validation), len(splits.test)) == (10_000, 10_000) @pytest.mark.parametrize( From 4b6922819f8743a3883ba7e0ee52b323709cb876 Mon Sep 17 00:00:00 2001 From: Adrian Blumer Date: Tue, 17 Nov 2026 10:43:35 -0800 Subject: [PATCH 06/20] fix(connectors): reject non-numeric M4-Caption values The series cell accepted values that are not numbers. Pydantic turned true into 1.0 and "3.5" into 3.5. An empty list passed the row check and failed later without the file or the row. The series cell now takes strict finite floats and at least one value. An M4Frequency enum now owns the six frequencies: their order, the id letter, and the two release file names. The connector sets the CSV cell limit once in convert, not once for each frequency. The tests check a Boolean value and an empty series, and no longer repeat the pydantic NaN check. The card and the README get small text fixes. --- .../datasets/opentslm/m4_caption/README.md | 9 +- .../datasets/opentslm/m4_caption/connector.py | 99 +++++++++++++------ .../datasets/opentslm/m4_caption/dataset.yaml | 5 +- .../m4_caption/tests/test_connector.py | 10 +- 4 files changed, 83 insertions(+), 40 deletions(-) diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/README.md b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/README.md index 8094607aa..458b1ef0b 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/README.md +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/README.md @@ -38,8 +38,9 @@ With a parent, the 24 million values exist once, and a reader gets the M4 catego test part. The values become the float64 M4 values, not the float32 values that OpenTSLM plotted for GPT-4o. -## Future work: Change axis types +## Future work: change axis types -We currently use ordinal axis for consistency, as some of the frequencies are only regular in -calendar terms, e.g. "monthly". If [Proposal: calendar axes, value cells and civil-date origins -](https://github.com/OpenTSLM/TimeNet/issues/555) lands we can reconsider this choice. +We currently use an ordinal axis for consistency, as some of the frequencies are only regular in +calendar terms, e.g. "monthly". If +[Proposal: calendar axes, value cells and civil-date origins](https://github.com/OpenTSLM/TimeNet/issues/555) +lands we can reconsider this choice. diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py index 934713a9d..407f94cc9 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py @@ -9,13 +9,14 @@ from collections import Counter from collections.abc import Iterator, Sequence from dataclasses import dataclass +from enum import StrEnum import lzma from pathlib import Path import re -from typing import Self +from typing import Annotated, Self import numpy as np -from pydantic import BaseModel, ConfigDict, FiniteFloat, Json, ValidationError, model_validator +from pydantic import AllowInfNan, BaseModel, ConfigDict, Field, Json, StrictFloat, ValidationError, model_validator from timenet.connectors import BaseConnector from timenet.dataset import Record, Signal, Source, TimeFDataset @@ -30,8 +31,6 @@ M4_CAPTION_SHA256 = "4acb748d94d7287fe58dbb5c3cf6314ea259010b7720f42506739269dec54edf" RELEASE_FOLDER = "M4TimeSeriesCaptionDataset" """The folder in the archive that holds the CSV files.""" -FREQUENCIES = ("Daily", "Hourly", "Monthly", "Quarterly", "Weekly", "Yearly") -"""The M4 frequencies, in the order that OpenTSLM's loader reads them.""" MAX_SERIES_CHARS = 1_000_000 """The largest series cell that the connector reads, in characters. The largest cell of the release holds a daily series of 9,919 values in 169,126 characters.""" @@ -41,15 +40,71 @@ # The release states no unit, and the M4 series come from many domains. M4_SERIES = TimeSeriesSpec(spec_type="m4_series", name="M4 series", unit_value=None, dtype="float32") -_SERIES_ID = re.compile(r"series-(?P(?P[DHMQWY])[1-9][0-9]*)") +_SERIES_ID = re.compile(r"series-(?P(?P[A-Z])[1-9][0-9]*)") """A release id: the M4 id, such as M1, after a ``series-`` prefix that OpenTSLM added.""" +_SeriesValue = Annotated[StrictFloat, AllowInfNan(False)] +"""A finite JSON number. Strict, so that a Boolean or a string in the list is an error, not a number.""" + + +class M4Frequency(StrEnum): + """An M4 frequency. The members are in the order that OpenTSLM's loader reads them. + + The value is the name in the release file names and in the ``frequency`` annotation. + """ + + DAILY = "Daily" + HOURLY = "Hourly" + MONTHLY = "Monthly" + QUARTERLY = "Quarterly" + WEEKLY = "Weekly" + YEARLY = "Yearly" + + @property + def id_letter(self) -> str: + """The letter that starts the M4 id of each series of this frequency, such as M in M1.""" + return _M4_ID_LETTERS[self] + + @property + def series_file(self) -> str: + """The name of the release file that holds the series of this frequency.""" + return f"m4_series_{self}.csv" + + @property + def captions_file(self) -> str: + """The name of the release file that holds the captions of this frequency.""" + return f"m4_captions_{self}.csv" + + def parse_m4_id(self, series_id: str) -> str: + """Get the M4 id from a release id, and check that it belongs to this frequency. + + Returns: + The M4 id, such as ``M1``. + + Raises: + TimeNetConnectorError: If the id is not an M4 series id of this frequency. + """ + match = _SERIES_ID.fullmatch(series_id) + if match is None or match["letter"] != self.id_letter: + raise TimeNetConnectorError(f"{series_id!r} is not a {self} M4 series id") + return match["m4_id"] + + +_M4_ID_LETTERS = { + M4Frequency.DAILY: "D", + M4Frequency.HOURLY: "H", + M4Frequency.MONTHLY: "M", + M4Frequency.QUARTERLY: "Q", + M4Frequency.WEEKLY: "W", + M4Frequency.YEARLY: "Y", +} + class _SeriesRow(DataRow): """A row of a series file: the release id and the values as a JSON list.""" id: str - series: Json[list[FiniteFloat]] + series: Json[Annotated[list[_SeriesValue], Field(min_length=1)]] class _CaptionRow(DataRow): @@ -59,21 +114,6 @@ class _CaptionRow(DataRow): caption: str -def _parse_m4_id(series_id: str, frequency: str) -> str: - """Get the M4 id from a release id, and check that it belongs to the frequency of its file. - - Returns: - The M4 id, such as ``M1``. - - Raises: - TimeNetConnectorError: If the id is not an M4 series id of the frequency. - """ - match = _SERIES_ID.fullmatch(series_id) - if match is None or match["letter"] != frequency[0]: - raise TimeNetConnectorError(f"{series_id!r} is not a {frequency} M4 series id") - return match["m4_id"] - - def _as_float32(values: Sequence[float]) -> np.ndarray: """Convert the values to float32, and check that the conversion keeps every value exactly. @@ -97,7 +137,7 @@ class M4CaptionSeries: """One M4 series of the release, with its frequency and caption.""" m4_id: str - frequency: str + frequency: M4Frequency values: np.ndarray caption: str @@ -108,7 +148,7 @@ def create_record(self) -> Record: The Record, not yet added to a dataset. """ signal = Signal.from_values(self.values, spec=M4_SERIES, name="value", time_axis=OrdinalAxis()) - frequency = Annotation(key="frequency", value=self.frequency) + frequency = Annotation(key="frequency", value=self.frequency.value) return Record( sources=(Source(name="M4", signals=(signal,)),), annotations=(frequency,), @@ -203,7 +243,7 @@ def read_series(self) -> Iterator[M4CaptionSeries]: Yields: Each series with its caption. """ - for frequency in FREQUENCIES: + for frequency in M4Frequency: yield from self._read_frequency(frequency) def read_splits(self, m4_ids: Sequence[str]) -> list[Split]: @@ -214,7 +254,7 @@ def read_splits(self, m4_ids: Sequence[str]) -> list[Split]: """ return M4CaptionSplits.read_from_file(self.splits_path).assign_split_to_each_series(m4_ids) - def _read_frequency(self, frequency: str) -> Iterator[M4CaptionSeries]: + def _read_frequency(self, frequency: M4Frequency) -> Iterator[M4CaptionSeries]: """Read the series of one frequency, paired with the caption in the same row of its caption file. Yields: @@ -223,9 +263,8 @@ def _read_frequency(self, frequency: str) -> Iterator[M4CaptionSeries]: Raises: TimeNetConnectorError: If the files do not pair one to one, or a series row is malformed. """ - series_path = self.directory / f"m4_series_{frequency}.csv" - captions_path = self.directory / f"m4_captions_{frequency}.csv" - CsvDataReader.set_field_size_limit(MAX_SERIES_CHARS) + series_path = self.directory / frequency.series_file + captions_path = self.directory / frequency.captions_file series_rows = list(CsvDataReader(series_path, _SeriesRow, expected_columns=("id", "series")).iter_rows()) caption_rows = list(CsvDataReader(captions_path, _CaptionRow, expected_columns=("id", "caption")).iter_rows()) if len(series_rows) != len(caption_rows): @@ -234,7 +273,7 @@ def _read_frequency(self, frequency: str) -> Iterator[M4CaptionSeries]: ) for number, (series_row, caption_row) in enumerate(zip(series_rows, caption_rows, strict=True), start=1): try: - m4_id = _parse_m4_id(series_row.id, frequency) + m4_id = frequency.parse_m4_id(series_row.id) if series_row.id != caption_row.id: raise TimeNetConnectorError( f"series id {series_row.id!r} does not match caption id {caption_row.id!r}" @@ -274,6 +313,8 @@ def convert(self, raw_refs: list[M4CaptionRelease]) -> TimeFDataset: The populated dataset. """ (release,) = raw_refs + # A daily series of the release does not fit in the default cell limit of the csv module. + CsvDataReader.set_field_size_limit(MAX_SERIES_CHARS) all_series = list(release.read_series()) splits = release.read_splits([series.m4_id for series in all_series]) dataset = TimeFDataset(metadata=self.metadata()) diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml index e2d5f73c8..b1b3ace9f 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml @@ -12,9 +12,8 @@ description: >- yearly series, with 13 to 9,919 values each. The OpenTSLM paper gives 64 to 512 values, but the release has the full length. The release holds the M4 values rounded to float32, and the dataset keeps them in float32 without a change. The release has no timestamps and states no unit. The M4 - series come - from the micro, industry, macro, finance, demographic and other domains, so the values have mixed - units. Each record states the M4 id, such as M1, and the M4 frequency. The release has no split + series come from the micro, industry, macro, finance, demographic and other domains, so the values + have mixed units. Each record states the M4 id, such as M1, and the M4 frequency. The release has no split column, so the dataset gives each series the split of OpenTSLM's loader. That loader merges all frequencies and makes a random 80/10/10 split with the datasets library. diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/tests/test_connector.py b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/tests/test_connector.py index 51c5be379..fbce2e5a5 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/tests/test_connector.py +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/tests/test_connector.py @@ -130,7 +130,7 @@ def test_a_split_file_that_does_not_fit_the_release_raises(tmp_path, changes, me _convert(tmp_path, splits=_SPLITS | changes) -def test_the_frozen_split_holds_the_opentslm_split_of_the_pinned_release(): +def test_the_frozen_split_is_of_the_pinned_release_and_has_the_paper_counts(): splits = M4CaptionSplits.read_from_file(SPLITS_PATH) assert splits.source_sha256 == M4_CAPTION_SHA256 # The 80/10/10 split of 100,000 series that the OpenTSLM paper reports. @@ -142,7 +142,8 @@ def test_the_frozen_split_holds_the_opentslm_split_of_the_pinned_release(): [ ({"Daily": [("series-D1", json.dumps([0.1, 0.2])), ("series-D2", "[1.0]")]}, "not exactly float32"), ({"Daily": [("series-D1", "[1.0, null]"), ("series-D2", "[1.0]")]}, "line 2: .*Input should be a valid number"), - ({"Daily": [("series-D1", "[1.0, NaN]"), ("series-D2", "[1.0]")]}, "line 2: .*Input should be a finite number"), + ({"Daily": [("series-D1", "[1.0, true]"), ("series-D2", "[1.0]")]}, "line 2: .*Input should be a valid number"), + ({"Daily": [("series-D1", "[]"), ("series-D2", "[1.0]")]}, "line 2: .*List should have at least 1 item"), ({"Daily": [("series-D2", "[1.0]"), ("series-D1", "[1.0]")]}, "series id 'series-D2' does not match"), ({"Daily": [("series-M9", "[1.0]"), ("series-D2", "[1.0]")]}, "is not a Daily M4 series id"), ({"Daily": [("series-D1", "[1.0]")]}, "has 1 series rows but 2 caption rows"), @@ -150,14 +151,15 @@ def test_the_frozen_split_holds_the_opentslm_split_of_the_pinned_release(): ids=[ "a value that is not float32", "a null value", - "a NaN value", + "a Boolean value", + "an empty series", "series and captions out of step", "an id of another frequency", "a series row too few", ], ) def test_a_malformed_series_file_raises_with_its_location(tmp_path, series_rows, message): - # The CSV reader rejects a null or NaN value itself, and names the line of the file. + # The CSV reader rejects a cell that does not hold a list of numbers itself, and names the line of the file. with pytest.raises(TimeNetConnectorError, match=rf"(?s)m4_series_Daily\.csv.*{message}"): _convert(tmp_path, series_rows=series_rows) From 368899efde4ee9e54c1d5b1edc9f3c5507aadb2d Mon Sep 17 00:00:00 2001 From: Adrian Blumer Date: Tue, 17 Nov 2026 10:59:50 -0800 Subject: [PATCH 07/20] docs(connectors): call the M4-Caption source the Polybox release The card said "the release" for the zip archive that OpenTSLM publishes on Polybox. It now introduces that archive once and calls it the Polybox release. --- .../datasets/opentslm/m4_caption/dataset.yaml | 20 ++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml index b1b3ace9f..014497402 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml @@ -6,18 +6,20 @@ name: M4-Caption description: >- 100,000 univariate series from the M4 forecasting competition (80,000 train, 10,000 validation, 10,000 test). Each series has one caption in English. GPT-4o wrote each caption from a plot of the - series, with the prompt "Generate a detailed caption for the following time-series data:". The - series are the train part of M4, the history that the competitors received, without the forecast - horizon. There are 4,227 daily, 414 hourly, 48,000 monthly, 24,000 quarterly, 359 weekly and 23,000 - yearly series, with 13 to 9,919 values each. The OpenTSLM paper gives 64 to 512 values, but the - release has the full length. The release holds the M4 values rounded to float32, and the dataset - keeps them in float32 without a change. The release has no timestamps and states no unit. The M4 - series come from the micro, industry, macro, finance, demographic and other domains, so the values - have mixed units. Each record states the M4 id, such as M1, and the M4 frequency. The release has no split + series, with the prompt "Generate a detailed caption for the following time-series data:". + OpenTSLM publishes the series and the captions as one zip archive of CSV files on Polybox, the + Polybox release that this dataset converts. The series are the train part of M4, the history that + the competitors received, without the forecast horizon. There are 4,227 daily, 414 hourly, 48,000 + monthly, 24,000 quarterly, 359 weekly and 23,000 yearly series, with 13 to 9,919 values each. The + OpenTSLM paper gives 64 to 512 values, but the Polybox release has the full length. The Polybox + release holds the M4 values rounded to float32, and the dataset keeps them in float32 without a + change. The Polybox release has no timestamps and states no unit. The M4 series come from the + micro, industry, macro, finance, demographic and other domains, so the values have mixed units. + Each record states the M4 id, such as M1, and the M4 frequency. The Polybox release has no split column, so the dataset gives each series the split of OpenTSLM's loader. That loader merges all frequencies and makes a random 80/10/10 split with the datasets library. - The release archive also holds m4_series.csv, a copy of the weekly series, and m4_captions.csv, + The Polybox release also holds m4_series.csv, a copy of the weekly series, and m4_captions.csv, with 40 other captions of weekly series. OpenTSLM does not use these two files, and the dataset does not keep them. From 5616a3fc4925542defae0e0f9895c360074afe9d Mon Sep 17 00:00:00 2001 From: Adrian Blumer Date: Tue, 17 Nov 2026 12:03:53 -0800 Subject: [PATCH 08/20] refactor(connectors): drop the parse check from generate_splits.py The pinned Polybox release parses fully, so the script does not need to parse each series to mirror the rows that the OpenTSLM loader skips. The split file is unchanged. --- .../datasets/opentslm/m4_caption/generate_splits.py | 3 --- 1 file changed, 3 deletions(-) diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/generate_splits.py b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/generate_splits.py index 633bfc131..40b129b30 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/generate_splits.py +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/generate_splits.py @@ -52,9 +52,6 @@ def load_samples(archive: zipfile.ZipFile) -> list[dict[str, str]]: captions_df = captions_df[captions_df["id"].isin(common_ids)].reset_index(drop=True) merged_df = series_df.merge(captions_df, on="id", how="inner") for _, row in merged_df.iterrows(): - # The loader skips a row whose series does not parse, so parse each one. The split depends - # only on the number and order of the rows, so the samples here hold no values. - json.loads(row["series"]) all_samples.append({"id": row["id"], "frequency": frequency}) return all_samples From 7e3be54591b1a117a12e74a6ac230b5ee63840a0 Mon Sep 17 00:00:00 2001 From: Adrian Blumer Date: Tue, 17 Nov 2026 12:04:49 -0800 Subject: [PATCH 09/20] docs(connectors): shorten the M4-Caption card Introduce the Polybox archive in one sentence, and drop the sentence about float32 values. --- .../datasets/opentslm/m4_caption/dataset.yaml | 21 +++++++++---------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml index 014497402..37d2696fd 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml @@ -7,17 +7,16 @@ description: >- 100,000 univariate series from the M4 forecasting competition (80,000 train, 10,000 validation, 10,000 test). Each series has one caption in English. GPT-4o wrote each caption from a plot of the series, with the prompt "Generate a detailed caption for the following time-series data:". - OpenTSLM publishes the series and the captions as one zip archive of CSV files on Polybox, the - Polybox release that this dataset converts. The series are the train part of M4, the history that - the competitors received, without the forecast horizon. There are 4,227 daily, 414 hourly, 48,000 - monthly, 24,000 quarterly, 359 weekly and 23,000 yearly series, with 13 to 9,919 values each. The - OpenTSLM paper gives 64 to 512 values, but the Polybox release has the full length. The Polybox - release holds the M4 values rounded to float32, and the dataset keeps them in float32 without a - change. The Polybox release has no timestamps and states no unit. The M4 series come from the - micro, industry, macro, finance, demographic and other domains, so the values have mixed units. - Each record states the M4 id, such as M1, and the M4 frequency. The Polybox release has no split - column, so the dataset gives each series the split of OpenTSLM's loader. That loader merges all - frequencies and makes a random 80/10/10 split with the datasets library. + OpenTSLM publishes the series and the captions as one zip archive of CSV files on Polybox. The + series are the train part of M4, the history that the competitors received, without the forecast + horizon. There are 4,227 daily, 414 hourly, 48,000 monthly, 24,000 quarterly, 359 weekly and + 23,000 yearly series, with 13 to 9,919 values each. The OpenTSLM paper gives 64 to 512 values, but + the Polybox release has the full length. The Polybox release has no timestamps and states no unit. + The M4 series come from the micro, industry, macro, finance, demographic and other domains, so + the values have mixed units. Each record states the M4 id, such as M1, and the M4 frequency. The + Polybox release has no split column, so the dataset gives each series the split of OpenTSLM's + loader. That loader merges all frequencies and makes a random 80/10/10 split with the datasets + library. The Polybox release also holds m4_series.csv, a copy of the weekly series, and m4_captions.csv, with 40 other captions of weekly series. OpenTSLM does not use these two files, and the dataset From 5531bb5ea92649b98c51ba01661a8e6a35710a1f Mon Sep 17 00:00:00 2001 From: Adrian Blumer Date: Tue, 17 Nov 2026 12:25:32 -0800 Subject: [PATCH 10/20] docs(connectors): shorten M4-Caption docstrings and card Shorten the M4Frequency docstring, the docstring of generate_splits.py and the M4-Caption card. --- .../datasets/opentslm/m4_caption/connector.py | 5 +---- .../datasets/opentslm/m4_caption/dataset.yaml | 11 +++++------ .../datasets/opentslm/m4_caption/generate_splits.py | 7 +++---- 3 files changed, 9 insertions(+), 14 deletions(-) diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py index 407f94cc9..78a88c893 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py @@ -48,10 +48,7 @@ class M4Frequency(StrEnum): - """An M4 frequency. The members are in the order that OpenTSLM's loader reads them. - - The value is the name in the release file names and in the ``frequency`` annotation. - """ + """An M4 frequency. The members are in the order that OpenTSLM's loader reads them.""" DAILY = "Daily" HOURLY = "Hourly" diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml index 37d2696fd..6c8ed5dfd 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml @@ -12,15 +12,14 @@ description: >- horizon. There are 4,227 daily, 414 hourly, 48,000 monthly, 24,000 quarterly, 359 weekly and 23,000 yearly series, with 13 to 9,919 values each. The OpenTSLM paper gives 64 to 512 values, but the Polybox release has the full length. The Polybox release has no timestamps and states no unit. - The M4 series come from the micro, industry, macro, finance, demographic and other domains, so - the values have mixed units. Each record states the M4 id, such as M1, and the M4 frequency. The - Polybox release has no split column, so the dataset gives each series the split of OpenTSLM's - loader. That loader merges all frequencies and makes a random 80/10/10 split with the datasets - library. + The M4 series come from the micro, industry, macro, finance, demographic and other domains. Each + record states the M4 id, such as M1, and the M4 frequency. The Polybox release has no split + column, so the dataset gives each series the split of OpenTSLM's loader. That loader merges all + frequencies and makes a random 80/10/10 split with the datasets library. The Polybox release also holds m4_series.csv, a copy of the weekly series, and m4_captions.csv, with 40 other captions of weekly series. OpenTSLM does not use these two files, and the dataset - does not keep them. + does not include them. The M4 organizers at the University of Nicosia state no license for the M4 data. OpenTSLM releases the captions under MIT. diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/generate_splits.py b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/generate_splits.py index 40b129b30..572822706 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/generate_splits.py +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/generate_splits.py @@ -11,10 +11,9 @@ The release does not store the split. OpenTSLM's loader makes it at load time with the datasets library and a fixed seed, so the split depends on the versions of datasets and NumPy. Instead of pinning these -libraries in the connector, this script ran the calls of the loader once, with the library versions of -the OpenTSLM uv.lock, and wrote the validation and test series to splits.json.xz. The connector reads -that file. xz keeps the file small, and Python reads it with the lzma module of the standard library. -The script is here for reference, so you can see how the file was made. +libraries in the connector, this script reproduces the behavior of the OpenTSLM release. It ran once, +with the library versions of the OpenTSLM uv.lock, and wrote the validation and test series to splits.json.xz. +The connector reads that file. The script is kept here for reference. Run it once with the release archive, from this directory:: From 12ac217bbea8fb770bc691b1f41791604290c78c Mon Sep 17 00:00:00 2001 From: Adrian Blumer Date: Tue, 17 Nov 2026 12:26:52 -0800 Subject: [PATCH 11/20] refactor(connectors): drop the float32 check of M4-Caption values The pinned Polybox release holds only exact float32 values, so the connector converts each series to float32 without checking every value again. --- .../datasets/opentslm/m4_caption/connector.py | 20 +------------------ .../m4_caption/tests/test_connector.py | 2 -- 2 files changed, 1 insertion(+), 21 deletions(-) diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py index 78a88c893..173e9e99e 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py @@ -111,24 +111,6 @@ class _CaptionRow(DataRow): caption: str -def _as_float32(values: Sequence[float]) -> np.ndarray: - """Convert the values to float32, and check that the conversion keeps every value exactly. - - The release holds M4 values that OpenTSLM rounded to float32, so float32 is lossless for it. - - Returns: - The values as float32. - - Raises: - TimeNetConnectorError: If a value is not exactly a float32 value. - """ - exact = np.array(values, dtype=np.float64) - rounded = exact.astype(np.float32) - if not np.array_equal(rounded.astype(np.float64), exact): - raise TimeNetConnectorError("the series holds a value that is not exactly float32") - return rounded - - @dataclass(frozen=True) class M4CaptionSeries: """One M4 series of the release, with its frequency and caption.""" @@ -278,7 +260,7 @@ def _read_frequency(self, frequency: M4Frequency) -> Iterator[M4CaptionSeries]: yield M4CaptionSeries( m4_id=m4_id, frequency=frequency, - values=_as_float32(series_row.series), + values=np.array(series_row.series, dtype=np.float32), caption=caption_row.caption, ) except TimeNetConnectorError as exc: diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/tests/test_connector.py b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/tests/test_connector.py index fbce2e5a5..98c0fedef 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/tests/test_connector.py +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/tests/test_connector.py @@ -140,7 +140,6 @@ def test_the_frozen_split_is_of_the_pinned_release_and_has_the_paper_counts(): @pytest.mark.parametrize( ("series_rows", "message"), [ - ({"Daily": [("series-D1", json.dumps([0.1, 0.2])), ("series-D2", "[1.0]")]}, "not exactly float32"), ({"Daily": [("series-D1", "[1.0, null]"), ("series-D2", "[1.0]")]}, "line 2: .*Input should be a valid number"), ({"Daily": [("series-D1", "[1.0, true]"), ("series-D2", "[1.0]")]}, "line 2: .*Input should be a valid number"), ({"Daily": [("series-D1", "[]"), ("series-D2", "[1.0]")]}, "line 2: .*List should have at least 1 item"), @@ -149,7 +148,6 @@ def test_the_frozen_split_is_of_the_pinned_release_and_has_the_paper_counts(): ({"Daily": [("series-D1", "[1.0]")]}, "has 1 series rows but 2 caption rows"), ], ids=[ - "a value that is not float32", "a null value", "a Boolean value", "an empty series", From 0a591e42af01a7bbf897ea55def8c23e8eab5ad1 Mon Sep 17 00:00:00 2001 From: Adrian Blumer Date: Tue, 17 Nov 2026 12:49:19 -0800 Subject: [PATCH 12/20] refactor(connectors): give each M4-Caption series its split The release now assigns the split while it reads the series, so each series carries its own split. One method creates the Record and its caption task together, so convert no longer passes the Record and the split back in. --- .../datasets/opentslm/m4_caption/connector.py | 78 ++++++++++--------- 1 file changed, 43 insertions(+), 35 deletions(-) diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py index 173e9e99e..4f4bf03ce 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py @@ -111,36 +111,43 @@ class _CaptionRow(DataRow): caption: str +@dataclass(frozen=True) +class _CaptionedSeries: + """A series of one release file with its caption, before the split is known.""" + + m4_id: str + values: np.ndarray + caption: str + + @dataclass(frozen=True) class M4CaptionSeries: - """One M4 series of the release, with its frequency and caption.""" + """One M4 series of the release, with its frequency, caption and split.""" m4_id: str frequency: M4Frequency values: np.ndarray caption: str + split: Split + + def create_record_and_caption_task(self) -> tuple[Record, AnswerTask]: + """Create the Record of the series and the task that asks for its caption. - def create_record(self) -> Record: - """Create the Record of the series, with its M4 id and frequency. + The Record holds the values, the M4 id and the frequency. The task names the Record as its + input. Add the Record to the dataset before the task. Returns: - The Record, not yet added to a dataset. + The Record and the task, not yet added to a dataset. """ signal = Signal.from_values(self.values, spec=M4_SERIES, name="value", time_axis=OrdinalAxis()) frequency = Annotation(key="frequency", value=self.frequency.value) - return Record( + record = Record( sources=(Source(name="M4", signals=(signal,)),), annotations=(frequency,), metadata={"m4_id": self.m4_id}, ) - - def create_caption_task(self, record: Record, *, split: Split) -> AnswerTask: - """Create the task that asks for the caption of the series. - - Returns: - The task, not yet added to a dataset. - """ - return AnswerTask(inputs=(record,), targets=(self.caption,), split=split) + task = AnswerTask(inputs=(record,), targets=(self.caption,), split=self.split) + return record, task class M4CaptionSplits(BaseModel): @@ -212,28 +219,31 @@ class M4CaptionRelease: directory: Path splits_path: Path - def read_series(self) -> Iterator[M4CaptionSeries]: - """Read every series of the release, in the order of OpenTSLM's loader. + def read_series(self) -> list[M4CaptionSeries]: + """Read every series of the release with its caption and split, in the order of OpenTSLM's loader. The loader reads the files of each frequency, and skips ``m4_series.csv`` and ``m4_captions.csv``. A malformed file raises a :class:`~timenet.errors.TimeNetConnectorError` that names the file and - its row. - - Yields: - Each series with its caption. - """ - for frequency in M4Frequency: - yield from self._read_frequency(frequency) - - def read_splits(self, m4_ids: Sequence[str]) -> list[Split]: - """Read the split of each series from the split file. + its row. The split comes from the split file, which the method checks against every M4 id. Returns: - The split of each series, in the order of ``m4_ids``. + Each series with its caption and split. """ - return M4CaptionSplits.read_from_file(self.splits_path).assign_split_to_each_series(m4_ids) + captioned = [(frequency, series) for frequency in M4Frequency for series in self._read_frequency(frequency)] + m4_ids = [series.m4_id for _, series in captioned] + splits = M4CaptionSplits.read_from_file(self.splits_path).assign_split_to_each_series(m4_ids) + return [ + M4CaptionSeries( + m4_id=series.m4_id, + frequency=frequency, + values=series.values, + caption=series.caption, + split=split, + ) + for (frequency, series), split in zip(captioned, splits, strict=True) + ] - def _read_frequency(self, frequency: M4Frequency) -> Iterator[M4CaptionSeries]: + def _read_frequency(self, frequency: M4Frequency) -> Iterator[_CaptionedSeries]: """Read the series of one frequency, paired with the caption in the same row of its caption file. Yields: @@ -257,9 +267,8 @@ def _read_frequency(self, frequency: M4Frequency) -> Iterator[M4CaptionSeries]: raise TimeNetConnectorError( f"series id {series_row.id!r} does not match caption id {caption_row.id!r}" ) - yield M4CaptionSeries( + yield _CaptionedSeries( m4_id=m4_id, - frequency=frequency, values=np.array(series_row.series, dtype=np.float32), caption=caption_row.caption, ) @@ -294,12 +303,11 @@ def convert(self, raw_refs: list[M4CaptionRelease]) -> TimeFDataset: (release,) = raw_refs # A daily series of the release does not fit in the default cell limit of the csv module. CsvDataReader.set_field_size_limit(MAX_SERIES_CHARS) - all_series = list(release.read_series()) - splits = release.read_splits([series.m4_id for series in all_series]) dataset = TimeFDataset(metadata=self.metadata()) - for series, split in zip(all_series, splits, strict=True): - record = dataset.add_record(record=series.create_record()) - dataset.add_task(task=series.create_caption_task(record, split=split)) + for series in release.read_series(): + record, task = series.create_record_and_caption_task() + dataset.add_record(record=record) + dataset.add_task(task=task) return dataset From c60d82fb72c16954cfd51a6e52e73e3dd55876ff Mon Sep 17 00:00:00 2001 From: Adrian Blumer Date: Tue, 17 Nov 2026 15:16:23 -0800 Subject: [PATCH 13/20] docs(connectors): say why the M4-Caption task has no prompt --- .../datasets/opentslm/m4_caption/connector.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py index 4f4bf03ce..3f8e5d49f 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py @@ -146,6 +146,8 @@ def create_record_and_caption_task(self) -> tuple[Record, AnswerTask]: annotations=(frequency,), metadata={"m4_id": self.m4_id}, ) + # The task has no prompt. By convention, an AnswerTask without a prompt is an unprompted + # caption or description. task = AnswerTask(inputs=(record,), targets=(self.caption,), split=self.split) return record, task From b9f8804b534fa4f8428025710ffd739c3aeaf36e Mon Sep 17 00:00:00 2001 From: Adrian Blumer Date: Tue, 17 Nov 2026 15:37:35 -0800 Subject: [PATCH 14/20] refactor(connectors): lower the M4-Caption cell limit to 200,000 characters --- .../datasets/opentslm/m4_caption/connector.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py index 3f8e5d49f..5f65e30b1 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py @@ -31,7 +31,7 @@ M4_CAPTION_SHA256 = "4acb748d94d7287fe58dbb5c3cf6314ea259010b7720f42506739269dec54edf" RELEASE_FOLDER = "M4TimeSeriesCaptionDataset" """The folder in the archive that holds the CSV files.""" -MAX_SERIES_CHARS = 1_000_000 +MAX_SERIES_CHARS = 200_000 """The largest series cell that the connector reads, in characters. The largest cell of the release holds a daily series of 9,919 values in 169,126 characters.""" SPLITS_PATH = Path(__file__).with_name("splits.json.xz") From 775a3721fae39f830c4a81736c3263c3d2ebcaeb Mon Sep 17 00:00:00 2001 From: Adrian Blumer Date: Tue, 17 Nov 2026 17:00:08 -0800 Subject: [PATCH 15/20] docs(connectors): tag M4-Caption with demographics --- .../timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml index 6c8ed5dfd..35fed3e7c 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml @@ -41,3 +41,4 @@ tags: - forecasting - captioning - generated-supervision + - demographics From 3c2e707e9b466faae27ba01b0b0962d64fe918e0 Mon Sep 17 00:00:00 2001 From: Adrian Blumer Date: Tue, 17 Nov 2026 17:15:15 -0800 Subject: [PATCH 16/20] refactor(connectors): let the CSV reader handle long M4-Caption cells --- .../datasets/opentslm/m4_caption/connector.py | 5 ----- 1 file changed, 5 deletions(-) diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py index 5f65e30b1..3b4a312f6 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py @@ -31,9 +31,6 @@ M4_CAPTION_SHA256 = "4acb748d94d7287fe58dbb5c3cf6314ea259010b7720f42506739269dec54edf" RELEASE_FOLDER = "M4TimeSeriesCaptionDataset" """The folder in the archive that holds the CSV files.""" -MAX_SERIES_CHARS = 200_000 -"""The largest series cell that the connector reads, in characters. The largest cell of the release -holds a daily series of 9,919 values in 169,126 characters.""" SPLITS_PATH = Path(__file__).with_name("splits.json.xz") """The split of OpenTSLM's loader for the release, as generate_splits.py wrote it.""" @@ -303,8 +300,6 @@ def convert(self, raw_refs: list[M4CaptionRelease]) -> TimeFDataset: The populated dataset. """ (release,) = raw_refs - # A daily series of the release does not fit in the default cell limit of the csv module. - CsvDataReader.set_field_size_limit(MAX_SERIES_CHARS) dataset = TimeFDataset(metadata=self.metadata()) for series in release.read_series(): record, task = series.create_record_and_caption_task() From dffd82e1ac746ee79200e994869c867ee7fd51d6 Mon Sep 17 00:00:00 2001 From: Adrian Blumer Date: Wed, 18 Nov 2026 11:30:58 -0800 Subject: [PATCH 17/20] feat(connectors): give M4-Caption tasks the prompt of OpenTSLM's loader Each AnswerTask now has the post-prompt of OpenTSLM's M4QADataset, the same text for every series. The card and the README state it. M4CaptionRelease is now M4CaptionReader, and the reader knows the file names of each frequency, not M4Frequency. read_series is easier to read, and the docstrings say that the release archive stores no split and that OpenTSLM's loader makes it. --- .../datasets/opentslm/m4_caption/README.md | 9 ++-- .../datasets/opentslm/m4_caption/connector.py | 53 +++++++++---------- .../datasets/opentslm/m4_caption/dataset.yaml | 4 +- .../m4_caption/tests/test_connector.py | 12 +++-- 4 files changed, 39 insertions(+), 39 deletions(-) diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/README.md b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/README.md index 458b1ef0b..f591ef1a7 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/README.md +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/README.md @@ -4,13 +4,14 @@ M4-Caption pairs each of the 100,000 series of the M4 forecasting competition wi GPT-4o wrote. OpenTSLM publishes it as a zip archive of CSV files, one series file and one caption file for each M4 frequency. -The connector converts each series into one Record and one `AnswerTask` without a prompt. The -Record holds the series as one float32 Signal on an ordinal axis, the M4 id in its metadata, and -the M4 frequency as an annotation. The task target is the caption. +The connector converts each series into one Record and one `AnswerTask`. The Record holds the +series as one float32 Signal on an ordinal axis, the M4 id in its metadata, and the M4 frequency as +an annotation. The task target is the caption. The task prompt is the prompt of the OpenTSLM loader +(the post-prompt of `M4QADataset`), the same for every series. ## Split -The release has no split column. The OpenTSLM loader splits the series at load time with the +The release archive stores no split. The OpenTSLM loader splits the series at load time with the `train_test_split` function of the datasets library, so the split depends on the versions of datasets and NumPy. `generate_splits.py` ran the calls of the loader once, with the library versions of the OpenTSLM `uv.lock`. It wrote the 10,000 validation and 10,000 test series, by M4 id, to diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py index 3b4a312f6..f8e19ff61 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py @@ -2,8 +2,8 @@ The OpenTSLM release holds the train part of all 100,000 M4 series, one CSV of series and one CSV of captions for each of the six M4 frequencies. Each series becomes one Record and one AnswerTask. The -target is the caption. The release has no split, so the connector reads the split of OpenTSLM's -loader from splits.json.xz, which generate_splits.py wrote. +target is the caption. The release archive stores no split. OpenTSLM's loader makes one when it loads +the data, and the connector reads that split from splits.json.xz, which generate_splits.py wrote. """ from collections import Counter @@ -34,6 +34,9 @@ SPLITS_PATH = Path(__file__).with_name("splits.json.xz") """The split of OpenTSLM's loader for the release, as generate_splits.py wrote it.""" +CAPTION_PROMPT = "Please generate a detailed caption for this time-series, describing it as accurately as possible." +"""The prompt of OpenTSLM's loader, the same for every series: the post-prompt of ``M4QADataset``.""" + # The release states no unit, and the M4 series come from many domains. M4_SERIES = TimeSeriesSpec(spec_type="m4_series", name="M4 series", unit_value=None, dtype="float32") @@ -59,16 +62,6 @@ def id_letter(self) -> str: """The letter that starts the M4 id of each series of this frequency, such as M in M1.""" return _M4_ID_LETTERS[self] - @property - def series_file(self) -> str: - """The name of the release file that holds the series of this frequency.""" - return f"m4_series_{self}.csv" - - @property - def captions_file(self) -> str: - """The name of the release file that holds the captions of this frequency.""" - return f"m4_captions_{self}.csv" - def parse_m4_id(self, series_id: str) -> str: """Get the M4 id from a release id, and check that it belongs to this frequency. @@ -143,17 +136,16 @@ def create_record_and_caption_task(self) -> tuple[Record, AnswerTask]: annotations=(frequency,), metadata={"m4_id": self.m4_id}, ) - # The task has no prompt. By convention, an AnswerTask without a prompt is an unprompted - # caption or description. - task = AnswerTask(inputs=(record,), targets=(self.caption,), split=self.split) + task = AnswerTask(inputs=(record,), prompt=CAPTION_PROMPT, targets=(self.caption,), split=self.split) return record, task class M4CaptionSplits(BaseModel): """The validation and test series of OpenTSLM's split, by M4 id. - The release has no split. generate_splits.py ran the calls of OpenTSLM's loader once and wrote this - split to splits.json.xz. Every series that the file does not name is in the train split. + The release archive stores no split. OpenTSLM's loader makes one when it loads the data. + generate_splits.py ran the calls of the loader once and wrote this split to splits.json.xz. Every + series that the file does not name is in the train split. """ model_config = ConfigDict(extra="forbid", frozen=True) @@ -212,8 +204,8 @@ def assign_split_to_each_series(self, m4_ids: Sequence[str]) -> list[Split]: @dataclass(frozen=True) -class M4CaptionRelease: - """The extracted release and the file that holds the split of its series.""" +class M4CaptionReader: + """Read the series, the captions and the split of the extracted release.""" directory: Path splits_path: Path @@ -228,9 +220,12 @@ def read_series(self) -> list[M4CaptionSeries]: Returns: Each series with its caption and split. """ - captioned = [(frequency, series) for frequency in M4Frequency for series in self._read_frequency(frequency)] + captioned: list[tuple[M4Frequency, _CaptionedSeries]] = [] + for frequency in M4Frequency: + captioned.extend((frequency, series) for series in self._read_frequency(frequency)) m4_ids = [series.m4_id for _, series in captioned] - splits = M4CaptionSplits.read_from_file(self.splits_path).assign_split_to_each_series(m4_ids) + split_file = M4CaptionSplits.read_from_file(self.splits_path) + splits = split_file.assign_split_to_each_series(m4_ids) return [ M4CaptionSeries( m4_id=series.m4_id, @@ -251,8 +246,8 @@ def _read_frequency(self, frequency: M4Frequency) -> Iterator[_CaptionedSeries]: Raises: TimeNetConnectorError: If the files do not pair one to one, or a series row is malformed. """ - series_path = self.directory / frequency.series_file - captions_path = self.directory / frequency.captions_file + series_path = self.directory / f"m4_series_{frequency}.csv" + captions_path = self.directory / f"m4_captions_{frequency}.csv" series_rows = list(CsvDataReader(series_path, _SeriesRow, expected_columns=("id", "series")).iter_rows()) caption_rows = list(CsvDataReader(captions_path, _CaptionRow, expected_columns=("id", "caption")).iter_rows()) if len(series_rows) != len(caption_rows): @@ -275,26 +270,26 @@ def _read_frequency(self, frequency: M4Frequency) -> Iterator[_CaptionedSeries]: raise TimeNetConnectorError(f"{series_path.name} data row {number}: {exc}") from exc -class M4CaptionConnector(BaseConnector[M4CaptionRelease]): +class M4CaptionConnector(BaseConnector[M4CaptionReader]): """Connector for the M4-Caption release of OpenTSLM.""" - async def download_async(self, cache_dir: Path) -> list[M4CaptionRelease]: # ruff: ignore[no-self-use] + async def download_async(self, cache_dir: Path) -> list[M4CaptionReader]: # ruff: ignore[no-self-use] """Download and extract the release archive once. Args: cache_dir: The directory that holds the extracted files. Returns: - The extracted release, with the frozen split of the connector. + A reader of the extracted release and of the split file of the connector. """ root = await ensure_archive(M4_CAPTION_URL, cache_dir, filename="m4_caption.zip", sha256=M4_CAPTION_SHA256) - return [M4CaptionRelease(directory=root / RELEASE_FOLDER, splits_path=SPLITS_PATH)] + return [M4CaptionReader(directory=root / RELEASE_FOLDER, splits_path=SPLITS_PATH)] - def convert(self, raw_refs: list[M4CaptionRelease]) -> TimeFDataset: + def convert(self, raw_refs: list[M4CaptionReader]) -> TimeFDataset: """Create one Record and one AnswerTask for each series. Args: - raw_refs: The release from :meth:`download_async`. + raw_refs: The reader from :meth:`download_async`. Returns: The populated dataset. diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml index 35fed3e7c..672d60bae 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml @@ -13,7 +13,9 @@ description: >- 23,000 yearly series, with 13 to 9,919 values each. The OpenTSLM paper gives 64 to 512 values, but the Polybox release has the full length. The Polybox release has no timestamps and states no unit. The M4 series come from the micro, industry, macro, finance, demographic and other domains. Each - record states the M4 id, such as M1, and the M4 frequency. The Polybox release has no split + record states the M4 id, such as M1, and the M4 frequency. Each task asks for the caption with the + prompt of OpenTSLM's loader: "Please generate a detailed caption for this time-series, describing + it as accurately as possible.". The Polybox release has no split column, so the dataset gives each series the split of OpenTSLM's loader. That loader merges all frequencies and makes a random 80/10/10 split with the datasets library. diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/tests/test_connector.py b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/tests/test_connector.py index 98c0fedef..4fc861884 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/tests/test_connector.py +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/tests/test_connector.py @@ -18,7 +18,7 @@ M4_CAPTION_SHA256, SPLITS_PATH, M4CaptionConnector, - M4CaptionRelease, + M4CaptionReader, M4CaptionSplits, ) @@ -72,7 +72,7 @@ def _write_release( *, series_rows: dict[str, list[tuple[str, str]]] | None = None, splits: dict[str, str | list[str]] = _SPLITS, -) -> M4CaptionRelease: +) -> M4CaptionReader: # Like the archive, the files sit in a folder of their own, beside the files that the loader skips. root = directory / "M4TimeSeriesCaptionDataset" root.mkdir() @@ -86,7 +86,7 @@ def _write_release( _write_csv(root / "m4_captions.csv", ("id", "caption"), [("series-W1", "A caption that OpenTSLM never used.")]) splits_path = directory / "splits.json.xz" splits_path.write_bytes(lzma.compress(json.dumps(splits).encode())) - return M4CaptionRelease(directory=root, splits_path=splits_path) + return M4CaptionReader(directory=root, splits_path=splits_path) def _convert(directory: Path, **changes) -> TimeFDataset: @@ -111,8 +111,10 @@ def test_each_series_becomes_a_record_and_a_caption_task(tmp_path): assert (annotation.key, read_value(annotation.value)) == ("frequency", frequency) assert task.targets is not None assert [read_value(target) for target in task.targets] == [f"Caption of {m4_id}.\n\nA second paragraph."] - # A caption task has no prompt. The training prompt of OpenTSLM is not part of the release. - assert task.prompt is None + # The prompt of OpenTSLM's loader, the same for every series. + assert read_value(task.prompt) == ( + "Please generate a detailed caption for this time-series, describing it as accurately as possible." + ) assert task.split == _expected_split(m4_id) From 4d928c88a9203043890587f16e920698dbc80756 Mon Sep 17 00:00:00 2001 From: Adrian Blumer Date: Thu, 19 Nov 2026 14:21:56 -0800 Subject: [PATCH 18/20] feat(connectors): stratify the M4-Caption split by frequency The split of OpenTSLM's loader is random over all frequencies, so the small frequencies drift: its test split holds 6.5% of the hourly series. generate_splits.py now makes an 80/10/10 split with StratifiedSplitter, stratified by M4 frequency, and writes it to splits.json.xz as before. Validation and test each hold a tenth of every frequency. The dataset no longer has the split of the OpenTSLM paper. The script now runs in the workspace and reads the M4 ids with the new M4CaptionReader.read_m4_ids. Two runs write the same file. --- .../datasets/opentslm/m4_caption/README.md | 15 ++- .../datasets/opentslm/m4_caption/connector.py | 22 ++-- .../datasets/opentslm/m4_caption/dataset.yaml | 6 +- .../opentslm/m4_caption/generate_splits.py | 100 ++++++++---------- .../opentslm/m4_caption/splits.json.xz | Bin 19476 -> 19368 bytes .../m4_caption/tests/test_connector.py | 14 ++- 6 files changed, 83 insertions(+), 74 deletions(-) diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/README.md b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/README.md index f591ef1a7..29194efdf 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/README.md +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/README.md @@ -11,11 +11,16 @@ an annotation. The task target is the caption. The task prompt is the prompt of ## Split -The release archive stores no split. The OpenTSLM loader splits the series at load time with the -`train_test_split` function of the datasets library, so the split depends on the versions of -datasets and NumPy. `generate_splits.py` ran the calls of the loader once, with the library versions -of the OpenTSLM `uv.lock`. It wrote the 10,000 validation and 10,000 test series, by M4 id, to -`splits.json.xz`. The connector reads that file and puts every other series in the train split. +The release archive stores no split. `generate_splits.py` makes an 80/10/10 split with +`StratifiedSplitter`, stratified by M4 frequency. Validation and test each hold a tenth of every +frequency, so the small hourly and weekly frequencies keep their share in each split. The result +depends on the version of scikit-learn, so the script ran once. It wrote the 10,000 validation and +10,000 test series, by M4 id, to `splits.json.xz`. The connector reads that file and puts every +other series in the train split. + +This split is not the split of the OpenTSLM paper. The OpenTSLM loader makes a random split of all +frequencies together, so its share of the small frequencies drifts. For example, its test split +holds 6.5% of the hourly series. The file is JSON compressed with xz, about 19 KB. Python reads it with the `lzma` module of the standard library. To read it yourself, run `xz -dc splits.json.xz`. The file also states the SHA-256 diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py index f8e19ff61..016d0e4a9 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py @@ -2,8 +2,8 @@ The OpenTSLM release holds the train part of all 100,000 M4 series, one CSV of series and one CSV of captions for each of the six M4 frequencies. Each series becomes one Record and one AnswerTask. The -target is the caption. The release archive stores no split. OpenTSLM's loader makes one when it loads -the data, and the connector reads that split from splits.json.xz, which generate_splits.py wrote. +target is the caption. The release archive stores no split. generate_splits.py made an 80/10/10 split, +stratified by frequency, and wrote it to splits.json.xz. The connector reads that file. """ from collections import Counter @@ -32,7 +32,7 @@ RELEASE_FOLDER = "M4TimeSeriesCaptionDataset" """The folder in the archive that holds the CSV files.""" SPLITS_PATH = Path(__file__).with_name("splits.json.xz") -"""The split of OpenTSLM's loader for the release, as generate_splits.py wrote it.""" +"""The stratified split of the release, as generate_splits.py wrote it.""" CAPTION_PROMPT = "Please generate a detailed caption for this time-series, describing it as accurately as possible." """The prompt of OpenTSLM's loader, the same for every series: the post-prompt of ``M4QADataset``.""" @@ -141,11 +141,11 @@ def create_record_and_caption_task(self) -> tuple[Record, AnswerTask]: class M4CaptionSplits(BaseModel): - """The validation and test series of OpenTSLM's split, by M4 id. + """The validation and test series of the split, by M4 id. - The release archive stores no split. OpenTSLM's loader makes one when it loads the data. - generate_splits.py ran the calls of the loader once and wrote this split to splits.json.xz. Every - series that the file does not name is in the train split. + The release archive stores no split. generate_splits.py made an 80/10/10 split, stratified by + frequency, and wrote it to splits.json.xz. Every series that the file does not name is in the train + split. """ model_config = ConfigDict(extra="forbid", frozen=True) @@ -237,6 +237,14 @@ def read_series(self) -> list[M4CaptionSeries]: for (frequency, series), split in zip(captioned, splits, strict=True) ] + def read_m4_ids(self) -> list[str]: + """Read the M4 id of every series, in the order of :meth:`read_series`, without the split. + + Returns: + The M4 ids, such as ``M1``. + """ + return [series.m4_id for frequency in M4Frequency for series in self._read_frequency(frequency)] + def _read_frequency(self, frequency: M4Frequency) -> Iterator[_CaptionedSeries]: """Read the series of one frequency, paired with the caption in the same row of its caption file. diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml index 672d60bae..d8ff27b0d 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml @@ -15,9 +15,9 @@ description: >- The M4 series come from the micro, industry, macro, finance, demographic and other domains. Each record states the M4 id, such as M1, and the M4 frequency. Each task asks for the caption with the prompt of OpenTSLM's loader: "Please generate a detailed caption for this time-series, describing - it as accurately as possible.". The Polybox release has no split - column, so the dataset gives each series the split of OpenTSLM's loader. That loader merges all - frequencies and makes a random 80/10/10 split with the datasets library. + it as accurately as possible.". The Polybox release has no split column, so the dataset gives + each series an 80/10/10 split, stratified by M4 frequency. This split is not the random split of + OpenTSLM's loader. The Polybox release also holds m4_series.csv, a copy of the weekly series, and m4_captions.csv, with 40 other captions of weekly series. OpenTSLM does not use these two files, and the dataset diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/generate_splits.py b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/generate_splits.py index 572822706..09dba3402 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/generate_splits.py +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/generate_splits.py @@ -1,23 +1,15 @@ -# /// script -# requires-python = ">=3.12" -# dependencies = [ -# # The versions that the OpenTSLM uv.lock pins. The split depends on datasets and numpy. -# "datasets==4.4.1", -# "numpy==2.3.5", -# "pandas==2.3.3", -# ] -# /// """Write splits.json.xz, the frozen train, validation and test split of m4-caption. -The release does not store the split. OpenTSLM's loader makes it at load time with the datasets library -and a fixed seed, so the split depends on the versions of datasets and NumPy. Instead of pinning these -libraries in the connector, this script reproduces the behavior of the OpenTSLM release. It ran once, -with the library versions of the OpenTSLM uv.lock, and wrote the validation and test series to splits.json.xz. -The connector reads that file. The script is kept here for reference. +The release archive stores no split. This script makes an 80/10/10 split with StratifiedSplitter, +stratified by M4 frequency, so that validation and test each hold a tenth of every frequency. The +result depends on the version of scikit-learn. So the script ran once and wrote the validation and +test series to splits.json.xz, and the connector reads that file. The script is kept here for +reference. -Run it once with the release archive, from this directory:: +Run it once from the root of the repository. The argument is the path to the release archive, +M4TimeSeriesCaptionDatasetV02.zip:: - uv run generate_splits.py + uv run python -m timenet_connectors.datasets.opentslm.m4_caption.generate_splits """ import hashlib @@ -25,34 +17,29 @@ import lzma from pathlib import Path import sys +import tempfile import zipfile +from timenet.types import Split +from timenet_connectors.datasets.opentslm.m4_caption.connector import ( + M4_CAPTION_SHA256, + RELEASE_FOLDER, + SPLITS_PATH, + M4CaptionReader, +) +from timenet_connectors.splitting import StratifiedSplitter -FREQUENCIES = ["Daily", "Hourly", "Monthly", "Quarterly", "Weekly", "Yearly"] -SPLITS_PATH = Path(__file__).with_name("splits.json.xz") +SEED = 42 -def load_samples(archive: zipfile.ZipFile) -> list[dict[str, str]]: - """Read the samples in the order of load_all_m4_data and create_combined_dataset. + +def frequency_letter(m4_id: str) -> str: + """Return the letter that starts an M4 id, such as M in M1. The letter names the frequency. Returns: - One sample with the release id and the frequency for each series. + The letter. """ - # Discovery imports every module beside the connectors, so the script imports its own dependencies - # only when it runs. - import pandas as pd # ruff: ignore[import-outside-top-level] - - all_samples = [] - for frequency in FREQUENCIES: - series_df = pd.read_csv(archive.open(f"M4TimeSeriesCaptionDataset/m4_series_{frequency}.csv")) - captions_df = pd.read_csv(archive.open(f"M4TimeSeriesCaptionDataset/m4_captions_{frequency}.csv")) - common_ids = set(series_df["id"]) & set(captions_df["id"]) - series_df = series_df[series_df["id"].isin(common_ids)].reset_index(drop=True) - captions_df = captions_df[captions_df["id"].isin(common_ids)].reset_index(drop=True) - merged_df = series_df.merge(captions_df, on="id", how="inner") - for _, row in merged_df.iterrows(): - all_samples.append({"id": row["id"], "frequency": frequency}) - return all_samples + return m4_id[0] def m4_id_order(m4_id: str) -> tuple[str, int]: @@ -65,29 +52,30 @@ def m4_id_order(m4_id: str) -> tuple[str, int]: def main() -> None: - """Split the release archive that the first argument names, and write splits.json.xz.""" - from datasets import Dataset # ruff: ignore[import-outside-top-level] # ty: ignore[unresolved-import] + """Split the release archive that the first argument names, and write splits.json.xz. + Raises: + SystemExit: If the archive is not the pinned release. + """ archive_path = Path(sys.argv[1]) - with zipfile.ZipFile(archive_path) as archive: - all_samples = load_samples(archive) - - # The calls of create_combined_dataset, with their names and settings. - full_dataset = Dataset.from_list(all_samples) - test_frac = 0.1 - val_frac = 0.1 - seed = 42 - train_val, test = full_dataset.train_test_split(test_size=test_frac, seed=seed).values() - val_frac_adj = val_frac / (1.0 - test_frac) - _, val = train_val.train_test_split(test_size=val_frac_adj, seed=seed + 1).values() - - # The file names each series by its M4 id: the release id without its "series-" prefix. - splits = { - "source_sha256": hashlib.sha256(archive_path.read_bytes()).hexdigest(), - "validation": sorted((sample_id.removeprefix("series-") for sample_id in val["id"]), key=m4_id_order), - "test": sorted((sample_id.removeprefix("series-") for sample_id in test["id"]), key=m4_id_order), + source_sha256 = hashlib.sha256(archive_path.read_bytes()).hexdigest() + if source_sha256 != M4_CAPTION_SHA256: + raise SystemExit(f"{archive_path} has the SHA-256 {source_sha256}, not the pinned {M4_CAPTION_SHA256}") + with tempfile.TemporaryDirectory() as directory, zipfile.ZipFile(archive_path) as archive: + archive.extractall(directory) + reader = M4CaptionReader(directory=Path(directory) / RELEASE_FOLDER, splits_path=SPLITS_PATH) + m4_ids = reader.read_m4_ids() + + splitter = StratifiedSplitter[str]( + train_folds=8, validation_folds=1, test_folds=1, stratify_by=frequency_letter, seed=SEED + ) + splits = splitter.split(m4_ids) + content = { + "source_sha256": source_sha256, + "validation": sorted(splits[Split.VALIDATION], key=m4_id_order), + "test": sorted(splits[Split.TEST], key=m4_id_order), } - SPLITS_PATH.write_bytes(lzma.compress((json.dumps(splits, indent=2) + "\n").encode())) + SPLITS_PATH.write_bytes(lzma.compress((json.dumps(content, indent=2) + "\n").encode())) if __name__ == "__main__": diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/splits.json.xz b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/splits.json.xz index 0077df9176b204faefcbde8bdc9ff8ebe041e5f9..59f218bdfd30a4a6530ff3d2ef88d0b037e23811 100644 GIT binary patch literal 19368 zcmV(pK=8l)H+ooF000E$*0e?f03iVu0001VFXf};CbCOtT>w3TfEOGw4ruAWZ=TAj zCSd4?`W3V2_A0G#4&mCC4*!A8>uhiAO9{}@60MtElosPI$Y!pJb5>|SvX$9r z_1KZ*Wo7FbB^NYciia4tYhA~Dy?`eG_%apnqwB5|>k}cqyfqrW3zjtMI%G~ax>*;) zzO!la*ddeaosZ5c^FG&q<_YvaPPwngiixRQeMcs(a1{A2CknMS-C+ntZFdIl9V^mr z8&>1=Ed<}%eO}+3X5cPA3PPYwG$+A9;Y;|E8j=oK2q2bBRT!RbLe>5O3qTLs(ALD) z9`LGM`Y!a>`?M2SQ~wgnfkDVjaa_I{0&`!!rRMcP3-FgLymZ*oDz_smHmg!>LSG)u z7kVt*(YTL7mp=b#A#U$gDocLUKlw=5|_tq0K18f#YCSvdeC)jAr>qTgS)j_wg%j7Izlc084lSAzT_A390yM*Ajb0DUX$k z7XIt})Ac-J=~^jv(#a@Z+!)@eV=WOu^|-&>r?HtpOmbbu1w9FAkn2<$zvEL@RD;v% zQQ=@Us?{P;Z$)?we@b<;AM2p~BS7f;QX(uSP%1Z)+XT;Ehxyv(a16nQn8RMKEQ_1` zM8xBj_q>}TZn)BBuP5u2AvC&SoqIC}zHmQ1+-RLe+Luj{1C{rO*&(j1tsA)TSf`75 zd4ZAZe?jK2=t)F5nG>^K?JMD~Dck$dN2dJDtH#ixk#rEEAVpVlV=BCp=9H+^-;1#i zq=^|Q8-+shhWk~59mgG#H}L?u3l(X0cv{?l>0HDm@tCCYmsLr1>3&Bzio zP^5tM5(zk4&$M{ipJU~J}&LRV|<*jX39BK&_+_UEJ5*w6KpZ<=~QhN@4T zaNDK24oN3-M{29s3L1mr)D4OAhuq{$XHN6P4du)1)_MZkxLBg?IHPF& zO++bIs(Vv3ROjM<>n>BA^u7MUy1eLuOrEtWoB~4AJa1)w-8lhO?}Z{gHR#nY*MU>8 zTBsKnxS43j16z#uiG78keqkr`s8k0SAl}#x%GbEN#Fhp7$dhx|;L!KtEx8|@?bs`{ z>R<(3CE$x^S(fzSpV6(jOwb$4c8Zo#%R`ii|9hW^A*r~(A8nD1MvNxvD98Ze1^&4J z`WNF7thhrd-i1&DE2&RJ2wmiT0Fb|7qcmHi%?=4Z)`Mj>nfV*c_ z{BAR#YiHp9na3}S2aR=FN>X^5E+(*RlFF_qp$vKG$*`^M(TR{IVv_lkD}VGhrA+y` zbG4bHNv!KK1=_>%!~_UoV0!FfHi(D?sb?xV3i34*VFe&rfi{MaBW>jZ|A3upNRC3F z#KIQ^86*De#mdXrvbKYtu69G914pN%>f1?`g-WkB-Ik>+V}gc@JuW9S-K0`+L9&Wj zNs&=ouvV^ zN2QkWa7A@nD*glvUYPft8vLFTwpMlzMNX!)Mrrx%c8ZXfsp?%GCUU_pGFd*U(mB2=&8915d-oKU14W; zC@B0=7;WH|2pucyKN|s0-zb9r)aP1F>AEvKao*<`}C||c1G;;Yd9xXOjhdgcWre z#{cmzUOlmBG}AeZChn#U!>moMPa}2YC(rWgkRea5ul*su9HublhOc-=h?DUjMip(0 zY+I;Pyl@hG>)G#*!4@|p6?lBOwBk-jD)kQ>*{QF^^%z$l#V z0#u1qL^YW@H4+wgyDTY~ZhbFe{>G&g9TK_*H4AM`@s7{rqS)THLQn7=CT!LL=Wz!8 zm1)#eK@cGq_@Sk(AI^Mz6R6ZI;Q=4MacNLHz%mtP*et)lemgl!=SA0BT`i($D`3hs zUYVJ#XF}t=Y4YXnHdsDZ$n|3{+W2TDU7ICR*H?&$?s*u`7Re)b;fIefxE^C@(0U!3 zh;zEDR-KdRtcQmq`JH^{0Zmg!QP*47k)HM!c$T5pdMIcZ%cvEaP$scg^zEOc;T!fb zi725>9cE`^7Onu}AO{aalE#I(OW%@IfjbU&M_rLiz&rOKjh4F4Gy&aCs@0tvLHi%+ z7E#NwB$%>$szJFU)S8O}CED%D2^aH65>HX_U|NHw<+3(rxJIOnA6wg#p$mrY!cTE-}7+mKG&r zXMx_k?GtTLkA`$pf7FArpAud3O$6L6LBRFHhJ>vTYT!t0ff@-gd+<}ZI9de*mY&@6 zgOmvLz9x z&Wu1Sl~{9tmz6(p^K}~#ob-ld6WOzHc`h-B!dujSaZ^dTIn_;Ann7Q({y}FZs?SE4 zrcNZf0+gESl+*26JlsszwTeZwt+-+Lxe8djvW6&4hO(2S_*3by&kMg;TLcbrVB9M|U$4Q>j1;+;C4qpV5=H zE`MPsyo5>05-D3=&>8F>q=+_lrPODS)TMN5kQs&?D#*&6&}jfAVH-G%C01f*{+={U z64X~vb*Xe0J{Nu>E>Ho&q0OI%K0IhUPL$XQU)?9OkBSCKu2iFl`*5O{b41a}HX>=f zMw6gB@FnoJd_AwI+6$Hjv>RGQLRYhNTPTf5s!sI(dUJ8tsv2l>G7Af^WoZJCogwSC z>*k?m8{z8l=&c62v;DL$Zm+pyiLx4KNSENObZ~Z!Tds4R=F~OOt$j62`V4$jhFrr< z*NZG~qecJiZ$xe`_^}@~!coL03(UuW0f?)F>Xqdx_;Y*tYn3KvzkV-41-aa#^(Oe zMYowkM+sH3_I}Sc8A7~oE^RwQ%M25W5J>Kcvkj{0KS#qzIL@JFnAaCttMFplsd-$pUwKlOJW;Y56{x`XKLMoB8v6zP~x%% zv16`Q!f9kjQuO7L4MKw1mdcPRAC?w-bbjvwCU^PGqyoRsnlkW4S_pSab|3n(NT5d8C)g z={p!sD`wf;BJ+KJ zM=pQ@P!|CryWYM$tc`21UTlC240t>|BdQ7KjF~WeoX{5`7ep^#o5yF-Y zDfu^AmBnM{K${p-DdjVDOuIg8lGz43xS_e1gR5K~xX$iMd52LR$#E5Q*01y0xTysB z3>r{86!w!s13c$uA>rYBlx~h9B*-jk5XZX}v5N=0lTW>;3M>{e?(h4kbmU&dW25{N zuwZFLgt&T&l}w3>H@{#KO+Pxn3wKuDpi`E?>@2s_#>&&(P}GV+72fRj;Tn&YJ&;1u ze*Hn&nYj_8^zl6R1;C6xofe8se!dQtsb)OTcEn7Rtwq%fae(ux!G@A&Zza)= zH45CtD#17Qfm`Q0x}>#U3ZI=Bxulkngj{A4H**4zYJE>&ro_IVCsemgikxv!%HaPh zU=iWn)EajH;X%wc0zCu{#k_Y`29@%*={Og-_C^*TqPqnME=p~XOe`+W!b~wq_mt?%l?hfK- zB|V{TycDiv&nySlsUj!;vx5Viw zTHv?j^_%kW0Z6)ok{M5iZEmG1&E3$$_eNkRi`0KsWFa63$kn#!rFl9qr;F3dvi1$M z__z4-{zRmd5Ek>I4G*Is+KXb6|GlE)wYhAD#SSSM%<&1JuC?vZ6{LW-1s2R0Xunx) z0i2z#Ln>$Bj@db$7GwUUt~R^5%`u@$!Ea#)HkqP504S<~;O8;6M+mVv=)jCM+3FF> zpIy1N1CUYpS6&@%oM9bnD#i^8ON}Pt?267haofYbHXyokC<0<&*^)`)lj5h!`2FV$N~V7l zpM`AMnJ1jT^#KvCD9%D!I44(%sv72Rjxj|(#-85rjs|CX(y^K&V=&@S1Uj|_~FDLhn@mt2t?ZeCgfXDF|q|9(H z5bq#_7O}UoAXzgn>owZ})ki0w$;zy{45XuYpQZl!n4~0RGE5Ft8CI^j{+A@6DxT%h*PkiI3l$fZ< zmgoSsV&`PyLd<9EA1NZayq zg}Iyx5Oq7+AQ=YHtdOL)l#gy0g$G*A?Ww*<-T3wq;tl)!E`gLsbSnC~5^ys!3omK6 zn}e>$k)k=uZq=nce@pw_kEg~P=%(pviG|+;FS-rCp0Yz(eB8bA6B(~C=?^PujCk)U zPLmDDn1tjgKCq(o#gim&SsS`H(Q2LQbEyT}HvDg`G-H4gGDT32(`0?4?KdX8_Evjt z6O63yo9sHrz6OXFzrJ2SDXp7nbsnO6b~ct#_817d3=gVHmDc3<4LvCLE#}vt?2K5# z&aeoyt>f$rUoOsE5no^2yOvaF8REjX(90f#faJ?*bKgH+GCX?(Qy9ufC7&(B!>dxu zXv~obERw#Thqg0j=z>rv1!tp9Z1#e%1nMfts%W^)JlQH&(-So8qN7fu0s&?NU?^@C z-+>yWV&*b)C<5!OzoHD=sM%>AB*(*BUXj+FH=E=~OC$bN<)_j*0n zmZ0ykQ07h-;01N9aWzG8jUD-61ia<#CcS@eRCja0fetu82E7O0wv-zm{x)m=mxXKbgywaO$&gXYic>B+ooE z$g5$+z3^dsn)>w$&>L}oL2EAkp4or_GcKlfYP6;SFgJa9*iZ*enp7#Wory^CsvIm; zY$tFBAObPL)L*}W_@KS0pe0H)uV@m}jNdJ3@Ss&)L1DB`stKJo^4j@_H~M0 zlmwE0V{kcNeNCzK>Y!?FK|di3AL5GaRm6^YXUu9aDGfZLuMio=(Ci?O_2=YMsGp5N zfv^TBr(~OiH>j&=Ft|Z5w(8|yl1<;LRe$~BCXr&HVK3F9rIfLhb0Po3E7tN-dZH9N zR>@hn(05h6g&QWef1cTs0F5zoRsB(UECL_-{0%{&BdG8$tZx||hZ&?+J|zM6!fol* zd3v*w|I?NoxT?lmnFCI=a$GjWr~6JL&I}I zlu(%q_`4K}dn(^wYSp#J9ZjT2fW}0gv410u)X99i0OLCV@zeJ1$79+1PE0fo4~JHk zvN8q)%KcBNfG8*rN5i`L0)*Qf!gM|=VUR9i5nss7hBfiE;9q211kZmews5<}rqljy zx^CNuj%sI=<@aVvFxQA#l%VbIYUeiv| zEltSi%WOhHx~W(G$S5a&omPZ>TKYF|e?OP9fY@c@ccT7^XHi@26PrKBTT-df61c2~ zfBP~8cl~$%!8=9C^uVxv{<+c|pMoOJy-8tu&#xV;thEl*`a9x2M3chBPo@mk31=Ct z*X^+yTf>pF>6jzxNs?l$?^}3J*jeH*z9V&)H!L+<>$Ig)BjOIM7G>{R*Phnwbv$$c zCnI^kt|E=979$$rC7AQ#0;lm9m_FlNlJj8;dI;zP`69m1YWCL2V~#3W&rxM1>X&RK|cDho4rpXGfp4U z>rk%(a@*Bo66)T07uu4Ns`oAuw*MlaHJ$XpVne(ha#LXXndr9d4GTFa7hY*~;^{(6 zB$LK+gGs6{(5g`#e&TpTBEdVqChSL0HbGf&D32N74rg_G#WXVaKTNU#`=M|H%0$RT zv-s6fQc_yK6#!>*>J6r*z%Z2V+IuF~1cPD9+_lI{hG8sP#YawZMPpYoa^#md=k$r` z+m||xiE*LoJv8p#WAh0$H}xMFRn>!?h+7v*Tdz%{QJPy5K^rd{p`p+Efvm*c(r&cR zDpG~--Tm%T%S=ZO0X)}|T0 z^5akgsSva|>ys8|q~b*Xo_$zmJR(#0%Zx(8j|GcOmpX6H&iO4E1KT?6L{Klmx0Gqfz_Dt0i)!unuW6qOQOyH#a{? z*H7C`QdZZt{~eosbdiR2 z@jZMD?9*SHbiK}!UN7vx586|wpLwT}38OD4=%%`ARK_UOey;&j9Za>5!7sn<6Qe|o zWFhLHnT47_iM14chBAgl*g~sV@jxZa%7Xy}EtSVXd5)p4P8oK$^OXZ8ZVoXbLNv(_ zYTg+TdfM{#U^fO^?LgLQe9eDiiOuQ543$eBW+}T$u@jYC1y0&qE+HH2TkRo)1C{4B z+2=&4Ai9dR+I3PjzLU_PlL~yj(+wSR*dO<){ZkY;5YW-UX_(8TWGTP(Yai!-lz=it z0`+cakDe=9dYZ%53h}pue8+cQTELIWBZrF3QGH1BJV!Y&{{?oGNNeK0p7&DFD|`urvv?i z(6$5B`g8w`SoRXdv@qX&0cx18o_wT8p!Ksm{d@4Gf+Q7-f|-zCjeT1LZ^rG0<*1Jc ztII1ev``jge}TxddfSMz1dN3uZJbNguU$Dm69@Bod^i<0>k{MlM9jlpx^q6kMiWDeN*=Z z@e~t|crF2LW-uxG#8jdnnwm@Y*MHdjiPOpBF1y!R!uS#Y)Iv9tkq;kGNaeRnn>z8^O!=Pf_>JWiq@SIU} zVx`{lliKILji*@$W%hddWRFw(FU!fkavfE0kk60ErPzRTR}}HR15v3220XeBkU08D zAg%i{UEG6wuoz_>`K>>l!m$6$!CV=@k>5qu9yaOBdt9(*HR`p&ln&bgj#w*J9D>#* zjFS$20gVoU=4$UEV6!;+6f^&u^M_+ebQSd5nc4Yo*7L23;8KStDC0Ara}vL|>;|g? zLwryZ89!#ef)d3Eo@_aoBg0(1JQMlJ&{B`|1q>3^;$J@R(j)U=ogAh${7fXsC?OTAmx$B(oEE6*9Is#_Xrkl!j}vYV`k> zXeymZ13V-c@UB9yT9tF(Xz4_T4x=*vj)QaD`K1i5QiG2WJRkC)%A8LG*?W6tIJn38 zDP|>`jiNg#7qzZX^xR0dQOCUc#guF~YiCM!&%!^X*{R8p`7hW9(G)imU4CWdf|PP+ zwNyQyY+nDT60zgDkPIIpbvdQ4y0h;NVbk`IyflKP52BdkBA$=@;Ow%YCv;xf3fwz< z1^yhypN4$1@SLWykWS6~82~{APmN$sI&2=WVnJwl0x|0B85sZ>klhT^+w_Z2<*I)k z{OwJIM|6X=79{{%7 zbjyQhGnljUp7H$?J&9;6-=`ZA0gDI5(2L%z& z>Oe=^u4U57ds4ImBO%17;{uf-))a(;1uRO!&#Lc|p69fMSU9(j1PS7)$kp+F&Z za~0ixo%%ad?0`ubd`G~0-9gRX%4utQ?gddlf@)8I~3427rQR;Cxw{j!8?x9b4hv{@M7MN-RDRZ)1A#4Qzxjoj49q_C?I zx~K>;L@y9qaa@@S}~O?V{2KzURmN@4JwDF5Ta2GjE}562_-9mq?%uY8bEPJ%uOBM{*1@ zV|x5^4FpCyny%vl+ zZ#TP^Ti7!g@!<{RHnN)E6|K;|O4amre(CM|PMH`->T<$X2K|Si2iQNY@VIX~F3JU5 zT~@yE+h*Oiv_;iy;awSy`%6`7m4i!S>beJY8Tm;&0DU*vv8l2M;&wMk7(a_`?>vI% z2;>xlhvs$cNWZnL5ahSs(vv5$pnX;z5)Ccki=jvJmKHZaM}bwfa1xeJRzXkQ+26_+ zOA(Falq=>Bp#}@GKZjM7*~;i-{ZKK8^A%>+hv-^{WE-%T5`LnM)cx>Tt}^ZTnDHAq zhNspSvc7`BGU9jb6EN0AUET)|H2z1Gslfi z*oKKi^V19lSLun#L*Y$8x#cKQIAk5DtV_1oxQftf{O$ldcDaoCp085BaktOk$))aB4l0Cmx9n6HNm- z)3dq@7lToQ?)=5QA>_D_Q8=SP=RoZbtmEz%jhQb)d|%=!6MXY6VdCn?oJIr^tcY;pznlokF8d!XZlMcay1dYN5wvmBC`FNIW^*vzy4S z-)J1-F+9yF)o8kOoSe`FoA@;*mDV(@70bJ&9Dv8g37TGR4wl4&`=)@{AscWm&j<90 zQ3|AL3(2H7ORk9jjm$(+u_Fa-o}R1C z(UJW?HDj%T42N@C-L{Op+FTh_96~AANiG?jwmG{tG=-WGYWhLPp+XXDCU*pa$qnTo zq&jbUt74VI59Pfh>w>&!`!siRSN;C#w?vS> z8e4lANmnDRVXjQ{O>@lTRJvKLqu-L8{-|=XdVGoDc9Rz+2@KGUa81I&_b-FF?UuyL20D!Bpfqv}?cw;NFfxz~fI^Z0E2*gx;oT z|MRO+_8CA&rE^~J=z-V_-O4cIebX@mRd#nvt~c&*D8xBhH|6VbTPssVTe$IBYKZ`d zp(G@IN9@AW+h)~G?u{sH{=*I?eMocqXCyXie0ILoVS)0ppCkuP0-O?JT!S^p$TQtB z6r{R$GV3|dW8zbkRjHcte0wM>OtP)qGQFI*rk!e!S;yoxaio@LqV!>v80FYSbA`f3 zN1x@9|GpSdIpYWpjCoJ^pSxEwx=dh)G5|MBUfCdmJnr+H)j|DmeDYM=WQ1Ufp7@*{ zBT?)wz3}MVhxx!o71QxfEY0B4*sR#OP)>smQE#6WL#v$4KO4+)5t3BafZ z`}Z$<&zxGKJ6$QSAIBbn5Ku!`dxZH5W=$1_52J!>#MD*i`f`DLLLVYix2- zxTOjbpw%ae!&MefmY>>ejCRiNz15qEePfou<%lNEyjkYB0JK%cd_D(_8F@Y|Hgc!u zIzi!Em63avrG1v^nB-f@J%V_nvPvEoRn}Jx%S97Yv&wpLHoBcPd&@uB#32waRLuV} z?~F9p{H$ArWLMfHrQtApSRFLFrxWJ7tmh7s{|hpA7Rhv>=N_lPoMk{G(n^1MPD=nO zNo&-RUw+{IH`o*3pn3cJo>}c|5&Z>eUA~Nn9AV zI7Vj@4&k^)+}K8d52CSyz1~|LqM8B~$BFZq7cc2yx{ggZ*4m%Zf(KT84NWD~@9`w# zKB*VX%hRg_Tg4CeEjp~!V|$hchJCmZ{$y1UBj+uc{_5}GNRTtidR|(I!hET7FM zocV3%D{ijT2aqH%6AMUuCX*?LUM1Z%e=tikFu2{zw;(qqeGs~=T`j-inHv?F)5dS? zp;AsX&O%&|gbt(XqzCO+(Cn6T`?N;750~Yqp{taq@E1NlD$JO!zya7c1<2~OcOwuGHk$9j z;96~GR)HbZeydPGyLx?K&;*f7F_PR@tv)}^DSI4;iIuZ}_JLO8?_dATy2mE)AViSj z8O)90h0EyM=a)v4`|ogqvTT)Kz?wGFq4bZ5s}pP#FlrPUn3rsPzKS;D67EVd>xt&S zhe*Wg`38i23C6}f&dfR{*$!#h8H0GjoFGc#3D8|~jaAiHVMn29Vn<=42GpZO!9hBx zB}~}r-^tf|YYNAYBjLy~3egIO)Z?q}#@|JXxN&N|!N$B~-K*;d0?+mID5^k_q!$!R z&2}uG3hhe%$qIhAqDB5L;v|w&s=hBLqbYzx=(GptK!FMfi&BBCVg5m6J?iQ~kcns8 zfes^A^V_9YGVA_1KuWjBq<8b?w8PFt*%l;}*#104De*1K047 zO7KDsi`eY_<1qx~iEIcIYvz{FnF<4mdYEJp;Xmd0PwoG7ZySw!HcbgG8o5t(QefC+ zH-*7x0_VsoFZVPB2}K+B?cM7Qeq4%pHAav1DV!@bUL~3Npj}jKB0TsIT1;J+^9%G1 zx(qm_rKCLH6*mXAD+@+!1i(ApQAMyQoFM@#zF1DWY*0wKx}G~3;Wsf z9^QIO^5uqph$7E)TJsT=stu2j6B@)cHfS}t7Slv8d45T~UPQ@%k1nz;KcZb$46xlN zaC69)Jf*U_oXiTmPzSa$FvsH(VsVu|u!}bdq7X9?dp>n#ZX)Tu1b6QWn3boY zwv`!~jIcPL$EMcgM++PnnI?=v3yzz=Eo<`wCx@bNIVgA(gNQiR9QrN(#7`J#`OK|8wE7XOl5&+lZJc~rQ#{BZrwg#a* z184Xoxn$^^s0LA>L)T_TgJ&Hr3iS5W|Dq(OtFz(>KrbuKoMUyQ8TwFL|3Iza&thSv zvjw8@nSgw=d^sCir{p8CEM7~X4W{+Gb$?1|L#qZ5&rwot1qip$FEIVx>a8-#D%Jl$ zNG(IXJ4m`YTUBnJriKNDUp!tVnZQK41k^fnHNxlLqb1S_o|h87+E4-U|68W1(4a+>pc5Fdta@0* z76onLM;2p_%1&G|Pe}IM)E;nwHtTu0h+TN(6C}&X*DCCrqjYRGGxs6(N6C71T47a0 zvOdMhnJF97WhMz7*u97K!ac)(s5=1`EMRL>h1{e<7id{IOhqsKA9uT|5cgf|l)cS} zL*Bv?n-_$*WM2x{rt0vWDNiVnic2GT&|V};HmcNsQ1NCYqsRxD zIM)f(zkail*+tPbe#PH$zUoW!4}R7XG_@2X*2r>}D5fUD0`$4Tp|!WW?tJs5}(4gF?%u=0pc>;U!h6h5h7$rW0I1D6;g znspA5hRXBIQ?aW&&RO{2(~OJA7CURLX44Z+|0A$1Wn((PxEJ8wp~d`4jq%-Y>;Q5WZ0*?*d^n~b4cpT_T*LAFDA8&3(2q7Av*c)53qL3=hz;Z%Na&p*@cL?a-=!dQX$Q_is8C$fT)?-XQNywIrv|!G}VlEgqI_-!TzKUQ&yiDuVP*G9sAp5Y74ybeS6td} z9{#i@B>P~y*MrE_1GULV&l^blLgUof%DSIw10SD=2y+OH^BDsFCQQ0x+7-tOX%m=@ zr0@PyuY|P)~1<1Ch&;#)J-YcdH< z2$FLWj9XBe%+$;`pm}S1Pql3@)Ib{>EtOYwO_KMd%S61?gfcB7 z61k?&g=-hRr7Bdnj2avt<5j?xsPQ}Sx@W@9kemV@vQ)oaq!-gq%ADWAmYQgn*ee~= zzZdpgao1H3JB^(*A({&^x%Q*x8VrO*y8?BrETTuRj1Ibx3Yf&YOSHSNcGbn z#^1lyN^B;2H3Y*QjfSUFiB(i`3dY9J4wR&=fp_gs6mTT&_8q#Hsb9>NF zyM4~I5$@98nN^F^)QEex)1uhDGSiE(?L#@?`p(F?gG5-tEC0`9Dm!tCr~LAtO+cFr zqCRe`oHcxj^mIAx=GusK%>Tm6g7VN+LL>>|s0-aMkpPqU;~nb=jsv13n!Lc)%v@i# zpdMc4U9@n0Q+k1}8@3LAH8=)e>$7zXdYcQ)8z=$J3V?ER)Jj0noEBiVVQ4-T?p5Jz z9#dWI0vWMkmnZUtpukk%5sE~3_jJV9w++4e-OU`R=mXV=?Ltq%@j#aYloa(xRK$-t z$4>v8^9mLw2~Xz1(OFwT;&DX|4eX7}l*rjEX)Er(Slu?^%6uJ8y#U~Vo+u%z@Tck5 z7*7xa?z%_74SuLhe9<90{RLgDvsH=^D7m2{5o%B>7aeQy_uZ_TdQ@c<>uFUVVPIVg zj^@KlUJ{Sk&?h4-A@%EntD=AdOuyB5(Se>^TbPK%UwNt1V=0$8V--L9QWI>388@3D zv6?prX|ObCxikA%c$_(CKW5UGufPfUw0%}K`>JK7K6un6-tN>JO=Q3Z93BP8L1E(1 znrVIgC)A4{5-N_QY3t%WGsPSW0lfL3l@3LCD-ld&<-Z0Hf^YMjitnU@xIAC&_^eOV zV8x^4q4SuNn1H+OcPVASCzT;dyb*8fCKOkL$TCf7TUrK`zq>e?vp~7>LgcB+28!xA zWjYO5k>NDmqRj&5vo>`glmSdmymToXBzgHZvN89K(|JvkZz*s z>qA0AkWQ<($aYL9!XE_Dp+yE$6+QsPN=K9!#v7jPdFgG~VjJwLKbPXd<(&&9>g-dm z@c2>3#QBottn@H@M3B9wysVw}y6AqMvBmK(m9-y5Iwhb>b1@+q{Z$jS3L@3E)wIp0 zM4&F?CJ>VRhY;j3$0VtJP8ppbT`o*Kh6lM69{fVwZ%tDTXMCAD>$PYJV~jqD>nf5k z|7O~@k!VIJYd$eShCGMw&R#dK#qISkE9EfaXEA_Vvi(fxhR4Cz-S6CZQ8%mn1|VZLOS7=-GO03K}Ze`3eVn9lmop;Yr2AZGJd zQ4Q$XGdlIOoF)^6rvt9+3nHcprx}yMuyGsYK^luM{;3%#U|F* zC6%RcpT_>aaP-bm(j73>%`Y1_wU7j@$2nMS&M(gkMsIX+4HyFVMc6dxrfUU(g&)Wl zRys;ZM#4jXT-h6igG9=9d|KGX7b-`t9cpcyP-d|q8mYZUr^87-oEeBEtfuRxuEi^z z&1%vc1FE67ccCp}%i&Yw^{Z9Em>uKZyI(JLCEkeui4elMfF=-?hHUFt9J2M6_sK*; zW5e4461AUe6^w{dD}e-w7E)MyH<7Dw6JMaQ*RDb-w^i<@t{1gB>tiXD>||RtuATR8 z6xqRjj1|jN=x%q2jpFxSPal;1;?|=9f>4ej;-hZJVgm+#XSY)lu*pWF@Toe5;JVrC z@OUty_u8m4@a4jT!o1%5v=TxuEW(u`&irqFQ%?<%tq^TV#KN-4d?V}n$OgDe zH;bTW3WWqYmxjlxmqBTQCC|_^rhr?{umGto5|(&E?-U-t)Pp^4@!H^8EC~iDBlHf4 z3%VOe?=+LWz=EpaD_Utle%6O}bObn_gxqX|4mwUpaHuyV!?%S~>p6+(y$4vsfJ8$c_VH+z|2Q5uliEBot@yAw64Z_;2dP%zztw@uU1bqXM zU-V`sfMPvsiR&w%>+knL?6U6@5YEpGeD1=tBnjmDvqo{ zF$etCC=$%1NS8^(EvMEzqjoh-?APvu#*r zKClDr7K?Tlg6I0&i$^4~R>;+4v3JT1;J^Wy3ug4_wVkWpA-(v|(e+Wv*B?!$kxuwHL5G9Dj7UNhl9MTTjos3GlsPl-q1e4qS#f zBu7J@3@D!`Jb@t$)IIEeA3Lxyo~6aAC@I&md{yrh_<@J47hlI@!^-1So3CNx&%O-h z{#^o!bM+_!ceGXto8z#-sNTfcz{--rWwnDpnT#^a{1zJ8ptsvbvdyPBVwx9&0wFlxRU4YLg#2irKoiz*xfmPLTh!-W1))LYWCIn_|VaA-+zCC@sWFfs~%$=2-7>Jh4osWBnsA~?7SgE^Y3T8dQwY4IK=mSBf8^EoL<-K&kqK=Hea*#x3l0_& zMLB1RE`ypeQP2p*+u^>DGZHJ0E~j%uhNK0eq?7n;g*gp(=)77RiI^M;n?+S3YXAd- zlXTuk-8jXdR4qQIKnsa3FF<&nav*<@Rz!2w%BwRS^&^C?uc&x5KfQ!Eh#f1+un;n7 zL+d?vqmAg7_i*TAiA93*Mv>TtVwJI3N?X&m?wY}2%WF&aG{u!yP`vF zF(hGmh93q&e?v%VmA`;2k2;Dt_+un_ew(;0>KFa5EI}wRUoN}SL9%4+IJ(9S)W^DR z%T8nO1C&fVYY=*}@guR84D-{oYwr46$j&pv@I2g4*Z(JzP=mS=ln|1ICp<-~5u8w$ zKekAWk@Bp!zl;VoKY?8;$7|%t%68KPe!0h82h;$Vw-5%_h$bv=W7vTJ;YYhn>xetP-wfaaWJeLUjgkHve`PW2Bmv| z{JWzkDx&MQIl~i7ea1zeQC3R1@Xyv~a>(gB)hPuj=VQWFh}UsypvIBkH2_pb`_#%K zK>R!u-+vRWb7D*%pPx(7gccm0ER3Xxx>%p3(;#sRuEH+FgnnM@I$?_Ql{OHEAu{3i zNv+)YNMWwxOglae9lC?FMsH<{qq>H#%B77sZ+}l)@Yvtp+4k00?x13R&=eDxArwj# z5McnOZpkURlJ>+`(lyNVeI~d63%`W*sQq7aix8RS`YBxR7F{QS|4e=*k1sH(T+wOE<(#;FK z|I@`_$SB~A!0Lh!5oYs`>dK`rzbkFaq_nkVK*KiFlN5C{tF9`@&$qO=0kVO88x@8B zUOcC>cmov(S&;SE557lYgIV!-MJAJ@=fPc2)TiG%YwPx)p)*Yjv2tlr>-nKn$)}hM z$K9frrUA;a%Q7?X63Ue0V~s6l&w0Oi{-kFl|3$@>Aj>Yuri^{c9>%koX^zJ`4W_ZA zX1(eJSYO``t>r>_ivP0V_!!67YI0C52oxV9&P_*G-SS{_ddDCc9W&(6TCVZvK)-y2 zl$EYtVQ}LQ-`+?}e;lr9cXTcS@*H3M09Y@7B!H{-?D2MvGq=z1-s=8@l?&nG_tG0i z&OR!cpi^HmF8vX@R7L(WhryueHWAK?kYk!n_7-fd1)qj%U1OjOa2#L=?TrQ*XFKRN zhe9whD5f=OI8&TcgoT>qfk&t9l3fxnRb%IQE!srX8FnR-1i7V-dbp4e3asiaI+z7{ zcv!>h7BZAw{A-*rb3CC3P+d`H)UsT()B>oK?Jm^vD%paWvX6?MG4S{4OH%ngW6fyG zdaqQIx15;$xgX-qzGbJC4c&7}L`Q(#ixb|hQ$hGMt{3prkDhd=n<1E~k)-kitg|P= zZcvsh+AFjC)6Na@U80hi#->6Y&Ei4B;m5J^n}92x`Tv<6nH<| zOlm;PqomvwB&rL<>**!(G>Wi0O8FB$lzKndCs&mMf_lT%+iNfN6ptdco0vhuSP(7I z&fo(@h*%TJsG;q=>Zh>T&|d6n*r}X7RYdY*Vts9e{oz0arS(~-pq?(?1Mt^l zKGK}gFQfsUJ)`Pc=9JX|eCBvP@$`*vmO%RD+*}lU)jM8(tSDISVnz7W8mIz&rdh{ zdEU`Gbp7cHd>hJYi~WFJ2PB7IR~^_c-m*m&w7b3rj$0Rx{b;R+ z`&fHvHoo~TN$fVmX8mT#MNorFLe$&EjliRD7z&@6te<*;scjjTlY(P&W1|@X=e&Xr zj+-4NatRg5bQ0nH`n|3Mt@YNZ$K!W#6%L8_wN&PaE-Kdrgzg#9eLE>p*%j(mrWa>) z!6Vm5Y5RgyuQP9AL4_dx9=2ZX;9*J&E zNi&c#V8y3)4uD`lOr0cCydfII&HA}>Fiilf7oS5$Gy&Fxj@X#t+fK!F<{>BZ{HI`X z#$8rMsZn-*eQ=vX#n-O~XU#|wiwdZmCdc;1(Byp>GdHOI&>=$bgXezgV`-o`ikXN% ze8E3TOBiub&d$fftU`9dHp4^c9487_nhO+kf#W4XDKUtLaU^^%vjef`kt88!>J_1LlG!n`ZYF>byg2?t}a zNyx%fb2<-gGi8fzs9XR{n^p@XP<}m~im#PJ4DBeT n9|(W|v4dSzwH<>{00D%T0kh2zSmzZvvBYQl0ssI200dcD9W3hZ literal 19476 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 diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/tests/test_connector.py b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/tests/test_connector.py index 4fc861884..69bd66ebc 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/tests/test_connector.py +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/tests/test_connector.py @@ -1,3 +1,4 @@ +from collections import Counter import csv import json import lzma @@ -132,11 +133,18 @@ def test_a_split_file_that_does_not_fit_the_release_raises(tmp_path, changes, me _convert(tmp_path, splits=_SPLITS | changes) -def test_the_frozen_split_is_of_the_pinned_release_and_has_the_paper_counts(): +_RELEASE_SERIES_COUNTS = {"D": 4227, "H": 414, "M": 48000, "Q": 24000, "W": 359, "Y": 23000} +"""The number of series of each frequency in the release, by the letter that starts their M4 ids.""" + + +def test_the_frozen_split_is_of_the_pinned_release_and_has_a_tenth_of_each_frequency_in_validation_and_test(): splits = M4CaptionSplits.read_from_file(SPLITS_PATH) assert splits.source_sha256 == M4_CAPTION_SHA256 - # The 80/10/10 split of 100,000 series that the OpenTSLM paper reports. - assert (len(splits.validation), len(splits.test)) == (10_000, 10_000) + for m4_ids in (splits.validation, splits.test): + counts = Counter(m4_id[0] for m4_id in m4_ids) + for letter, release_count in _RELEASE_SERIES_COUNTS.items(): + # A tenth of the series of each frequency, rounded down or up. + assert release_count // 10 <= counts[letter] <= -(-release_count // 10) @pytest.mark.parametrize( From dae9fb0775b41327cb284b0a3ed0a0d18cdbc8ac Mon Sep 17 00:00:00 2001 From: Adrian Blumer Date: Thu, 19 Nov 2026 17:06:33 -0800 Subject: [PATCH 19/20] feat(connectors): leave out M4-Caption error captions, keep duplicates in one split For 706 series, the release has an error message of the caption API instead of a caption, such as "Error generating caption: Connection error.". The connector now leaves out these series, so the dataset has 99,294 series. M4 has 90 pairs of series whose histories are equal value for value. The split put 34 pairs across two splits, so a model could train on the exact input of a test series. generate_splits.py now passes a digest of the values as group_by to StratifiedSplitter, so each pair stays in one split. The script reads the series with the new M4CaptionReader.read_captioned_series, so it also leaves out the error captions. Two runs write the same file. --- .../datasets/opentslm/m4_caption/README.md | 15 +++++- .../datasets/opentslm/m4_caption/connector.py | 44 ++++++++++------ .../datasets/opentslm/m4_caption/dataset.yaml | 13 +++-- .../opentslm/m4_caption/generate_splits.py | 49 +++++++++++++----- .../opentslm/m4_caption/splits.json.xz | Bin 19368 -> 19324 bytes .../m4_caption/tests/test_connector.py | 28 +++++++--- 6 files changed, 105 insertions(+), 44 deletions(-) diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/README.md b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/README.md index 29194efdf..438e31c47 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/README.md +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/README.md @@ -4,6 +4,11 @@ M4-Caption pairs each of the 100,000 series of the M4 forecasting competition wi GPT-4o wrote. OpenTSLM publishes it as a zip archive of CSV files, one series file and one caption file for each M4 frequency. +For 706 series, the release has an error message of the caption API instead of a caption. There are +three messages, each after the prefix "Error generating caption: ": "Connection error." (630 +series), "Error code: 404" (75) and "Request timed out." (1). The connector leaves out these 253 +daily, 57 monthly and 396 quarterly series, so the dataset has 99,294 series. + The connector converts each series into one Record and one `AnswerTask`. The Record holds the series as one float32 Signal on an ordinal axis, the M4 id in its metadata, and the M4 frequency as an annotation. The task target is the caption. The task prompt is the prompt of the OpenTSLM loader @@ -14,10 +19,16 @@ an annotation. The task target is the caption. The task prompt is the prompt of The release archive stores no split. `generate_splits.py` makes an 80/10/10 split with `StratifiedSplitter`, stratified by M4 frequency. Validation and test each hold a tenth of every frequency, so the small hourly and weekly frequencies keep their share in each split. The result -depends on the version of scikit-learn, so the script ran once. It wrote the 10,000 validation and -10,000 test series, by M4 id, to `splits.json.xz`. The connector reads that file and puts every +depends on the version of scikit-learn, so the script ran once. It wrote the 9,929 validation and +9,929 test series, by M4 id, to `splits.json.xz`. The connector reads that file and puts every other series in the train split. +M4 has 90 pairs of series whose histories are equal value for value: 19 monthly, 35 quarterly and +36 yearly pairs. The two series of a pair have different M4 ids and different M4 test horizons. All +pairs but one also have different captions. A model that trains on one series of a pair sees the +exact input of the other. So the script groups the series by their values with the `group_by` +option of `StratifiedSplitter`, and each pair stays in one split. + This split is not the split of the OpenTSLM paper. The OpenTSLM loader makes a random split of all frequencies together, so its share of the small frequencies drifts. For example, its test split holds 6.5% of the hourly series. diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py index 016d0e4a9..feeca0e1f 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py @@ -2,7 +2,7 @@ The OpenTSLM release holds the train part of all 100,000 M4 series, one CSV of series and one CSV of captions for each of the six M4 frequencies. Each series becomes one Record and one AnswerTask. The -target is the caption. The release archive stores no split. generate_splits.py made an 80/10/10 split, +target is the caption. The connector leaves out the 706 series whose caption is an error message. The release archive stores no split. generate_splits.py made an 80/10/10 split, stratified by frequency, and wrote it to splits.json.xz. The connector reads that file. """ @@ -37,6 +37,10 @@ CAPTION_PROMPT = "Please generate a detailed caption for this time-series, describing it as accurately as possible." """The prompt of OpenTSLM's loader, the same for every series: the post-prompt of ``M4QADataset``.""" +CAPTION_ERROR_PREFIX = "Error generating caption: " +"""The start of an error message of the caption API, which the release has instead of a caption for +706 series. The dataset leaves out these series.""" + # The release states no unit, and the M4 series come from many domains. M4_SERIES = TimeSeriesSpec(spec_type="m4_series", name="M4 series", unit_value=None, dtype="float32") @@ -102,10 +106,11 @@ class _CaptionRow(DataRow): @dataclass(frozen=True) -class _CaptionedSeries: - """A series of one release file with its caption, before the split is known.""" +class M4CaptionedSeries: + """One M4 series of the release, with its frequency and caption, before the split is known.""" m4_id: str + frequency: M4Frequency values: np.ndarray caption: str @@ -220,36 +225,38 @@ def read_series(self) -> list[M4CaptionSeries]: Returns: Each series with its caption and split. """ - captioned: list[tuple[M4Frequency, _CaptionedSeries]] = [] - for frequency in M4Frequency: - captioned.extend((frequency, series) for series in self._read_frequency(frequency)) - m4_ids = [series.m4_id for _, series in captioned] + captioned = self.read_captioned_series() split_file = M4CaptionSplits.read_from_file(self.splits_path) - splits = split_file.assign_split_to_each_series(m4_ids) + splits = split_file.assign_split_to_each_series([series.m4_id for series in captioned]) return [ M4CaptionSeries( m4_id=series.m4_id, - frequency=frequency, + frequency=series.frequency, values=series.values, caption=series.caption, split=split, ) - for (frequency, series), split in zip(captioned, splits, strict=True) + for series, split in zip(captioned, splits, strict=True) ] - def read_m4_ids(self) -> list[str]: - """Read the M4 id of every series, in the order of :meth:`read_series`, without the split. + def read_captioned_series(self) -> list[M4CaptionedSeries]: + """Read every series of the release with its caption, in the order of :meth:`read_series`. + + The method leaves out each series whose caption is an error message of the caption API. Returns: - The M4 ids, such as ``M1``. + Each series with its caption, without the split. """ - return [series.m4_id for frequency in M4Frequency for series in self._read_frequency(frequency)] + captioned: list[M4CaptionedSeries] = [] + for frequency in M4Frequency: + captioned.extend(self._read_frequency(frequency)) + return captioned - def _read_frequency(self, frequency: M4Frequency) -> Iterator[_CaptionedSeries]: + def _read_frequency(self, frequency: M4Frequency) -> Iterator[M4CaptionedSeries]: """Read the series of one frequency, paired with the caption in the same row of its caption file. Yields: - Each series with its caption. + Each series with its caption, except a series whose caption is an error message. Raises: TimeNetConnectorError: If the files do not pair one to one, or a series row is malformed. @@ -269,8 +276,11 @@ def _read_frequency(self, frequency: M4Frequency) -> Iterator[_CaptionedSeries]: raise TimeNetConnectorError( f"series id {series_row.id!r} does not match caption id {caption_row.id!r}" ) - yield _CaptionedSeries( + if caption_row.caption.startswith(CAPTION_ERROR_PREFIX): + continue + yield M4CaptionedSeries( m4_id=m4_id, + frequency=frequency, values=np.array(series_row.series, dtype=np.float32), caption=caption_row.caption, ) diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml index d8ff27b0d..1f60e0bfb 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/dataset.yaml @@ -4,8 +4,8 @@ dataset_id: opentslm/m4-caption dataset_version: 1.0.0 name: M4-Caption description: >- - 100,000 univariate series from the M4 forecasting competition (80,000 train, 10,000 validation, - 10,000 test). Each series has one caption in English. GPT-4o wrote each caption from a plot of the + 99,294 univariate series from the M4 forecasting competition (79,436 train, 9,929 validation, + 9,929 test). Each series has one caption in English. GPT-4o wrote each caption from a plot of the series, with the prompt "Generate a detailed caption for the following time-series data:". OpenTSLM publishes the series and the captions as one zip archive of CSV files on Polybox. The series are the train part of M4, the history that the competitors received, without the forecast @@ -13,11 +13,14 @@ description: >- 23,000 yearly series, with 13 to 9,919 values each. The OpenTSLM paper gives 64 to 512 values, but the Polybox release has the full length. The Polybox release has no timestamps and states no unit. The M4 series come from the micro, industry, macro, finance, demographic and other domains. Each - record states the M4 id, such as M1, and the M4 frequency. Each task asks for the caption with the + record states the M4 id, such as M1, and the M4 frequency. For 706 series, the Polybox release has + an error message of the caption API instead of a caption, such as "Error generating caption: + Connection error.". The dataset leaves out these 253 daily, 57 monthly and 396 quarterly series. Each task asks for the caption with the prompt of OpenTSLM's loader: "Please generate a detailed caption for this time-series, describing it as accurately as possible.". The Polybox release has no split column, so the dataset gives - each series an 80/10/10 split, stratified by M4 frequency. This split is not the random split of - OpenTSLM's loader. + each series an 80/10/10 split, stratified by M4 frequency. M4 has 90 pairs of series whose + histories are equal value for value, and each pair stays in one split. This split is not the + random split of OpenTSLM's loader. The Polybox release also holds m4_series.csv, a copy of the weekly series, and m4_captions.csv, with 40 other captions of weekly series. OpenTSLM does not use these two files, and the dataset diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/generate_splits.py b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/generate_splits.py index 09dba3402..7f57381b5 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/generate_splits.py +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/generate_splits.py @@ -1,9 +1,14 @@ """Write splits.json.xz, the frozen train, validation and test split of m4-caption. The release archive stores no split. This script makes an 80/10/10 split with StratifiedSplitter, -stratified by M4 frequency, so that validation and test each hold a tenth of every frequency. The -result depends on the version of scikit-learn. So the script ran once and wrote the validation and -test series to splits.json.xz, and the connector reads that file. The script is kept here for +stratified by M4 frequency, so that validation and test each hold a tenth of every frequency. + +M4 has 90 pairs of series whose train parts are equal value for value. Series with the same values +must stay in one split, so the splitter groups the series by their values. The script reads the +series through the connector, so it leaves out the series whose caption is an error message. + +The result depends on the version of scikit-learn. So the script ran once and wrote the validation +and test series to splits.json.xz, and the connector reads that file. The script is kept here for reference. Run it once from the root of the repository. The argument is the path to the release archive, @@ -25,7 +30,9 @@ M4_CAPTION_SHA256, RELEASE_FOLDER, SPLITS_PATH, + M4CaptionedSeries, M4CaptionReader, + M4Frequency, ) from timenet_connectors.splitting import StratifiedSplitter @@ -33,13 +40,22 @@ SEED = 42 -def frequency_letter(m4_id: str) -> str: - """Return the letter that starts an M4 id, such as M in M1. The letter names the frequency. +def frequency(series: M4CaptionedSeries) -> M4Frequency: + """Return the frequency of a series, which the split stratifies by. + + Returns: + The frequency. + """ + return series.frequency + + +def values_digest(series: M4CaptionedSeries) -> str: + """Return the SHA-256 digest of the values of a series. Series with the same values form one group. Returns: - The letter. + The digest. """ - return m4_id[0] + return hashlib.sha256(series.values.tobytes()).hexdigest() def m4_id_order(m4_id: str) -> tuple[str, int]: @@ -64,16 +80,21 @@ def main() -> None: with tempfile.TemporaryDirectory() as directory, zipfile.ZipFile(archive_path) as archive: archive.extractall(directory) reader = M4CaptionReader(directory=Path(directory) / RELEASE_FOLDER, splits_path=SPLITS_PATH) - m4_ids = reader.read_m4_ids() - - splitter = StratifiedSplitter[str]( - train_folds=8, validation_folds=1, test_folds=1, stratify_by=frequency_letter, seed=SEED + captioned = reader.read_captioned_series() + + splitter = StratifiedSplitter[M4CaptionedSeries]( + train_folds=8, + validation_folds=1, + test_folds=1, + stratify_by=frequency, + group_by=values_digest, + seed=SEED, ) - splits = splitter.split(m4_ids) + splits = splitter.split(captioned) content = { "source_sha256": source_sha256, - "validation": sorted(splits[Split.VALIDATION], key=m4_id_order), - "test": sorted(splits[Split.TEST], key=m4_id_order), + "validation": sorted((series.m4_id for series in splits[Split.VALIDATION]), key=m4_id_order), + "test": sorted((series.m4_id for series in splits[Split.TEST]), key=m4_id_order), } SPLITS_PATH.write_bytes(lzma.compress((json.dumps(content, indent=2) + "\n").encode())) diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/splits.json.xz b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/splits.json.xz index 59f218bdfd30a4a6530ff3d2ef88d0b037e23811..b49688eb9d517c7120343b40f1a6346ea8931cc9 100644 GIT binary patch literal 19324 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 literal 19368 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 diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/tests/test_connector.py b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/tests/test_connector.py index 69bd66ebc..3e6c9cf1e 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/tests/test_connector.py +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/tests/test_connector.py @@ -57,6 +57,10 @@ def _values(m4_id: str) -> list[float]: return values.tolist()[: 2 + len(m4_id)] +def _caption(m4_id: str) -> str: + return f"Caption of {m4_id}.\n\nA second paragraph." + + def _write_csv(path: Path, columns: tuple[str, str], rows: list[tuple[str, str]]) -> None: with path.open("w", newline="", encoding="utf-8") as stream: writer = csv.writer(stream) @@ -72,6 +76,7 @@ def _write_release( directory: Path, *, series_rows: dict[str, list[tuple[str, str]]] | None = None, + captions: dict[str, str] | None = None, splits: dict[str, str | list[str]] = _SPLITS, ) -> M4CaptionReader: # Like the archive, the files sit in a folder of their own, beside the files that the loader skips. @@ -79,7 +84,7 @@ def _write_release( root.mkdir() for frequency, m4_ids in _SERIES_IDS.items(): default_rows = [(f"series-{m4_id}", json.dumps(_values(m4_id))) for m4_id in m4_ids] - caption_rows = [(f"series-{m4_id}", f"Caption of {m4_id}.\n\nA second paragraph.") for m4_id in m4_ids] + caption_rows = [(f"series-{m4_id}", (captions or {}).get(m4_id, _caption(m4_id))) for m4_id in m4_ids] _write_csv( root / f"m4_series_{frequency}.csv", ("id", "series"), (series_rows or {}).get(frequency, default_rows) ) @@ -111,7 +116,7 @@ def test_each_series_becomes_a_record_and_a_caption_task(tmp_path): (annotation,) = record.annotations assert (annotation.key, read_value(annotation.value)) == ("frequency", frequency) assert task.targets is not None - assert [read_value(target) for target in task.targets] == [f"Caption of {m4_id}.\n\nA second paragraph."] + assert [read_value(target) for target in task.targets] == [_caption(m4_id)] # The prompt of OpenTSLM's loader, the same for every series. assert read_value(task.prompt) == ( "Please generate a detailed caption for this time-series, describing it as accurately as possible." @@ -119,6 +124,16 @@ def test_each_series_becomes_a_record_and_a_caption_task(tmp_path): assert task.split == _expected_split(m4_id) +def test_a_series_whose_caption_is_an_error_message_is_left_out(tmp_path): + # Two of the three error messages of the caption API that the release has instead of a caption. + captions = { + "D2": "Error generating caption: Connection error.", + "Q1": "Error generating caption: Error code: 404", + } + tasks = _convert(tmp_path, captions=captions).tasks_of(AnswerTask) + assert [task.inputs[0].metadata["m4_id"] for task in tasks] == ["D1", "H1", "M1", "M2", "M3", "Q2", "W1", "Y1"] + + @pytest.mark.parametrize( ("changes", "message"), [ @@ -133,8 +148,9 @@ def test_a_split_file_that_does_not_fit_the_release_raises(tmp_path, changes, me _convert(tmp_path, splits=_SPLITS | changes) -_RELEASE_SERIES_COUNTS = {"D": 4227, "H": 414, "M": 48000, "Q": 24000, "W": 359, "Y": 23000} -"""The number of series of each frequency in the release, by the letter that starts their M4 ids.""" +_DATASET_SERIES_COUNTS = {"D": 3974, "H": 414, "M": 47943, "Q": 23604, "W": 359, "Y": 23000} +"""The number of series of each frequency in the dataset, by the letter that starts their M4 ids. The +dataset leaves out 253 daily, 57 monthly and 396 quarterly series, whose caption is an error message.""" def test_the_frozen_split_is_of_the_pinned_release_and_has_a_tenth_of_each_frequency_in_validation_and_test(): @@ -142,9 +158,9 @@ def test_the_frozen_split_is_of_the_pinned_release_and_has_a_tenth_of_each_frequ assert splits.source_sha256 == M4_CAPTION_SHA256 for m4_ids in (splits.validation, splits.test): counts = Counter(m4_id[0] for m4_id in m4_ids) - for letter, release_count in _RELEASE_SERIES_COUNTS.items(): + for letter, dataset_count in _DATASET_SERIES_COUNTS.items(): # A tenth of the series of each frequency, rounded down or up. - assert release_count // 10 <= counts[letter] <= -(-release_count // 10) + assert dataset_count // 10 <= counts[letter] <= -(-dataset_count // 10) @pytest.mark.parametrize( From 1bdf0cf0fa9f308b655940a443d449476624bea1 Mon Sep 17 00:00:00 2001 From: masquare <11543761+masquare@users.noreply.github.com> Date: Fri, 20 Nov 2026 11:45:21 -0800 Subject: [PATCH 20/20] refactor(connectors): move opentslm/m4_caption to the new connector API Main changed the connector API. A label set carries its name as an annotation, a Hugging Face connector passes its Hub settings as class keywords and reads a mapping from part to path, BaseConnector names the whole download result, and Annotation takes its value by keyword. --- .../datasets/opentslm/m4_caption/connector.py | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py index feeca0e1f..57c1c6656 100644 --- a/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py +++ b/packages/timenet-connectors/src/timenet_connectors/datasets/opentslm/m4_caption/connector.py @@ -135,13 +135,12 @@ def create_record_and_caption_task(self) -> tuple[Record, AnswerTask]: The Record and the task, not yet added to a dataset. """ signal = Signal.from_values(self.values, spec=M4_SERIES, name="value", time_axis=OrdinalAxis()) - frequency = Annotation(key="frequency", value=self.frequency.value) record = Record( - sources=(Source(name="M4", signals=(signal,)),), - annotations=(frequency,), + sources=[Source(name="M4", signals=[signal])], + annotations=[Annotation("frequency", value=self.frequency.value)], metadata={"m4_id": self.m4_id}, ) - task = AnswerTask(inputs=(record,), prompt=CAPTION_PROMPT, targets=(self.caption,), split=self.split) + task = AnswerTask(inputs=[record], prompt=CAPTION_PROMPT, targets=self.caption, split=self.split) return record, task @@ -288,7 +287,7 @@ def _read_frequency(self, frequency: M4Frequency) -> Iterator[M4CaptionedSeries] raise TimeNetConnectorError(f"{series_path.name} data row {number}: {exc}") from exc -class M4CaptionConnector(BaseConnector[M4CaptionReader]): +class M4CaptionConnector(BaseConnector[list[M4CaptionReader]]): """Connector for the M4-Caption release of OpenTSLM.""" async def download_async(self, cache_dir: Path) -> list[M4CaptionReader]: # ruff: ignore[no-self-use] @@ -303,21 +302,21 @@ async def download_async(self, cache_dir: Path) -> list[M4CaptionReader]: # ruf root = await ensure_archive(M4_CAPTION_URL, cache_dir, filename="m4_caption.zip", sha256=M4_CAPTION_SHA256) return [M4CaptionReader(directory=root / RELEASE_FOLDER, splits_path=SPLITS_PATH)] - def convert(self, raw_refs: list[M4CaptionReader]) -> TimeFDataset: + def convert(self, releases: list[M4CaptionReader]) -> TimeFDataset: """Create one Record and one AnswerTask for each series. Args: - raw_refs: The reader from :meth:`download_async`. + releases: The reader from :meth:`download_async`. Returns: The populated dataset. """ - (release,) = raw_refs + (release,) = releases dataset = TimeFDataset(metadata=self.metadata()) for series in release.read_series(): record, task = series.create_record_and_caption_task() - dataset.add_record(record=record) - dataset.add_task(task=task) + dataset.add_record(record) + dataset.add_task(task) return dataset