financial.fractional_differentiation
====================================

.. py:module:: financial.fractional_differentiation

.. autoapi-nested-parse::

   Implementation of fractional differentiation from the book
   `Advances in Financial Machine Learning` by Marcos Lopez de Prado.

   Fractional differentiation is a technique to make time series stationary
   while preserving the memory of the original data.

   This implementation utilizes a fixed window size to calculate the
   fractional differentiation. Note that this implementation is a simplified
   version compared to the one presented in the book by Marcos Lopez de Prado.
   Here, we do not consider the weight loss. In the book, weight loss is
   calculated to account for the fact that the initial points in
   the series carry different amounts of information than the final points.

   In the calculation of fractional differentiation,
   the price is convolved with the weights to obtain the
   fractional differentiated series. This process enables the
   transformation of the time series into a stationary form while
   retaining the memory of the original data.

   To determine the optimal degree of differentiation,
   one needs to find the minimum value of the differentiation degree,
   a value between 0 and 1, that renders the time series stationary.

   Reference
   ---------
   https://www.wiley.com/en-us/Advances+in+Financial+Machine+Learning-p-9781119482086

   https://papers.ssrn.com/sol3/papers.cfm?abstract_id=3257419



Functions
---------

.. autoapisummary::

   financial.fractional_differentiation.calculate_weights
   financial.fractional_differentiation.fracdiff_fixedwindow


Module Contents
---------------

.. py:function:: calculate_weights(degree: float, length: int) -> list[float]

   Calculate the weights for fractional differentiation.

   .. math::

       w_{0} = 1
       w_{k} = -w_{k-1} * (d - k + 1) / k

   Parameters
   ----------
   degree : float
       The degree of differentiation.
   length : int
       The length of the weights.

   Returns
   -------
   list[float]
       The weights for fractional differentiation.

   Examples
   --------
   >>> calculate_weights(0.5, 3)
   [1.0, -0.5, -0.125]
   >>> calculate_weights(0.5, 4)
   [1.0, -0.5, -0.125, -0.0625]


.. py:function:: fracdiff_fixedwindow(price_series: collections.abc.Sequence[float], degree: float, window_size: int) -> list[float]

   Calculate the fractional differentiation with a fixed window size.

   Parameters
   ----------
   price_series : Sequence[float]
       The price series to calculate the fractional differentiation.
   degree : float
       The degree of differentiation.
   window_size : int
       The number of past observations used to compute each value.

   Returns
   -------
   list[float]
       The fractional differentiated series.

   Raises
   ------
   ValueError
       If ``window_size`` is greater than the length of ``price_series``.

   Examples
   --------
   >>> price_series = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
   >>> fracdiff_fixedwindow(price_series, 0.5, 3)
   [nan, nan, nan, 2.25, 2.625, 3.0, 3.375, 3.75, 4.125, 4.5]