Rolling and rolling exponential averages (rolling)

Rolling and rolling exponential averages (rolling)#

Functions:

construct_rolling_window_array(x, window, *)

Convert an array to one with rolling windows.

rolling_data(data, *, window[, axis, dim, ...])

Moving average of central moments array.

rolling_vals(x, *y, mom, window[, axis, ...])

Moving average of central moments generated by values.

rolling_exp_data(data, alpha, *[, axis, ...])

Moving average of central moments array.

rolling_exp_vals(x, *y, alpha, mom[, axis, ...])

Moving average of central moments generated by values.
cmomy.rolling.construct_rolling_window_array(x, window, *, axis=MISSING, dim=MISSING, center=False, stride=1, fill_value=nan, mom_ndim=None, mom_axes=None, mom_dims=None, mom_params=None, window_dim=None, keep_attrs=None, **kwargs)[source]#

Convert an array to one with rolling windows.

Parameters:

  • x (array or DataArray or Dataset) – Input array.

  • axis (int or iterable of int) – To sample along.

  • dim (str or sequence of hashable)

  • window (int or sequence of int) – Window size.

  • center (bool) – If True, center windows.

  • stride (int) – Size of strides in rolling window.

  • fill_value (scalar) – Fill value for missing values.

  • mom_ndim ({1, 2}, optional) – If mom_ndim is not None, then wrap axis relative to mom_ndim. For Example, with mom_ndim=``2``, axis = -1 will be transformed to axis = -3. If mom_dims is passed and data is an xarray object, infer mom_n=ndim from mom_dims.

  • mom_axes (int or tuple of int, optional) – Location of the moment dimensions. Default to (-mom_ndim, -mom_ndim+1, ...). If specified and mom_ndim is None, set mom_ndim to len(mom_axes). Note that if mom_axes is specified, negative values are relative to the end of the array. This is also the case for axes if mom_axes is specified.

  • mom_dims (hashable or tuple of hashable) – Name of moment dimensions. If specified, infer mom_ndim from mom_dims. If also pass mom_ndim, check that mom_dims is consistent with mom_dims. If not specified, defaults to data.dims[-mom_ndim:]. This is primarily used if data is a Dataset, or if mom_dims are not the last dimensions.

  • mom_params (MomParams or MomParamsDict or dict, optional) – Moment parameters. You can set moment parameters axes and dims using this option. For example, passing mom_params={"dim": ("a", "b")} is equivalent to passing mom_dims=("a", "b"). You can also pass as a MomParams object with mom_params=cmomy.MomParams(dims=("a", "b")).

  • window_dim (str or Sequence of str, optional) – Names of output window dimension(s). Default to rolling_dim : hashable Dimension to reduce/sample along. where dim : hashable Dimension to reduce/sample along. is replaced by dim names.

  • keep_attrs ({"drop", "identical", "no_conflicts", "drop_conflicts", "override"} or bool, optional) –

    • ‘drop’ or False: empty attrs on returned xarray object.

    • ’identical’: all attrs must be the same on every object.

    • ’no_conflicts’: attrs from all objects are combined, any that have the same name must also have the same value.

    • ’drop_conflicts’: attrs from all objects are combined, any that have the same name but different values are dropped.

    • ’override’ or True: skip comparing and copy attrs from the first object to the result.

  • **kwargs (Any) – Extra arguments to xarray.DataArray.rolling() or xarray.Dataset.rolling().

Returns:

output (array) – Array of shape (window, *shape).

Notes

This function uses different syntax compared to xarray.DataArray.rolling(). Instead of mappings for center, etc, here you pass scalar or sequence values corresponding to axis/dim. Corresponding mappings are created from, for example center=dict(zip(dim, center)).

Examples

>>> x = np.arange(5).astype(float)
>>> construct_rolling_window_array(x, window=4, axis=0)
array([[nan, nan, nan,  0.,  1.],
       [nan, nan,  0.,  1.,  2.],
       [nan,  0.,  1.,  2.,  3.],
       [ 0.,  1.,  2.,  3.,  4.]])

>>> dx = xr.DataArray(x)
>>> construct_rolling_window_array(dx, window=4, center=True, dim="dim_0")
<xarray.DataArray (rolling_dim_0: 4, dim_0: 5)> Size: 160B
array([[nan, nan,  0.,  1.,  2.],
       [nan,  0.,  1.,  2.,  3.],
       [ 0.,  1.,  2.,  3.,  4.],
       [ 1.,  2.,  3.,  4., nan]])
Dimensions without coordinates: rolling_dim_0, dim_0

See also

xarray.DataArray.rolling

cmomy.rolling.rolling_data(data, *, window, axis=MISSING, dim=MISSING, mom_ndim=None, mom_axes=None, mom_dims=None, mom_params=None, min_periods=None, center=False, zero_missing_weights=True, out=None, dtype=None, casting='same_kind', order=None, parallel=None, axes_to_end=False, keep_attrs=None, apply_ufunc_kwargs=None)[source]#

Moving average of central moments array.

Parameters:

  • data (array-like or DataArray or Dataset)

  • window (int) – Size of moving window.

  • axis (int) – Axis to reduce/sample along.

  • dim (hashable) – Dimension to reduce/sample along.

  • mom_ndim ({1, 2}, optional) – Value indicates if moments (mom_ndim = 1) or comoments (mom_ndim=2). If not specified and data is an xarray object attempt to infer mom_ndim from mom_dims. Otherwise, default to mom_ndim = 1.

  • mom_axes (int or tuple of int, optional) – Location of the moment dimensions. Default to (-mom_ndim, -mom_ndim+1, ...). If specified and mom_ndim is None, set mom_ndim to len(mom_axes). Note that if mom_axes is specified, negative values are relative to the end of the array. This is also the case for axes if mom_axes is specified.

  • mom_dims (hashable or tuple of hashable) – Name of moment dimensions. If specified, infer mom_ndim from mom_dims. If also pass mom_ndim, check that mom_dims is consistent with mom_dims. If not specified, defaults to data.dims[-mom_ndim:]. This is primarily used if data is a Dataset, or if mom_dims are not the last dimensions.

  • mom_params (MomParams or MomParamsDict or dict, optional) – Moment parameters. You can set moment parameters axes and dims using this option. For example, passing mom_params={"dim": ("a", "b")} is equivalent to passing mom_dims=("a", "b"). You can also pass as a MomParams object with mom_params=cmomy.MomParams(dims=("a", "b")).

  • min_periods (int, optional) – Minimum number of observations in window required to have a value (otherwise result is NA). The default, None, is equivalent to setting min_periods equal to the size of the window.

  • center (bool, default False) – If True, set the labels at the center of the window.

  • zero_missing_weights (bool, default True) – If True, set missing weights (np.nan) to 0.

  • out (ndarray) – Optional output array. If specified, output will be a reference to this array. Note that if the output if method returns a Dataset, then this option is ignored.

  • dtype (dtype) – Optional dtype for output data.

  • casting ({'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional) –

    Controls what kind of data casting may occur.

    • ’no’ means the data types should not be cast at all.

    • ’equiv’ means only byte-order changes are allowed.

    • ’safe’ means only casts which can preserve values are allowed.

    • ’same_kind’ means only safe casts or casts within a kind, like float64 to float32, are allowed.

    • ’unsafe’ (default) means any data conversions may be done.

  • order ({"C", "F", "A", "K"}, optional) – Order argument. See numpy.asarray().

  • parallel (bool, optional) – If True, use parallel numba numba.njit or numba.guvectorized code if possible. If None, use a heuristic to determine if should attempt to use parallel method.

  • axes_to_end (bool) – If True, place sampled dimension (if exists in output) and moment dimensions at end of output. Otherwise, place sampled dimension (if exists in output) at same position as input axis and moment dimensions at same position as input (if input does not contain moment dimensions, place them at end of array).

  • keep_attrs ({"drop", "identical", "no_conflicts", "drop_conflicts", "override"} or bool, optional) –

    • ‘drop’ or False: empty attrs on returned xarray object.

    • ’identical’: all attrs must be the same on every object.

    • ’no_conflicts’: attrs from all objects are combined, any that have the same name must also have the same value.

    • ’drop_conflicts’: attrs from all objects are combined, any that have the same name but different values are dropped.

    • ’override’ or True: skip comparing and copy attrs from the first object to the result.

  • apply_ufunc_kwargs (dict-like) – Extra parameters to xarray.apply_ufunc(). One useful option is on_missing_core_dim, which can take the value "copy" (the default), "raise", or "drop" and controls what to do with variables of a Dataset missing core dimensions. Other options are join, dataset_join, dataset_fill_value, and dask_gufunc_kwargs. Unlisted options are handled internally.

Returns:

out (ndarray or DataArray or Dataset) – Moving average data, of same shape and type as data.

cmomy.rolling.rolling_vals(x, *y, mom, window, axis=MISSING, dim=MISSING, weight=None, mom_axes=None, mom_dims=None, mom_params=None, min_periods=None, center=False, zero_missing_weights=True, out=None, dtype=None, casting='same_kind', order=None, parallel=None, axes_to_end=False, keep_attrs=None, apply_ufunc_kwargs=None)[source]#

Moving average of central moments generated by values.

Parameters:

  • x (array-like or DataArray or Dataset) – Values to reduce.

  • *y (array-like or DataArray or Dataset) – Additional values (needed if len(mom)==2). y has same type restrictions and broadcasting rules as weight.

  • mom (int or tuple of int) – Order or moments. If integer or length one tuple, then moments are for a single variable. If length 2 tuple, then comoments of two variables

  • window (int) – Size of moving window.

  • axis (int) – Axis to reduce/sample along.

  • dim (hashable) – Dimension to reduce/sample along.

  • weight (array-like or DataArray or Dataset) –

    Optional weight. The type of weight must be “less than” the type of x.

    In the case that weight is array-like, it must broadcast to x using usual broadcasting rules (see numpy.broadcast_to()), with the following exceptions: If weight is a 1d array of length x.shape[axis]], it will be formatted to broadcast along the other dimensions of x. For example, if x has shape (10, 2, 3) and weight has shape (10,), then weight will be converted to the broadcastable shape (10, 1, 1). If weight is a scalar, it will be broadcast to x.shape.

  • mom_axes (int or tuple of int, optional) – Location of the moment dimensions. Default to (-mom_ndim, -mom_ndim+1, ...). If specified and mom_ndim is None, set mom_ndim to len(mom_axes). Note that if mom_axes is specified, negative values are relative to the end of the array. This is also the case for axes if mom_axes is specified.

  • mom_dims (hashable or tuple of hashable) – Name of moment dimensions. Defaults to ("mom_0",) for mom_ndim==1 and (mom_0, mom_1) for mom_ndim==2

  • mom_params (MomParams or MomParamsDict or dict, optional) – Moment parameters. You can set moment parameters axes and dims using this option. For example, passing mom_params={"dim": ("a", "b")} is equivalent to passing mom_dims=("a", "b"). You can also pass as a MomParams object with mom_params=cmomy.MomParams(dims=("a", "b")).

  • min_periods (int, optional) – Minimum number of observations in window required to have a value (otherwise result is NA). The default, None, is equivalent to setting min_periods equal to the size of the window.

  • center (bool, default False) – If True, set the labels at the center of the window.

  • zero_missing_weights (bool, default True) – If True, set missing weights (np.nan) to 0.

  • out (ndarray) – Optional output array. If specified, output will be a reference to this array. Note that if the output if method returns a Dataset, then this option is ignored.

  • dtype (dtype) – Optional dtype for output data.

  • casting ({'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional) –

    Controls what kind of data casting may occur.

    • ’no’ means the data types should not be cast at all.

    • ’equiv’ means only byte-order changes are allowed.

    • ’safe’ means only casts which can preserve values are allowed.

    • ’same_kind’ means only safe casts or casts within a kind, like float64 to float32, are allowed.

    • ’unsafe’ (default) means any data conversions may be done.

  • order ({"C", "F"}, optional) – Order argument. See numpy.zeros().

  • parallel (bool, optional) – If True, use parallel numba numba.njit or numba.guvectorized code if possible. If None, use a heuristic to determine if should attempt to use parallel method.

  • axes_to_end (bool) – If True, place sampled dimension (if exists in output) and moment dimensions at end of output. Otherwise, place sampled dimension (if exists in output) at same position as input axis and moment dimensions at same position as input (if input does not contain moment dimensions, place them at end of array).

  • keep_attrs ({"drop", "identical", "no_conflicts", "drop_conflicts", "override"} or bool, optional) –

    • ‘drop’ or False: empty attrs on returned xarray object.

    • ’identical’: all attrs must be the same on every object.

    • ’no_conflicts’: attrs from all objects are combined, any that have the same name must also have the same value.

    • ’drop_conflicts’: attrs from all objects are combined, any that have the same name but different values are dropped.

    • ’override’ or True: skip comparing and copy attrs from the first object to the result.

  • apply_ufunc_kwargs (dict-like) – Extra parameters to xarray.apply_ufunc(). One useful option is on_missing_core_dim, which can take the value "copy" (the default), "raise", or "drop" and controls what to do with variables of a Dataset missing core dimensions. Other options are join, dataset_join, dataset_fill_value, and dask_gufunc_kwargs. Unlisted options are handled internally.

Returns:

out (ndarray or DataArray) – Central moments array of same type as x. out.shape = shape + (mom0, ...) where shape = np.broadcast_shapes(*(a.shape for a in (x_, *y_, weight_))) and x_, y_ and weight_ are the input arrays with axis moved to the last axis. That is, the last dimensions are the moving average axis axis and the moments dimensions.

See also

numpy.broadcast_shapes

cmomy.rolling.rolling_exp_data(data, alpha, *, axis=MISSING, dim=MISSING, mom_ndim=None, mom_axes=None, mom_dims=None, mom_params=None, min_periods=None, alpha_axis=MISSING, adjust=True, zero_missing_weights=True, out=None, dtype=None, casting='same_kind', order=None, parallel=None, axes_to_end=False, keep_attrs=None, apply_ufunc_kwargs=None)[source]#

Moving average of central moments array.

Parameters:

  • data (array-like)

  • alpha (array-like) – alpha values.

  • axis (int) – Axis to reduce/sample along.

  • dim (hashable) – Dimension to reduce/sample along.

  • mom_ndim ({1, 2}, optional) – Value indicates if moments (mom_ndim = 1) or comoments (mom_ndim=2). If not specified and data is an xarray object attempt to infer mom_ndim from mom_dims. Otherwise, default to mom_ndim = 1.

  • mom_axes (int or tuple of int, optional) – Location of the moment dimensions. Default to (-mom_ndim, -mom_ndim+1, ...). If specified and mom_ndim is None, set mom_ndim to len(mom_axes). Note that if mom_axes is specified, negative values are relative to the end of the array. This is also the case for axes if mom_axes is specified.

  • mom_dims (hashable or tuple of hashable) – Name of moment dimensions. If specified, infer mom_ndim from mom_dims. If also pass mom_ndim, check that mom_dims is consistent with mom_dims. If not specified, defaults to data.dims[-mom_ndim:]. This is primarily used if data is a Dataset, or if mom_dims are not the last dimensions.

  • mom_params (MomParams or MomParamsDict or dict, optional) – Moment parameters. You can set moment parameters axes and dims using this option. For example, passing mom_params={"dim": ("a", "b")} is equivalent to passing mom_dims=("a", "b"). You can also pass as a MomParams object with mom_params=cmomy.MomParams(dims=("a", "b")).

  • min_periods (int, optional) – Minimum number of observations in window required to have a value (otherwise result is NA). The default, None, is equivalent to setting min_periods equal to the size of the window.

  • alpha_axis (int) – Axis of alpha corresponding to axis for data.

  • adjust (bool, default True) – Same as adjust parameter of pandas.DataFrame.ewm()

  • zero_missing_weights (bool, default True) – If True, set missing weights (np.nan) to 0.

  • out (ndarray) – Optional output array. If specified, output will be a reference to this array. Note that if the output if method returns a Dataset, then this option is ignored.

  • dtype (dtype) – Optional dtype for output data.

  • casting ({'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional) –

    Controls what kind of data casting may occur.

    • ’no’ means the data types should not be cast at all.

    • ’equiv’ means only byte-order changes are allowed.

    • ’safe’ means only casts which can preserve values are allowed.

    • ’same_kind’ means only safe casts or casts within a kind, like float64 to float32, are allowed.

    • ’unsafe’ (default) means any data conversions may be done.

  • order ({"C", "F", "A", "K"}, optional) – Order argument. See numpy.asarray().

  • parallel (bool, optional) – If True, use parallel numba numba.njit or numba.guvectorized code if possible. If None, use a heuristic to determine if should attempt to use parallel method.

  • axes_to_end (bool) – If True, place sampled dimension (if exists in output) and moment dimensions at end of output. Otherwise, place sampled dimension (if exists in output) at same position as input axis and moment dimensions at same position as input (if input does not contain moment dimensions, place them at end of array).

  • keep_attrs ({"drop", "identical", "no_conflicts", "drop_conflicts", "override"} or bool, optional) –

    • ‘drop’ or False: empty attrs on returned xarray object.

    • ’identical’: all attrs must be the same on every object.

    • ’no_conflicts’: attrs from all objects are combined, any that have the same name must also have the same value.

    • ’drop_conflicts’: attrs from all objects are combined, any that have the same name but different values are dropped.

    • ’override’ or True: skip comparing and copy attrs from the first object to the result.

  • apply_ufunc_kwargs (dict-like) – Extra parameters to xarray.apply_ufunc(). One useful option is on_missing_core_dim, which can take the value "copy" (the default), "raise", or "drop" and controls what to do with variables of a Dataset missing core dimensions. Other options are join, dataset_join, dataset_fill_value, and dask_gufunc_kwargs. Unlisted options are handled internally.

Returns:

out (ndarray or DataArray) – Exponential moving average of same shape and type of data.

See also

xarray.DataArray.rolling_exp, pandas.DataFrame.ewm

cmomy.rolling.rolling_exp_vals(x, *y, alpha, mom, axis=MISSING, dim=MISSING, weight=None, mom_axes=None, mom_dims=None, mom_params=None, min_periods=None, adjust=True, zero_missing_weights=True, out=None, dtype=None, casting='same_kind', order=None, parallel=None, axes_to_end=False, keep_attrs=None, apply_ufunc_kwargs=None)[source]#

Moving average of central moments generated by values.

Parameters:

  • x (array-like or DataArray or Dataset) – Values to reduce.

  • *y (array-like or DataArray or Dataset) – Additional values (needed if len(mom)==2). y has same type restrictions and broadcasting rules as weight.

  • alpha (array-like) – alpha values.

  • mom (int or tuple of int) – Order or moments. If integer or length one tuple, then moments are for a single variable. If length 2 tuple, then comoments of two variables

  • axis (int) – Axis to reduce/sample along.

  • dim (hashable) – Dimension to reduce/sample along.

  • weight (array-like or DataArray or Dataset) –

    Optional weight. The type of weight must be “less than” the type of x.

    In the case that weight is array-like, it must broadcast to x using usual broadcasting rules (see numpy.broadcast_to()), with the following exceptions: If weight is a 1d array of length x.shape[axis]], it will be formatted to broadcast along the other dimensions of x. For example, if x has shape (10, 2, 3) and weight has shape (10,), then weight will be converted to the broadcastable shape (10, 1, 1). If weight is a scalar, it will be broadcast to x.shape.

  • mom_axes (int or tuple of int, optional) – Location of the moment dimensions. Default to (-mom_ndim, -mom_ndim+1, ...). If specified and mom_ndim is None, set mom_ndim to len(mom_axes). Note that if mom_axes is specified, negative values are relative to the end of the array. This is also the case for axes if mom_axes is specified.

  • mom_dims (hashable or tuple of hashable) – Name of moment dimensions. Defaults to ("mom_0",) for mom_ndim==1 and (mom_0, mom_1) for mom_ndim==2

  • mom_params (MomParams or MomParamsDict or dict, optional) – Moment parameters. You can set moment parameters axes and dims using this option. For example, passing mom_params={"dim": ("a", "b")} is equivalent to passing mom_dims=("a", "b"). You can also pass as a MomParams object with mom_params=cmomy.MomParams(dims=("a", "b")).

  • min_periods (int, optional) – Minimum number of observations in window required to have a value (otherwise result is NA). The default, None, is equivalent to setting min_periods equal to the size of the window.

  • adjust (bool, default True) – Same as adjust parameter of pandas.DataFrame.ewm()

  • zero_missing_weights (bool, default True) – If True, set missing weights (np.nan) to 0.

  • out (ndarray) – Optional output array. If specified, output will be a reference to this array. Note that if the output if method returns a Dataset, then this option is ignored.

  • dtype (dtype) – Optional dtype for output data.

  • casting ({'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional) –

    Controls what kind of data casting may occur.

    • ’no’ means the data types should not be cast at all.

    • ’equiv’ means only byte-order changes are allowed.

    • ’safe’ means only casts which can preserve values are allowed.

    • ’same_kind’ means only safe casts or casts within a kind, like float64 to float32, are allowed.

    • ’unsafe’ (default) means any data conversions may be done.

  • order ({"C", "F"}, optional) – Order argument. See numpy.zeros().

  • parallel (bool, optional) – If True, use parallel numba numba.njit or numba.guvectorized code if possible. If None, use a heuristic to determine if should attempt to use parallel method.

  • axes_to_end (bool) – If True, place sampled dimension (if exists in output) and moment dimensions at end of output. Otherwise, place sampled dimension (if exists in output) at same position as input axis and moment dimensions at same position as input (if input does not contain moment dimensions, place them at end of array).

  • keep_attrs ({"drop", "identical", "no_conflicts", "drop_conflicts", "override"} or bool, optional) –

    • ‘drop’ or False: empty attrs on returned xarray object.

    • ’identical’: all attrs must be the same on every object.

    • ’no_conflicts’: attrs from all objects are combined, any that have the same name must also have the same value.

    • ’drop_conflicts’: attrs from all objects are combined, any that have the same name but different values are dropped.

    • ’override’ or True: skip comparing and copy attrs from the first object to the result.

  • apply_ufunc_kwargs (dict-like) – Extra parameters to xarray.apply_ufunc(). One useful option is on_missing_core_dim, which can take the value "copy" (the default), "raise", or "drop" and controls what to do with variables of a Dataset missing core dimensions. Other options are join, dataset_join, dataset_fill_value, and dask_gufunc_kwargs. Unlisted options are handled internally.

Returns:

out (ndarray or DataArray) – Central moments array of same type as x. out.shape = shape + (mom0, ...) where shape = np.broadcast_shapes(*(a.shape for a in (x_, *y_, weight_))) and x_, y_ and weight_ are the input arrays with axis moved to the last axis. That is, the last dimensions are the moving average axis axis and the moments dimensions.

See also

numpy.broadcast_shapes

Contents