Skip to content

sse #

Functions to calculate the squared standard error series.

Functions:

get_sse_series_init_seq #

get_sse_series_init_seq(
    data: NDArray[float64],
    sequence_estimator: str = "initial_convex",
    min_max_lag_time: int = 3,
    max_max_lag_time: int | None = None,
    smooth_lag_times: bool = False,
    frac_padding: float = 0.1,
) -> tuple[NDArray[float64], NDArray[float64]]

Compute a series of squared standard errors for a time series.

Squared standard errors are computed as data is discarded from the beginning of the time series. The squared standard error is computed using the sequence estimator specified.

Parameters:

  • data (ndarray) –

    A time series of data with shape (n_samples,).

  • sequence_estimator (str, default: 'initial_convex' ) –

    The initial sequence estimator to use. Can be "positive", "initial_positive", "initial_monotone", or "initial_convex". The default is "initial_convex". "positive" corresponds to truncating the auto-covariance function at the first negative value, as is done in pymbar. The other methods correspond to the methods described in Geyer, 1992: https://www.jstor.org/stable/2246094.

  • min_max_lag_time (int, default: 3 ) –

    The minimum maximum lag time to use when estimating the statistical inefficiency.

  • max_max_lag_time (int, default: None ) –

    The maximum maximum lag time to use when calculating the auto-correlation function. If None, the maximum lag time will be the length of the time series.

  • smooth_lag_times (bool, default: False ) –

    Whether to smooth out the max lag times by a) converting them to a monotinically decreasing sequence and b) linearly interpolating between points where the sequence changes. This may be useful when the max lag times are noisy.

  • frac_padding (float, default: 0.1 ) –

    The fraction of the end of the timeseries to avoid calculating the variance for. For example, if frac_padding = 0.1, the variance will be calculated for the first 90% of the time series. This helps to avoid noise in the variance when there are few data points.

Returns:

  • ndarray –

    The squared standard error series.

  • ndarray –

    The maximum lag times used.

Source code in red/sse.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
def get_sse_series_init_seq(
    data: _npt.NDArray[_np.float64],
    sequence_estimator: str = "initial_convex",
    min_max_lag_time: int = 3,
    max_max_lag_time: int | None = None,
    smooth_lag_times: bool = False,
    frac_padding: float = 0.1,
) -> tuple[_npt.NDArray[_np.float64], _npt.NDArray[_np.float64]]:
    """Compute a series of squared standard errors for a time series.

    Squared standard errors are computed as data is discarded from the beginning of the
    time series. The squared standard error is computed using the sequence estimator
    specified.

    Parameters
    ----------
    data : numpy.ndarray
        A time series of data with shape (n_samples,).

    sequence_estimator : str, optional
        The initial sequence estimator to use. Can be "positive", "initial_positive",
        "initial_monotone", or "initial_convex". The default is "initial_convex". "positive"
        corresponds to truncating the auto-covariance function at the first negative value, as is
        done in pymbar. The other methods correspond to the methods described in Geyer, 1992:
        https://www.jstor.org/stable/2246094.

    min_max_lag_time : int, optional, default=3
        The minimum maximum lag time to use when estimating the statistical inefficiency.

    max_max_lag_time : int, optional, default=None
        The maximum maximum lag time to use when calculating the auto-correlation function.
        If None, the maximum lag time will be the length of the time series.

    smooth_lag_times : bool, optional, default=False
        Whether to smooth out the max lag times by a) converting them to a monotinically
        decreasing sequence and b) linearly interpolating between points where the sequence
        changes. This may be useful when the max lag times are noisy.

    frac_padding : float, optional, default=0.1
        The fraction of the end of the timeseries to avoid calculating the variance
        for. For example, if frac_padding = 0.1, the variance will be calculated
        for the first 90% of the time series. This helps to avoid noise in the
        variance when there are few data points.

    Returns
    -------
    np.ndarray
        The squared standard error series.

    np.ndarray
        The maximum lag times used.

    """
    # Validate the data.
    data = check_data(data, one_dim_allowed=True)
    n_runs, n_samples = data.shape

    # Compute the variance estimates.
    var_series, max_lag_times = get_variance_series_initial_sequence(
        data,
        sequence_estimator=sequence_estimator,
        min_max_lag_time=min_max_lag_time,
        max_max_lag_time=max_max_lag_time,
        smooth_lag_times=smooth_lag_times,
        frac_padding=frac_padding,
    )

    # Compute the squared standard error series by dividing the variance series by
    # the total number of samples.
    tot_samples = _np.arange(n_samples, n_samples - len(var_series), -1) * n_runs
    sse_series = var_series / tot_samples

    return sse_series, max_lag_times

get_sse_series_window #

get_sse_series_window(
    data: NDArray[float64],
    kernel: Callable[[int], NDArray[float64]] = bartlett,
    window_size_fn: (
        Callable[[int], int] | None
    ) = lambda x: round(x**0.5),
    window_size: int | None = None,
    frac_padding: float = 0.1,
) -> tuple[NDArray[float64], NDArray[float64]]

Compute a series of squared standard errors for a time series.

Squared standard errors are computed as data is discarded from the beginning of the time series. The squared standard error is computed using the window size and kernel specified.

Parameters:

  • data (ndarray) –

    A time series of data with shape (n_samples,).

  • kernel (callable, default: numpy.bartlett ) –

    A function that takes a window size and returns a window function.

  • window_size_fn (callable, default: lambda x: round(x**0.5) ) –

    A function that takes the length of the time series and returns the window size to use. If this is not None, window_size must be None.

  • window_size (int, default: None ) –

    The size of the window to use, defined in terms of time lags in the forwards direction. If this is not None, window_size_fn must be None.

  • frac_padding (float, default: 0.1 ) –

    The fraction of the end of the timeseries to avoid calculating the variance for. For example, if frac_padding = 0.1, the variance will be calculated for the first 90% of the time series. This helps to avoid noise in the variance when there are few data points.

Returns:

  • ndarray –

    The squared standard error series.

  • ndarray –

    The window sizes used.

Source code in red/sse.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
def get_sse_series_window(
    data: _npt.NDArray[_np.float64],
    kernel: _Callable[[int], _npt.NDArray[_np.float64]] = _np.bartlett,
    window_size_fn: _Callable[[int], int] | None = lambda x: round(x**0.5),
    window_size: int | None = None,
    frac_padding: float = 0.1,
) -> tuple[_npt.NDArray[_np.float64], _npt.NDArray[_np.float64]]:
    """Compute a series of squared standard errors for a time series.

    Squared standard errors are computed as data is discarded from the beginning of the
    time series. The squared standard error is computed using the window size and kernel
    specified.

    Parameters
    ----------
    data : numpy.ndarray
        A time series of data with shape (n_samples,).

    kernel : callable, optional, default=numpy.bartlett
        A function that takes a window size and returns a window function.

    window_size_fn : callable, optional, default=lambda x: round(x**0.5)
        A function that takes the length of the time series and returns the window size
        to use. If this is not None, window_size must be None.

    window_size : int, optional, default=None
        The size of the window to use, defined in terms of time lags in the
        forwards direction. If this is not None, window_size_fn must be None.

    frac_padding : float, optional, default=0.1
        The fraction of the end of the timeseries to avoid calculating the variance
        for. For example, if frac_padding = 0.1, the variance will be calculated
        for the first 90% of the time series. This helps to avoid noise in the
        variance when there are few data points.

    Returns
    -------
    np.ndarray
        The squared standard error series.

    np.ndarray
        The window sizes used.

    """
    # Validate the data.
    data = check_data(data, one_dim_allowed=True)
    n_runs, n_samples = data.shape

    # Compute the variance estimates.
    var_series, window_sizes = get_variance_series_window(
        data,
        kernel=kernel,
        window_size_fn=window_size_fn,
        window_size=window_size,
        frac_padding=frac_padding,
    )

    # Compute the squared standard error series by dividing the variance series by
    # the total number of samples.
    tot_samples = _np.arange(n_samples, n_samples - len(var_series), -1) * n_runs
    sse_series = var_series / tot_samples

    return sse_series, window_sizes