DeepTrackDataDict

class deeptrack.backend.core.DeepTrackDataDict

Bases: object

Stores multiple data objects indexed by a tuple of integers (ID).

DeepTrackDataDict can store multiple DeepTrackDataObject instances, each associated with a unique tuple of integers (its ID). This is particularly useful to handle sequences of data or nested structures.

The default ID is an empty tuple, (). Once the first entry is created, all IDs must match the established key length:

• If an ID longer than the set length is requested, it is trimmed.

• If an ID shorter than the set length is requested, a dictionary slice containing all matching entries is returned.

Attributes

keylengthint or None

The length of the IDs currently stored. Set when the first entry is created. If None, no entries have been created yet, and any ID length is valid.

dictDict[Tuple[int, …], DeepTrackDataObject]

A dictionary mapping tuples of integers (IDs) to DeepTrackDataObject instances.

Methods

invalidate() -> None

Marks all stored data objects as invalid.

validate() -> None

Marks all stored data objects as valid.

valid_index(_IDTuple[int, …]) -> bool

Checks if the given ID is valid for the current configuration.

create_index(_IDTuple[int, …] = ()) -> None

Creates an entry for the given ID if it does not exist.

__getitem__(_IDTuple[int, …]) -> DeepTrackDataObject or Dict[Tuple[int, …], DeepTrackDataObject]

Retrieves data associated with the ID. Can return a DeepTrackDataObject or a dict of matching entries if _ID is shorter than keylength.

__contains__(_IDTuple[int, …]) -> bool

Checks if the given ID exists in the dictionary.

Example

Create a structure to store multiple, indexed instances of data:

>>> data_dict = DeepTrackDataDict()

Create the entries:

>>> data_dict.create_index((0, 0))
>>> data_dict.create_index((0, 1))
>>> data_dict.create_index((1, 0))
>>> data_dict.create_index((1, 1))

Store the values associated with each ID:

>>> data_dict[(0, 0)].store("Data at (0, 0)")
>>> data_dict[(0, 1)].store("Data at (0, 1)")
>>> data_dict[(1, 0)].store("Data at (1, 0)")
>>> data_dict[(1, 1)].store("Data at (1, 1)")

Retrieve values based on their IDs:

>>> print(data_dict[(0, 0)].current_value())
Data at (0, 0)

>>> print(data_dict[(1, 1)].current_value())
Data at (1, 1)

If requesting a shorter ID, it returns all matching nested entries:

>>> print(data_dict[(0,)])
{
    (0, 0): <DeepTrackDataObject>, 
    (0, 1): <DeepTrackDataObject>,
}

Methods Summary

create_index([_ID])	Create a new data entry for the given ID if not already existing.
invalidate()	Mark all stored data objects as invalid.
valid_index(_ID)	Check if a given ID is valid for this data dictionary.
validate()	Mark all stored data objects as valid.

Methods Documentation

create_index(_ID: Tuple[int, ...] = ()) → None

Create a new data entry for the given ID if not already existing.

Each newly created index is associated with a new DeepTrackDataObject. If _ID is already in dict, no new entry is created.

If keylength is None, it is set to the length of _ID. Once established, all subsequently created IDs must have this same length.

Parameters

_IDTuple[int, …], optional

A tuple of integers representing the ID for the data entry. Default is (), which represents a root-level data entry with no nesting.

Raises

AssertionError

• If _ID is not a tuple of integers.

• If _ID is not valid for the current configuration.

invalidate() → None

Mark all stored data objects as invalid.

Calls invalidate() on every DeepTrackDataObject in the dictionary.

valid_index(_ID: Tuple[int, ...]) → bool

Check if a given ID is valid for this data dictionary.

If keylength is None, any tuple _ID is considered valid since no entries have been created yet. If _ID already exists in dict, it is automatically valid. Otherwise, _ID must have the same length as keylength to be considered valid.

Parameters

_IDTuple[int, …]

The index to check, consisting of a tuple of integers.

Returns

bool

True if the ID is valid given the current configuration, False otherwise.

Raises

AssertionError

If _ID is not a tuple of integers.

validate() → None

Mark all stored data objects as valid.

This method calls validate() on every DeepTrackDataObject in the dictionary.