Skip to content

Types

timenet.types source

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

TASKS module-attribute source

TASKS: dict[TaskType, type[Task]] = _build_task_registry()

US_PER_S module-attribute source

US_PER_S = 1000000

ureg module-attribute source

ureg = pint.UnitRegistry()

Access source

Bases: StrEnum

How a user obtains the source data.

CREDENTIALED class-attribute instance-attribute source

CREDENTIALED = 'credentialed'

A credentialed account and a signed agreement are needed, for example a PhysioNet DUA.

OPEN class-attribute instance-attribute source

OPEN = 'open'

Anyone can fetch the data; no account or agreement is needed.

RESTRICTED class-attribute instance-attribute source

RESTRICTED = 'restricted'

Access is granted case by case, for example an AWS-IAM grant or a direct request.

Annotation dataclass source

Contextual metadata attached to a record, optionally anchored to a region of its timeline.

An annotation carries a value, a span, or both. With a span, it says where on the recording timeline it applies and which series it targets. Without a span, it is record-scoped context that has no place in time, like a subject's age. The span's own shape says whether the annotation marks a time offset or covers a stretch. One class covers every shape::

Annotation(key="age", value=64)
Annotation(key="stimulus", span=TimePoint.seconds(0.5))
Annotation(key="artifact", value="motion", span=TimeInterval.seconds(0.0, 0.25))

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.

source class-attribute instance-attribute source

source: str | None = None

Optional per-instance provenance (the rater, method, or model behind this value). Unlike description, which the descriptor holds once per key, source can differ between annotations that share a key.

span class-attribute instance-attribute source

span: TimePoint | TimeInterval | None = None

Where on the recording timeline this annotation applies, and which series it targets. None means it is record-scoped context with no place in time.

unit class-attribute instance-attribute source

unit: str | Unit | None = None

Optional physical unit of value. Give a unit string (for example "years") or a :class:pint.Unit. Construction validates the unit against the shared registry. An unrecognized string raises ValueError. Construction stores a pint.Unit as its canonical name.

value class-attribute instance-attribute source

value: Any = None

The annotation's payload value. None makes it a pure marker, which needs a span to mark something.

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, list, or map).

AnnotationType source

Bases: StrEnum

Name the shape an annotation key takes across the dataset. It is a schema-level projection 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'

AnswerTask dataclass source

Bases: Task

Free-form text out. With no prompt it is a caption. With a prompt it answers a question.

rationale (on the base) carries the chain of thought. So a plain answer and a reasoned answer are the same type, with the field unset or set.

answer_fields class-attribute source

answer_fields: tuple[str, ...] = ('target',)

The payload fields holding the inline answer. A subclass whose answer is not (only) target overrides this, so the answer-exclusivity check stays generic instead of hardcoding target.

answer_is_record class-attribute source

answer_is_record: bool = False

True when the answer is a produced series, found by a payload record id and not 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.

input_annotation_ids class-attribute instance-attribute source

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

Annotations given to the model as context, not ones it must produce.

prompt class-attribute instance-attribute source

prompt: str | None = None

What the model is asked, when the task is prompted. None for an unprompted task.

rationale class-attribute instance-attribute source

rationale: str | None = None

Chain of thought to train on. Any task can carry one. None when the source stores none.

record_ids class-attribute instance-attribute source

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

Ids of the records this task is about. add_task sets them.

refs class-attribute source

refs: TaskRefs = TaskRefs()

Which payload fields hold record ids or spans (see :class:TaskRefs).

scope class-attribute instance-attribute source

scope: Span | None = None

The region of the input the task is about. None means the whole record.

target class-attribute instance-attribute source

target: str | None = None

The answer, or the caption when the task is unprompted.

target_annotation_ids class-attribute instance-attribute source

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

The answer by reference: it is these stored annotations, not an inline copy of them. It is exclusive with target. :meth:~timenet.dataset.TimeFDataset.add_task enforces that.

target_is_scalar class-attribute source

target_is_scalar: bool = True

task_type class-attribute source

task_type: TaskType = TaskType.ANSWER

check_against_scope source

check_against_scope() -> None

Validate payload that depends on the task's finalized scope.

:meth:~timenet.dataset.TimeFDataset.add_task calls this after stamping any scope= passed there, so a scope supplied at registration is in force. The base task has nothing scope-dependent to check. :class:ForecastingTask overrides it.

spans source

spans() -> tuple[Span, ...]

Return every span the task carries: its scope and any span-valued payload field.

This lets :meth:~timenet.dataset.TimeFDataset.add_task check a task's spans without knowledge of its concrete type.

Returns:

Type Description
tuple[Span, ...]

The task's spans, scope first.

ClassificationTask dataclass source

Bases: Task

One categorical label: over the whole record, or over scope when one is set.

A whole-recording class ("this ECG shows atrial fibrillation") and a scoped label ("this 30 s epoch is sleep stage N2") differ in one way. The only difference is whether scope narrows the input. So both are this type.

answer_fields class-attribute source

answer_fields: tuple[str, ...] = ('target',)

The payload fields holding the inline answer. A subclass whose answer is not (only) target overrides this, so the answer-exclusivity check stays generic instead of hardcoding target.

answer_is_record class-attribute source

answer_is_record: bool = False

True when the answer is a produced series, found by a payload record id and not 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.

input_annotation_ids class-attribute instance-attribute source

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

Annotations given to the model as context, not ones it must produce.

prompt class-attribute instance-attribute source

prompt: str | None = None

What the model is asked, when the task is prompted. None for an unprompted task.

rationale class-attribute instance-attribute source

rationale: str | None = None

Chain of thought to train on. Any task can carry one. None when the source stores none.

record_ids class-attribute instance-attribute source

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

Ids of the records this task is about. add_task sets them.

refs class-attribute source

refs: TaskRefs = TaskRefs()

Which payload fields hold record ids or spans (see :class:TaskRefs).

scope class-attribute instance-attribute source

scope: Span | None = None

The region of the input the task is about. None means the whole record.

target class-attribute instance-attribute source

target: str | None = None

The label.

target_annotation_ids class-attribute instance-attribute source

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

The answer by reference: it is these stored annotations, not an inline copy of them. It is exclusive with target. :meth:~timenet.dataset.TimeFDataset.add_task enforces that.

target_is_scalar class-attribute source

target_is_scalar: bool = True

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

check_against_scope source

check_against_scope() -> None

Validate payload that depends on the task's finalized scope.

:meth:~timenet.dataset.TimeFDataset.add_task calls this after stamping any scope= passed there, so a scope supplied at registration is in force. The base task has nothing scope-dependent to check. :class:ForecastingTask overrides it.

spans source

spans() -> tuple[Span, ...]

Return every span the task carries: its scope and any span-valued payload field.

This lets :meth:~timenet.dataset.TimeFDataset.add_task check a task's spans without knowledge of its concrete type.

Returns:

Type Description
tuple[Span, ...]

The task's spans, scope first.

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.

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.

The dataset card holds these fields. dataset_version is the semantic version of the upstream source. yaml_schema_version is the version of the card's own field schema. dataset_id is an org/name pair in HuggingFace style with exactly one slash. Ids are case-sensitive, so avoid casing-only differences on case-insensitive filesystems.

access class-attribute instance-attribute source

access: Access = Access.OPEN

How a user obtains the data (see :class:Access). OPEN needs nothing.

access_url class-attribute instance-attribute source

access_url: str | None = None

Where to obtain access (the DUA or credentialing page). Required when access is not OPEN.

citation class-attribute instance-attribute source

citation: str | None = None

How to cite the dataset, when the source asks for attribution.

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.

license_url class-attribute instance-attribute source

license_url: str | None = None

Where to read the full license text. Required when license is :attr:License.OTHER.

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.

The enum and version fields arrive as strings (license, domains, dataset_version). This method coerces them and ignores unmodeled keys. :meth:from_yaml and the manifest codec share it, so the mapping lives in one place. Coercion can raise KeyError for a missing field or ValueError for a bad license, domain, or version. 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.

This method validates the card against the packaged dataset-card.schema.json before construction. Authoring mistakes then surface as clear, aggregated messages instead of a stack trace from deep inside coercion. PyYAML and jsonschema are optional. This method imports them lazily, so the types package does not depend on them. Install the timenet[build] 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
TimeNetInvalidCardError

If the build 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).

It holds flat descriptor instances for specs and annotations. It also holds the real built-in :class:~timenet.types.tasks.Task subclasses, resolved against the registry instead of reconstructed.

annotations class-attribute instance-attribute source

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

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

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'

AUDIO class-attribute instance-attribute source

AUDIO = 'audio'

CARDIOLOGY class-attribute instance-attribute source

CARDIOLOGY = 'cardiology'

ECONOMICS class-attribute instance-attribute source

ECONOMICS = 'economics'

ENERGY class-attribute instance-attribute source

ENERGY = 'energy'

ENVIRONMENT class-attribute instance-attribute source

ENVIRONMENT = 'environment'

FINANCE class-attribute instance-attribute source

FINANCE = 'finance'

GENERAL class-attribute instance-attribute source

GENERAL = 'general'

HEALTH class-attribute instance-attribute source

HEALTH = 'health'

MOTION class-attribute instance-attribute source

MOTION = 'motion'

OBSERVABILITY class-attribute instance-attribute source

OBSERVABILITY = 'observability'

RESPIRATORY class-attribute instance-attribute source

RESPIRATORY = 'respiratory'

SLEEP class-attribute instance-attribute source

SLEEP = 'sleep'

TRANSPORT class-attribute instance-attribute source

TRANSPORT = 'transport'

ForecastingTask dataclass source

Bases: Task

A series out: continue the context into the future.

The future is either a whole separate record (target_record_id) or a region of the attached record (target_span). Exactly one of the two is set, never both and never neither. The second shape lets one unsplit series carry a horizon. So the dataset can ship the raw recording, not a context/target pair. target_span also needs scope. Without it, the base Task.scope default of None means the whole record, which then covers the region that target_span predicts.

answer_fields class-attribute source

answer_fields: tuple[str, ...] = ('target',)

The payload fields holding the inline answer. A subclass whose answer is not (only) target overrides this, so the answer-exclusivity check stays generic instead of hardcoding target.

answer_is_record class-attribute source

answer_is_record: bool = True

context_record_ids class-attribute instance-attribute source

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

Ids of the records 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.

input_annotation_ids class-attribute instance-attribute source

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

Annotations given to the model as context, not ones it must produce.

prompt class-attribute instance-attribute source

prompt: str | None = None

What the model is asked, when the task is prompted. None for an unprompted task.

rationale class-attribute instance-attribute source

rationale: str | None = None

Chain of thought to train on. Any task can carry one. None when the source stores none.

record_ids class-attribute instance-attribute source

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

Ids of the records this task is about. add_task sets them.

refs class-attribute source

refs: TaskRefs = TaskRefs(
    record_id_fields=(
        "context_record_ids",
        "target_record_id",
    ),
    span_fields=("target_span",),
)

scope class-attribute instance-attribute source

scope: Span | None = None

The region of the input the task is about. None means the whole record.

target class-attribute instance-attribute source

target: object | None = None

The answer, typed by the subclass. None when the answer is stored by reference, or produced as a series (see answer_is_record).

target_annotation_ids class-attribute instance-attribute source

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

The answer by reference: it is these stored annotations, not an inline copy of them. It is exclusive with target. :meth:~timenet.dataset.TimeFDataset.add_task enforces that.

target_is_scalar class-attribute source

target_is_scalar: bool = False

True when to_features_and_targets can return target as a scalar.

target_record_id class-attribute instance-attribute source

target_record_id: str | None = None

Id of the record whose future values the task predicts. None when target_span names the region to predict in the attached record instead.

target_span class-attribute instance-attribute source

target_span: TimeInterval | StepInterval | None = None

The region to predict, inside the record the task is attached to. It is an interval, not a point (the type says so), and it is exclusive with target_record_id. It is in the same frame as scope. For a series with a timeline, that is a :class:~timenet.types.spans.TimeInterval in microseconds. For a series that counts in steps, it is a :class:~timenet.types.spans.StepInterval, the only frame an ordinal series can carry. :meth:~timenet.dataset.TimeFDataset.add_task checks that it falls inside the record, because that method has the record. It needs an explicit scope for the context region. A scope of None means the whole record, which covers the region to predict.

task_type class-attribute source

task_type: TaskType = TaskType.FORECASTING

check_against_scope source

check_against_scope() -> None

Reject a target_span forecast whose context scope is missing, misframed, or leaks the target.

Raises:

Type Description
TimeFValidationError

If target_span is set with no scope, the whole-record default would include the region to predict. If scope and target_span are in different frames. If scope reaches into or past target_span on a series they share.

spans source

spans() -> tuple[Span, ...]

Return every span the task carries: its scope and any span-valued payload field.

This lets :meth:~timenet.dataset.TimeFDataset.add_task check a task's spans without knowledge of its concrete type.

Returns:

Type Description
tuple[Span, ...]

The task's spans, scope first.

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'

OTHER class-attribute instance-attribute source

OTHER = 'other'

Escape hatch for a license outside this list; requires a license_url on the card.

LocalizationMode source

Bases: StrEnum

Whether a localization target covers the whole recording or can leave some time unmarked.

EXHAUSTIVE class-attribute instance-attribute source

EXHAUSTIVE = 'exhaustive'

The spans intend to tile the whole region of interest (for example, sleep staging).

SPARSE class-attribute instance-attribute source

SPARSE = 'sparse'

Only the marked spans are claimed. Unmarked time stays unlabeled (for example, R-peaks).

ScalarPredictionTask dataclass source

Bases: Task

One number out, with the quantity it measures and its physical unit kept as data.

An answer task stores a regression target as a string, which loses its type. A float with a unit keeps the type. It makes regression metrics, batching, and unit-aware conversion simple.

answer_fields class-attribute source

answer_fields: tuple[str, ...] = ('target',)

The payload fields holding the inline answer. A subclass whose answer is not (only) target overrides this, so the answer-exclusivity check stays generic instead of hardcoding target.

answer_is_record class-attribute source

answer_is_record: bool = False

True when the answer is a produced series, found by a payload record id and not 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.

input_annotation_ids class-attribute instance-attribute source

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

Annotations given to the model as context, not ones it must produce.

prompt class-attribute instance-attribute source

prompt: str | None = None

What the model is asked, when the task is prompted. None for an unprompted task.

rationale class-attribute instance-attribute source

rationale: str | None = None

Chain of thought to train on. Any task can carry one. None when the source stores none.

record_ids class-attribute instance-attribute source

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

Ids of the records this task is about. add_task sets them.

refs class-attribute source

refs: TaskRefs = TaskRefs()

Which payload fields hold record ids or spans (see :class:TaskRefs).

scope class-attribute instance-attribute source

scope: Span | None = None

The region of the input the task is about. None means the whole record.

target class-attribute instance-attribute source

target: float | None = None

The predicted value.

target_annotation_ids class-attribute instance-attribute source

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

The answer by reference: it is these stored annotations, not an inline copy of them. It is exclusive with target. :meth:~timenet.dataset.TimeFDataset.add_task enforces that.

target_is_scalar class-attribute source

target_is_scalar: bool = True

target_name class-attribute instance-attribute source

target_name: str | None = None

Name of the quantity to predict (for example, "mean_heart_rate").

task_type class-attribute source

task_type: TaskType = TaskType.SCALAR_PREDICTION

unit class-attribute instance-attribute source

unit: str | Unit | None = None

Optional physical unit of target. Give a unit string (for example, "bpm") or a :class:pint.Unit. The constructor checks it against the shared registry. It stores a pint.Unit as its name.

check_against_scope source

check_against_scope() -> None

Validate payload that depends on the task's finalized scope.

:meth:~timenet.dataset.TimeFDataset.add_task calls this after stamping any scope= passed there, so a scope supplied at registration is in force. The base task has nothing scope-dependent to check. :class:ForecastingTask overrides it.

spans source

spans() -> tuple[Span, ...]

Return every span the task carries: its scope and any span-valued payload field.

This lets :meth:~timenet.dataset.TimeFDataset.add_task check a task's spans without knowledge of its concrete type.

Returns:

Type Description
tuple[Span, ...]

The task's spans, scope first.

Span dataclass source

Abstract base for every localized region. Not constructible. Build a concrete leaf type.

The concrete spans are :class:TimePoint, :class:TimeInterval, :class:StepPoint, and :class:StepInterval. Annotate with Span where any of them fits, and shared code reads them through this base.

exclusive_end property source

exclusive_end: int

The exclusive upper bound of the span, in its own frame.

The region is half-open, so a point ends one unit past its position and an interval ends at its stored end. Each concrete leaf supplies this.

is_point class-attribute source

is_point: bool = False

Whether this span marks a single position rather than a bounded interval.

StepInterval dataclass source

Bases: StepSpan

The half-open range [start, stop) of step ordinals on the named series.

exclusive_end property source

exclusive_end: int

The range's own exclusive end, stop.

frame class-attribute source

frame: str = 'steps'

The frame its bounds read in, as stored on disk.

is_point class-attribute source

is_point: bool = False

Whether this span marks a single position rather than a bounded interval.

n_steps property source

n_steps: int

How many steps the interval covers, the horizon h step-based forecasting libraries speak in.

start instance-attribute source

start: int

The position, or the start of the interval, as a step ordinal from the series' first stored step.

stop instance-attribute source

stop: int

Last step ordinal, exclusive.

time_series_id instance-attribute source

time_series_id: str

The single series whose steps the span counts.

StepPoint dataclass source

Bases: StepSpan

One step ordinal on the named series.

exclusive_end property source

exclusive_end: int

One step past the ordinal, so the half-open range covering it is [start, +1).

frame class-attribute source

frame: str = 'steps'

The frame its bounds read in, as stored on disk.

is_point class-attribute source

is_point: bool = True

start instance-attribute source

start: int

The position, or the start of the interval, as a step ordinal from the series' first stored step.

time_series_id instance-attribute source

time_series_id: str

The single series whose steps the span counts.

StepSpan dataclass source

Bases: Span

Abstract base for a region counted in the step ordinals of one series.

A step index means nothing without a series to count on, so a step span names exactly one time_series_id. Valid only on a series whose axis is ordinal (no timeline).

exclusive_end property source

exclusive_end: int

The exclusive upper bound of the span, in its own frame.

The region is half-open, so a point ends one unit past its position and an interval ends at its stored end. Each concrete leaf supplies this.

frame class-attribute source

frame: str = 'steps'

The frame its bounds read in, as stored on disk.

is_point class-attribute source

is_point: bool = False

Whether this span marks a single position rather than a bounded interval.

start instance-attribute source

start: int

The position, or the start of the interval, as a step ordinal from the series' first stored step.

time_series_id instance-attribute source

time_series_id: str

The single series whose steps the span counts.

TSCorrespondenceTask dataclass source

Bases: Task

Relate one series to others: which candidate record corresponds to the records in record_ids.

This covers retrieval, nearest-neighbor, and match questions. The base record_ids are the query. candidate_record_ids is the pool for the answer, and target names the correct one or ones. An empty pool keeps the answer open. Then any record in the dataset can be the answer.

answer_fields class-attribute source

answer_fields: tuple[str, ...] = (
    "target",
    "target_time_series_ids",
)

answer_is_record class-attribute source

answer_is_record: bool = False

True when the answer is a produced series, found by a payload record id and not target.

candidate_record_ids class-attribute instance-attribute source

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

Ids of the records that supply the answer. Empty means the pool has no limit.

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.

input_annotation_ids class-attribute instance-attribute source

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

Annotations given to the model as context, not ones it must produce.

prompt class-attribute instance-attribute source

prompt: str | None = None

What the model is asked, when the task is prompted. None for an unprompted task.

rationale class-attribute instance-attribute source

rationale: str | None = None

Chain of thought to train on. Any task can carry one. None when the source stores none.

record_ids class-attribute instance-attribute source

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

Ids of the records this task is about. add_task sets them.

refs class-attribute source

refs: TaskRefs = TaskRefs(
    record_id_fields=("candidate_record_ids", "target"),
    time_series_id_fields=("target_time_series_ids",),
)

scope class-attribute instance-attribute source

scope: Span | None = None

The region of the input the task is about. None means the whole record.

target class-attribute instance-attribute source

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

Ids of the corresponding record(s), which must be in candidate_record_ids when it is set.

target_annotation_ids class-attribute instance-attribute source

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

The answer by reference: it is these stored annotations, not an inline copy of them. It is exclusive with target. :meth:~timenet.dataset.TimeFDataset.add_task enforces that.

target_is_scalar class-attribute source

target_is_scalar: bool = False

True when to_features_and_targets can return target as a scalar.

target_time_series_ids class-attribute instance-attribute source

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

Ids of the corresponding series, when the answer names signals rather than whole records (for example "which signals correlate with X"). Each id must resolve to a series on the task's records.

task_type class-attribute source

task_type: TaskType = TaskType.TS_CORRESPONDENCE

check_against_scope source

check_against_scope() -> None

Validate payload that depends on the task's finalized scope.

:meth:~timenet.dataset.TimeFDataset.add_task calls this after stamping any scope= passed there, so a scope supplied at registration is in force. The base task has nothing scope-dependent to check. :class:ForecastingTask overrides it.

spans source

spans() -> tuple[Span, ...]

Return every span the task carries: its scope and any span-valued payload field.

This lets :meth:~timenet.dataset.TimeFDataset.add_task check a task's spans without knowledge of its concrete type.

Returns:

Type Description
tuple[Span, ...]

The task's spans, scope first.

TSEditingTask dataclass source

Bases: Task

A series out: transform the source record into the target record, as the prompt instructs.

This covers denoising, filtering, and deliberate corruption ("add baseline wander"). The prompt is the instruction, and both sides of the edit are stored records.

answer_fields class-attribute source

answer_fields: tuple[str, ...] = ('target',)

The payload fields holding the inline answer. A subclass whose answer is not (only) target overrides this, so the answer-exclusivity check stays generic instead of hardcoding target.

answer_is_record class-attribute source

answer_is_record: bool = True

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.

input_annotation_ids class-attribute instance-attribute source

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

Annotations given to the model as context, not ones it must produce.

prompt class-attribute instance-attribute source

prompt: str | None = None

What the model is asked, when the task is prompted. None for an unprompted task.

rationale class-attribute instance-attribute source

rationale: str | None = None

Chain of thought to train on. Any task can carry one. None when the source stores none.

record_ids class-attribute instance-attribute source

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

Ids of the records this task is about. add_task sets them.

refs class-attribute source

refs: TaskRefs = TaskRefs(
    record_id_fields=(
        "source_record_id",
        "target_record_id",
    )
)

scope class-attribute instance-attribute source

scope: Span | None = None

The region of the input the task is about. None means the whole record.

source_record_id instance-attribute source

source_record_id: str

Id of the record to edit.

target class-attribute instance-attribute source

target: object | None = None

The answer, typed by the subclass. None when the answer is stored by reference, or produced as a series (see answer_is_record).

target_annotation_ids class-attribute instance-attribute source

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

The answer by reference: it is these stored annotations, not an inline copy of them. It is exclusive with target. :meth:~timenet.dataset.TimeFDataset.add_task enforces that.

target_is_scalar class-attribute source

target_is_scalar: bool = False

True when to_features_and_targets can return target as a scalar.

target_record_id instance-attribute source

target_record_id: str

Id of the record that holds the edited result.

task_type class-attribute source

task_type: TaskType = TaskType.TS_EDITING

check_against_scope source

check_against_scope() -> None

Validate payload that depends on the task's finalized scope.

:meth:~timenet.dataset.TimeFDataset.add_task calls this after stamping any scope= passed there, so a scope supplied at registration is in force. The base task has nothing scope-dependent to check. :class:ForecastingTask overrides it.

spans source

spans() -> tuple[Span, ...]

Return every span the task carries: its scope and any span-valued payload field.

This lets :meth:~timenet.dataset.TimeFDataset.add_task check a task's spans without knowledge of its concrete type.

Returns:

Type Description
tuple[Span, ...]

The task's spans, scope first.

TSGenerationTask dataclass source

Bases: Task

A series out from a text specification alone: the prompt describes what to synthesize.

answer_fields class-attribute source

answer_fields: tuple[str, ...] = ('target',)

The payload fields holding the inline answer. A subclass whose answer is not (only) target overrides this, so the answer-exclusivity check stays generic instead of hardcoding target.

answer_is_record class-attribute source

answer_is_record: bool = True

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.

input_annotation_ids class-attribute instance-attribute source

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

Annotations given to the model as context, not ones it must produce.

prompt class-attribute instance-attribute source

prompt: str | None = None

What the model is asked, when the task is prompted. None for an unprompted task.

rationale class-attribute instance-attribute source

rationale: str | None = None

Chain of thought to train on. Any task can carry one. None when the source stores none.

record_ids class-attribute instance-attribute source

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

Ids of the records this task is about. add_task sets them.

refs class-attribute source

refs: TaskRefs = TaskRefs(
    record_id_fields=("target_record_id",)
)

scope class-attribute instance-attribute source

scope: Span | None = None

The region of the input the task is about. None means the whole record.

target class-attribute instance-attribute source

target: object | None = None

The answer, typed by the subclass. None when the answer is stored by reference, or produced as a series (see answer_is_record).

target_annotation_ids class-attribute instance-attribute source

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

The answer by reference: it is these stored annotations, not an inline copy of them. It is exclusive with target. :meth:~timenet.dataset.TimeFDataset.add_task enforces that.

target_is_scalar class-attribute source

target_is_scalar: bool = False

True when to_features_and_targets can return target as a scalar.

target_record_id instance-attribute source

target_record_id: str

Id of the record that holds the series to generate.

task_type class-attribute source

task_type: TaskType = TaskType.TS_GENERATION

check_against_scope source

check_against_scope() -> None

Validate payload that depends on the task's finalized scope.

:meth:~timenet.dataset.TimeFDataset.add_task calls this after stamping any scope= passed there, so a scope supplied at registration is in force. The base task has nothing scope-dependent to check. :class:ForecastingTask overrides it.

spans source

spans() -> tuple[Span, ...]

Return every span the task carries: its scope and any span-valued payload field.

This lets :meth:~timenet.dataset.TimeFDataset.add_task check a task's spans without knowledge of its concrete type.

Returns:

Type Description
tuple[Span, ...]

The task's spans, scope first.

Task dataclass source

Base for all tasks. You do not construct it directly. Each subclass declares task_type and an answer type.

It holds everything that is the same across task types. So generic code (training loops, the writer, the editor) can read a task without its concrete type.

answer_fields class-attribute source

answer_fields: tuple[str, ...] = ('target',)

The payload fields holding the inline answer. A subclass whose answer is not (only) target overrides this, so the answer-exclusivity check stays generic instead of hardcoding target.

answer_is_record class-attribute source

answer_is_record: bool = False

True when the answer is a produced series, found by a payload record id and not 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.

input_annotation_ids class-attribute instance-attribute source

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

Annotations given to the model as context, not ones it must produce.

prompt class-attribute instance-attribute source

prompt: str | None = None

What the model is asked, when the task is prompted. None for an unprompted task.

rationale class-attribute instance-attribute source

rationale: str | None = None

Chain of thought to train on. Any task can carry one. None when the source stores none.

record_ids class-attribute instance-attribute source

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

Ids of the records this task is about. add_task sets them.

refs class-attribute source

refs: TaskRefs = TaskRefs()

Which payload fields hold record ids or spans (see :class:TaskRefs).

scope class-attribute instance-attribute source

scope: Span | None = None

The region of the input the task is about. None means the whole record.

target class-attribute instance-attribute source

target: object | None = None

The answer, typed by the subclass. None when the answer is stored by reference, or produced as a series (see answer_is_record).

target_annotation_ids class-attribute instance-attribute source

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

The answer by reference: it is these stored annotations, not an inline copy of them. It is exclusive with target. :meth:~timenet.dataset.TimeFDataset.add_task enforces that.

target_is_scalar class-attribute source

target_is_scalar: bool = False

True when to_features_and_targets can return target as a scalar.

task_type class-attribute source

task_type: TaskType

The subclass's stable type tag. Deliberately absent here: the base is not a task.

check_against_scope source

check_against_scope() -> None

Validate payload that depends on the task's finalized scope.

:meth:~timenet.dataset.TimeFDataset.add_task calls this after stamping any scope= passed there, so a scope supplied at registration is in force. The base task has nothing scope-dependent to check. :class:ForecastingTask overrides it.

spans source

spans() -> tuple[Span, ...]

Return every span the task carries: its scope and any span-valued payload field.

This lets :meth:~timenet.dataset.TimeFDataset.add_task check a task's spans without knowledge of its concrete type.

Returns:

Type Description
tuple[Span, ...]

The task's spans, scope first.

TaskRefs dataclass source

Which of a task's payload fields hold references. Each task declares this next to its class.

The writer, the reader, and the copy-on-write editor must know that ForecastingTask.target_record_id is a record id, and that ScalarPredictionTask.target is a plain number. The declaration on the class keeps that knowledge next to the field. The other place for it is a lookup table in the format layer and an isinstance chain in the editor. Those two drift the moment someone adds a task.

The base fields (record_ids, scope, the annotation id tuples) are common to every task. The format layer handles them directly. This declaration covers only the type-specific payload.

record_id_fields class-attribute instance-attribute source

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

Payload fields that hold a record id or a tuple of them. If one id is lost, the task is not valid.

span_fields class-attribute instance-attribute source

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

Payload fields that hold a :class:~timenet.types.spans.Span or a tuple of them.

time_series_id_fields class-attribute instance-attribute source

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

Payload fields that hold a time-series id or a tuple of them, resolved against the task's records.

TaskType source

Bases: StrEnum

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

ANSWER class-attribute instance-attribute source

ANSWER = 'answer'

CLASSIFICATION class-attribute instance-attribute source

CLASSIFICATION = 'classification'

FORECASTING class-attribute instance-attribute source

FORECASTING = 'forecasting'

SCALAR_PREDICTION class-attribute instance-attribute source

SCALAR_PREDICTION = 'scalar_prediction'

TEMPORAL_LOCALIZATION class-attribute instance-attribute source

TEMPORAL_LOCALIZATION = 'temporal_localization'

TS_CORRESPONDENCE class-attribute instance-attribute source

TS_CORRESPONDENCE = 'ts_correspondence'

TS_EDITING class-attribute instance-attribute source

TS_EDITING = 'ts_editing'

TS_GENERATION class-attribute instance-attribute source

TS_GENERATION = 'ts_generation'

TemporalLocalizationTask dataclass source

Bases: Task

Regions out: find where something happens, from a description of it.

This is the inverse of a scoped :class:ClassificationTask, which gives the region and asks for its label. One type covers event detection, segmentation, and change-point detection, because they share one target: a tuple of :class:~timenet.types.spans.TimePoint or :class:~timenet.types.spans.TimeInterval spans, on the recording timeline. An optional label from a referenced annotation marks each one, and each one is scoped to particular series.

answer_fields class-attribute source

answer_fields: tuple[str, ...] = ('target',)

The payload fields holding the inline answer. A subclass whose answer is not (only) target overrides this, so the answer-exclusivity check stays generic instead of hardcoding target.

answer_is_record class-attribute source

answer_is_record: bool = False

True when the answer is a produced series, found by a payload record id and not 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.

input_annotation_ids class-attribute instance-attribute source

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

Annotations given to the model as context, not ones it must produce.

mode class-attribute instance-attribute source

mode: LocalizationMode = LocalizationMode.SPARSE

Whether the spans must cover the region of interest (see :class:LocalizationMode).

prompt class-attribute instance-attribute source

prompt: str | None = None

What the model is asked, when the task is prompted. None for an unprompted task.

rationale class-attribute instance-attribute source

rationale: str | None = None

Chain of thought to train on. Any task can carry one. None when the source stores none.

record_ids class-attribute instance-attribute source

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

Ids of the records this task is about. add_task sets them.

refs class-attribute source

refs: TaskRefs = TaskRefs(span_fields=('target',))

scope class-attribute instance-attribute source

scope: Span | None = None

The region of the input the task is about. None means the whole record.

target class-attribute instance-attribute source

target: tuple[TimePoint | TimeInterval, ...] | None = None

The regions to find. None means the answer is stored by reference in target_annotation_ids; () is a positive answer that nothing was found in scope.

target_annotation_ids class-attribute instance-attribute source

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

The answer by reference: it is these stored annotations, not an inline copy of them. It is exclusive with target. :meth:~timenet.dataset.TimeFDataset.add_task enforces that.

target_is_scalar class-attribute source

target_is_scalar: bool = False

True when to_features_and_targets can return target as a scalar.

task_type class-attribute source

task_type: TaskType = TaskType.TEMPORAL_LOCALIZATION

check_against_scope source

check_against_scope() -> None

Validate payload that depends on the task's finalized scope.

:meth:~timenet.dataset.TimeFDataset.add_task calls this after stamping any scope= passed there, so a scope supplied at registration is in force. The base task has nothing scope-dependent to check. :class:ForecastingTask overrides it.

spans source

spans() -> tuple[Span, ...]

Return every span the task carries: its scope and any span-valued payload field.

This lets :meth:~timenet.dataset.TimeFDataset.add_task check a task's spans without knowledge of its concrete type.

Returns:

Type Description
tuple[Span, ...]

The task's spans, scope first.

TimeInterval dataclass source

Bases: TimeSpan

The half-open range [start_us, end_us) on the recording timeline.

end_us instance-attribute source

end_us: int

End of the interval, exclusive, in microseconds.

exclusive_end property source

exclusive_end: int

The interval's own exclusive end, end_us.

frame class-attribute source

frame: str = 'seconds'

The frame its bounds read in, as stored on disk.

is_point class-attribute source

is_point: bool = False

Whether this span marks a single position rather than a bounded interval.

start_us instance-attribute source

start_us: int

The position, or the start of the interval, in microseconds on the source recording timeline.

time_series_ids class-attribute instance-attribute source

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

Series the span is scoped to. None covers every series in the record.

micros classmethod source

micros(
    start: int,
    end: int,
    *,
    time_series_ids: tuple[str, ...] | None = None,
) -> TimeInterval

Construct an interval from whole microseconds, for a source that already has them.

Parameters:

Name Type Description Default
start int

Start of the interval, in microseconds.

 required
end int

End of the interval, exclusive, in microseconds.

 required
time_series_ids tuple[str, ...] | None

Series the interval is scoped to. None covers every series.

 None

Returns:

Type Description
TimeInterval

The interval.

seconds classmethod source

seconds(
    start: float,
    end: float,
    *,
    time_series_ids: tuple[str, ...] | None = None,
) -> TimeInterval

Construct an interval from recording seconds, each bound rounded to the nearest microsecond.

Parameters:

Name Type Description Default
start float

Start of the interval, in recording seconds.

 required
end float

End of the interval, exclusive, in recording seconds.

 required
time_series_ids tuple[str, ...] | None

Series the interval is scoped to. None covers every series.

 None

Returns:

Type Description
TimeInterval

The interval.

TimePoint dataclass source

Bases: TimeSpan

One point on the recording timeline.

exclusive_end property source

exclusive_end: int

One microsecond past the point, so the half-open window covering it is [start_us, +1).

frame class-attribute source

frame: str = 'seconds'

The frame its bounds read in, as stored on disk.

is_point class-attribute source

is_point: bool = True

start_us instance-attribute source

start_us: int

The position, or the start of the interval, in microseconds on the source recording timeline.

time_series_ids class-attribute instance-attribute source

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

Series the span is scoped to. None covers every series in the record.

micros classmethod source

micros(
    at: int,
    *,
    time_series_ids: tuple[str, ...] | None = None,
) -> TimePoint

Construct a point from whole microseconds, for a source that already has them.

Parameters:

Name Type Description Default
at int

The position, in microseconds.

 required
time_series_ids tuple[str, ...] | None

Series the point is scoped to. None covers every series.

 None

Returns:

Type Description
TimePoint

The point.

seconds classmethod source

seconds(
    at: float,
    *,
    time_series_ids: tuple[str, ...] | None = None,
) -> TimePoint

Construct a point from recording seconds, rounded to the nearest microsecond.

Parameters:

Name Type Description Default
at float

The position, in recording seconds.

 required
time_series_ids tuple[str, ...] | None

Series the point is scoped to. None covers every series.

 None

Returns:

Type Description
TimePoint

The point.

TimeSeriesSpec dataclass source

Define the contract for a measurement modality: identity, value unit, dtype, and per-timestep shape.

The spec carries no unit for time or for a sampling rate. Time offsets are integer microseconds and a cadence is a Fraction of them, so those units can only be second and hertz.

categories class-attribute instance-attribute source

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

Ordered codebook for dtype="enum". Empty for every other dtype.

data_source class-attribute instance-attribute source

data_source: DataSource | None = None

Origin that produced this modality, if known.

dimension_names class-attribute instance-attribute source

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

Optional names for the dimensions in :attr:value_shape.

dtype class-attribute instance-attribute source

dtype: str = 'float32'

Value dtype: a NumPy scalar dtype, "str" for text, or "enum" for a categorical value.

name instance-attribute source

name: str

Human-readable display name of the modality.

nullable class-attribute instance-attribute source

nullable: bool = False

Whether a whole timestep can be missing. An Arrow bit marks whether each timestep is present.

spec_type instance-attribute source

spec_type: str

Type tag identifying the modality. Callers use it to filter datasets by spec type.

unit_value instance-attribute source

unit_value: Unit

Unit of the measured values.

value_shape class-attribute instance-attribute source

value_shape: tuple[int, ...] = ()

Shape of one timestep, excluding the leading time axis. An empty shape means scalar values.

TimeSpan dataclass source

Bases: Span

Abstract base for a region on the recording timeline. Bounds are microseconds.

Covers the whole record when time_series_ids is None, or a subset of series when it names them. Valid only on a series whose axis is a timeline (regular or irregular).

exclusive_end property source

exclusive_end: int

The exclusive upper bound of the span, in its own frame.

The region is half-open, so a point ends one unit past its position and an interval ends at its stored end. Each concrete leaf supplies this.

frame class-attribute source

frame: str = 'seconds'

The frame its bounds read in, as stored on disk.

is_point class-attribute source

is_point: bool = False

Whether this span marks a single position rather than a bounded interval.

start_us instance-attribute source

start_us: int

The position, or the start of the interval, in microseconds on the source recording timeline.

time_series_ids class-attribute instance-attribute source

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

Series the span is scoped to. None covers every series in the record.

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. Increments on breaking changes.

minor instance-attribute source

minor: int

Minor version. Increments on backwards-compatible additions.

patch instance-attribute source

patch: int

Patch version. Increments 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
TimeFValidationError

If text is not exactly three integer components.

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, derived from the span rather than from a class.

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).

normalize_unit source

normalize_unit(unit: str | Unit | None) -> str | None

Validate a unit against the shared registry, rejecting an unrecognized unit string.

A :class:pint.Unit becomes its canonical name. The function keeps a unit string as written but validates it, and raises on an unknown one. None passes through. The result is always a string or None, so serialization is unchanged. Every type that carries a unit uses this function, so annotation values and scalar task targets accept and store units the same way.

Parameters:

Name Type Description Default
unit str | Unit | None

A :class:pint.Unit, a unit string (for example "years"), or None.

 required

Returns:

Type Description
str | None

The unit as a string, or None.

Raises:

Type Description
TimeFValidationError

If unit is a string the shared registry does not recognize.

offset_us source

offset_us(
    moment: datetime, start_time: datetime | int | None
) -> int

Convert a wall-clock moment to an offset on a record's recording timeline.

Parameters:

Name Type Description Default
moment datetime

The wall-clock moment, timezone-aware.

 required
start_time datetime | int | None

The target record's start_time.

 required

Returns:

Type Description
int

Microseconds from the record's relative zero.

Raises:

Type Description
TimeFValidationError

If start_time is None. A record with no wall-clock anchor has no calendar time to measure a moment against.

seconds_to_us source

seconds_to_us(seconds: float) -> int

Round seconds onto the microsecond timeline.

Parameters:

Name Type Description Default
seconds float

A time offset or duration in seconds.

 required

Returns:

Type Description
int

The nearest whole microsecond.

unix_us source

unix_us(moment: datetime | int) -> int

Normalize a wall-clock timestamp to Unix microseconds.

This accepts two forms. A timezone-aware :class:~datetime.datetime already resolves to microseconds, so this changes the origin without rounding. An int passes through, for a source that gives microseconds directly.

This refuses a float. The value 1700000000.5 can mean seconds or microseconds, and the wrong reading is off by a factor of a million. If the source gives seconds, wrap it in :func:seconds_to_us so the unit is visible at the call site.

Parameters:

Name Type Description Default
moment datetime | int

A timezone-aware datetime, or whole Unix microseconds.

 required

Returns:

Type Description
int

Unix microseconds.

Raises:

Type Description
TimeFValidationError

If moment is a float, any other type, or a naive datetime. A naive datetime reads in the local zone of the building machine. That anchors the same recording differently for each builder.

us_to_seconds source

us_to_seconds(microseconds: int) -> float

Render microseconds back as seconds.

This is exact for everything TimeF can store. A value written in seconds reads back equal to itself, unless it was finer than a microsecond.

Parameters:

Name Type Description Default
microseconds int

A time offset or duration in microseconds.

 required

Returns:

Type Description
float

The same quantity in seconds.

use_as_application_registry source

use_as_application_registry() -> None

Make TimeNet's registry pint's process-wide application registry.

Opt in for two cases. First, when you pickle bare :class:pint.Unit or :class:pint.Quantity objects built from :data:ureg, because custom units such as bpm otherwise fail to unpickle. Second, when you want units from :data:ureg to compare and convert against units another library built.

Importing this module does not call this function. It replaces the process-wide registry, so a host with its own registry can break. Call it once from application startup, where the decision is yours.

This is a global assignment, not a merge. The last call wins, and any custom units that a previously installed registry defined stop resolving.

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.

validate_dataset_id source

validate_dataset_id(dataset_id: str) -> None

Check that a dataset id is a safe org/name pair.

The registry, the writer, and the download cache join ids into filesystem paths. This check is the only gate that stops an id from naming a location outside its root.

Parameters:

Name Type Description Default
dataset_id str

The id to check.

 required

Raises:

Type Description
TimeFValidationError

If the id is not a single-slash org/name pair, or has a segment starting with ..

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" | "map", or None for a pure marker.

Raises:

Type Description
TimeFValidationError

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