Functions

Documentation for all the functions in kramersmoyal.

Kramers—Moyal coefficients

kramersmoyal.kmc.km(timeseries: numpy.ndarray, bins: str = 'default', powers: int = 4, kernel: callable = <function epanechnikov>, bw: float = None, tol: float = 1e-10, conv_method: str = 'auto', center_edges: bool = True, full: bool = False) -> (<class 'numpy.ndarray'>, <class 'numpy.ndarray'>)

Estimates the Kramers─Moyal coefficients from a timeseries using a kernel estimator method. km can calculate the Kramers─Moyal coefficients for a timeseries of any dimension, up to any desired power.

Parameters:
  • timeseries (np.ndarray) – The D-dimensional timeseries (N, D). The timeseries of length N and dimensions D.
  • bins (int or list or np.ndarray or string (default default)) –

    The number of bins. This is the underlying space for the Kramers─Moyal coefficients to be estimated. If desired, bins along each dimension can be given as monotonically increasing bin edges (tuple or list), e.g.,

    • in 1-D, (np.linspace(lower, upper, length),);
    • in 2-D, `(np.linspace(lower_x, upper_x, length_x),
      np.linspace(lower_y, upper_y, length_y))`,

    with desired lower and upper ranges (in each dimension). If default, the bin numbers for different dimensions are:

    • 1-D, 5000;
    • 2-D, 100×100;
    • 3-D, 25×25×25.

    The bumber of bins along each dimension can be specified, e.g.,

    • 2-D, [125, 75],
    • 3-D, [100, 80, 120].

    If bins is int, or a list or np.array of dimension 1, and the timeseries dimension is D, then int(bins**(1/D)).

  • powers (int or list or tuple or np.ndarray (default 4)) –

    Powers for the operation of calculating the Kramers─Moyal coefficients. Default is the largest power used, e.g., if 4, then (0, 1, 2, 3, 4). They can be specified, matching the dimensions of the timeseries. E.g., in 1-dimension the first four Kramers─Moyal coefficients can be given as powers=(0, 1, 2, 3, 4), which is the same as powers=4. Setting powers=p for higher dimensions will results in all possible combinations up to the desired power ‘p’, e.g.

    • 2-D, powers=2 results in
      powers = np.array([[0, 0, 1, 1, 0, 1, 2, 2, 2],
      [0, 1, 0, 1, 2, 2, 0, 1, 2]]).T

    Set full=True to output powers. The order that they appear dictactes the order in the output kmc.

  • kernel (callable (default epanechnikov)) –

    Kernel used to convolute with the Kramers-Moyal coefficients. To select for example a Gaussian kernel use

    kernel = kernels.gaussian
  • bw (float (default None)) – Desired bandwidth of the kernel. A value of 1 occupies the full space of the bin space. Recommended are values 0.005 < bw < 0.5. Set full=True to output bw.
  • tol (float (default 1e-10)) – Round to zero absolute values smaller than tol, after the convolutions.
  • conv_method (str (default auto)) – A string indicating which method to use to calculate the convolution. https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.convolve.html
  • center_edges (bool (default True)) – Whether to return the bin centers or the bin edges (since for n bins there are n + 1 edges).
  • full (bool (default False)) – Outputs bandwidth bw and powers powers.
Returns:

  • kmc (np.ndarray) – The calculated Kramers─Moyal coefficients in accordance to the timeseries dimensions in (D, bins.shape) shape. To extract the selected orders of the kmc, use kmc[i,…], with i the order according to powers.
  • edges (np.ndarray) – The bin edges with shape (D, bins.shape) of the estimated Kramers─Moyal coefficients.
  • (…, bw, powers) (tuple) – This is only returned if full=True:
    • The bandwidth bw,
    • An array of the powers.

References

[Lamouroux2009]
  1. Lamouroux and K. Lehnertz, “Kernel-based regression of

drift and diffusion coefficients of stochastic processes.” Physics Letters A 373(39), 3507─3512, 2009.

Kernels

kramersmoyal.kernels.kernel(kernel_func)

Transforms a kernel function into a scaled kernel function (for a certain bandwidth bw)

Currently implemented kernels are:
Epanechnikov, Gaussian, Uniform, Triangular, Quartic

For a good overview of various kernels see https://en.wikipedia.org/wiki/Kernel_(statistics)

kramersmoyal.kernels.epanechnikov(x: numpy.ndarray, dims: int) → numpy.ndarray

The Epanechnikov kernel in dimensions dims.

kramersmoyal.kernels.gaussian(x: numpy.ndarray, dims: int) → numpy.ndarray

Gaussian kernel in dimensions dims.

kramersmoyal.kernels.uniform(x: numpy.ndarray, dims: int) → numpy.ndarray

Uniform, or rectangular kernel in dimensions dims.

kramersmoyal.kernels.triagular(x: numpy.ndarray, dims: int) → numpy.ndarray

Triagular kernel in dimensions dims.

kramersmoyal.kernels.quartic(x: numpy.ndarray, dims: int) → numpy.ndarray

Quartic, or biweight kernel in dimensions dims.

Helping functions

Binning function

The binning function has no documentation