DeepTrackDataDict#

class deeptrack.backend.core.DeepTrackDataDict#

Bases: object

Store multiple data objects indexed by tuples of integers (_ID).

DeepTrackDataDict can store multiple DeepTrackDataObject instances, each associated with a unique tuple of integers (its _ID).

The default _ID is an empty tuple, _ID = ().

Once the first entry is created, all `_ID`s must match the set key-length.

When retrieving the data associated to an _ID: - If an _ID longer than the set key-length is requested, it is trimmed. - If an _ID shorter than the set key-length is requested, a dictionary

slice containing all matching entries is returned.

NOTE: The _ID`s are specifically used in the `Repeat feature to allow it to return different values without changing the input.

Attributes#

keylength: int or None

Read-only property exposing the internal variable with the length of the _ID`s set when the first entry is created. If `None, no entry has been created, and any _ID length is valid.

dict: dict[tuple[int, …], DeepTrackDataObject] or {}

Read-only property exposing the internal dictionary of stored data, _dict. This is a dictionary mapping tuples of integers (_ID`s) to `DeepTrackDataObject instances.

Methods#

create_index(_ID) -> None

Create an entry for the given _ID if it does not exist.

invalidate(_ID) -> None

Mark stored data objects as invalid.

validate(_ID) -> None

Mark stored data objects as valid.

valid_index(_ID) -> bool

Check if the given _ID is valid for the current configuration.

__getitem__(_ID) -> DeepTrackDataObject or dict[_ID, DeepTrackDataObject]

Retrieve data associated with the _ID. Can return a DeepTrackDataObject, or a dictionary of DeepTrackDataObject`s if `_ID is shorter than keylength.

__contains__(_ID) -> bool

Return whether the given _ID exists in the dictionary.

__len__() -> int

Return the number of stored entries.

__iter__() -> Iterator

Iterate over the keys of the dictionary.

items() -> ItemsView[tuple[int, …], DeepTrackDataObject]

Return a view of the dictionary’s (key, value) pairs.

keys() -> KeysView[tuple[int, …]]

Return a view of the dictionary’s keys.

values() -> ValuesView[DeepTrackDataObject]

Return a view of the dictionary’s values.

__repr__() -> str

Return a string representation of the data dictionary.

Example#

>>> import deeptrack as dt

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

>>> data_dict = dt.DeepTrackDataDict()
>>> data_dict
DeepTrackDataDict(0 entries, keylength=None)

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))
>>> data_dict
DeepTrackDataDict(4 entries, keylength=2)

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)")
>>> data_dict
DeepTrackDataDict(4 entries, keylength=2)

Retrieve values based on their `_ID`s:

>>> data_dict[(0, 0)]
DeepTrackDataObject(data='Data at (0, 0)', valid=True)

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

>>> data_dict[(1, 1)]

DeepTrackDataObject(data=’Data at (1, 1)’, valid=True)

>>> data_dict[(1, 1)].current_value()

‘Data at (1, 1)’

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

>>> data_dict[(0,)]
{(0, 0): DeepTrackDataObject(data='Data at (0, 0)', valid=True),
 (0, 1): DeepTrackDataObject(data='Data at (0, 1)', valid=True)}

Validate and invalidate all entries at once:

>>> data_dict.invalidate()
>>> data_dict[(0, 0)].is_valid()
False

>>> data_dict[(1, 1)].is_valid()
False

>>> data_dict.validate()
>>> data_dict[(0, 0)].is_valid()
True

>>> data_dict[(1, 1)].is_valid()
True

Invalidate and validate a single entry:

>>> data_dict[(0, 1)].invalidate()
>>> data_dict[(0, 1)].is_valid()
False

>>> data_dict[(0, 1)].validate()
>>> data_dict[(0, 1)].is_valid()
True

Check if a given _ID exists:

>>> (1, 0) in data_dict
True

>>> (2, 2) in data_dict
False

Iterate over all entries:

>>> for key, value in data_dict.items():
...     print(key, value.current_value())
(0, 0) Data at (0, 0)
(0, 1) Data at (0, 1)
(1, 0) Data at (1, 0)
(1, 1) Data at (1, 1)

>>> for key in data_dict.keys():
...     print(key)
(0, 0)
(0, 1)
(1, 0)
(1, 1)

>>> for value in data_dict.values():
...     print(value)
DeepTrackDataObject(data='Data at (0, 0)', valid=True)
DeepTrackDataObject(data='Data at (0, 1)', valid=True)
DeepTrackDataObject(data='Data at (1, 0)', valid=True)
DeepTrackDataObject(data='Data at (1, 1)', valid=True)

Check if an _ID is valid according to current keylength:

>>> data_dict.valid_index((0, 1))
True

>>> data_dict.valid_index((0,))  # Shorter than keylength
False

>>> data_dict.valid_index((0, 1, 2))  # Longer than keylength
False

>>> data_dict.valid_index((2, 2))  # Valid length, even if not created yet
True

Attributes Summary

dict

Access the internal data dictionary (read-only).

keylength

Access the internal keylength (read-only).

Methods Summary

create_index([_ID])

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

invalidate([_ID])

Mark stored data objects as invalid.

items()

Return a view of the dictionary’s (key, value) pairs.

keys()

Return a view of the dictionary’s keys.

valid_index(_ID)

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

validate([_ID])

Mark stored data objects as valid.

values()

Return a view of the dictionary’s values.

Attributes Documentation

dict#

Access the internal data dictionary (read-only).

This property exposes the internal _dict attribute as a public read-only interface. It allows access to all stored data objects indexed by their _ID.

Returns#

dict[tuple[int, …], DeepTrackDataObject]

The mapping of _ID`s to `DeepTrackDataObject instances.

keylength#

Access the internal keylength (read-only).

This property exposes the internal _keylength attribute as a public read-only interface.

Returns#

int or None

The key length.

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 and a warning is issued.

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

Parameters#

_ID: tuple[int, …], optional

A tuple of integers representing the _ID for the data entry. Defaults to (), 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(_ID: tuple[int, ...] = ()) → None#

Mark stored data objects as invalid.

Parameters#

_ID: tuple[int, …], optional

If empty, invalidates all cached entries. If shorter than keylength, invalidates entries matching the prefix. If equal to keylength, invalidates that exact entry (if present). If longer than keylength, trims to keylength.

items() → ItemsView[tuple[int, ...], DeepTrackDataObject]#

Return a view of the dictionary’s (key, value) pairs.

Returns#

ItemsView[tuple[int, …], DeepTrackDataObject]

A dynamic view of the internal dictionary’s entries.

keys() → KeysView[tuple[int, ...]]#

Return a view of the dictionary’s keys.

Returns#

KeysView[tuple[int, …]]

A dynamic view of the internal dictionary’s keys.

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#

_ID: tuple[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(_ID: tuple[int, ...] = ()) → None#

Mark stored data objects as valid.

Parameters#

_ID: tuple[int, …], optional

If empty, validates all cached entries. If shorter than keylength, validates entries matching the prefix. If equal to keylength, validates that exact entry (if present). If longer than keylength, trims to keylength.

values() → ValuesView[DeepTrackDataObject]#

Return a view of the dictionary’s values.

Returns#

ValuesView[DeepTrackDataObject]

A dynamic view of the internal dictionary’s values.