deeptrack.elementwise Module

Elementwise mathematical operations for DeepTrack features.

This module defines a collection of Feature classes that apply mathematical functions elementwise to arrays or tensors in a DeepTrack2 pipeline. These operations are backend-agnostic and compatible with both NumPy and PyTorch.

Elementwise features can be created in two ways:

1. Using the Factory Function (`create_elementwise_class`)

   For most functions that are available in both NumPy and PyTorch and are supported by the array-api-compat backend abstraction (xp), the class can be generated dynamically using the create_elementwise_class factory.

   For example:

   >>> from deeptrack.backend import xp
   >>> from deeptrack.elementwise import create_elementwise_class
   >>>
   >>> Abs = create_elementwise_class("Abs", xp.abs)
   

   This creates a Feature class named Abs that applies abs() to the input elementwise, supporting both direct and pipeline usage.

2. Defining a Custom Subclass of `ElementwiseFeature`

   In cases where the array-api-compat implementation fails or does not support the required function for a backend (e.g., torch.float32 with xp.floor), a custom subclass of ElementwiseFeature can be defined explicitly.

   These subclasses manually dispatch to the appropriate backend function (e.g., torch.floor, np.floor) depending on the input type and device, ensuring robust and backend-safe behavior.

   For example, Floor, Ceil, Imag, and Sign are implemented this way.

This dual mechanism provides both flexibility and robustness for applying mathematical operations in a pipeline-agnostic, extensible, and modular way.

Key Features

• Seamless Backend Compatibility

  Most functions use array-api-compat (xp) to ensure compatibility with both NumPy and PyTorch backends. Manual dispatch is used for cases where xp fails (e.g., ceil, floor, imag, sign).

• Factory-Generated and Manual Implementations

  Elementwise operations are implemented using either: - create_elementwise_class() for standard backend-agnostic functions. - Dedicated subclasses of ElementwiseFeature for operations requiring

  manual backend dispatch.

• Supports Direct and Pipeline Composition

  These features can be applied directly to NumPy arrays or PyTorch tensors, or used in combination with other DeepTrack Feature objects in pipelines.

• Extensive Documentation and Examples

  Each class includes detailed docstrings with usage examples for both backends and for pipeline integration.

Module Structure

Classes:

• ElementwiseFeature

  Base class for features that apply mathematical operations elementwise to NumPy arrays or PyTorch tensors. Accepts a function and an optional input Feature.

Functions:

• create_elementwise_class(name, function, docstring) -> type

  Factory function that returns a new subclass of ElementwiseFeature with the given name and function. Automatically sets the class name, module, and docstring for full introspection and documentation support.

Elementwise Features

All elementwise features inherit from ElementwiseFeature and apply a mathematical operation elementwise to the output of another Feature, or directly to an input array or tensor.

The following features are available:

Trigonometric Functions: - Sin: Applies the sine function sin(x) elementwise. - Cos: Applies the cosine function cos(x) elementwise. - Tan: Applies the tangent function tan(x) elementwise.

Inverse Trigonometric Functions: - Arcsin: Applies the arcsine function arcsin(x) elementwise. - Arctan: Applies the arctangent function arctan(x) elementwise.

Hyperbolic Functions: - Sinh: Applies the hyperbolic sine function sinh(x) elementwise. - Cosh: Applies the hyperbolic cosine function cosh(x) elementwise. - Tanh: Applies the hyperbolic tangent function tanh(x) elementwise.

Inverse Hyperbolic Functions: - Arcsinh: Applies the inverse hyperbolic sine arcsinh(x) elementwise. - Arccosh: Applies the inverse hyperbolic cosine arccosh(x) elementwise. - Arctanh: Applies the inverse hyperbolic tangent arctanh(x) elementwise.

Rounding Functions: - Round: Applies nearest-integer rounding elementwise. - Floor: Applies floor function floor(x) elementwise. - Ceil: Applies ceil function ceil(x) elementwise.

Exponential and Logarithmic Functions: - Exp: Applies the exponential function exp(x) elementwise. - Log: Applies the natural logarithm log(x) elementwise. - Log10: Applies the base-10 logarithm log10(x) elementwise. - Log2: Applies the base-2 logarithm log2(x) elementwise.

Complex Number Functions: - Angle: Returns the phase angle angle(x) of complex inputs. - Real: Extracts the real part real(x) of complex inputs. - Imag: Extracts the imaginary part imag(x); returns zero for real tensors. - Abs: Returns the magnitude or absolute value abs(x). - Conj, Conjugate: Returns the complex conjugate conj(x).

Miscellaneous Mathematical Functions: - Sqrt: Applies the square root sqrt(x) elementwise. - Square: Applies squaring operation x**2 elementwise. - Sign: Applies the sign function sign(x); returns -1, 0, or 1.

Examples

>>> import deeptrack as dt

Import the backend-agnostic functionality from DeepTrack2:

>>> from deeptrack.backend  import xp

Create an elementwise feature to execute a backend-agnostic function:

>>> from deeptrack.elementwise import create_elementwise_class
>>>
>>> Abs = create_elementwise_class(
...     name="Abs",
...     function=xp.abs,
...     docstring="Elementwise abs function."
... )
>>>
>>> abs_feature = Abs()

NumPy backend with direct resolved input

>>> import numpy as np
>>>
>>> array = np.array([-1.0, 0.0, 2.5])
>>> result = Abs()(array)
>>> result
array([1. , 0. , 2.5])

PyTorch backend with direct resolved input

>>> import torch
>>>
>>> tensor = torch.tensor([-1.0, 0.0, 2.5])
>>> result = Abs()(tensor)
>>> result
tensor([1.0000, 0.0000, 2.5000])

NumPy pipeline

>>> value = dt.Value(value=np.array([-3.0, 0.0, 3.0]))
>>> pipeline = value >> Abs()
>>> result = pipeline()
>>> result
array([3., 0., 3.])

This is equivalent to:

>>> pipeline = Abs(value)

PyTorch pipeline

>>> value = dt.Value(value=torch.tensor([-3.0, 0.0, 3.0]))
>>> pipeline = value >> Abs()
>>> result = pipeline()
>>> result
tensor([3., 0., 3.])

This is equivalent to:

>>> pipeline = Abs(value)

Functions

create_elementwise_class(name, function[, ...])

Factory function to create subclasses of ElementwiseFeature.

Classes

ElementwiseFeature(function[, feature, ...])	Base class for applying NumPy or PyTorch functions elementwise.
Sin([feature])	Apply the sine function elementwise.
Cos([feature])	Apply the cosine function elementwise.
Tan([feature])	Apply the tangent function elementwise.
Arcsin([feature])	Apply the arcsine function elementwise.
Arctan([feature])	Apply the arctangent function elementwise.
Sinh([feature])	Apply the hyperbolic sine function elementwise.
Cosh([feature])	Apply the hyperbolic cosine function elementwise.
Tanh([feature])	Apply the hyperbolic tangent function elementwise.
Arcsinh([feature])	Apply the inverse hyperbolic sine function elementwise.
Arccosh([feature])	Apply the inverse hyperbolic cosine function elementwise.
Arctanh([feature])	Apply the inverse hyperbolic tangent function elementwise.
Round([feature])	Apply the rounding function elementwise.
Floor([feature])	Apply the floor function elementwise.
Ceil([feature])	Apply the ceiling function elementwise.
Exp([feature])	Apply the exponential function elementwise.
Log([feature])	Apply the natural logarithm function elementwise.
Log10([feature])	Apply the base-10 logarithm function elementwise.
Log2([feature])	Apply the base-2 logarithm function elementwise.
Angle([feature])	Apply the angle (phase) function elementwise.
Real([feature])	Apply the real-part function elementwise.
Imag([feature])	Apply the imaginary-part function elementwise.
Abs([feature])	Apply the absolute value function elementwise.
Conj([feature])	Apply the complex conjugate function elementwise.
Conjugate	alias of Conj
Sqrt([feature])	Apply the square root function elementwise.
Square([feature])	Apply the square function elementwise.
Sign([feature])	Apply the sign function elementwise.