SequentialProperty

class deeptrack.properties.SequentialProperty(initialization: Any | None = None, **kwargs: Dict[str, Property])

Bases: Property

Property that yields different values for sequential steps.

The SequentialProperty extends the standard Property to handle scenarios where the property’s value evolves over discrete steps, such as frames in a video, time-series data, or any sequential process. At each step, it selects whether to use the initialization function (step = 0) or the current function (steps >= 1). It also keeps track of all previously generated values, allowing to refer back to them if needed.

Parameters

initializationAny, optional

A sampling rule for the first step of the sequence (step=0). Can be any value or callable that is acceptable to Property. If not provided, the initial value is None.

**kwargsDict[str, Property]

Additional dependencies that might be required if initialization is a callable. These dependencies are injected when evaluating initialization.

Attributes

sequence_lengthProperty

A Property holding the total number of steps in the sequence. Initialized to 0 by default.

sequence_stepProperty

A Property holding the index of the current step (starting at 0).

previous_valuesProperty

A Property returning all previously stored values up to, but not including, the current value and the previous value.

previous_valueProperty

A Property returning the most recently stored value, or None if there is no history yet.

initializationCallable[…, Any], optional

A function to compute the value at step=0. If None, the property returns None at the first step.

currentCallable[…, Any]

A function to compute the value at steps >= 1. By default, it returns None.

actionCallable[…, Any]

Overrides the default Property.action to select between initialization (if sequence_step is 0) or current (otherwise).

Methods

_action_override(_ID: Tuple[int, …]) -> Any

Internal logic to pick which function (initialization or current) to call based on the sequence_step.

store(value: Any, _ID: Tuple[int, …] = ()) -> None

Store a newly computed value in the property’s internal list of previously generated values.

current_value(_ID: Tuple[int, …] = ()) -> Any

Retrieve the value associated with the current step index.

__call__(_ID: Tuple[int, …] = ()) -> Any

Evaluate the property at the current step, returning either the initialization (if step=0) or current value (if step>0).

Examples

>>> import deeptrack as dt
>>> import numpy as np

>>> seq_prop = dt.SequentialProperty()
>>> seq_prop.sequence_length.store(5)
>>> seq_prop.current = lambda _ID=(): seq_prop.sequence_step() + 1
>>> for step in range(seq_prop.sequence_length()):
...     seq_prop.sequence_step.store(step)
...     current_value = seq_prop.current()
...     seq_prop.store(current_value)
...     print(seq_prop.data[()].current_value())
[1]
[1, 2]
[1, 2, 3]
[1, 2, 3, 4]
[1, 2, 3, 4, 5]

Methods Summary

__call__([_ID])	Evaluate the property at the current step.
current_value([_ID])	Retrieve the value corresponding to the current step.
store(value[, _ID])	Append value to the internal list of previously generated values.

Methods Documentation

__call__(_ID: Tuple[int, ...] = ()) → Any

Evaluate the property at the current step.

It returns either the initialization (if step=0) or the result of self.current.

Parameters

_IDTuple[int, …], optional

A unique identifier for parallel evaluations.

Returns

Any

The computed value for this step.

current_value(_ID: Tuple[int, ...] = ()) → Any

Retrieve the value corresponding to the current step.

It expects that each step’s value has been stored. If no value has been stored for this step, it thorws an IndexError.

Parameters

_IDTuple[int, …], optional

A unique identifier for separate parallel evaluations.

Returns

Any

The value stored at the index = self.sequence_step(_ID=_ID).

store(value: Any, _ID: Tuple[int, ...] = ()) → None

Append value to the internal list of previously generated values.

It retrieves the existing list of values for this _ID. If this _ID has never been used, it starts an empty list

Parameters

valueAny

The value to store, e.g., the output from calling self().

_IDTuple[int, …], optional

A unique identifier that allows the property to keep separate histories for different parallel evaluations.

Raises

KeyError

If no existing data for this _ID, it initializes an empty list.