Skip to content

Types

timenet.types source

TimeF value types and type system: versions, units, enums, specs, annotations, tasks, metadata.

ANNOTATION_BASES module-attribute source

ANNOTATION_BASES: dict[AnnotationType, type[Annotation]] = {
    AnnotationType.STATIC: StaticAnnotation,
    AnnotationType.POINT: PointAnnotation,
    AnnotationType.INTERVAL: IntervalAnnotation,
}

TASKS module-attribute source

TASKS: dict[TaskType, type[Task]] = {
    (cls.task_type): cls
    for cls in (_concrete_task_classes())
}

ureg module-attribute source

ureg = pint.UnitRegistry()

Annotation dataclass source

Base for all annotations. Not instantiated directly; use one of the three shapes below.

description class-attribute instance-attribute source

description: str | None = None

Optional human-readable description of the annotation.

id class-attribute instance-attribute source

id: str = field(default_factory=new_id)

Unique identifier, a UUIDv7 string by default.

key instance-attribute source

key: str

Name identifying the annotation.

unit class-attribute instance-attribute source

unit: str | Unit | None = None

Optional physical unit of value — a unit string (e.g. "years") or a :class:pint.Unit. Validated against the shared registry on construction; an unrecognized string raises ValueError, and a pint.Unit is stored as its canonical name.

value class-attribute instance-attribute source

value: Any = None

The annotation's payload value.

AnnotationDescriptor dataclass source

Type-level projection of an annotation key, stored in the schema and manifest.

annotation_type instance-attribute source

annotation_type: AnnotationType

Which of the three annotation shapes this key uses.

description class-attribute instance-attribute source

description: str | None = None

Optional human-readable description of the annotation.

key instance-attribute source

key: str

Name of the annotation this descriptor projects.

unit class-attribute instance-attribute source

unit: str | None = None

Optional physical unit of the value.

value_type class-attribute instance-attribute source

value_type: str | None = None

Manifest value-type tag (bool, int, float, str, or list).

AnnotationType source

Bases: StrEnum

The three annotation shapes; the discriminator stored on disk and in the manifest.

INTERVAL class-attribute instance-attribute source

INTERVAL = 'interval'

POINT class-attribute instance-attribute source

POINT = 'point'

STATIC class-attribute instance-attribute source

STATIC = 'static'

CaptioningTask dataclass source

Bases: TargetTask

Free-form text describing the sample (the target is the caption).

from_task_ids property source

from_task_ids: tuple[str, ...]

Return the ids of the tasks this one was derived from.

Returns:

Type Description
tuple[str, ...]

The id of every task in from_tasks.

from_tasks class-attribute instance-attribute source

from_tasks: tuple[Task, ...] = ()

Source tasks this one was derived from.

id class-attribute instance-attribute source

id: str = field(default_factory=new_id)

Unique task identifier, a UUIDv7 string by default.

sample_ids class-attribute instance-attribute source

sample_ids: tuple[str, ...] = ()

Ids of the samples this task targets, populated by add_task.

target instance-attribute source

target: str

The supervised target: the class label, region label, answer, or caption for the sample.

task_type class-attribute source

task_type: TaskType = TaskType.CAPTIONING

ClassificationTask dataclass source

Bases: TargetTask

One discrete label applied to the whole sample (the target).

from_task_ids property source

from_task_ids: tuple[str, ...]

Return the ids of the tasks this one was derived from.

Returns:

Type Description
tuple[str, ...]

The id of every task in from_tasks.

from_tasks class-attribute instance-attribute source

from_tasks: tuple[Task, ...] = ()

Source tasks this one was derived from.

id class-attribute instance-attribute source

id: str = field(default_factory=new_id)

Unique task identifier, a UUIDv7 string by default.

sample_ids class-attribute instance-attribute source

sample_ids: tuple[str, ...] = ()

Ids of the samples this task targets, populated by add_task.

target instance-attribute source

target: str

The supervised target: the class label, region label, answer, or caption for the sample.

target_schema class-attribute instance-attribute source

target_schema: str | None = None

Name of the label vocabulary the target belongs to.

task_type class-attribute source

task_type: TaskType = TaskType.CLASSIFICATION

DataSource dataclass source

The origin that produced a modality: a device, an API feed, a model, an institution.

data_source_type instance-attribute source

data_source_type: str

Type tag identifying the kind of source; keys the spec-to-source link in the manifest.

name instance-attribute source

name: str

Human-readable display name of the source.

provider class-attribute instance-attribute source

provider: str | None = None

Organization or platform behind the source, if any.

DatasetMetadata dataclass source

A dataset's descriptive identity: who it is, not what it emits.

Authored in the dataset card. dataset_version is the upstream source's semantic version; yaml_schema_version is the card's own field-schema version. dataset_id is an org/name pair (HuggingFace style, exactly one slash); ids are case-sensitive, so avoid casing-only differences on case-insensitive filesystems.

dataset_id instance-attribute source

dataset_id: str

HuggingFace-style org/name pair; case-sensitive, exactly one slash.

dataset_version instance-attribute source

dataset_version: Version

Semantic version of the upstream source data.

description instance-attribute source

description: str

Free-text description of the dataset.

domains class-attribute instance-attribute source

domains: tuple[Domain, ...] = ()

Kinds of data the dataset contains.

license instance-attribute source

license: License

Legal license of the source data, as an SPDX-style identifier.

name instance-attribute source

name: str

Human-readable display name.

source_url class-attribute instance-attribute source

source_url: str | None = None

Link to the dataset's origin, if any.

tags class-attribute instance-attribute source

tags: tuple[str, ...] = ()

Free-form tags for search and grouping.

yaml_schema_version class-attribute instance-attribute source

yaml_schema_version: int = 1

Version of the card's own field schema.

from_dict classmethod source

from_dict(data: dict[str, Any]) -> DatasetMetadata

Build metadata from a plain mapping of card fields.

Enum and version fields arrive as strings (license, domains, dataset_version) and are coerced here; unmodeled keys are ignored. Shared by :meth:from_yaml and the manifest codec so the mapping lives in one place. Coercion may raise KeyError (missing field) or ValueError (bad license/domain/version/id); callers wrap these in their own error type.

Parameters:

Name Type Description Default
data dict[str, Any]

A mapping with the card fields (strings for the enums and the version).

 required

Returns:

Type Description
DatasetMetadata

The constructed :class:DatasetMetadata.

from_yaml classmethod source

from_yaml(path: str | Path) -> DatasetMetadata

Load and validate a dataset card YAML into metadata.

The card is validated against the packaged dataset-card.schema.json (so authoring mistakes surface with clear, aggregated messages) before construction. PyYAML and jsonschema are optional and imported lazily; install the timenet[curation] extra to use this.

Parameters:

Name Type Description Default
path str | Path

Path to the card YAML file.

 required

Returns:

Type Description
DatasetMetadata

The constructed :class:DatasetMetadata.

Raises:

Type Description
InvalidCardError

If the curation extra is missing, or the card is unreadable, is not a mapping, fails schema validation, or has an invalid field value.

DatasetSchema dataclass source

A dataset's type declaration, derived from its data (never hand-authored).

Holds flat descriptor instances for specs / data sources / annotations, and the real built-in :class:~timenet.types.tasks.Task subclasses (resolved against the registry, not reconstructed).

annotations class-attribute instance-attribute source

annotations: tuple[AnnotationDescriptor, ...] = ()

Type-level descriptors for the dataset's annotation keys.

data_sources class-attribute instance-attribute source

data_sources: tuple[DataSource, ...] = ()

Origins that produced the modalities, keyed by data_source_type.

tasks class-attribute instance-attribute source

tasks: tuple[type[Task], ...] = field(default=())

Built-in Task subclasses the dataset declares, resolved from the registry.

time_series_specs class-attribute instance-attribute source

time_series_specs: tuple[TimeSeriesSpec, ...] = ()

Descriptors for the dataset's measurement modalities.

Domain source

Bases: StrEnum

Describes what kind of data a dataset contains. A dataset may declare more than one.

ACTIVITY class-attribute instance-attribute source

ACTIVITY = 'activity'

CARDIOLOGY class-attribute instance-attribute source

CARDIOLOGY = 'cardiology'

ECONOMICS class-attribute instance-attribute source

ECONOMICS = 'economics'

FINANCE class-attribute instance-attribute source

FINANCE = 'finance'

GENERAL class-attribute instance-attribute source

GENERAL = 'general'

HEALTH class-attribute instance-attribute source

HEALTH = 'health'

SLEEP class-attribute instance-attribute source

SLEEP = 'sleep'

ForecastingTask dataclass source

Bases: Task

Predict future values of a series, conditioned on context samples (no scalar target).

context_sample_ids instance-attribute source

context_sample_ids: tuple[str, ...]

Ids of the samples that provide forecasting context.

from_task_ids property source

from_task_ids: tuple[str, ...]

Return the ids of the tasks this one was derived from.

Returns:

Type Description
tuple[str, ...]

The id of every task in from_tasks.

from_tasks class-attribute instance-attribute source

from_tasks: tuple[Task, ...] = ()

Source tasks this one was derived from.

id class-attribute instance-attribute source

id: str = field(default_factory=new_id)

Unique task identifier, a UUIDv7 string by default.

sample_ids class-attribute instance-attribute source

sample_ids: tuple[str, ...] = ()

Ids of the samples this task targets, populated by add_task.

target_sample_id instance-attribute source

target_sample_id: str

Id of the sample whose future values are predicted.

task_type class-attribute source

task_type: TaskType = TaskType.FORECASTING

IntervalAnnotation dataclass source

Bases: Annotation

Anchored to a bounded interval in the original recording timeline.

description class-attribute instance-attribute source

description: str | None = None

Optional human-readable description of the annotation.

end_time_s instance-attribute source

end_time_s: float

Interval end in seconds; must exceed start_time_s.

id class-attribute instance-attribute source

id: str = field(default_factory=new_id)

Unique identifier, a UUIDv7 string by default.

key instance-attribute source

key: str

Name identifying the annotation.

start_time_s instance-attribute source

start_time_s: float

Interval start on the recording timeline, in seconds.

time_series_ids class-attribute instance-attribute source

time_series_ids: tuple[str, ...] | None = None

Series this annotation targets; None covers the whole sample.

unit class-attribute instance-attribute source

unit: str | Unit | None = None

Optional physical unit of value — a unit string (e.g. "years") or a :class:pint.Unit. Validated against the shared registry on construction; an unrecognized string raises ValueError, and a pint.Unit is stored as its canonical name.

value class-attribute instance-attribute source

value: Any = None

The annotation's payload value.

LabelingTask dataclass source

Bases: TargetTask

Time-localized labels within a sample, optionally targeting specific series and windows.

from_task_ids property source

from_task_ids: tuple[str, ...]

Return the ids of the tasks this one was derived from.

Returns:

Type Description
tuple[str, ...]

The id of every task in from_tasks.

from_tasks class-attribute instance-attribute source

from_tasks: tuple[Task, ...] = ()

Source tasks this one was derived from.

id class-attribute instance-attribute source

id: str = field(default_factory=new_id)

Unique task identifier, a UUIDv7 string by default.

sample_ids class-attribute instance-attribute source

sample_ids: tuple[str, ...] = ()

Ids of the samples this task targets, populated by add_task.

target instance-attribute source

target: str

The supervised target: the class label, region label, answer, or caption for the sample.

target_schema class-attribute instance-attribute source

target_schema: str | None = None

Name of the label vocabulary the target belongs to.

task_type class-attribute source

task_type: TaskType = TaskType.LABELING

time_series_ids class-attribute instance-attribute source

time_series_ids: tuple[str, ...] | None = None

Series the label targets, or None for all series in the sample.

windows_s class-attribute instance-attribute source

windows_s: tuple[tuple[float, float], ...] | None = None

Labeled windows as (start, end) times in seconds, or None for the whole sample.

License source

Bases: StrEnum

The legal license of the source data. Values are SPDX-style identifiers.

APACHE_2_0 class-attribute instance-attribute source

APACHE_2_0 = 'Apache-2.0'

BSD_2_CLAUSE class-attribute instance-attribute source

BSD_2_CLAUSE = 'BSD-2-Clause'

BSD_3_CLAUSE class-attribute instance-attribute source

BSD_3_CLAUSE = 'BSD-3-Clause'

CC0_1_0 class-attribute instance-attribute source

CC0_1_0 = 'CC0-1.0'

CC_BY_4_0 class-attribute instance-attribute source

CC_BY_4_0 = 'CC-BY-4.0'

CC_BY_NC_4_0 class-attribute instance-attribute source

CC_BY_NC_4_0 = 'CC-BY-NC-4.0'

CC_BY_SA_4_0 class-attribute instance-attribute source

CC_BY_SA_4_0 = 'CC-BY-SA-4.0'

GPL_3_0 class-attribute instance-attribute source

GPL_3_0 = 'GPL-3.0'

LGPL_3_0 class-attribute instance-attribute source

LGPL_3_0 = 'LGPL-3.0'

MIT class-attribute instance-attribute source

MIT = 'MIT'

MPL_2_0 class-attribute instance-attribute source

MPL_2_0 = 'MPL-2.0'

ODBL_1_0 class-attribute instance-attribute source

ODBL_1_0 = 'ODbL-1.0'

ODC_BY_1_0 class-attribute instance-attribute source

ODC_BY_1_0 = 'ODC-By-1.0'

PointAnnotation dataclass source

Bases: Annotation

Anchored to a single instant in the original recording timeline.

description class-attribute instance-attribute source

description: str | None = None

Optional human-readable description of the annotation.

id class-attribute instance-attribute source

id: str = field(default_factory=new_id)

Unique identifier, a UUIDv7 string by default.

key instance-attribute source

key: str

Name identifying the annotation.

start_time_s instance-attribute source

start_time_s: float

Instant on the original recording timeline, in seconds.

time_series_ids class-attribute instance-attribute source

time_series_ids: tuple[str, ...] | None = None

Series this annotation targets; None covers the whole sample.

unit class-attribute instance-attribute source

unit: str | Unit | None = None

Optional physical unit of value — a unit string (e.g. "years") or a :class:pint.Unit. Validated against the shared registry on construction; an unrecognized string raises ValueError, and a pint.Unit is stored as its canonical name.

value class-attribute instance-attribute source

value: Any = None

The annotation's payload value.

QATask dataclass source

Bases: TargetTask

A question and its answer (the target).

from_task_ids property source

from_task_ids: tuple[str, ...]

Return the ids of the tasks this one was derived from.

Returns:

Type Description
tuple[str, ...]

The id of every task in from_tasks.

from_tasks class-attribute instance-attribute source

from_tasks: tuple[Task, ...] = ()

Source tasks this one was derived from.

id class-attribute instance-attribute source

id: str = field(default_factory=new_id)

Unique task identifier, a UUIDv7 string by default.

question instance-attribute source

question: str

The question posed about the sample.

sample_ids class-attribute instance-attribute source

sample_ids: tuple[str, ...] = ()

Ids of the samples this task targets, populated by add_task.

target instance-attribute source

target: str

The supervised target: the class label, region label, answer, or caption for the sample.

task_type class-attribute source

task_type: TaskType = TaskType.QUESTION_AND_ANSWER

ReasoningTask dataclass source

Bases: TargetTask

A question answered by reasoning to a final answer. Often composed via from_tasks.

Unlike :class:QATask (single-label answer), a reasoning task carries the chain of thought in rationale. The target is the evaluation answer; the rationale is the reasoning trace to train / fine-tune on (None when the source has no stored rationale).

from_task_ids property source

from_task_ids: tuple[str, ...]

Return the ids of the tasks this one was derived from.

Returns:

Type Description
tuple[str, ...]

The id of every task in from_tasks.

from_tasks class-attribute instance-attribute source

from_tasks: tuple[Task, ...] = ()

Source tasks this one was derived from.

id class-attribute instance-attribute source

id: str = field(default_factory=new_id)

Unique task identifier, a UUIDv7 string by default.

question instance-attribute source

question: str

The question to be answered by reasoning.

rationale class-attribute instance-attribute source

rationale: str | None = None

The reasoning trace to train on, or None when the source stores none.

sample_ids class-attribute instance-attribute source

sample_ids: tuple[str, ...] = ()

Ids of the samples this task targets, populated by add_task.

target instance-attribute source

target: str

The supervised target: the class label, region label, answer, or caption for the sample.

task_type class-attribute source

task_type: TaskType = TaskType.REASONING

StaticAnnotation dataclass source

Bases: Annotation

Sample-scoped, time-independent context. Carries a required value and no time fields.

description class-attribute instance-attribute source

description: str | None = None

Optional human-readable description of the annotation.

id class-attribute instance-attribute source

id: str = field(default_factory=new_id)

Unique identifier, a UUIDv7 string by default.

key instance-attribute source

key: str

Name identifying the annotation.

unit class-attribute instance-attribute source

unit: str | Unit | None = None

Optional physical unit of value — a unit string (e.g. "years") or a :class:pint.Unit. Validated against the shared registry on construction; an unrecognized string raises ValueError, and a pint.Unit is stored as its canonical name.

value class-attribute instance-attribute source

value: Any = None

Required payload value; must not be None.

TargetTask dataclass source

Bases: Task

Base for tasks that carry a single supervised target.

Every task type except :class:ForecastingTask derives from this, so generic training code can read task.target without knowing the concrete type (see :meth:~timenet.dataset.TimeFDataset.to_features_and_targets). Not instantiated directly.

from_task_ids property source

from_task_ids: tuple[str, ...]

Return the ids of the tasks this one was derived from.

Returns:

Type Description
tuple[str, ...]

The id of every task in from_tasks.

from_tasks class-attribute instance-attribute source

from_tasks: tuple[Task, ...] = ()

Source tasks this one was derived from.

id class-attribute instance-attribute source

id: str = field(default_factory=new_id)

Unique task identifier, a UUIDv7 string by default.

sample_ids class-attribute instance-attribute source

sample_ids: tuple[str, ...] = ()

Ids of the samples this task targets, populated by add_task.

target instance-attribute source

target: str

The supervised target: the class label, region label, answer, or caption for the sample.

task_type class-attribute source

task_type: TaskType

Task dataclass source

Base for all tasks. Not instantiated directly; subclasses declare task_type and a payload.

from_task_ids property source

from_task_ids: tuple[str, ...]

Return the ids of the tasks this one was derived from.

Returns:

Type Description
tuple[str, ...]

The id of every task in from_tasks.

from_tasks class-attribute instance-attribute source

from_tasks: tuple[Task, ...] = ()

Source tasks this one was derived from.

id class-attribute instance-attribute source

id: str = field(default_factory=new_id)

Unique task identifier, a UUIDv7 string by default.

sample_ids class-attribute instance-attribute source

sample_ids: tuple[str, ...] = ()

Ids of the samples this task targets, populated by add_task.

task_type class-attribute source

task_type: TaskType

TaskType source

Bases: StrEnum

Stable type tags for the built-in task classes; also the on-disk task partition names.

CAPTIONING class-attribute instance-attribute source

CAPTIONING = 'captioning'

CLASSIFICATION class-attribute instance-attribute source

CLASSIFICATION = 'classification'

FORECASTING class-attribute instance-attribute source

FORECASTING = 'forecasting'

LABELING class-attribute instance-attribute source

LABELING = 'labeling'

QUESTION_AND_ANSWER class-attribute instance-attribute source

QUESTION_AND_ANSWER = 'question_and_answer'

REASONING class-attribute instance-attribute source

REASONING = 'reasoning'

TimeSeriesSpec dataclass source

The contract for a measurement modality: type tag, name, and the units of its axes.

data_source class-attribute instance-attribute source

data_source: DataSource | None = None

Origin that produced this modality, if known.

name instance-attribute source

name: str

Human-readable display name of the modality.

spec_type instance-attribute source

spec_type: str

Type tag identifying the modality; used to filter datasets by spec type.

unit_sampling_rate instance-attribute source

unit_sampling_rate: Unit

Unit of the sampling rate; must have frequency dimensionality.

unit_timestamp instance-attribute source

unit_timestamp: Unit

Unit of the timestamp axis; must have time dimensionality.

unit_value instance-attribute source

unit_value: Unit

Unit of the measured values.

Version dataclass source

A major.minor.patch semantic version with non-negative integer components.

Frozen and ordered, so versions compare with the usual precedence (Version(1, 2, 0) > Version(1, 1, 9)).

major instance-attribute source

major: int

Major version. Incremented on breaking changes.

minor instance-attribute source

minor: int

Minor version. Incremented on backwards-compatible additions.

patch instance-attribute source

patch: int

Patch version. Incremented on backwards-compatible fixes.

parse classmethod source

parse(text: str) -> Version

Parse a major.minor.patch string.

Parameters:

Name Type Description Default
text str

The version string to parse.

 required

Returns:

Type Description
Version

The parsed :class:Version.

Raises:

Type Description
ValueError

If text is not exactly three integer components.

View source

Bases: StrEnum

Identifies which slice of the source a :class:~timenet.dataset.Sample represents.

FULL class-attribute instance-attribute source

FULL = 'full'

SINGLE_CHANNEL class-attribute instance-attribute source

SINGLE_CHANNEL = 'single_channel'

SUBSET class-attribute instance-attribute source

SUBSET = 'subset'

WINDOW class-attribute instance-attribute source

WINDOW = 'window'

annotation_type_of source

annotation_type_of(
    annotation: Annotation,
) -> AnnotationType

Return the :class:AnnotationType shape of an annotation instance.

Parameters:

Name Type Description Default
annotation Annotation

The annotation to classify.

 required

Returns:

Type Description
AnnotationType

The matching :class:AnnotationType.

Raises:

Type Description
ValueError

If annotation is not one of the three concrete shapes.

new_id source

new_id() -> str

Return a new canonical UUIDv7 string, the default id for every TimeF entity.

Returns:

Type Description
str

The canonical 36-character UUIDv7 string (time-ordered).

uuid7 source

uuid7() -> UUID

Return a UUIDv7 (RFC 9562 §5.7): 48-bit ms timestamp, then random bits.

Returns:

Type Description
UUID

A version-7 :class:uuid.UUID. Two calls in the same millisecond differ in their random bits.

value_type_of source

value_type_of(value: Any) -> str | None

Return the manifest value_type tag for an annotation value.

Parameters:

Name Type Description Default
value Any

The annotation's value.

 required

Returns:

Type Description
str | None

One of "bool" | "int" | "float" | "str" | "list", or None for a pure marker.

Raises:

Type Description
TypeError

If value is a non-null value of an unsupported type.