Quant.Math.Utils (quant v0.1.0-alpha.1)

Shared utility functions for mathematical operations in the Quant.Math module.

This module provides common utilities used across different technical indicator implementations, including DataFrame/NX bridge functions, validation, and core mathematical operations.

Summary

Functions

exponential_mean(tensor, period, alpha \\ nil)

Calculate exponential moving average over a tensor.

rolling_mean(tensor, window_size)

Calculate rolling mean over a tensor using a sliding window.

to_series(tensor, name)

Convert an NX Tensor back to an Explorer Series.

to_tensor(series)

Convert an Explorer Series to an NX Tensor.

validate_column(df, column)

Validate that a column exists in the DataFrame.

validate_column!(df, column)

Validate that a column exists in the DataFrame and raise if not.

validate_dataframe!(df)

Validate that a DataFrame is valid and raise if not.

validate_period!(period, name \\ "period")

Validate that a period is a positive integer and raise if not.

weighted_mean(tensor, period, weights \\ nil)

Calculate weighted moving average over a tensor using a sliding window.

Functions

exponential_mean(tensor, period, alpha \\ nil)

@spec exponential_mean(Nx.Tensor.t(), pos_integer(), float() | nil) :: Nx.Tensor.t()

Calculate exponential moving average over a tensor.

Parameters

  • tensor - The input NX Tensor
  • period - The period for the EMA calculation
  • alpha - Optional alpha (smoothing factor). If not provided, uses 2/(period+1)

Returns

  • Nx.Tensor.t() - Tensor with EMA values, first value is SMA of first period values

Algorithm

  • First EMA value = SMA of first period values
  • Subsequent EMA values = alpha current_price + (1 - alpha) previous_ema
  • Default alpha = 2 / (period + 1)

rolling_mean(tensor, window_size)

@spec rolling_mean(Nx.Tensor.t(), pos_integer()) :: Nx.Tensor.t()

Calculate rolling mean over a tensor using a sliding window.

Parameters

  • tensor - The input NX Tensor
  • window_size - The size of the rolling window

Returns

  • Nx.Tensor.t() - Tensor with rolling means, NaN for insufficient data

to_series(tensor, name)

@spec to_series(Nx.Tensor.t(), String.t()) :: Explorer.Series.t()

Convert an NX Tensor back to an Explorer Series.

Parameters

  • tensor - The NX Tensor to convert
  • name - The name for the series (currently unused but kept for API consistency)

Returns

  • Series.t() - The converted series with :f64 dtype

to_tensor(series)

@spec to_tensor(Explorer.Series.t()) :: Nx.Tensor.t()

Convert an Explorer Series to an NX Tensor.

Parameters

  • series - The Explorer Series to convert

Returns

  • Nx.Tensor.t() - The converted tensor with :f64 type

validate_column(df, column)

@spec validate_column(Explorer.DataFrame.t(), atom()) :: :ok | {:error, String.t()}

Validate that a column exists in the DataFrame.

Parameters

  • df - The DataFrame to check
  • column - The column name (atom) to validate

Returns

  • :ok if column exists
  • {:error, message} if column is missing

validate_column!(df, column)

@spec validate_column!(Explorer.DataFrame.t(), atom()) :: :ok

Validate that a column exists in the DataFrame and raise if not.

Parameters

  • df - The DataFrame to check
  • column - The column name (atom) to validate

Returns

  • :ok if column exists

Raises

validate_dataframe!(df)

@spec validate_dataframe!(any()) :: :ok

Validate that a DataFrame is valid and raise if not.

Parameters

  • df - The DataFrame to validate

Returns

  • :ok if valid DataFrame

Raises

validate_period!(period, name \\ "period")

@spec validate_period!(any(), String.t()) :: :ok

Validate that a period is a positive integer and raise if not.

Parameters

  • period - The period to validate
  • name - Optional name for better error messages (default: "period")

Returns

  • :ok if valid period

Raises

weighted_mean(tensor, period, weights \\ nil)

@spec weighted_mean(Nx.Tensor.t(), pos_integer(), Nx.Tensor.t() | nil) ::
  Nx.Tensor.t()

Calculate weighted moving average over a tensor using a sliding window.

Parameters

  • tensor - The input NX Tensor
  • period - The period for the WMA calculation
  • weights - Optional weight vector. If not provided, uses linear weights [1, 2, 3, ..., period]

Returns

  • Nx.Tensor.t() - Tensor with WMA values, NaN for insufficient data

Algorithm

  • Default weights: Linear sequence [1, 2, 3, ..., period]
  • WMA = Σ(price_i × weight_i) / Σ(weight_i)
  • Gives more weight to recent prices in the linear case