mean_crossing_rate

timecave.data_characteristics.mean_crossing_rate(ts)

Compute the series' mean-crossing rate.

This function computes the mean-crossing rate of a given time series. The mean-crossing rate is defined as the rate at which the values of a time series change from being below its mean value to above said value. In practice, the mean is subtracted from the time series, and the zero-crossing rate is then computed.

Parameters:

Name	Type	Description	Default
ts	ndarray | Series	Univariate time series.	required

Returns:

Type	Description
float	Mean-crossing rate.

Raises:

Type	Description
TypeError	If ts is neither a Numpy array nor a Pandas series.

See also

median_crossing_rate: Uses the median instead of the mean.

Notes

The mean-crossing rate is defined as the fraction of times a mean-crossing takes place in the whole time series. A mean-crossing occurs when two adjacent values have different signs with respect to the mean (i.e. the first one is below the mean while the second one is above it, and vice-versa).

\[ MCR = \frac{1}{n-1} \sum_{i=2}^{n} |sign(a_i - \mu) - sign(a_{i-1} - \mu)| \]

where \(n\) is the number of samples in the time series, \(a_i\) are its values, and \(\mu\) represents its mean. For more details, please refer to [1].

References

1

Bohdan Myroniv, Cheng-Wei Wu, Yi Ren, Albert Christian, Ensa Bajo, and Yu-chee Tseng. Analyzing user emotions via physiology signals. Data Science and Pattern Recognition, 2, 12 2017.

Examples:

>>> import numpy as np
>>> from timecave.data_characteristics import mean_crossing_rate
>>> ts = np.array([0, 20, 0, 20, 0]);
>>> mean_crossing_rate(ts)
1.0
>>> ts2 = np.ones(10);
>>> mean_crossing_rate(ts2)
0.0
>>> ts3 = np.array([50, 50, 50, 0, 0]);
>>> mean_crossing_rate(ts3)
0.25

If the time series is neither an array nor a series, an exception is thrown:

>>> mean_crossing_rate([0, 1, 2])
Traceback (most recent call last):
...
TypeError: Time series must be either a Numpy array or a Pandas series.

Source code in timecave/data_characteristics.py

def mean_crossing_rate(ts: np.ndarray | pd.Series) -> float:

    """
    Compute the series' mean-crossing rate.

    This function computes the mean-crossing rate of a given time series.
    The mean-crossing rate is defined as the rate at which the values of a time
    series change from being below its mean value to above said value.
    In practice, the mean is subtracted from the time series, and the zero-crossing
    rate is then computed.

    Parameters
    ----------
    ts : np.ndarray | pd.Series
        Univariate time series.

    Returns
    -------
    float
        Mean-crossing rate.

    Raises
    ------
    TypeError
        If `ts` is neither a Numpy array nor a Pandas series.

    See also
    --------
    [median_crossing_rate](med_cr.md):
        Uses the median instead of the mean.

    Notes
    -----
    The mean-crossing rate is defined as the fraction of times a mean-crossing takes place in the whole time series. \
    A mean-crossing occurs when two adjacent values have different signs with respect to the mean \
    (i.e. the first one is below the mean while the second one is above it, and vice-versa).

    $$
    MCR = \\frac{1}{n-1} \sum_{i=2}^{n} |sign(a_i - \mu) - sign(a_{i-1} - \mu)|  
    $$

    where $n$ is the number of samples in the time series, $a_i$ are its values, and $\mu$ represents its mean.
    For more details, please refer to [[1]](#1).

    References
    ----------
    ##1
    Bohdan Myroniv, Cheng-Wei Wu, Yi Ren, Albert Christian, Ensa Bajo,
    and Yu-chee Tseng. Analyzing user emotions via physiology signals. Data
    Science and Pattern Recognition, 2, 12 2017.

    Examples
    --------
    >>> import numpy as np
    >>> from timecave.data_characteristics import mean_crossing_rate
    >>> ts = np.array([0, 20, 0, 20, 0]);
    >>> mean_crossing_rate(ts)
    1.0
    >>> ts2 = np.ones(10);
    >>> mean_crossing_rate(ts2)
    0.0
    >>> ts3 = np.array([50, 50, 50, 0, 0]);
    >>> mean_crossing_rate(ts3)
    0.25

    If the time series is neither an array nor a series, an exception is thrown:

    >>> mean_crossing_rate([0, 1, 2])
    Traceback (most recent call last):
    ...
    TypeError: Time series must be either a Numpy array or a Pandas series.
    """

    _check_type(ts);

    new_ts = ts - ts.mean();

    if(isinstance(ts, pd.Series) is True):

        ts = ts.to_numpy();

    mcr = np.nonzero(np.diff(np.sign(new_ts)))[0].shape[0] / (ts.shape[0] - 1);

    return mcr;