signature_calculator Module

The signature_calculator module implements path signature computation using the roughpy library with Lie increment calculations. Path signatures provide a mathematically rigourous framework for capturing geometric and temporal features of advertising creative performance data, enabling detection of creative fatigue patterns in advertising campaigns.

Mathematical Foundation

The module computes signatures as elements of the free Lie algebra, which offers computational efficiency while maintaining the full expressiveness of tensor algebra representations. For a d-dimensional path X:[0,T] → ℝ^d, the signature S(X) encodes:

  • Level 1: Path increments (directional changes)

  • Level 2: Signed areas and path curvature

  • Higher levels: Complex geometric interactions

Key Implementation Details

  • Lie Increments: Uses roughpy with Lie algebra computations rather than tensor products

  • Normalization: All paths are normalized to [0,1]×[0,1] before signature computation

  • Numerical Stability: Adds ε=10^-8 to prevent division by zero for constant metrics

  • Default Parameters:

    • Signature depth: 2 (captures up to quadratic variations)

    • Window size: 7 (weekly patterns in daily data)

Core Functions

Signature Computation for CreativeDynamics Library

This module provides signature computation functionality using the roughpy library for the CreativeDynamics time-series analysis package.

Copyright (c) 2024-2025 T&P Data Science Ltd. Author(s): Charles Shaw Created: 2024-07-19 Last Modified: 2025-11-26

creativedynamics.core.signature_calculator.get_cache_stats() → dict[source]

Get signature cache statistics.

Returns:

Dictionary with cache hit/miss counts and hit rate.

creativedynamics.core.signature_calculator.clear_signature_cache() → None[source]

Clear the signature computation cache.

creativedynamics.core.signature_calculator.calculate_path_signature(time_values: ndarray[tuple[int, ...], dtype[float64]], metric_values: ndarray[tuple[int, ...], dtype[float64]], depth: int = 4, normalize: bool = True) → ndarray[tuple[int, ...], dtype[float64]][source]

Compute the signature of a path using the roughpy library.

Parameters:

  • time_values (numpy.ndarray) – Array of time values (1D).

  • metric_values (numpy.ndarray) – Array of metric values (1D).

  • depth (int) – Truncation depth for signature computation. Defaults to 4.

  • normalize (bool) – Whether to normalize the path before computing the signature. Time is scaled to [0, 1]. Metric is min-max scaled to [0, 1]. Defaults to True.

Returns:

Flattened signature of the path. Returns an empty array if path length < 2.

Return type:

numpy.ndarray

creativedynamics.core.signature_calculator.calculate_path_signature_cached(time_values: ndarray[tuple[int, ...], dtype[float64]], metric_values: ndarray[tuple[int, ...], dtype[float64]], depth: int = 4, normalize: bool = True) → ndarray[tuple[int, ...], dtype[float64]][source]

Compute signature with LRU caching for repeated calculations.

This function caches results based on the input arrays, making it significantly faster when computing signatures for overlapping sliding windows or repeated analyses.

Parameters:

  • time_values (numpy.ndarray) – Array of time values (1D).

  • metric_values (numpy.ndarray) – Array of metric values (1D).

  • depth (int) – Truncation depth for signature computation. Defaults to 4.

  • normalize (bool) – Whether to normalize the path. Defaults to True.

Returns:

Flattened signature of the path.

Return type:

numpy.ndarray

Note

Use clear_signature_cache() to clear the cache when memory is a concern or between different analysis runs.

creativedynamics.core.signature_calculator.compute_signature(time_values: ndarray[tuple[int, ...], dtype[float64]], metric_values: ndarray[tuple[int, ...], dtype[float64]], depth: int = 4, normalize: bool = True, method: str | None = None) → ndarray[tuple[int, ...], dtype[float64]][source]

Wrapper function to compute the signature of a 2D path (time vs. metric) using the roughpy library.

This function constructs a 2D path from the provided time and metric values, optionally normalizes it, and then computes its truncated signature up to the specified depth. The signature includes all terms from level 0 to the specified depth.

Parameters:

  • time_values (numpy.ndarray) – Array of time values (1D).

  • metric_values (numpy.ndarray) – Array of metric values (1D).

  • depth (int, optional) – The truncation depth for the signature computation. Defaults to 4.

  • normalize (bool, optional) – Whether to normalize the path data before computing the signature. If True, time is scaled to [0, 1] and the metric is min-max scaled to [0, 1]. Defaults to True.

  • method (Optional[str], optional) – This argument is ignored and only present for backward compatibility. The computation always uses roughpy. Defaults to None.

Returns:

A flattened numpy array representing the computed path

signature. Returns an empty array if the path has fewer than 2 points or if an error occurs during computation.

Return type:

numpy.ndarray

Usage Example

from creativedynamics.core.signature_calculator import SignatureCalculator

# Initialize calculator
calc = SignatureCalculator(depth=2)

# Compute signature for a time series
import numpy as np
time_series = np.array([1.0, 1.2, 1.1, 1.3, 1.4, 1.2, 1.0])
signature = calc.compute_signature(time_series)

# The signature is a vector containing Lie increments
# that capture the geometric properties of the path

Algorithm Complexity

The computational complexity for signature calculation is O(T·d²) where:

  • T is the length of the time series

  • d is the signature depth

  • This assumes a fixed window size w

This efficiency enables real-time analysis of advertising performance data at scale.