Skip to content

Introduction and contents

Introduction

CausalityTools is a Julia package providing algorithms for detecting causal relations in complex systems based on time series data.

Getting started

Causality statistics and their different methods/estimators are described on method-specific pages. These can be accessed from the 'Package ecosystem' tab in the top menu.

For more flexibility, however, check out the causality interface, which provides a unified syntax for applying all the tests, even on uncertain data!

Contents

The CausalityTools module provides set of tools for time series causality testing. Much of the machinery required for these to work are organised in different packages/submodules. Simpler algorithms are implemented directly as submodules in CausalityTools. Relevant types and methods are all re-exported by CausalityTools. The functionality and purpose of these modules are summarised below.

CausalityTests

Provides parameter wrapper types for the different causality statistics. This gives unified syntax to evaluate different statistics on empirical scalar valued time series, uncertain time series and directly from dynamical systems through the causality method.

For time series, the syntax is causality(source, target, test::CausalityTest). Here, source and target are your time series (may also be uncertain data, see below) and test is an instance of any of the following causality test parameter types.

Transfer entropy tests

Predictive asymmetry tests

Distance based tests

For those interested, low-level methods are available individual method pages under Package ecosystem in the menu. These also provide a bit more information on each of the causality statistics.

CausalityToolsBase

Simplices

  • Computing exact intersections between n-dimensional simplices. Used internally in the transfer operators estimators.

PerronFrobenius

CrossMappings

  • Implementations of the (convergent) cross mapping routines from Sugihara et al. (2012).

Joint distance distribution

  • Implementation of the joint distance distribution algorithm for detecting directional causality.

SMeasure

  • Implementation of the S-measure algorithm for detecting directional causality.

TransferEntropy

TimeseriesSurrogates

TimeseriesSurrogates provides a set of methods to generate surrogate time series. It provides functionality useful outside causality testing, so is organised in an independent package which also maintains its own documentation.

Selected features:

  • Random surrogates
  • Fourier transform amplitude surrogates
  • Fourier transform phase surrogates
  • Amplitude-adjusted Fourier transform surrogates.
  • Visualisation tools making it easy to visualise surrogate data for your time series.

UncertainData

UncertainData is a package for generic uncertain data handling. It was originally developed for handling uncertainties in proxy data when doing causal analyses, but provides functionality useful elsewhere, so is kept in a separate package.

  • Defines AbstractUncertainValue and its concrete subtypes, which represent uncertainties of different types, such as theoretical distributions (e.g. normal distributions with mean and standard deviation), kernel density estimated distributions, fitted distributions, and weighted populations (population members may themself be uncertain values.
  • Provides the UncertainIndexValueDataset type which allows you to define time series whose data points may have uncertainties both in time indices and values. Different uncertainty types can be mixed seamlessly.
  • Has routines for resampling, binning and interpolating UncertainIndexValueDatasets.

CausalityTools is integrated with UncertainData (see below) in the following way:

  • Any combination of real-valued vectors, Vector{<:AbstractUncertainValue}, or AbstractUncertainValueDataset are accepted as inputs to causality, making uncertainty quantification on the causality statistics a breeze.
  • Causality test parameter types can be combined with resampling routines from UncertainData.jl to provide meta-tests which employs more advanced resampling schemes to compute the causality statistics from your time series.

Goals

Status

The package and documentation is under active development. Breaking changes may occur in CausalityTools and its dependencies until the 1.0 release.

It is almost certainly guaranteed that the high level causality methods and [CausalityTest] types will persist in their current form. Low-level methods might change slightly. Using the causality methods to compute various statistics for your time series is therefore more future-proof than directly applying the low-level methods.

Installation

CausalityTools is a registrered Julia package. You can install it by running the following in a Julia console.

using Pkg
Pkg.add("CausalityTools")

You can also enter package mode from the console by typing ], then add CausalityTools.

Main contributors

  • DynamicalSystems.jl provides a range of tools for exploring nonlinear dynamics and chaos, both for synthetic and observed systems. We provide seamless interaction with Dataset outputs from DynamicalSystems. Most of our example systems are also implemented as DiscreteDynamicalSystems or ContinuousDynamicalSystems from DynamicalSystems.