Sequence#

class deeptrack.sequences.Sequence(feature: Feature, sequence_length: int | Callable[[...], int] = 1, **kwargs: Any)#

Bases: Feature

Resolve a feature repeatedly as a sequence.

The Sequence class evaluates a wrapped feature multiple times in succession, producing a sequence of outputs. Before each evaluation, the sequential context (sequence_index and sequence_length) is propagated to all dependent SequentialProperty attributes in the feature graph.

This enables temporal simulations and animations in which feature properties evolve over discrete time steps according to user-defined sampling rules. The wrapped feature itself may be a single feature or a composed feature graph.

Parameters#

feature: Feature: The feature to be evaluated repeatedly.
sequence_length: int: The number of sequential evaluations to perform. Defaults to 1.
**kwargs: Any: Additional keyword arguments passed to the base Feature constructor.

Attributes#

feature: Feature: The wrapped feature that is evaluated at each step.
__distributed__: bool: Indicates whether this feature is distributed across processes or devices. Always set to False for Sequence, as sequential evaluation requires ordered execution.

Methods#

get(input_list, sequence_length, _ID, **kwargs) -> list[Any] | tuple[…]: Evaluate the wrapped feature sequence_length times. The outputs are returned as a list. If the wrapped feature returns a tuple or list, the result is transposed into a tuple of lists.

Examples#

>>> import deeptrack as dt

Sequential evaluation

In this example, a feature is evaluated repeatedly while one of its properties evolves over time. No optics or image formation is involved.

Define a simple feature with a time-dependent property:

>>> feature = dt.Value(value=0)

Define a sampling rule that increments the value at each step:

>>> def increment(sequence_length, previous_value):
...     return previous_value + 1

Convert the feature to a sequential feature:

>>> sequential_feature = feature.to_sequential(value=increment)

Wrap the feature in a Sequence and evaluate it:

>>> sequence = dt.Sequence(sequential_feature, sequence_length=5)
>>> sequence()
[0, 1, 2, 3, 4]

Simulating a spinning ellipsoid.

Define an imaging system:

>>> optics = dt.Fluorescence(output_region=(0, 0, 32, 32))

Define a static ellipse:

>>> ellipse = dt.Ellipse(
...     radius=(1e-6, 0.5e-6),
...     position=(16, 16),
...     rotation=0.78,  # Initial rotation
...     intensity=1,
... )

Define a rotation function that increments the previous angle:

>>> def rotate(sequence_length, previous_value):
...     return previous_value + 6.28 / sequence_length

Convert the ellipse to a sequential feature:

>>> rotating_ellipse = ellipse.to_sequential(rotation=rotate)

Compose with the optics:

>>> imaged_rotating_ellipse = optics(rotating_ellipse)

Wrap the composed feature in a Sequence:

>>> imaged_rotating_ellipse_sequence = dt.Sequence(
...     imaged_rotating_ellipse,
...     sequence_length=50,
... )

Generate and display the result:

>>> imaged_rotating_ellipse_sequence.update().plot();

Methods Summary

get(input_list, sequence_length[, _ID])

Resolve the wrapped feature as a sequence of outputs.

Methods Documentation

get(input_list: list[Any] | None, sequence_length: int, _ID: tuple[int, ...] = (), **kwargs: Any) → list[Any] | tuple[list[Any], ...]#

Resolve the wrapped feature as a sequence of outputs.

This method evaluates the wrapped feature sequence_length times. Before each evaluation, the sequential context (sequence_index and sequence_length) is propagated to all dependent SequentialProperty attributes in the feature graph.

The outputs of each evaluation are collected and returned as a sequence. If the wrapped feature returns multiple values (as a tuple or list), the result is transposed into a tuple of lists, one per output component.

Parameters#

input_list: list[Any] or None: Previously resolved outputs to extend. If None, a new output list is initialized.
sequence_length: int: Number of sequential evaluations to perform.
_ID: tuple[int, …], optional: Evaluation identifier used to store and retrieve sequential state.
**kwargs: Any: Unused. Present for compatibility with the Feature interface.

Returns#

list[Any] | tuple[list[Any], …]: The sequence of resolved outputs. If the wrapped feature returns a tuple or list, the result is a tuple of lists.