Source code for interpreTS.core.features.feature_variance

import pandas as pd
import numpy as np



def calculate_variance(data, ddof=0):
    """
    Calculate the variance value of a time series with specified degrees of freedom.
    
    Parameters
    ----------
    data : pd.Series or np.ndarray
        The time series data for which the variance is to be calculated.
    ddof : int, optional
        Delta degrees of freedom. The divisor used in calculations is N - ddof, where N is the number of elements. 
        A ddof of 1 provides the sample variance, and a ddof of 0 provides the population variance. Default is 1.
        
    Returns
    -------
    float
        The variance of the provided time series with specified degrees of freedom.
        
    Raises
    ------
    TypeError
        If the data is not numeric.
    ValueError
        If the data contains NaN values or is not one-dimensional.

    Examples
    --------
    >>> import pandas as pd
    >>> import numpy as np
    >>> data = pd.Series([10, 12, 14, 16, 18])
    >>> calculate_variance(data)
    10.0

    >>> data = np.array([2, 4, 6, 8, 10])
    >>> calculate_variance(data, ddof=0)
    8.0

    >>> data = pd.Series([5])
    >>> calculate_variance(data)
    0.0
    """
    # Handle the case where the series has only one value
    if len(data) == 1:
        return 0.0

    # Calculate and return the variance with specified ddof, handling empty series by returning NaN
    return np.var(data, ddof=ddof) if len(data) > 0 else np.nan