SequentialProperty#

class deeptrack.properties.SequentialProperty(node_name: str | None = None, initial_sampling_rule: Any | None = None, sampling_rule: Any | None = None, sequence_length: int | None = None, **kwargs: Property)#

Bases: Property

Property that yields different values across sequential steps.

A SequentialProperty encapsulates sampling rules and step management in a single object for sequential evaluation.

This class extends Property to support scenarios where a property value evolves over discrete steps, such as frames in a video, time-series data, or other sequential processes. At each step, it selects whether to use the initial_sampling_rule (when step == 0 and it is provided) or the sampling_rule (otherwise). It also keeps track of previously generated values, allowing sampling rules to depend on history.

Parameters#

node_name: str | None, optional: The name of this node. Defaults to None.
initial_sampling_rule: Any, optional: A sampling rule for the first step (step == 0). Can be any value or callable accepted by Property. Defaults to None.
sampling_rule: Any, optional: The sampling rule (value or callable) for steps > 0, and also for step == 0 when initial_sampling_rule is None. Defaults to None.
sequence_length: int, optional: The length of the sequence. Defaults to None.
**kwargs: Property: Additional dependencies injected when evaluating callable sampling rules.

Attributes#

sequence_length: Property: A Property holding the total number of steps (int) in the sequence. Initialized to 0 by default.
sequence_index: Property: A Property holding the index (int) of the current step (starting at 0).
previous_values: Property: A Property returning all stored values strictly before the previous value (list[Any]).
previous_value: Property: A Property returning the most recently stored value (Any), or None if no values have been stored yet.
initial_sampling_rule: Callable[…, Any] | None: A function (or constant wrapped as an action) used to compute the value at step 0. If None, the property falls back to sampling_rule at step 0.
sample: Callable[…, Any]: The action used to compute the value at steps > 0 (and at step 0 if initial_sampling_rule is None). If no sampling_rule is provided, it returns None.
action: Callable[…, Any]: Overrides the default Property.action to select between initial_sampling_rule (when step is 0) and sample (otherwise).

Methods#

_action_override(_ID) -> Any: Select the appropriate sampling rule based on sequence_index.
sequence(_ID) -> list[Any]: Return the stored sequence for _ID without recomputing.
next_step(_ID) -> bool: Advance the sequence index by one step (if possible).
store(value, _ID) -> None: Append a newly computed value to the stored sequence for _ID.
current_value(_ID) -> Any: Return the stored value at the current step index.

Examples#

To illustrate the use of SequentialProperty, we will implement a one-dimensional Brownian walker.

>>> import deeptrack as dt

Define the SequentialProperty:

>>> import numpy as np
>>>
>>> seq_prop = dt.SequentialProperty(
...     initial_sampling_rule=0,  # Sampling rule for first time step
...     sampling_rule=(  # Sampl. rule for subsequent steps
...         lambda previous_value: previous_value + np.random.randn()
...     ),
...     sequence_length=10,  # Number of steps
... )

Iteratively calculate the sequence:

>>> for step in range(seq_prop.sequence_length()):
...     seq_prop()
...     seq_prop.next_step()  # Returns False at the final step

Print all values of the sequence:

>>> seq_prop.sequence()
[0,
-0.38200070551587934,
0.4107493780458869,
0.4168147820083061,
-0.37943277485427523,
-0.24658839362797394,
0.6200008820895946,
0.7763449126000742,
1.9552313612982135,
1.8016703270391572]

Methods Summary

`current_value`([_ID])	Return the stored value at the current step index.
`next_step`([_ID])	Advance the sequence index by one step.
`sequence`([_ID])	Retrieve the stored sequence for _ID without recomputing.
`store`(value[, _ID])	Append a value to the stored sequence for _ID.

Methods Documentation

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

Return the stored value at the current step index.

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

Parameters#

_ID: tuple[int, …], optional: A unique identifier for separate parallel evaluations.

Returns#

Any: The value stored at the index = self.sequence_index(_ID=_ID).

Raises#

IndexError: If no value has been stored for this step, it throws an IndexError.

next_step(_ID: tuple[int, ...] = ()) → bool#

Advance the sequence index by one step.

This method increments sequence_index by one for the given _ID if the next index remains strictly less than sequence_length. It also invalidates cached properties that depend on the sequence index to ensure correct recomputation on subsequent access. If the sequence is already at its final step, the index is not changed.

Parameters#

_ID: tuple[int, …], optional: A unique identifier that allows the property to keep separate sequence states for different parallel evaluations.

Returns#

bool: True if the index was advanced, False if already at the final step.

sequence(_ID: tuple[int, ...] = ()) → list[Any]#

Retrieve the stored sequence for _ID without recomputing.

Parameters#

_ID: tuple[int, …], optional: The ID for which to retrieve the previous value.

Returns#

list[Any]: The list of stored values for this _ID. Returns an empty list if no values have been stored yet.

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

Append a value to the stored sequence for _ID.

Appends value to the stored sequence for _ID. If no values have been stored yet for _ID, it starts a new list.

Parameters#

value: Any: The value to store, e.g., the output from calling self().
_ID: tuple[int, …], optional: A unique identifier that allows the property to keep separate histories for different parallel evaluations.