GitHub

ComplexityMeasures.jl

ComplexityMeasures — Module

ComplexityMeasures.jl

docsdev docsstable CI codecov Package Downloads Package Downloads DOI

A Julia package that provides:

  • A rigorous framework for extracting probabilities from data, based on the mathematical formulation of probability spaces.
  • Several (12+) outcome spaces, i.e., ways to discretize data into probabilities.
  • Several estimators for estimating probabilities given an outcome space, which correct theoretically known estimation biases.
  • Several definitions of information measures, such as various flavours of entropies (Shannon, Tsallis, Curado...), extropies, and probability-based complexity measures, that are used in the context of nonlinear dynamics, nonlinear timeseries analysis, and complex systems.
  • Several discrete and continuous (differential) estimators for entropies, which correct theoretically known estimation biases.
  • Estimators for other complexity measures that are not estimated based on probability functions.
  • An extendable interface and well thought out API accompanied by dedicated developer documentation pages. These makes it trivial to define new outcome spaces, or new estimators for probabilities, information measures, or complexity measures and integrate them with everything else in the software.

ComplexityMeasures.jl can be used as a standalone package, or as part of other projects in the JuliaDynamics organization, such as DynamicalSystems.jl or CausalityTools.jl.

To install it, run import Pkg; Pkg.add("ComplexityMeasures").

All further information is provided in the documentation, which you can either find online or build locally by running the docs/make.jl file.

Previously, this package was called Entropies.jl.

source

Latest news

ComplexityMeasures.jl has been updated to v3!

The software has been massively improved and its core principles were redesigned to be extendable, accessible, and more closely based on the rigorous mathematics of probabilities and entropies.

For more details of this new release, please see our announcement post on discourse or the central Tutorial of the v3 documentation.

In this v3 many concepts were renamed, but there is no formally breaking change. Everything that changed has been deprecated and is backwards compatible. You can see the CHANGELOG.md for more details!

Documentation contents

  • Before anything else, we recommend users to go through our overarching Tutorial, which teaches not only central API functions, but also terminology and crucial core concepts:
  • Probabilities lists all outcome spaces and probabilities estimators.
  • Information measures lists all implemented information measure definitions and estimators (both discrete and differential).
  • Complexity measures lists all implemented complexity measures that are not functionals of probabilities (unlike information measures).
  • The Examples page lists dozens of runnable example code snippets along with their outputs.

Input data for ComplexityMeasures.jl

The input data type typically depend on the outcome space chosen. In general though, the standard DynamicalSystems.jl approach is taken and as such we have three types of input data:

  • Timeseries, which are AbstractVector{<:Real}, used in e.g. with WaveletOverlap.
  • Multi-variate timeseries, or datasets, or state space sets, which are StateSpaceSets, used e.g. with NaiveKernel. The short syntax SSSet may be used instead of StateSpaceSet.
  • Spatial data, which are higher dimensional standard Arrays, used e.g. with SpatialOrdinalPatterns.
StateSpaceSets.StateSpaceSet — Type
StateSpaceSet{D, T} <: AbstractStateSpaceSet{D,T}

A dedicated interface for sets in a state space. It is an ordered container of equally-sized points of length D. Each point is represented by SVector{D, T}. The data are a standard Julia Vector{SVector}, and can be obtained with vec(ssset::StateSpaceSet). Typically the order of points in the set is the time direction, but it doesn't have to be.

When indexed with 1 index, StateSpaceSet is like a vector of points. When indexed with 2 indices it behaves like a matrix that has each of the columns be the timeseries of each of the variables. When iterated over, it iterates over its contained points. See description of indexing below for more.

StateSpaceSet also supports almost all sensible vector operations like append!, push!, hcat, eachrow, among others.

Description of indexing

In the following let i, j be integers, typeof(X) <: AbstractStateSpaceSet and v1, v2 be <: AbstractVector{Int} (v1, v2 could also be ranges, and for performance benefits make v2 an SVector{Int}).

  • X[i] == X[i, :] gives the ith point (returns an SVector)
  • X[v1] == X[v1, :], returns a StateSpaceSet with the points in those indices.
  • X[:, j] gives the jth variable timeseries (or collection), as Vector
  • X[v1, v2], X[:, v2] returns a StateSpaceSet with the appropriate entries (first indices being "time"/point index, while second being variables)
  • X[i, j] value of the jth variable, at the ith timepoint

Use Matrix(ssset) or StateSpaceSet(matrix) to convert. It is assumed that each column of the matrix is one variable. If you have various timeseries vectors x, y, z, ... pass them like StateSpaceSet(x, y, z, ...). You can use columns(dataset) to obtain the reverse, i.e. all columns of the dataset in a tuple.

source