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.

Main Concepts

• 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 Feature 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.

Key Classes

• Feature:

  Base class for all features in DeepTrack2. Represents a modular data transformation with properties and methods for customization.

• StructuralFeature:

  A specialized feature for organizing and managing hierarchical or logical structures in the pipeline.

• Value:

  Stores a constant value as a feature. Useful for passing parameters through the pipeline.

• Chain:

  Sequentially applies multiple features to the input data (>>).

• DummyFeature:

  A no-op feature that passes the input data unchanged.

• ArithmeticOperationFeature:

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

Module Highlights

• Feature Properties

  Features in DeepTrack2 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.

Example

Define a simple pipeline with features:

>>> import numpy as np
>>> from deeptrack.features import Feature, Chain, Value

Create a basic addition feature:

>>> class Add(Feature):
...     def get(self, image, value, **kwargs):
...         return image + value

Create two features:

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

Chain features together:

>>> pipeline = Chain(add_five, add_ten)

or equivalently:

>>> pipeline = add_five >> add_ten

Process an input image:

>>> input_image = np.array([1, 2, 3])
>>> output_image = pipeline(input_image)
>>> print(output_image)
[16, 17, 18]

Functions

create_context([xpixel, ypixel, zpixel, ...])	Creates a new context for unit conversions.
propagate_data_to_dependencies(feature, **kwargs)	Updates the properties of dependencies in a feature's dependency tree.

Classes

Add([value])	Add a value to the input.
Arguments([_input])	A convenience container for pipeline arguments.
ArithmeticOperationFeature(op[, value])	Applies an arithmetic operation element-wise to inputs.
AsType([dtype])	Convert the data type of images.
Bind(feature, **kwargs)	Bind a feature with property arguments.
BindResolve	alias of Bind
BindUpdate(feature, **kwargs)	Bind a feature with certain arguments.
Branch	alias of Chain
Chain(feature_1, feature_2, **kwargs)	Resolve two features sequentially.
ChannelFirst2d([axis])	Convert an image to a channel-first format.
Combine(features, **kwargs)	Combine multiple features into a single feature.
ConditionalSetFeature([on_false, on_true, ...])	Conditionally resolves one of two features based on a condition.
ConditionalSetProperty(feature[, condition])	Conditionally override the properties of child features.
ConversionTable(**conversions)	Convert a dictionary of values to the desired units.
DeepTrackNode([action])	Object corresponding to a node in a computation graph.
Divide([value])	Divide the input with a value.
DummyFeature([_input])	A no-op feature that simply returns the input unchanged.
Equal	alias of Equals
Equals([value])	Determine whether input is equal to value.
ExpandDims	alias of Unsqueeze
Feature([_input])	Base feature class.
FloorDivide([value])	Divide the input with a value.
GreaterThan([value])	Determine whether input is greater than value.
GreaterThanOrEqual	alias of GreaterThanOrEquals
GreaterThanOrEquals([value])	Determine whether input is greater than or equal to value.
Image(value[, copy])	Wrapper for array-like values with property tracking.
Label([output_shape])	Output the properties of this feature.
Lambda(function, **kwargs)	Apply a custom function on each image in the input.
LessThan([value])	Determine whether input is less than value.
LessThanOrEqual	alias of LessThanOrEquals
LessThanOrEquals([value])	Determine whether input is less than or equal to value.
LoadImage(path[, load_options, as_list, ...])	Load an image from disk.
Merge(function, **kwargs)	Apply a custom function to a list of images.
MoveAxis(source, destination, **kwargs)	Moves the axis of the input image.
Multiply([value])	Multiply the input by a value.
NonOverlapping(feature[, min_distance, ...])	Ensure volumes are placed non-overlapping in a 3D space.
OneHot(num_classes, **kwargs)	Converts the input to a one-hot encoded array.
OneOf(collection[, key])	Resolves one feature from a collection on the input.
OneOfDict(collection[, key])	Resolve one feature from a dictionary.
Permute	alias of Transpose
Power([value])	Raise the input to a power.
Probability(feature, probability, *args, ...)	Resolve a feature with a certain probability
PropertyDict(**kwargs)	Dictionary with Property elements.
Quantity()
Repeat(feature, N, **kwargs)	Repeats the evaluation of the input feature a certain number of times.
SampleToMasks(transformation_function[, ...])	Creates a mask from a list of images.
Slice(slices, **kwargs)	Array indexing for each Image in list.
SourceItem(callbacks, **kwargs)	A dict-like object that calls a list of callbacks when called.
Squeeze([axis])	Squeeze the input image to the smallest possible dimension.
Stack(value, **kwargs)	Stacks the input and the value.
Store(feature, key[, replace])	Stores the output of a feature for reuse.
StructuralFeature([_input])	Provides the structure of a feature set without input transformations.
Subtract([value])	Subtract a value from the input.
TakeProperties(feature, *names, **kwargs)	Extracts all instances of a set of properties from a pipeline.
Transpose([axes])	Transpose the input image.
Unsqueeze([axis])	Unsqueezes the input image to the smallest possible dimension.
Upscale(feature[, factor])	Perform the simulation at a higher resolution.
Value([value])	Represents a constant (per evaluation) value in a DeepTrack pipeline.