Differentiation

The differentiation module provides tools for calculating numerical derivatives of data in pandas.DataFrame objects. It includes methods forward_difference and backward_difference for approximating derivatives using one-sided differences, and central_difference for a more accurate two-sided approach. The derivative function simply wraps central_difference.

forward_difference(df, x_column, y_column)

Calculates the forward difference of a given DataFrame.

Parameters:

Name	Type	Description	Default
df	DataFrame	The DataFrame containing the data.	required
x_column	str	The name of the column representing the x-values.	required
y_column	str	The name of the column representing the y-values.	required

Returns:

Type	Description
Series	pandas.Series: A Series containing the forward differences of the y-values with respect to the x-values.

Examples:

>>> import quantalize as qz
>>> df['forward_diff'] = qz.forward_difference(df, 'x', 'y')

Source code in src/quantalyze/core/differentiation.py

def forward_difference(df, x_column, y_column) -> pd.Series:
    """
    Calculates the forward difference of a given DataFrame.

    Args:
        df (pandas.DataFrame): The DataFrame containing the data.
        x_column (str): The name of the column representing the x-values.
        y_column (str): The name of the column representing the y-values.

    Returns:
        pandas.Series: A Series containing the forward differences of the y-values with respect to the x-values.

    Examples:
        >>> import quantalize as qz
        >>> df['forward_diff'] = qz.forward_difference(df, 'x', 'y')
    """
    forward_diff = df[y_column].diff().shift(-1) / df[x_column].diff().shift(-1)
    return forward_diff

backward_difference(df, x_column, y_column)

Calculates the backward difference of a DataFrame column.

Parameters:

Name	Type	Description	Default
df	DataFrame	The DataFrame containing the data.	required
x_column	str	The name of the column to use as the x-values.	required
y_column	str	The name of the column to use as the y-values.	required

Returns:

Type	Description
Series	pandas.Series: The backward difference of the y_column with respect to the x_column.

Examples:

>>> import quantalize as qz
>>> df['backward_diff'] = qz.backward_difference(df, 'x', 'y')

Source code in src/quantalyze/core/differentiation.py

def backward_difference(df, x_column, y_column) -> pd.Series:
    """
    Calculates the backward difference of a DataFrame column.

    Args:
        df (pandas.DataFrame): The DataFrame containing the data.
        x_column (str): The name of the column to use as the x-values.
        y_column (str): The name of the column to use as the y-values.

    Returns:
        pandas.Series: The backward difference of the y_column with respect to the x_column.

    Examples:
        >>> import quantalize as qz
        >>> df['backward_diff'] = qz.backward_difference(df, 'x', 'y')
    """
    backward_diff = df[y_column].diff() / df[x_column].diff()
    return backward_diff

central_difference(df, x_column, y_column)

Calculates the central difference for a given DataFrame.

The central difference is computed as the average of the forward difference and the backward difference for the specified columns.

Parameters:

Name	Type	Description	Default
df	DataFrame	The input DataFrame containing the data.	required
x_column	str	The name of the column representing the x-values.	required
y_column	str	The name of the column representing the y-values.	required

Returns:

Type	Description
Series	pandas.Series: A Series containing the central difference values.

Examples:

>>> import quantalize as qz
>>> df['central_diff'] = qz.central_difference(df, 'x', 'y')

Source code in src/quantalyze/core/differentiation.py

def central_difference(df, x_column, y_column) -> pd.Series:
    """
    Calculates the central difference for a given DataFrame.

    The central difference is computed as the average of the forward difference
    and the backward difference for the specified columns.

    Args:
        df (pandas.DataFrame): The input DataFrame containing the data.
        x_column (str): The name of the column representing the x-values.
        y_column (str): The name of the column representing the y-values.

    Returns:
        pandas.Series: A Series containing the central difference values.

    Examples:
        >>> import quantalize as qz
        >>> df['central_diff'] = qz.central_difference(df, 'x', 'y')
    """
    forward_diff = forward_difference(df, x_column, y_column)
    backward_diff = backward_difference(df, x_column, y_column)
    central_diff = (forward_diff + backward_diff) / 2
    return central_diff

derivative(df, x_column, y_column)

Calculates the derivative of the y_column with respect to the x_column.

This method computes the numerical derivative of a given y_column with respect to an x_column in a pandas DataFrame using the central difference method.

Parameters:

Name	Type	Description	Default
df	DataFrame	The input DataFrame containing the data.	required
x_column	str	The name of the column representing the x-axis.	required
y_column	str	The name of the column representing the y-axis.	required

Returns:

Type	Description
Series	pandas.Series: A Series with the derivative values.

Examples:

>>> import quantalize as qz
>>> df['derivative'] = qz.derivative(df, 'x', 'y')

Source code in src/quantalyze/core/differentiation.py

def derivative(df, x_column, y_column) -> pd.Series:
    """
    Calculates the derivative of the y_column with respect to the x_column.

    This method computes the numerical derivative of a given y_column with respect to an x_column
    in a pandas DataFrame using the central difference method.

    Args:
        df (pandas.DataFrame): The input DataFrame containing the data.
        x_column (str): The name of the column representing the x-axis.
        y_column (str): The name of the column representing the y-axis.

    Returns:
        pandas.Series: A Series with the derivative values.

    Examples:
        >>> import quantalize as qz
        >>> df['derivative'] = qz.derivative(df, 'x', 'y')
    """
    return central_difference(df, x_column, y_column)