Types
timenet.types ¶source
TimeF value types and type system: versions, units, enums, specs, annotations, tasks, metadata.
Access ¶source
Bases: StrEnum
How a user obtains the source data.
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
Record timeline it applies. Its owner determines which Signals it covers. 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))
The class is final. Reuse content as a constant, or build content that varies with a function::
HEALTHY_ANNOTATION = Annotation(key="condition", value="healthy")
def quality_annotation(level: Literal["low", "medium", "high"]) -> Annotation:
return Annotation(key="quality", value=level)
confidence
class-attribute
instance-attribute
¶source
Optional confidence for this particular application.
description
class-attribute
instance-attribute
¶source
description: str | None = None
Optional human-readable description of the annotation.
metadata
class-attribute
instance-attribute
¶source
metadata: JsonMapping = field(default_factory=dict)
Optional metadata that is part of the reusable content.
occurrence_metadata
class-attribute
instance-attribute
¶source
occurrence_metadata: JsonMapping = field(
default_factory=dict, compare=False
)
Optional metadata for this particular application.
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 Record timeline this annotation applies. Its owner determines its scope.
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.
AnnotationDescriptor ¶source
Bases: TimeFModel
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
Optional human-readable description of the annotation.
model_config
class-attribute
instance-attribute
¶source
model_config = ConfigDict(
extra="forbid",
frozen=True,
revalidate_instances="always",
serialize_by_alias=True,
validate_by_name=True,
validate_default=True,
)
unit
class-attribute
instance-attribute
¶source
unit: Annotated[
StrictStr | None, BeforeValidator(normalize_unit)
] = None
Optional physical unit of the value.
AnnotationType ¶source
Bases: StrEnum
Name the shape an annotation key takes across the dataset. It is a schema-level projection in the manifest.
AnswerTask
dataclass
¶source
Bases: Task
Answer a question or caption the inputs.
annotations
class-attribute
instance-attribute
¶source
annotations: tuple[Annotation, ...] = ()
Annotations describing this task itself.
id
property
¶source
id: EntityId
The task's id, unique among the tasks of its dataset.
:meth:~timenet.dataset.TimeFDataset.add_task sets it. The reader sets it when it reads the task back.
Raises:
| Type | Description |
|---|---|
TimeFValidationError
|
If the task is not in a dataset yet. |
input_annotations
class-attribute
instance-attribute
¶source
input_annotations: tuple[Annotation, ...] = field(
default=(), compare=False
)
Existing annotation occurrences supplied to the model as context.
input_modalities
class-attribute
instance-attribute
¶source
input_modalities: frozenset[InputModality] | None = None
Optional override. None infers the input kinds when resolved or written.
metadata
class-attribute
instance-attribute
¶source
metadata: JsonMapping = field(default_factory=dict)
Optional JSON-compatible task metadata.
prompt
class-attribute
instance-attribute
¶source
prompt: ValueField[
str | TextHandle | None, TextHandle | None
] = field(default=ValueField(optional_text, None))
Call read() for the prompt; None identifies an unprompted task.
rationale
class-attribute
instance-attribute
¶source
rationale: ValueField[
str | TextHandle | None, TextHandle | None
] = field(default=ValueField(optional_text, None))
Call read() for the explanation; None means no rationale is present.
resolved_input_modalities
property
¶source
resolved_input_modalities: frozenset[InputModality]
The validated override, or kinds inferred from the current inputs.
Inference reads Signal specs within the scope, the prompt, and text input annotations. It does not load values or inspect targets. NO_INPUT means there are no input Records. The result is not cached: connectors can assign inputs after construction.
scope
class-attribute
instance-attribute
¶source
scope: Span | None = None
Optional region of the inputs to which the task applies.
split
class-attribute
instance-attribute
¶source
split: Split | None = None
The partition the task belongs to: train, validation, or test. None when the dataset does not partition its tasks.
target_annotations
class-attribute
instance-attribute
¶source
target_annotations: tuple[Annotation, ...] = field(
default=(), compare=False
)
Existing annotation occurrences that form the expected output.
targets
class-attribute
instance-attribute
¶source
targets: ValueField[
Iterable[TargetInput] | None,
tuple[TargetItem, ...] | None,
] = field(
default=ValueField(_target_values, None), compare=False
)
Ordered native values and stored objects that form the expected output.
annotate ¶source
annotate(annotation: Annotation) -> Annotation
Attach one annotation occurrence and return it.
Returns:
| Type | Description |
|---|---|
Annotation
|
The attached occurrence. |
named_records ¶source
Return the Records that the task names, each once: its inputs, then its Record targets.
A task class with candidate Records returns them too, after the inputs.
referenced_signals ¶source
Return the Signals that the task references, each once.
They are its Signal targets, then the Signals that its scope and its span targets name, in the
order of :meth:spans.
register_label_set ¶source
register_label_set(label_sets: LabelSetRegistry) -> None
Add the label set of the task to the dataset's label sets.
Only a classification task has a label set.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
label_sets
|
LabelSetRegistry
|
The label sets of the dataset so far. |
required |
with_references ¶source
Return a copy of the task that references the given Records and Signals, by ID.
The copy has the class of the task. Each input, candidate Record, Record target, and Signal
target of the copy is the object of the same ID in records or signals. The scope and
the span targets of the copy name the Signals of the same IDs in signals. Each span keeps
its class. The copy has no ID.
Every other field keeps its value: the annotations of the task, the annotations that it
references, from_tasks, the text, and the metadata. A caller that needs other values for
them sets them on the copy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
records
|
Mapping[EntityId, Record]
|
The Records for the copy, by ID. |
required |
signals
|
Mapping[EntityId, Signal]
|
The Signals for the copy, by ID. |
required |
Returns:
| Type | Description |
|---|---|
Self
|
The copy. |
Raises:
| Type | Description |
|---|---|
TimeFValidationError
|
If a Record or Signal that the task references has no ID, or if
|
ArrayHandle ¶source
Bases: ValueHandle[Array]
Refer to one array with one value per step, as Arrow, as NumPy, or as a range of steps.
A handle returns the values as it holds or stores them, nulls included, and checks them against no spec.
is_loaded
abstractmethod
property
¶source
is_loaded: bool
Whether the value is held in memory, so read() needs no storage access.
read_numpy ¶source
Return the values as a read-only NumPy array, shaped (n_steps, *value_shape).
The default converts :meth:read. A handle whose data is NumPy already returns it without
building Arrow.
Returns:
| Type | Description |
|---|---|
ndarray
|
The values, in the NumPy dtype of their Arrow type. |
Raises:
| Type | Description |
|---|---|
TimeFNullValuesError
|
If the values contain nulls, which NumPy cannot hold. Read them
with :meth: |
read_steps ¶source
Return the half-open step range [start, stop).
The default slices :meth:read, so a stop past the end reads to the end. A stored
handle reads only the chunks that cover the range.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
start
|
int
|
First step, inclusive, and not negative. |
required |
stop
|
int
|
Last step, exclusive, and not before |
required |
Returns:
| Type | Description |
|---|---|
Array
|
The steps' values, in the form :meth: |
ClassificationTask
dataclass
¶source
Bases: Task
Classify the inputs using a required set of allowed labels.
annotations
class-attribute
instance-attribute
¶source
annotations: tuple[Annotation, ...] = ()
Annotations describing this task itself.
id
property
¶source
id: EntityId
The task's id, unique among the tasks of its dataset.
:meth:~timenet.dataset.TimeFDataset.add_task sets it. The reader sets it when it reads the task back.
Raises:
| Type | Description |
|---|---|
TimeFValidationError
|
If the task is not in a dataset yet. |
input_annotations
class-attribute
instance-attribute
¶source
input_annotations: tuple[Annotation, ...] = field(
default=(), compare=False
)
Existing annotation occurrences supplied to the model as context.
input_modalities
class-attribute
instance-attribute
¶source
input_modalities: frozenset[InputModality] | None = None
Optional override. None infers the input kinds when resolved or written.
label_set
instance-attribute
¶source
label_set: LabelSet
The allowed labels and whether a target can contain more than one label.
metadata
class-attribute
instance-attribute
¶source
metadata: JsonMapping = field(default_factory=dict)
Optional JSON-compatible task metadata.
prompt
class-attribute
instance-attribute
¶source
prompt: ValueField[
str | TextHandle | None, TextHandle | None
] = field(default=ValueField(optional_text, None))
Call read() for the prompt; None identifies an unprompted task.
rationale
class-attribute
instance-attribute
¶source
rationale: ValueField[
str | TextHandle | None, TextHandle | None
] = field(default=ValueField(optional_text, None))
Call read() for the explanation; None means no rationale is present.
resolved_input_modalities
property
¶source
resolved_input_modalities: frozenset[InputModality]
The validated override, or kinds inferred from the current inputs.
Inference reads Signal specs within the scope, the prompt, and text input annotations. It does not load values or inspect targets. NO_INPUT means there are no input Records. The result is not cached: connectors can assign inputs after construction.
scope
class-attribute
instance-attribute
¶source
scope: Span | None = None
Optional region of the inputs to which the task applies.
split
class-attribute
instance-attribute
¶source
split: Split | None = None
The partition the task belongs to: train, validation, or test. None when the dataset does not partition its tasks.
target_annotations
class-attribute
instance-attribute
¶source
target_annotations: tuple[Annotation, ...] = field(
default=(), compare=False
)
Existing annotation occurrences that form the expected output.
targets
class-attribute
instance-attribute
¶source
targets: ValueField[
Iterable[TargetInput] | None,
tuple[TargetItem, ...] | None,
] = field(
default=ValueField(_target_values, None), compare=False
)
Ordered native values and stored objects that form the expected output.
annotate ¶source
annotate(annotation: Annotation) -> Annotation
Attach one annotation occurrence and return it.
Returns:
| Type | Description |
|---|---|
Annotation
|
The attached occurrence. |
check_targets ¶source
Make sure that the target labels follow the rules of the label set.
The labels come from the targets stored directly on the task or from its target annotations. Each label must be text.
After the targets are final, the dataset calls this method when it adds or streams the task.
Raises:
| Type | Description |
|---|---|
TimeFValidationError
|
If a label is not text or the labels break a rule of the label set. |
named_records ¶source
Return the Records that the task names, each once: its inputs, then its Record targets.
A task class with candidate Records returns them too, after the inputs.
referenced_signals ¶source
Return the Signals that the task references, each once.
They are its Signal targets, then the Signals that its scope and its span targets name, in the
order of :meth:spans.
register_label_set ¶source
register_label_set(label_sets: LabelSetRegistry) -> None
Add the label set of the task to the dataset's label sets.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
label_sets
|
LabelSetRegistry
|
The label sets of the dataset so far. |
required |
Raises:
| Type | Description |
|---|---|
TimeFValidationError
|
If a different set already has the same name. |
with_references ¶source
Return a copy of the task that references the given Records and Signals, by ID.
The copy has the class of the task. Each input, candidate Record, Record target, and Signal
target of the copy is the object of the same ID in records or signals. The scope and
the span targets of the copy name the Signals of the same IDs in signals. Each span keeps
its class. The copy has no ID.
Every other field keeps its value: the annotations of the task, the annotations that it
references, from_tasks, the text, and the metadata. A caller that needs other values for
them sets them on the copy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
records
|
Mapping[EntityId, Record]
|
The Records for the copy, by ID. |
required |
signals
|
Mapping[EntityId, Signal]
|
The Signals for the copy, by ID. |
required |
Returns:
| Type | Description |
|---|---|
Self
|
The copy. |
Raises:
| Type | Description |
|---|---|
TimeFValidationError
|
If a Record or Signal that the task references has no ID, or if
|
DatasetMetadata ¶source
Bases: TimeFModel
Dataset identity, release version, source information, and access requirements.
The dataset card defines these fields. dataset_version identifies the TimeNet release.
source_revision identifies the original source release, tag, or commit.
yaml_schema_version identifies the card schema. dataset_id is a case-sensitive
org/name pair with exactly one slash. Casing-only differences can cause conflicts on
case-insensitive filesystems.
access
class-attribute
instance-attribute
¶source
How a user obtains the data (see :class:Access). OPEN needs nothing.
An import into a child dataset does not change it. The level that applies to a release with
parents is :func:~timenet.types.access.effective_access.
access_url
class-attribute
instance-attribute
¶source
Where to obtain access (the DUA or credentialing page). Required when access is not OPEN.
citation
class-attribute
instance-attribute
¶source
How to cite the dataset, when the source asks for attribution.
dataset_id
instance-attribute
¶source
HuggingFace-style org/name pair, case-sensitive, exactly one slash.
license
instance-attribute
¶source
license: License
Legal license of the source data, as an SPDX-style identifier.
license_url
class-attribute
instance-attribute
¶source
Where to read the full license text. Required and nonblank when license is :attr:License.OTHER.
model_config
class-attribute
instance-attribute
¶source
model_config = ConfigDict(
extra="forbid",
frozen=True,
revalidate_instances="always",
serialize_by_alias=True,
validate_by_name=True,
validate_default=True,
)
parents
class-attribute
instance-attribute
¶source
Exact parent releases indexed by connector-local aliases.
source_revision
class-attribute
instance-attribute
¶source
Upstream release, tag, or commit, separate from the compiled dataset version.
tags
class-attribute
instance-attribute
¶source
tags: tuple[StrictStr, ...] = ()
Free-form tags for search and grouping.
yaml_schema_version
class-attribute
instance-attribute
¶source
Version of the card's own field schema.
from_yaml
classmethod
¶source
from_yaml(path: str | Path) -> DatasetMetadata
Load and validate a dataset card YAML into metadata.
Authoring mistakes surface as clear, aggregated messages instead of a stack trace from deep
inside coercion. PyYAML is optional and imported lazily. Install the timenet[build] extra
to use this method.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | Path
|
Path to the card YAML file. |
required |
Returns:
| Type | Description |
|---|---|
DatasetMetadata
|
The constructed :class: |
Raises:
| Type | Description |
|---|---|
TimeNetInvalidCardError
|
If the build extra is missing, or the card is unreadable or is not a mapping. |
DatasetSchema ¶source
Bases: TimeFModel
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.
model_config
class-attribute
instance-attribute
¶source
model_config = ConfigDict(
extra="forbid",
frozen=True,
revalidate_instances="always",
serialize_by_alias=True,
validate_by_name=True,
validate_default=True,
)
tasks
class-attribute
instance-attribute
¶source
tasks: tuple[TaskDeclaration, ...] = ()
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
What people are doing: labeled human activities and daily behavior, usually from wearables.
Declare motion as well when the signals record the movement itself.
AUDIO
class-attribute
instance-attribute
¶source
Recorded sound: speech, cough, and environmental audio.
ECONOMICS
class-attribute
instance-attribute
¶source
Economic activity: macroeconomic indicators, prices, sales, and demand.
ENERGY
class-attribute
instance-attribute
¶source
Energy systems: electricity load, generation, power grids, and transformers.
ENVIRONMENT
class-attribute
instance-attribute
¶source
The natural world: weather, climate, air quality, and hydrology.
FINANCE
class-attribute
instance-attribute
¶source
Financial markets: asset prices, returns, trading volumes, and exchange rates.
GENERAL
class-attribute
instance-attribute
¶source
No particular field: synthetic or demo data, or generic series without a stated origin.
A corpus that mixes such data with field-specific components declares those domains too.
HEALTH
class-attribute
instance-attribute
¶source
Human physiology and clinical care: biosignals, vital signs, clinical records, glucose.
The umbrella for cardiology, respiratory, and sleep. Declare it alongside them.
INDUSTRIAL
class-attribute
instance-attribute
¶source
Machines and industrial processes: engines, turbines, bearings, and production equipment.
Covers condition monitoring, degradation, fault diagnosis, and remaining useful life, including simulated run-to-failure data.
MOTION
class-attribute
instance-attribute
¶source
Movement of a body or an object: accelerometer, gyroscope, magnetometer, and motion capture.
OBSERVABILITY
class-attribute
instance-attribute
¶source
Software and IT infrastructure: service metrics and cloud monitoring.
RESPIRATORY
class-attribute
instance-attribute
¶source
Breathing and the lungs: respiration, airflow, oxygen saturation, and cough.
ForecastingTask
dataclass
¶source
Bases: Task
Predict future values from the supplied inputs.
annotations
class-attribute
instance-attribute
¶source
annotations: tuple[Annotation, ...] = ()
Annotations describing this task itself.
id
property
¶source
id: EntityId
The task's id, unique among the tasks of its dataset.
:meth:~timenet.dataset.TimeFDataset.add_task sets it. The reader sets it when it reads the task back.
Raises:
| Type | Description |
|---|---|
TimeFValidationError
|
If the task is not in a dataset yet. |
input_annotations
class-attribute
instance-attribute
¶source
input_annotations: tuple[Annotation, ...] = field(
default=(), compare=False
)
Existing annotation occurrences supplied to the model as context.
input_modalities
class-attribute
instance-attribute
¶source
input_modalities: frozenset[InputModality] | None = None
Optional override. None infers the input kinds when resolved or written.
metadata
class-attribute
instance-attribute
¶source
metadata: JsonMapping = field(default_factory=dict)
Optional JSON-compatible task metadata.
prompt
class-attribute
instance-attribute
¶source
prompt: ValueField[
str | TextHandle | None, TextHandle | None
] = field(default=ValueField(optional_text, None))
Call read() for the prompt; None identifies an unprompted task.
rationale
class-attribute
instance-attribute
¶source
rationale: ValueField[
str | TextHandle | None, TextHandle | None
] = field(default=ValueField(optional_text, None))
Call read() for the explanation; None means no rationale is present.
resolved_input_modalities
property
¶source
resolved_input_modalities: frozenset[InputModality]
The validated override, or kinds inferred from the current inputs.
Inference reads Signal specs within the scope, the prompt, and text input annotations. It does not load values or inspect targets. NO_INPUT means there are no input Records. The result is not cached: connectors can assign inputs after construction.
scope
class-attribute
instance-attribute
¶source
scope: Span | None = None
Optional region of the inputs to which the task applies.
split
class-attribute
instance-attribute
¶source
split: Split | None = None
The partition the task belongs to: train, validation, or test. None when the dataset does not partition its tasks.
target_annotations
class-attribute
instance-attribute
¶source
target_annotations: tuple[Annotation, ...] = field(
default=(), compare=False
)
Existing annotation occurrences that form the expected output.
targets
class-attribute
instance-attribute
¶source
targets: ValueField[
Iterable[TargetInput] | None,
tuple[TargetItem, ...] | None,
] = field(
default=ValueField(_target_values, None), compare=False
)
Ordered native values and stored objects that form the expected output.
annotate ¶source
annotate(annotation: Annotation) -> Annotation
Attach one annotation occurrence and return it.
Returns:
| Type | Description |
|---|---|
Annotation
|
The attached occurrence. |
named_records ¶source
Return the Records that the task names, each once: its inputs, then its Record targets.
A task class with candidate Records returns them too, after the inputs.
referenced_signals ¶source
Return the Signals that the task references, each once.
They are its Signal targets, then the Signals that its scope and its span targets name, in the
order of :meth:spans.
register_label_set ¶source
register_label_set(label_sets: LabelSetRegistry) -> None
Add the label set of the task to the dataset's label sets.
Only a classification task has a label set.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
label_sets
|
LabelSetRegistry
|
The label sets of the dataset so far. |
required |
with_references ¶source
Return a copy of the task that references the given Records and Signals, by ID.
The copy has the class of the task. Each input, candidate Record, Record target, and Signal
target of the copy is the object of the same ID in records or signals. The scope and
the span targets of the copy name the Signals of the same IDs in signals. Each span keeps
its class. The copy has no ID.
Every other field keeps its value: the annotations of the task, the annotations that it
references, from_tasks, the text, and the metadata. A caller that needs other values for
them sets them on the copy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
records
|
Mapping[EntityId, Record]
|
The Records for the copy, by ID. |
required |
signals
|
Mapping[EntityId, Signal]
|
The Signals for the copy, by ID. |
required |
Returns:
| Type | Description |
|---|---|
Self
|
The copy. |
Raises:
| Type | Description |
|---|---|
TimeFValidationError
|
If a Record or Signal that the task references has no ID, or if
|
Label ¶source
Bases: TimeFModel
One label in a label set, such as awake in a sleep-stage task.
description
class-attribute
instance-attribute
¶source
What the label means, such as The subject is awake..
LabelSet ¶source
Bases: TimeFModel
The allowed labels for a classification target.
A target must contain one label unless multi_label=True.
Tasks that ask the same kind of question share one label set::
SLEEP_STAGE = LabelSet(
name="sleep_stage",
labels=(
Label(name="awake", description="The subject is awake."),
Label(name="non_rem_sleep"),
Label(name="rem_sleep"),
),
)
ClassificationTask(inputs=(record,), targets=("awake",), label_set=SLEEP_STAGE)
Each name identifies one label set in a dataset.
model_config
class-attribute
instance-attribute
¶source
model_config = ConfigDict(
extra="forbid",
frozen=True,
revalidate_instances="always",
serialize_by_alias=True,
validate_by_name=True,
validate_default=True,
)
multi_label
class-attribute
instance-attribute
¶source
If False, a target holds exactly one label from the set.
If True, a target holds all labels from the set that apply.
An empty target means that no label applies.
check_targets ¶source
Make sure that the target labels follow the rules of this set.
For a set with the labels W, N1 and R, the rules are:
- Each label must be in the set.
("X",)fails. - If
multi_labelisFalse, the target holds exactly one label.("W",)passes.()and("W", "R")fail. - No label can repeat.
("W", "W")fails, also whenmulti_labelisTrue.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
targets
|
Sequence[str]
|
The target labels, in the order that the task stores them. |
required |
Raises:
| Type | Description |
|---|---|
TimeFValidationError
|
If a label is not in the set or a label repeats. Also if a single-label target does not hold exactly one label. |
LabelSetRegistry ¶source
The label sets of a dataset, with one set per name.
The sets stay in the order in which tasks first added them.
copy ¶source
copy() -> LabelSetRegistry
Return a separate registry with the same label sets.
The dataset uses the copy to check a batch before adding its tasks. If a task fails, the dataset discards the copy and keeps its original registry.
Returns:
| Type | Description |
|---|---|
LabelSetRegistry
|
The copy. |
register_or_reuse_matching_label_set ¶source
Store a label set by name.
If the registry already holds an equal set with this name, return that set.
Returns:
| Type | Description |
|---|---|
LabelSet
|
The set that the registry holds under the name. |
Raises:
| Type | Description |
|---|---|
TimeFValidationError
|
If a different set already has the same name. |
LazyText ¶source
Bases: _LazyTextBehaviour[str], TextHandle
Read one string through the supplied function on each request.
A connector can use this handle to load text from a source file. The writer stores the text in a separate payload file so readers can load it on request.
length
property
¶source
length: int
The number of characters or list items.
If the caller omits length, the first access reads the text to calculate it.
read ¶source
Return the text from the supplied function.
Raises:
| Type | Description |
|---|---|
TimeFValidationError
|
If the result has the wrong type or its length differs from the known length. |
LazyTextList ¶source
Bases: _LazyTextBehaviour[list[str]], TextListHandle
Read a list of strings through the supplied function on each request.
A connector can use this handle to load strings from a source file. The writer stores the list in a separate payload file so readers can load it on request.
length
property
¶source
length: int
The number of characters or list items.
If the caller omits length, the first access reads the text to calculate it.
read ¶source
Return the text from the supplied function.
Raises:
| Type | Description |
|---|---|
TimeFValidationError
|
If the result has the wrong type or its length differs from the known length. |
License ¶source
ScalarPredictionTask
dataclass
¶source
Bases: Task
Predict one or more quantities described by the task configuration.
annotations
class-attribute
instance-attribute
¶source
annotations: tuple[Annotation, ...] = ()
Annotations describing this task itself.
id
property
¶source
id: EntityId
The task's id, unique among the tasks of its dataset.
:meth:~timenet.dataset.TimeFDataset.add_task sets it. The reader sets it when it reads the task back.
Raises:
| Type | Description |
|---|---|
TimeFValidationError
|
If the task is not in a dataset yet. |
input_annotations
class-attribute
instance-attribute
¶source
input_annotations: tuple[Annotation, ...] = field(
default=(), compare=False
)
Existing annotation occurrences supplied to the model as context.
input_modalities
class-attribute
instance-attribute
¶source
input_modalities: frozenset[InputModality] | None = None
Optional override. None infers the input kinds when resolved or written.
metadata
class-attribute
instance-attribute
¶source
metadata: JsonMapping = field(default_factory=dict)
Optional JSON-compatible task metadata.
prompt
class-attribute
instance-attribute
¶source
prompt: ValueField[
str | TextHandle | None, TextHandle | None
] = field(default=ValueField(optional_text, None))
Call read() for the prompt; None identifies an unprompted task.
rationale
class-attribute
instance-attribute
¶source
rationale: ValueField[
str | TextHandle | None, TextHandle | None
] = field(default=ValueField(optional_text, None))
Call read() for the explanation; None means no rationale is present.
resolved_input_modalities
property
¶source
resolved_input_modalities: frozenset[InputModality]
The validated override, or kinds inferred from the current inputs.
Inference reads Signal specs within the scope, the prompt, and text input annotations. It does not load values or inspect targets. NO_INPUT means there are no input Records. The result is not cached: connectors can assign inputs after construction.
scope
class-attribute
instance-attribute
¶source
scope: Span | None = None
Optional region of the inputs to which the task applies.
split
class-attribute
instance-attribute
¶source
split: Split | None = None
The partition the task belongs to: train, validation, or test. None when the dataset does not partition its tasks.
target_annotations
class-attribute
instance-attribute
¶source
target_annotations: tuple[Annotation, ...] = field(
default=(), compare=False
)
Existing annotation occurrences that form the expected output.
target_name
class-attribute
instance-attribute
¶source
target_name: str | None = None
Optional name of the predicted quantity.
targets
class-attribute
instance-attribute
¶source
targets: ValueField[
Iterable[TargetInput] | None,
tuple[TargetItem, ...] | None,
] = field(
default=ValueField(_target_values, None), compare=False
)
Ordered native values and stored objects that form the expected output.
unit
class-attribute
instance-attribute
¶source
unit: str | Unit | None = None
Optional physical unit shared by numerical target items.
annotate ¶source
annotate(annotation: Annotation) -> Annotation
Attach one annotation occurrence and return it.
Returns:
| Type | Description |
|---|---|
Annotation
|
The attached occurrence. |
named_records ¶source
Return the Records that the task names, each once: its inputs, then its Record targets.
A task class with candidate Records returns them too, after the inputs.
referenced_signals ¶source
Return the Signals that the task references, each once.
They are its Signal targets, then the Signals that its scope and its span targets name, in the
order of :meth:spans.
register_label_set ¶source
register_label_set(label_sets: LabelSetRegistry) -> None
Add the label set of the task to the dataset's label sets.
Only a classification task has a label set.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
label_sets
|
LabelSetRegistry
|
The label sets of the dataset so far. |
required |
with_references ¶source
Return a copy of the task that references the given Records and Signals, by ID.
The copy has the class of the task. Each input, candidate Record, Record target, and Signal
target of the copy is the object of the same ID in records or signals. The scope and
the span targets of the copy name the Signals of the same IDs in signals. Each span keeps
its class. The copy has no ID.
Every other field keeps its value: the annotations of the task, the annotations that it
references, from_tasks, the text, and the metadata. A caller that needs other values for
them sets them on the copy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
records
|
Mapping[EntityId, Record]
|
The Records for the copy, by ID. |
required |
signals
|
Mapping[EntityId, Signal]
|
The Signals for the copy, by ID. |
required |
Returns:
| Type | Description |
|---|---|
Self
|
The copy. |
Raises:
| Type | Description |
|---|---|
TimeFValidationError
|
If a Record or Signal that the task references has no ID, or if
|
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.
StepInterval
dataclass
¶source
Bases: StepSpan
The half-open range [start, stop) of step ordinals on the named series.
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.
StepPoint
dataclass
¶source
Bases: StepSpan
One step ordinal on the named series.
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
series in time_series. 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.
is_point
class-attribute
¶source
is_point: bool = False
Whether this span marks a single position rather than a bounded interval.
SupportsAnnotate ¶source
Bases: Protocol
Anything an annotation occurrence can be attached to.
annotate binds a fresh occurrence of annotation to this object and returns it; the
returned occurrence is what a Task names in input_annotations or target_annotations.
annotations lists every occurrence attached so far. Records, Sources, Signals, Tasks, and
the dataset itself implement it. A :class:~timenet.dataset.SignalSelection does not: it fans
one annotation out over several Signals and returns every occurrence it created. The contract is
checked statically; there is no runtime isinstance support because annotations is a
property.
annotations
property
¶source
annotations: tuple[Annotation, ...]
The occurrences attached to this object.
annotate ¶source
annotate(annotation: Annotation) -> Annotation
Attach one occurrence of annotation and return it.
TSCorrespondenceTask
dataclass
¶source
Bases: Task
Relate input recordings to an optional candidate pool.
annotations
class-attribute
instance-attribute
¶source
annotations: tuple[Annotation, ...] = ()
Annotations describing this task itself.
candidate_records
class-attribute
instance-attribute
¶source
Optional candidate pool. An empty tuple means the dataset-wide pool.
id
property
¶source
id: EntityId
The task's id, unique among the tasks of its dataset.
:meth:~timenet.dataset.TimeFDataset.add_task sets it. The reader sets it when it reads the task back.
Raises:
| Type | Description |
|---|---|
TimeFValidationError
|
If the task is not in a dataset yet. |
input_annotations
class-attribute
instance-attribute
¶source
input_annotations: tuple[Annotation, ...] = field(
default=(), compare=False
)
Existing annotation occurrences supplied to the model as context.
input_modalities
class-attribute
instance-attribute
¶source
input_modalities: frozenset[InputModality] | None = None
Optional override. None infers the input kinds when resolved or written.
metadata
class-attribute
instance-attribute
¶source
metadata: JsonMapping = field(default_factory=dict)
Optional JSON-compatible task metadata.
prompt
class-attribute
instance-attribute
¶source
prompt: ValueField[
str | TextHandle | None, TextHandle | None
] = field(default=ValueField(optional_text, None))
Call read() for the prompt; None identifies an unprompted task.
rationale
class-attribute
instance-attribute
¶source
rationale: ValueField[
str | TextHandle | None, TextHandle | None
] = field(default=ValueField(optional_text, None))
Call read() for the explanation; None means no rationale is present.
resolved_input_modalities
property
¶source
resolved_input_modalities: frozenset[InputModality]
The validated override, or kinds inferred from the current inputs.
Inference reads Signal specs within the scope, the prompt, and text input annotations. It does not load values or inspect targets. NO_INPUT means there are no input Records. The result is not cached: connectors can assign inputs after construction.
scope
class-attribute
instance-attribute
¶source
scope: Span | None = None
Optional region of the inputs to which the task applies.
split
class-attribute
instance-attribute
¶source
split: Split | None = None
The partition the task belongs to: train, validation, or test. None when the dataset does not partition its tasks.
target_annotations
class-attribute
instance-attribute
¶source
target_annotations: tuple[Annotation, ...] = field(
default=(), compare=False
)
Existing annotation occurrences that form the expected output.
targets
class-attribute
instance-attribute
¶source
targets: ValueField[
Iterable[TargetInput] | None,
tuple[TargetItem, ...] | None,
] = field(
default=ValueField(_target_values, None), compare=False
)
Ordered native values and stored objects that form the expected output.
annotate ¶source
annotate(annotation: Annotation) -> Annotation
Attach one annotation occurrence and return it.
Returns:
| Type | Description |
|---|---|
Annotation
|
The attached occurrence. |
named_records ¶source
Return the Records that the task names, each once.
They are its inputs, its candidate Records, then its Record targets.
referenced_signals ¶source
Return the Signals that the task references, each once.
They are its Signal targets, then the Signals that its scope and its span targets name, in the
order of :meth:spans.
register_label_set ¶source
register_label_set(label_sets: LabelSetRegistry) -> None
Add the label set of the task to the dataset's label sets.
Only a classification task has a label set.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
label_sets
|
LabelSetRegistry
|
The label sets of the dataset so far. |
required |
with_references ¶source
Return a copy of the task that references the given Records and Signals, by ID.
The copy has the class of the task. Each input, candidate Record, Record target, and Signal
target of the copy is the object of the same ID in records or signals. The scope and
the span targets of the copy name the Signals of the same IDs in signals. Each span keeps
its class. The copy has no ID.
Every other field keeps its value: the annotations of the task, the annotations that it
references, from_tasks, the text, and the metadata. A caller that needs other values for
them sets them on the copy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
records
|
Mapping[EntityId, Record]
|
The Records for the copy, by ID. |
required |
signals
|
Mapping[EntityId, Signal]
|
The Signals for the copy, by ID. |
required |
Returns:
| Type | Description |
|---|---|
Self
|
The copy. |
Raises:
| Type | Description |
|---|---|
TimeFValidationError
|
If a Record or Signal that the task references has no ID, or if
|
TSEditingTask
dataclass
¶source
Bases: Task
Transform the input recording into the output described by targets.
annotations
class-attribute
instance-attribute
¶source
annotations: tuple[Annotation, ...] = ()
Annotations describing this task itself.
id
property
¶source
id: EntityId
The task's id, unique among the tasks of its dataset.
:meth:~timenet.dataset.TimeFDataset.add_task sets it. The reader sets it when it reads the task back.
Raises:
| Type | Description |
|---|---|
TimeFValidationError
|
If the task is not in a dataset yet. |
input_annotations
class-attribute
instance-attribute
¶source
input_annotations: tuple[Annotation, ...] = field(
default=(), compare=False
)
Existing annotation occurrences supplied to the model as context.
input_modalities
class-attribute
instance-attribute
¶source
input_modalities: frozenset[InputModality] | None = None
Optional override. None infers the input kinds when resolved or written.
metadata
class-attribute
instance-attribute
¶source
metadata: JsonMapping = field(default_factory=dict)
Optional JSON-compatible task metadata.
prompt
class-attribute
instance-attribute
¶source
prompt: ValueField[
str | TextHandle | None, TextHandle | None
] = field(default=ValueField(optional_text, None))
Call read() for the prompt; None identifies an unprompted task.
rationale
class-attribute
instance-attribute
¶source
rationale: ValueField[
str | TextHandle | None, TextHandle | None
] = field(default=ValueField(optional_text, None))
Call read() for the explanation; None means no rationale is present.
resolved_input_modalities
property
¶source
resolved_input_modalities: frozenset[InputModality]
The validated override, or kinds inferred from the current inputs.
Inference reads Signal specs within the scope, the prompt, and text input annotations. It does not load values or inspect targets. NO_INPUT means there are no input Records. The result is not cached: connectors can assign inputs after construction.
scope
class-attribute
instance-attribute
¶source
scope: Span | None = None
Optional region of the inputs to which the task applies.
split
class-attribute
instance-attribute
¶source
split: Split | None = None
The partition the task belongs to: train, validation, or test. None when the dataset does not partition its tasks.
target_annotations
class-attribute
instance-attribute
¶source
target_annotations: tuple[Annotation, ...] = field(
default=(), compare=False
)
Existing annotation occurrences that form the expected output.
targets
class-attribute
instance-attribute
¶source
targets: ValueField[
Iterable[TargetInput] | None,
tuple[TargetItem, ...] | None,
] = field(
default=ValueField(_target_values, None), compare=False
)
Ordered native values and stored objects that form the expected output.
annotate ¶source
annotate(annotation: Annotation) -> Annotation
Attach one annotation occurrence and return it.
Returns:
| Type | Description |
|---|---|
Annotation
|
The attached occurrence. |
named_records ¶source
Return the Records that the task names, each once: its inputs, then its Record targets.
A task class with candidate Records returns them too, after the inputs.
referenced_signals ¶source
Return the Signals that the task references, each once.
They are its Signal targets, then the Signals that its scope and its span targets name, in the
order of :meth:spans.
register_label_set ¶source
register_label_set(label_sets: LabelSetRegistry) -> None
Add the label set of the task to the dataset's label sets.
Only a classification task has a label set.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
label_sets
|
LabelSetRegistry
|
The label sets of the dataset so far. |
required |
with_references ¶source
Return a copy of the task that references the given Records and Signals, by ID.
The copy has the class of the task. Each input, candidate Record, Record target, and Signal
target of the copy is the object of the same ID in records or signals. The scope and
the span targets of the copy name the Signals of the same IDs in signals. Each span keeps
its class. The copy has no ID.
Every other field keeps its value: the annotations of the task, the annotations that it
references, from_tasks, the text, and the metadata. A caller that needs other values for
them sets them on the copy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
records
|
Mapping[EntityId, Record]
|
The Records for the copy, by ID. |
required |
signals
|
Mapping[EntityId, Signal]
|
The Signals for the copy, by ID. |
required |
Returns:
| Type | Description |
|---|---|
Self
|
The copy. |
Raises:
| Type | Description |
|---|---|
TimeFValidationError
|
If a Record or Signal that the task references has no ID, or if
|
TSGenerationTask
dataclass
¶source
Bases: Task
Generate output described by the prompt, optionally without record inputs.
annotations
class-attribute
instance-attribute
¶source
annotations: tuple[Annotation, ...] = ()
Annotations describing this task itself.
id
property
¶source
id: EntityId
The task's id, unique among the tasks of its dataset.
:meth:~timenet.dataset.TimeFDataset.add_task sets it. The reader sets it when it reads the task back.
Raises:
| Type | Description |
|---|---|
TimeFValidationError
|
If the task is not in a dataset yet. |
input_annotations
class-attribute
instance-attribute
¶source
input_annotations: tuple[Annotation, ...] = field(
default=(), compare=False
)
Existing annotation occurrences supplied to the model as context.
input_modalities
class-attribute
instance-attribute
¶source
input_modalities: frozenset[InputModality] | None = None
Optional override. None infers the input kinds when resolved or written.
metadata
class-attribute
instance-attribute
¶source
metadata: JsonMapping = field(default_factory=dict)
Optional JSON-compatible task metadata.
prompt
class-attribute
instance-attribute
¶source
prompt: ValueField[
str | TextHandle | None, TextHandle | None
] = field(default=ValueField(optional_text, None))
Call read() for the prompt; None identifies an unprompted task.
rationale
class-attribute
instance-attribute
¶source
rationale: ValueField[
str | TextHandle | None, TextHandle | None
] = field(default=ValueField(optional_text, None))
Call read() for the explanation; None means no rationale is present.
resolved_input_modalities
property
¶source
resolved_input_modalities: frozenset[InputModality]
The validated override, or kinds inferred from the current inputs.
Inference reads Signal specs within the scope, the prompt, and text input annotations. It does not load values or inspect targets. NO_INPUT means there are no input Records. The result is not cached: connectors can assign inputs after construction.
scope
class-attribute
instance-attribute
¶source
scope: Span | None = None
Optional region of the inputs to which the task applies.
split
class-attribute
instance-attribute
¶source
split: Split | None = None
The partition the task belongs to: train, validation, or test. None when the dataset does not partition its tasks.
target_annotations
class-attribute
instance-attribute
¶source
target_annotations: tuple[Annotation, ...] = field(
default=(), compare=False
)
Existing annotation occurrences that form the expected output.
targets
class-attribute
instance-attribute
¶source
targets: ValueField[
Iterable[TargetInput] | None,
tuple[TargetItem, ...] | None,
] = field(
default=ValueField(_target_values, None), compare=False
)
Ordered native values and stored objects that form the expected output.
annotate ¶source
annotate(annotation: Annotation) -> Annotation
Attach one annotation occurrence and return it.
Returns:
| Type | Description |
|---|---|
Annotation
|
The attached occurrence. |
named_records ¶source
Return the Records that the task names, each once: its inputs, then its Record targets.
A task class with candidate Records returns them too, after the inputs.
referenced_signals ¶source
Return the Signals that the task references, each once.
They are its Signal targets, then the Signals that its scope and its span targets name, in the
order of :meth:spans.
register_label_set ¶source
register_label_set(label_sets: LabelSetRegistry) -> None
Add the label set of the task to the dataset's label sets.
Only a classification task has a label set.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
label_sets
|
LabelSetRegistry
|
The label sets of the dataset so far. |
required |
with_references ¶source
Return a copy of the task that references the given Records and Signals, by ID.
The copy has the class of the task. Each input, candidate Record, Record target, and Signal
target of the copy is the object of the same ID in records or signals. The scope and
the span targets of the copy name the Signals of the same IDs in signals. Each span keeps
its class. The copy has no ID.
Every other field keeps its value: the annotations of the task, the annotations that it
references, from_tasks, the text, and the metadata. A caller that needs other values for
them sets them on the copy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
records
|
Mapping[EntityId, Record]
|
The Records for the copy, by ID. |
required |
signals
|
Mapping[EntityId, Signal]
|
The Signals for the copy, by ID. |
required |
Returns:
| Type | Description |
|---|---|
Self
|
The copy. |
Raises:
| Type | Description |
|---|---|
TimeFValidationError
|
If a Record or Signal that the task references has no ID, or if
|
Task
dataclass
¶source
Bases: SupportsAnnotate
One modelling problem with ordered inputs and ordered output items.
Targets deliberately accept a mixture of supported values. Concrete task classes describe the modelling operation, but they do not impose a second hierarchy of target wrapper classes. None means that the answer is supplied through target annotations. An empty tuple is an explicit empty answer.
Only a concrete task class, one that sets task_type, can be built; Task itself cannot.
The task classes form a closed set. TimeF stores a task's task_type tag, and the reader maps
it back to a built-in class, so only this module defines subclasses, and each concrete class is
final. To reuse a prompt, write a function that builds a built-in task::
def age_question(record: Record, age: int) -> AnswerTask:
return AnswerTask(inputs=(record,), prompt="How old is the subject?", targets=(str(age),))
annotations
class-attribute
instance-attribute
¶source
annotations: tuple[Annotation, ...] = ()
Annotations describing this task itself.
id
property
¶source
id: EntityId
The task's id, unique among the tasks of its dataset.
:meth:~timenet.dataset.TimeFDataset.add_task sets it. The reader sets it when it reads the task back.
Raises:
| Type | Description |
|---|---|
TimeFValidationError
|
If the task is not in a dataset yet. |
input_annotations
class-attribute
instance-attribute
¶source
input_annotations: tuple[Annotation, ...] = field(
default=(), compare=False
)
Existing annotation occurrences supplied to the model as context.
input_modalities
class-attribute
instance-attribute
¶source
input_modalities: frozenset[InputModality] | None = None
Optional override. None infers the input kinds when resolved or written.
metadata
class-attribute
instance-attribute
¶source
metadata: JsonMapping = field(default_factory=dict)
Optional JSON-compatible task metadata.
prompt
class-attribute
instance-attribute
¶source
prompt: ValueField[
str | TextHandle | None, TextHandle | None
] = field(default=ValueField(optional_text, None))
Call read() for the prompt; None identifies an unprompted task.
rationale
class-attribute
instance-attribute
¶source
rationale: ValueField[
str | TextHandle | None, TextHandle | None
] = field(default=ValueField(optional_text, None))
Call read() for the explanation; None means no rationale is present.
resolved_input_modalities
property
¶source
resolved_input_modalities: frozenset[InputModality]
The validated override, or kinds inferred from the current inputs.
Inference reads Signal specs within the scope, the prompt, and text input annotations. It does not load values or inspect targets. NO_INPUT means there are no input Records. The result is not cached: connectors can assign inputs after construction.
scope
class-attribute
instance-attribute
¶source
scope: Span | None = None
Optional region of the inputs to which the task applies.
split
class-attribute
instance-attribute
¶source
split: Split | None = None
The partition the task belongs to: train, validation, or test. None when the dataset does not partition its tasks.
target_annotations
class-attribute
instance-attribute
¶source
target_annotations: tuple[Annotation, ...] = field(
default=(), compare=False
)
Existing annotation occurrences that form the expected output.
targets
class-attribute
instance-attribute
¶source
targets: ValueField[
Iterable[TargetInput] | None,
tuple[TargetItem, ...] | None,
] = field(
default=ValueField(_target_values, None), compare=False
)
Ordered native values and stored objects that form the expected output.
annotate ¶source
annotate(annotation: Annotation) -> Annotation
Attach one annotation occurrence and return it.
Returns:
| Type | Description |
|---|---|
Annotation
|
The attached occurrence. |
named_records ¶source
Return the Records that the task names, each once: its inputs, then its Record targets.
A task class with candidate Records returns them too, after the inputs.
referenced_signals ¶source
Return the Signals that the task references, each once.
They are its Signal targets, then the Signals that its scope and its span targets name, in the
order of :meth:spans.
register_label_set ¶source
register_label_set(label_sets: LabelSetRegistry) -> None
Add the label set of the task to the dataset's label sets.
Only a classification task has a label set.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
label_sets
|
LabelSetRegistry
|
The label sets of the dataset so far. |
required |
with_references ¶source
Return a copy of the task that references the given Records and Signals, by ID.
The copy has the class of the task. Each input, candidate Record, Record target, and Signal
target of the copy is the object of the same ID in records or signals. The scope and
the span targets of the copy name the Signals of the same IDs in signals. Each span keeps
its class. The copy has no ID.
Every other field keeps its value: the annotations of the task, the annotations that it
references, from_tasks, the text, and the metadata. A caller that needs other values for
them sets them on the copy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
records
|
Mapping[EntityId, Record]
|
The Records for the copy, by ID. |
required |
signals
|
Mapping[EntityId, Signal]
|
The Signals for the copy, by ID. |
required |
Returns:
| Type | Description |
|---|---|
Self
|
The copy. |
Raises:
| Type | Description |
|---|---|
TimeFValidationError
|
If a Record or Signal that the task references has no ID, or if
|
TaskType ¶source
TemporalLocalizationTask
dataclass
¶source
Bases: Task
Locate events or regions in the inputs.
annotations
class-attribute
instance-attribute
¶source
annotations: tuple[Annotation, ...] = ()
Annotations describing this task itself.
id
property
¶source
id: EntityId
The task's id, unique among the tasks of its dataset.
:meth:~timenet.dataset.TimeFDataset.add_task sets it. The reader sets it when it reads the task back.
Raises:
| Type | Description |
|---|---|
TimeFValidationError
|
If the task is not in a dataset yet. |
input_annotations
class-attribute
instance-attribute
¶source
input_annotations: tuple[Annotation, ...] = field(
default=(), compare=False
)
Existing annotation occurrences supplied to the model as context.
input_modalities
class-attribute
instance-attribute
¶source
input_modalities: frozenset[InputModality] | None = None
Optional override. None infers the input kinds when resolved or written.
metadata
class-attribute
instance-attribute
¶source
metadata: JsonMapping = field(default_factory=dict)
Optional JSON-compatible task metadata.
mode
class-attribute
instance-attribute
¶source
mode: LocalizationMode = LocalizationMode.SPARSE
Whether the localization is sparse or exhaustive.
prompt
class-attribute
instance-attribute
¶source
prompt: ValueField[
str | TextHandle | None, TextHandle | None
] = field(default=ValueField(optional_text, None))
Call read() for the prompt; None identifies an unprompted task.
rationale
class-attribute
instance-attribute
¶source
rationale: ValueField[
str | TextHandle | None, TextHandle | None
] = field(default=ValueField(optional_text, None))
Call read() for the explanation; None means no rationale is present.
resolved_input_modalities
property
¶source
resolved_input_modalities: frozenset[InputModality]
The validated override, or kinds inferred from the current inputs.
Inference reads Signal specs within the scope, the prompt, and text input annotations. It does not load values or inspect targets. NO_INPUT means there are no input Records. The result is not cached: connectors can assign inputs after construction.
scope
class-attribute
instance-attribute
¶source
scope: Span | None = None
Optional region of the inputs to which the task applies.
split
class-attribute
instance-attribute
¶source
split: Split | None = None
The partition the task belongs to: train, validation, or test. None when the dataset does not partition its tasks.
target_annotations
class-attribute
instance-attribute
¶source
target_annotations: tuple[Annotation, ...] = field(
default=(), compare=False
)
Existing annotation occurrences that form the expected output.
targets
class-attribute
instance-attribute
¶source
targets: ValueField[
Iterable[TargetInput] | None,
tuple[TargetItem, ...] | None,
] = field(
default=ValueField(_target_values, None), compare=False
)
Ordered native values and stored objects that form the expected output.
annotate ¶source
annotate(annotation: Annotation) -> Annotation
Attach one annotation occurrence and return it.
Returns:
| Type | Description |
|---|---|
Annotation
|
The attached occurrence. |
named_records ¶source
Return the Records that the task names, each once: its inputs, then its Record targets.
A task class with candidate Records returns them too, after the inputs.
referenced_signals ¶source
Return the Signals that the task references, each once.
They are its Signal targets, then the Signals that its scope and its span targets name, in the
order of :meth:spans.
register_label_set ¶source
register_label_set(label_sets: LabelSetRegistry) -> None
Add the label set of the task to the dataset's label sets.
Only a classification task has a label set.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
label_sets
|
LabelSetRegistry
|
The label sets of the dataset so far. |
required |
with_references ¶source
Return a copy of the task that references the given Records and Signals, by ID.
The copy has the class of the task. Each input, candidate Record, Record target, and Signal
target of the copy is the object of the same ID in records or signals. The scope and
the span targets of the copy name the Signals of the same IDs in signals. Each span keeps
its class. The copy has no ID.
Every other field keeps its value: the annotations of the task, the annotations that it
references, from_tasks, the text, and the metadata. A caller that needs other values for
them sets them on the copy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
records
|
Mapping[EntityId, Record]
|
The Records for the copy, by ID. |
required |
signals
|
Mapping[EntityId, Signal]
|
The Signals for the copy, by ID. |
required |
Returns:
| Type | Description |
|---|---|
Self
|
The copy. |
Raises:
| Type | Description |
|---|---|
TimeFValidationError
|
If a Record or Signal that the task references has no ID, or if
|
TextHandle ¶source
Bases: _TextBehaviour, ValueHandle[str]
Refer to one string: a task prompt, rationale, or text target, or an annotation value.
is_loaded
abstractmethod
property
¶source
is_loaded: bool
Whether the value is held in memory, so read() needs no storage access.
TextListHandle ¶source
Bases: _TextBehaviour, ValueHandle[list[str]]
Refer to a list of strings, such as a recording's labels in one annotation value.
is_loaded
abstractmethod
property
¶source
is_loaded: bool
Whether the value is held in memory, so read() needs no storage access.
TimeInterval
dataclass
¶source
Bases: TimeSpan
The half-open range [start_us, end_us) on the recording timeline.
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
class-attribute
instance-attribute
¶source
Series the span is scoped to. None covers every series in the record.
micros
classmethod
¶source
micros(
start: int,
end: int,
*,
time_series: tuple[Signal, ...] | 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
|
tuple[Signal, ...] | None
|
Series the interval is scoped to. |
None
|
Returns:
| Type | Description |
|---|---|
TimeInterval
|
The interval. |
seconds
classmethod
¶source
seconds(
start: float,
end: float,
*,
time_series: tuple[Signal, ...] | 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
|
tuple[Signal, ...] | None
|
Series the interval is scoped to. |
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.
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
class-attribute
instance-attribute
¶source
Series the span is scoped to. None covers every series in the record.
micros
classmethod
¶source
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
|
tuple[Signal, ...] | None
|
Series the point is scoped to. |
None
|
Returns:
| Type | Description |
|---|---|
TimePoint
|
The point. |
seconds
classmethod
¶source
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
|
tuple[Signal, ...] | None
|
Series the point is scoped to. |
None
|
Returns:
| Type | Description |
|---|---|
TimePoint
|
The point. |
TimeSeriesSpec ¶source
Bases: TimeFModel
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[NonEmptyString, ...] = ()
Ordered codebook for dtype="enum". Empty for every other dtype.
dimension_names
class-attribute
instance-attribute
¶source
dimension_names: tuple[NonEmptyString, ...] = ()
Optional names for the dimensions in :attr:value_shape.
dtype
class-attribute
instance-attribute
¶source
Value dtype: a NumPy scalar dtype, "str" for text, or "enum" for a categorical value.
modality
class-attribute
instance-attribute
¶source
modality: InputModality = InputModality.TIME_SERIES
Semantic input kind. Set IMAGE, AUDIO, or TEXT for Signals that carry those kinds of data.
model_config
class-attribute
instance-attribute
¶source
model_config = ConfigDict(
extra="forbid",
frozen=True,
revalidate_instances="always",
serialize_by_alias=True,
validate_by_name=True,
validate_default=True,
)
nullable
class-attribute
instance-attribute
¶source
Whether a whole timestep can be missing. An Arrow bit marks whether each timestep is present.
spec_type
instance-attribute
¶source
Type tag identifying the modality. Callers use it to filter datasets by spec type.
TimeSpan
dataclass
¶source
Bases: Span
Abstract base for a region on the recording timeline. Bounds are microseconds.
Covers the whole record when time_series is None, or a subset of series when it holds
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.
ValueHandle ¶source
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)).
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 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: |
Raises:
| Type | Description |
|---|---|
TimeFValidationError
|
If |
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: |
check_id ¶source
Return value as an int if it is a valid entity id.
The function accepts any integral value, including NumPy integers read back from Arrow or pandas.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
object
|
The candidate id. |
required |
what
|
str
|
The name of the id, used in the error message. |
required |
Returns:
| Type | Description |
|---|---|
EntityId
|
|
Raises:
| Type | Description |
|---|---|
TimeFValidationError
|
If |
normalize_unit ¶source
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: |
required |
Returns:
| Type | Description |
|---|---|
str | None
|
The unit as a string, or |
Raises:
| Type | Description |
|---|---|
TimeFValidationError
|
If |
offset_us ¶source
Convert a wall-clock moment to an offset from the Record origin.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
moment
|
datetime
|
The wall-clock moment, timezone-aware. |
required |
start_time
|
datetime | int | None
|
The Record's absolute origin. |
required |
Returns:
| Type | Description |
|---|---|
int
|
Microseconds from the Record's relative zero. |
Raises:
| Type | Description |
|---|---|
TimeFValidationError
|
If the Record has no known absolute origin. |
parse_split ¶source
Coerce a split name to :class:Split.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Split | str
|
The member itself, or its value such as |
required |
Returns:
| Type | Description |
|---|---|
Split
|
The matching member. |
Raises:
| Type | Description |
|---|---|
TimeFValidationError
|
If |
read_value ¶source
read_value(value: TextHandle) -> str
read_value(value: TextListHandle) -> list[str]
read_value(value: TextHandle | None) -> str | None
read_value(
value: TextHandle | TextListHandle,
) -> str | list[str]
read_value(value: TargetItem) -> TargetValue
read_value(
value: TextHandle | TextListHandle | _Other,
) -> str | list[str] | _Other
Read a text handle and return any other value unchanged, None included.
Returns:
| Type | Description |
|---|---|
object
|
The handle's string or list of strings, or the value itself when it is not text. |
read_values ¶source
read_values(
values: Iterable[TextHandle],
) -> tuple[str, ...]
read_values(
values: Iterable[TextListHandle],
) -> tuple[list[str], ...]
read_values(
values: Iterable[TargetItem],
) -> tuple[TargetValue, ...]
read_values(
values: Iterable[TextHandle | TextListHandle | _Other],
) -> tuple[str | list[str] | _Other, ...]
Read every text handle among values and return every other item unchanged.
Each item is read as :func:read_value reads it.
Returns:
| Type | Description |
|---|---|
tuple[object, ...] | None
|
The items in order, or |
Raises:
| Type | Description |
|---|---|
TimeFValidationError
|
If |
unix_us ¶source
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 |
us_to_seconds ¶source
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
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.
value_type_of ¶source
value_type_of(value: Any) -> ValueType | 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 |
|---|---|
ValueType | None
|
One of |
ValueType | None
|
A list holds only strings, such as the names of activities in a recording. |
Raises:
| Type | Description |
|---|---|
TimeFValidationError
|
If |