Skip to content

feat(format)!: annotate label sets like other entities and store them by id - #797

Merged
masquare merged 15 commits into
feature/annotation-owner-walkfrom
feature/label-set-derived-name
Nov 20, 2026
Merged

masquare merged 15 commits into
feature/annotation-owner-walkfrom
feature/label-set-derived-name

Conversation

@masquare

@masquare masquare commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

A label set is now annotated like the other entities, and the control tables reference it by an integer id. LabelSet.name is gone. This builds on the owner walk in the PR below.

What changes

  • LabelSet is a dataclass with labels, multi_label, ordered and annotations, plus annotate(). That is the same contract as a Record, Source, Signal, Task and the dataset.
  • LabelSet(["a", "b"]) takes plain strings as labels without a description. Use Label(name=..., description=...) where a label needs a description.
  • ClassificationTask.walk_annotations() also yields the annotations of its label set, so the schema lists label set keys like any other keys.
  • Two label sets with the same labels (in any order, with the same descriptions) and the same multi_label and ordered are one set, and == says so. Annotations are not part of that identity, so equal sets with different name annotations merge into one stored set that keeps both annotations. A LabelSet is not hashable.
  • LabelSet(labels, ordered=True) makes the label order part of the identity: the same labels in another order are a different set, and the stored set keeps its own order. Use it for ordinal labels or for options that a model sees in a fixed order. Sets are unordered by default. An ordered set rejects a Python set as its labels, because the order of a Python set is not fixed. label_sets gets an ordered column.
  • The dataset no longer keeps a label set registry.
  • The writer stores each set once and keeps the label order of the first set. It keeps every distinct annotation occurrence of the equal sets, and it does not change the caller's sets.
  • On disk:
    • label_sets is keyed by label_set_id, and tasks.label_set_id refers to it.
    • Label set annotations are annotation_occurrences rows of the new LabelSet owner kind.
    • The reader shares one set object for each id in a read, and it reads only the label sets that the tasks of the read name.
  • A task copied by composition or edit gets its own copy of its label set.
  • The connectors that named their label sets attach the name as a name annotation: har_cot, sleep_cot, sleep_edfx, test_mean, hello_world and TSAQA. ARFBench stops deriving a name from its options and builds its option sets with ordered=True.
  • The control schema version goes from 2 to 3.

Breaking changes

  • LabelSet(name=...) is gone. Move the name into annotations, for example Annotation("name", value="sleep_stage"), and read it from label_set.annotations.
  • Releases with classification tasks that were written before this change must be built again. A reader from before this change rejects a new release with a version error, and this reader rejects an old one.
  • Code that reads label_set.name must read the name annotation instead.

Where the logic is

  • types/label_sets.py: the new LabelSet.
  • types/tasks.py: the label set as an owner, and the copy.
  • format/control_writer.py: _LabelSetRows, the dedup and the ids.
  • format/control_reader.py, format/control_schema.py: reading and the new owner kind.

The rest is tests, docs and the connector updates. The connectors change in the same commit, because the type check fails otherwise.

Checks

  • make check and make test-connectors pass.
  • The core suite passes per directory.
  • The registry and torch tests pass outside the sandbox.
  • A real build of the TimeSeriesExam connector (top of the stack) stores 148 label sets by id, and verify() passes.

@masquare
masquare added this pull request to stack #800 November 18, 2026 01:36
@masquare masquare added the area:core Changes packages/timenet label Nov 18, 2026
@masquare
masquare requested a review from karhu November 18, 2026 01:50
@masquare
masquare marked this pull request as ready for review November 18, 2026 01:50
@masquare
masquare marked this pull request as ready for review November 18, 2026 01:50
@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

✅ CI checks passed

Check Status
Quick checks ✅ Passed
Tests (Python 3.13) ✅ Passed
Tests (Python 3.11) ✅ Passed

Updated for fc7cf3d · run #8643

@masquare
masquare removed this pull request from stack #800 November 18, 2026 02:18
@masquare
masquare added this pull request to stack #803 November 18, 2026 02:18
@masquare
masquare removed this pull request from stack #803 November 18, 2026 02:20
@masquare
masquare added this pull request to stack #804 November 18, 2026 02:20
Comment thread docs/timef-format.md Resolved
@masquare
masquare force-pushed the feature/label-set-derived-name branch from c6bf947 to 75ee6d6 Compare November 18, 2026 20:52
@masquare masquare added breaking:format Older TimeNet versions cannot read the files that this change writes breaking:api Breaks callers of the Python API or the CLI area:connectors Changes packages/timenet-connectors labels Nov 18, 2026
@masquare masquare changed the title feat(types): name a label set from its content when no name is given feat(format)!: let a label set carry annotations and store label sets by id Nov 18, 2026
@masquare masquare changed the title feat(format)!: let a label set carry annotations and store label sets by id feat(format)!: annotate label sets like other entities and store them by id Nov 18, 2026
@masquare
masquare force-pushed the feature/label-set-derived-name branch from 75ee6d6 to ff9058a Compare November 18, 2026 22:03
@masquare
masquare removed this pull request from stack #804 November 18, 2026 23:46
@masquare
masquare force-pushed the feature/label-set-derived-name branch from ff9058a to f48f7da Compare November 18, 2026 23:46
@masquare
masquare changed the base branch from main to feature/annotation-owner-walk November 18, 2026 23:46
@masquare
masquare added this pull request to stack #813 November 18, 2026 23:46
@masquare
masquare force-pushed the feature/label-set-derived-name branch 3 times, most recently from 24f7c00 to 4647149 Compare November 19, 2026 02:21
@masquare
masquare removed this pull request from stack #813 November 19, 2026 05:19
@masquare
masquare force-pushed the feature/label-set-derived-name branch from 4647149 to 4e50d54 Compare November 19, 2026 05:19
@masquare
masquare added this pull request to stack #816 November 19, 2026 05:19
@masquare
masquare requested a review from karhu November 19, 2026 06:17
@masquare
masquare force-pushed the feature/label-set-derived-name branch from 24f5461 to 4607c5d Compare November 19, 2026 17:48
… by id

Remove LabelSet.name. A LabelSet is now an annotated object like a
Record, Source, Signal, Task or the dataset: it has annotations and
annotate(), and annotation(key) works on it. A ClassificationTask yields
its label set in annotation_owners(), so the schema lists label set keys
like any other keys. LabelSet(["a", "b"]) takes plain strings as labels
without a description.

Two label sets with the same labels (in any order, with the same
descriptions) and the same multi_label are one set, and == says so. The
dataset no longer keeps a label set registry. The writer stores each such
set once, keeps the label order of the first set, keeps every distinct
annotation occurrence of the equal sets, and does not change the caller's
sets. label_sets is keyed by an integer label_set_id, tasks.label_set_id
refers to it, and label set annotations are annotation_occurrences rows of
a new LabelSet owner kind. The reader shares one set object for each id in
a read. A copied task gets its own copy of its label set.

The connectors that named their label sets attach the name as a name
annotation: har_cot, sleep_cot, sleep_edfx, test_mean, hello_world and
TSAQA. ARFBench stops deriving a name from its options.

The control schema version stays 2.

BREAKING CHANGE: LabelSet takes no name, so move it into annotations.
Releases with classification tasks that were written before this change
must be built again.
Follow the rename in the base change: a ClassificationTask yields its
label set from annotatable_entities(), and the load plan reads it there.
The tests and the annotations docs read a label set's name annotation
from its annotations, since annotation(key) is gone.
…_annotations

A ClassificationTask yields its own annotations, then those of its label
set, from walk_annotations(). The load plan reads a task's annotations
through walk_annotations(), so it needs no separate label set handler,
and annotatable_entities() is gone.
LabelSet(labels, ordered=True) makes the label order part of the identity
of the set: the same labels in another order are a different set, and
the stored set keeps its own order. By default a set is unordered, as
before. label_sets gets an ordered column.

ARFBench builds its option sets with ordered=True, because a model sees
the options in their order.
Pass labels positionally and use plain strings where a label has no
description. Labels with a description stay Label objects.
A task read loaded every stored label set and all their annotations,
once for each read. It now loads the sets that its tasks name. The
audit keeps the check for an annotation of a missing label set.

The docs explain ordered label sets once.
…y the label set code

- LabelSet(..., ordered=True) rejects a set or frozenset, because its
  order is not fixed.
- assert_datasets_equal also compares label set annotations.
- The format doc says which owners a full read checks.
- Smaller cleanups in the label set field, a docstring and two tests.
Two label sets with the same labels and different annotations are two
sets, and the writer stores each one with its own annotations. Sets with
the same labels and the same annotations, in any order, are still stored
once. The writer no longer merges the annotations of equal sets.
…lify the key

The writer keeps the id of each label set object for the write, so a set
that many tasks share is checked and keyed once. The row and the id are
stored together. The key uses the frozen Label objects directly.
A label set rejects a Python set also when it is not ordered, because the
writer keeps the order of the first equal set and a Python set has no
fixed order.
@masquare
masquare force-pushed the feature/label-set-derived-name branch from 4607c5d to 86e5933 Compare November 20, 2026 07:25
@masquare
masquare removed this pull request from stack #826 November 20, 2026 07:25
@masquare
masquare added this pull request to stack #829 November 20, 2026 07:25
@masquare
masquare requested a review from karhu November 20, 2026 07:32
Version 3 stores label sets by id, with their annotations. A reader of
version 2 misreads it, and this reader misreads version 2, so both the
written and the oldest readable version are 3.
@masquare
masquare merged commit 24bca21 into main Nov 20, 2026
4 checks passed
@masquare
masquare deleted the feature/label-set-derived-name branch November 20, 2026 18:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:connectors Changes packages/timenet-connectors area:core Changes packages/timenet breaking:api Breaks callers of the Python API or the CLI breaking:format Older TimeNet versions cannot read the files that this change writes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants