deeptrack.features Module

Core features for building and processing pipelines in DeepTrack2.

This module defines the core classes and utilities used to create and manipulate features in DeepTrack2, enabling users to build sophisticated data processing pipelines with modular, reusable, and composable components.

Key Features

• Features

  A Feature is a building block of a data processing pipeline. It represents a transformation applied to data, such as image manipulation, data augmentation, or computational operations. Features are highly customizable and can be combined into pipelines for complex workflows.

• Structural Features

  Structural features extend the basic StructuralFeature class by adding hierarchical or logical structures, such as chains, branches, or probabilistic choices. They enable the construction of pipelines with advanced data flow requirements.

• Feature Properties

  Features can have dynamically sampled properties, enabling parameterization of transformations. These properties are defined at initialization and can be updated during pipeline execution.

• Pipeline Composition

  Features can be composed into flexible pipelines using intuitive operators (>>, &, etc.), making it easy to define complex data processing workflows.

• Lazy Evaluation

  DeepTrack2 supports lazy evaluation of features, ensuring that data is processed only when needed, which improves performance and scalability.

Module Structure

Key Classes:

• Feature: Base class for all features in DeepTrack2.

  In general, a feature represents a modular data transformation with properties and methods for customization.

• StructuralFeature: Base class for features providing structure.

  Base class for specialized features for organizing and managing hierarchical or logical structures in the pipeline without input transformations.

• ArithmeticOperationFeature: Apply arithmetic operation element-wise.

  Base class for features performing arithmetic operations like addition, subtraction, multiplication, and division.

Structural Feature Classes: - Chain: Sequentially apply multiple features to the input data (>>). - Branch: Alias of Chain. - Probability: Resolve a feature with a certain probability. - Repeat: Apply a feature multiple times in sequence (^). - Combine: Combine multiple features into a single feature. - Bind: Bind a feature with property arguments. - BindResolve: DEPRECATED Alias of Bind. - BindUpdate: DEPRECATED Bind a feature with certain arguments. - ConditionalSetProperty: DEPRECATED Conditionally override child properties. - ConditionalSetFeature: DEPRECATED Conditionally resolve features.

Other Feature Classes: - DummyFeature: A no-op feature that simply returns the input unchanged. - Value: Store a constant value as a feature. - Stack: Stack the input and the value. - Arguments: A convenience container for pipeline arguments. - Slice: Dynamically apply array indexing to inputs. - Lambda: Apply a user-defined function to the input. - Merge: Apply a custom function to a list of inputs. - OneOf: Resolve one feature from a given collection. - OneOfDict: Resolve one feature from a dictionary and apply it to an input. - LoadImage: Load an image from disk and preprocess it. - AsType: Convert the data type of the input. - ChannelFirst2d: DEPRECATED Convert an image to a channel-first format. - Store: Store the output of a feature for reuse. - Squeeze: Squeeze the input to the smallest possible dimension. - Unsqueeze: Unsqueeze the input. - ExpandDims: Alias of Unsqueeze. - MoveAxis: Move the axis of the input. - Transpose: Transpose the input. - Permute: Alias of Transpose. - OneHot: Convert the input to a one-hot encoded array. - TakeProperties: Extract all instances of properties from a pipeline.

Arithmetic Feature Classes: - Add: Add a value to the input.@dataclass - Subtract: Subtract a value from the input. - Multiply: Multiply the input by a value. - Divide: Divide the input by a value. - FloorDivide: Divide the input by a value. - Power: Raise the input to a power. - LessThan: Determine if input is less than value. - LessThanOrEquals: Determine if input is less than or equal to value. - LessThanOrEqual: Alias for LessThanOrEquals. - GreaterThan: Determine if input is greater than value. - GreaterThanOrEquals: Determine if input is greater than or equal to value. - GreaterThanOrEqual: Alias for GreaterThanOrEquals. - Equals: Determine if input is equal to value. - Equal: Alias for Equals.

Functions:

• propagate_data_to_dependencies(feature, _ID, **kwargs) -> None

  Propagates data to all dependencies of a feature, updating their properties with the provided values.

Examples

Define a simple pipeline with features.

>>> import deeptrack as dt

Create a basic addition feature:

>>> class BasicAdd(dt.Feature):
...     def get(self, data, value, **kwargs):
...         return data + value

Create two features:

>>> add_five = BasicAdd(value=5)
>>> add_ten = BasicAdd(value=10)

Chain features together:

>>> pipeline = dt.Chain(add_five, add_ten)

Or equivalently:

>>> pipeline = add_five >> add_ten

Process an input array:

>>> import numpy as np
>>>
>>> input = np.array([[1, 2, 3], [4, 5, 6]])
>>> output = pipeline(input)
>>> output
array([[16, 17, 18],
       [19, 20, 21]])

Classes

Feature([_input])	Base feature class.
StructuralFeature([_input])	Provide the structure of a feature set without input transformations.
Chain(feature_1, feature_2, **kwargs)	Resolve two features sequentially.
Branch	alias of Chain
DummyFeature([_input])	A no-op feature that simply returns the inputs unchanged.
Value(value, **kwargs)	Represent a constant value in a DeepTrack2 pipeline.
ArithmeticOperationFeature(op[, b])	Apply an arithmetic operation element-wise to the inputs.
Add([b])	Add a value to the input.
Subtract([b])	Subtract a value from the input.
Multiply([b])	Multiply the input by a value.
Divide([b])	Divide the input with a value.
FloorDivide([b])	Divide the input with a value.
Power([b])	Raise the input to a power.
LessThan([b])	Determine whether input is less than value.
LessThanOrEquals([b])	Determine whether input is less than or equal to value.
LessThanOrEqual	alias of LessThanOrEquals
GreaterThan([b])	Determine whether input is greater than value.
GreaterThanOrEquals([b])	Determine whether input is greater than or equal to value.
GreaterThanOrEqual	alias of GreaterThanOrEquals
Equals([b])	Determine whether input is equal to a given value.
Equal	alias of Equals
Stack(value, **kwargs)	Stack the input and the value.
Arguments([_input])	A convenience container for pipeline arguments.
Probability(feature, probability, **kwargs)	Resolve a feature with a certain probability.
Repeat(feature, N, **kwargs)	Apply a feature multiple times.
Combine(features, **kwargs)	Combine multiple features into a single feature.
Slice(slices, **kwargs)	Dynamically apply array indexing to inputs.
Bind(feature, **kwargs)	Bind a feature with property arguments.
BindResolve	alias of Bind
BindUpdate(feature, **kwargs)	Bind a feature with certain arguments.
ConditionalSetProperty(feature[, condition])	Conditionally override the properties of a child feature.
ConditionalSetFeature([on_false, on_true, ...])	Conditionally resolve one of two features.
Lambda(function, **kwargs)	Apply a user-defined function to the input.
Merge(function, **kwargs)	Apply a custom function to a list of inputs.
OneOf(collection[, key])	Resolve one feature from a given collection.
OneOfDict(collection[, key])	Resolve one feature from a dictionary and apply it to an input.
LoadImage(path[, load_options, as_list, ...])	Load an image from disk and preprocess it.
AsType([dtype])	Convert the data type of arrays.
ChannelFirst2d([axis])	Convert an image to a channel-first format.
Store(feature, key[, replace])	Store the output of a feature for reuse.
Squeeze([axis])	Squeeze the input array or tensor to the smallest possible dimension.
Unsqueeze([axis])	Unsqueeze the input array or tensor to the smallest possible dimension.
ExpandDims	alias of Unsqueeze
MoveAxis(source, destination, **kwargs)	Moves the axis of the input array or tensor.
Transpose([axes])	Transpose the input array or tensor.
Permute	alias of Transpose
OneHot(num_classes, **kwargs)	Convert the input to a one-hot encoded array.
TakeProperties(feature, *names, **kwargs)	Extract all instances of a set of properties from a pipeline.