Source-linked AI summary
Deeptime: a Python library for machine learning dynamical models from time series data
Moritz Hoffmann, Martin Scherer, Tim Hempel, Andreas Mardt, Brian de Silva, Brooke E. Husic, Stefan Klus, Hao Wu, Nathan Kutz, Steven L. Brunton, Frank Noé
TL;DR
Time-series analysis needs tools for estimating dynamical structure and physically meaningful behavior across diverse quantitative fields. Deeptime addresses this need with a general-purpose Python library combining conventional, kernel, and deep-learning dynamical models with analysis methods and a maintainable, scikit-learn-compatible design. Its transfer-operator methods and examples support dimension reduction, coherent-set detection, kinetic analysis, and governing-dynamics discovery, while one benchmark reaches a VAMP score of 1.81 in the infinite-data, optimal-featurization limit.
Problem
Researchers need general tools to relate time-series observations to future states and characterize kinetic, thermodynamic, and mechanistic properties.
Method
Deeptime provides a Python library combining conventional dynamical models with kernel and deep-learning methods, transfer-operator analysis, and scikit-learn-inspired estimators and models.
Results
1.81 is the VAMP score approached in the infinite-data, optimal-featurization limit for the benchmark described.
Takeaways & Limitations
Deeptime supports dimension reduction, coherent-set detection, kinetic analysis, and governing-dynamics discovery through transfer-operator-based methods and demonstrated examples.
Takeaways & Limitations
Deeptime does not target domain-specific workflows or direct forecasting, clustering, regression, and annotation of dynamical data.
Abstract
from arXiv · showhide
Generation and analysis of time-series data is relevant to many quantitative fields ranging from economics to fluid mechanics. In the physical sciences, structures such as metastable and coherent sets, slow relaxation processes, collective variables dominant transition pathways or manifolds and channels of probability flow can be of great importance for understanding and characterizing the kinetic, thermodynamic and mechanistic properties of the system. Deeptime is a general purpose Python library offering various tools to estimate dynamical models based on time-series data including conventional linear learning methods, such as Markov state models (MSMs), Hidden Markov Models and Koopman models, as well as kernel and deep learning approaches such as VAMPnets and deep MSMs. The library is largely compatible with scikit-learn, having a range of Estimator classes for these different models, but in contrast to scikit-learn also provides deep Model classes, e.g. in the case of an MSM, which provide a multitude of analysis methods to compute interesting thermodynamic, kinetic and dynamical quantities, such as free energies, relaxation times and transition paths. The library is designed for ease of use but also easily maintainable and extensible code. In this paper we introduce the main features and structure of the deeptime software.
1 Introduction
Deeptime is a general-purpose, open-source Python library for estimating and analyzing dynamical models from time-series data. It brings methods from different communities together through a scikit-learn-like API while emphasizing modularity and extensibility.
- Purpose: Deeptime relates instantaneous observations x_t to future observations x_t+τ by estimating dynamical behavior across lag time τ.Most implemented methods predict future data from current data.
- Method groups: The library combines linear methods, nonlinear and kernel approaches, and deep learning techniques for dynamical data.Its methods include PCA-related decompositions, TICA, DMD, kernels, VAMPnets, deep MSMs, deep Koopman networks, and variational dynamical encoders.
- Method groups: Transfer-operator methods support dimension reduction, coherent-set detection, kinetic analysis, and discovery of governing dynamics.Their linearity enables approximations that identify slow processes and metastable or coherent sets.
- Model classes: MSMs describe temporal transitions whose events depend only on their predecessors, whereas HMMs use hidden Markov processes to generate observable outputs.HMMs are more expressive than MSMs but harder to estimate.
- Method groups: SINDy identifies sparse nonlinear governing equations from candidate terms and complements methods based on time-shifted data pairs.It predicts infinitesimal expected temporal changes rather than only lagged relationships.
- Scope: Deeptime targets domain-agnostic dynamical-model estimation rather than direct forecasting, clustering, regression, or annotation of dynamical data.It can be combined with domain-specific packages that load and featurize data.
2 Design and implementation
Deeptime separates estimators, fitted models, and transformations within a modular Python package structure. Its implementation prioritizes maintainability, lightweight dependencies, reusable components, documentation, and extensibility.
- API design: Deeptime follows a scikit-learn-inspired API with Estimator classes that create independent Model instances when fit is called.Models store estimation results, may transform data, and can be updated incrementally through partial_fit when supported.
- API design: The Estimator–Model separation keeps model methods and properties distinct from fitting objects, avoiding an overcrowded interface.Models are lightweight objects separated from the data used for training.
- Maintainability: The implementation minimizes dependencies: core functionality uses NumPy, SciPy, and scikit-learn, while plotting and deep-learning dependencies are optional.Some computationally expensive routines use C++ through pybind11 or use NumPy and SciPy where appropriate.
- Development: Documentation combines Jupyter notebooks with theoretical background and examples, generated API documentation, automated testing, and an LGPLv3 license.The project uses GitHub, Azure Pipelines, and pytest for development and testing.
- Package structure: The package organizes interfaces, basis functions, kernels, decompositions, Markov models, clustering, numerical utilities, example data, and data-processing tools into separate modules.The entire user interface is exposed at package level through this subpackage structure.
- Reuse and compatibility: Deeptime incorporates adapted components from PyEMMA, d3s, PySINDy, and DMD implementations while removing molecular-dynamics-specific dependencies where applicable.The PySINDy integration remains compatible with PySINDy.
3 Dimension reduction and decomposition methods
Deeptime uses transfer-operator methods to reduce dynamical data onto dominant processes, including slow, metastable, and coherent structures. Its methods span reversible and nonreversible settings, variational and regression-based approaches, nonlinear featurizations, and deep learning.
- Transfer-operator framework: Transfer operators provide a linear framework for approximating nonlinear dynamics and identifying slow processes, metastable sets, and coherent sets.Deeptime uses projections or finite-dimensional approximations of transfer operators to study these structures.
- Conventional methods: TICA targets dominant slow components for time-homogeneous reversible processes, with eigenvalues related to process relaxation timescales.The leading TICA components form a projection ordered by descending real eigenvalues.
- Variational methods: VAMP generalizes VAC to time-inhomogeneous and nonreversible dynamics, but its singular values generally lose the direct interpretation as relaxation timescales.The broader applicability comes with reduced interpretability for dynamical timescales.
- Deep and nonlinear methods: VAMPnets optimize differentiable VAMP scores through neural-network feature transformations, while KVAD optimizes a differentiable score for Perron–Frobenius-operator approximations.VAMPNets optimize neural-network lobes; KVADNets analogously optimize feature functions for KVAD.
- Dimension-reduction evaluation: In a hidden Markov model with nonlinearly separable emissions, tailored featurization achieved 100% state-separation accuracy, whereas other projections showed lower or improved separation depending on the transformation.The tailored transformation made the states linearly separable, while VAMPNets produced near-perfect separation without that stated ground-truth transformation.
- Coherent-set detection: For Bickley-jet coherent-set detection, all methods revealed the main vortex structure, while KVADNets produced sharp clustering and the best coherence-score subdivision.Most of the detected vortex interiors contained no leaked particles, indicating the coherence construction identified persistent regions.
4 Markov state models
Deeptime provides tools to estimate and analyze Markov state models from discrete-state time series, connecting MSMs to transfer-operator methods and related models. Its MSM workflow supports discretization, transition statistics, multiple estimators, Bayesian sampling, and dynamical analysis.
- MSM foundations: MSMs model temporal transitions between discrete states using the Markov property, with each transition depending only on the current state.The model represents conditional transition probabilities with a row-stochastic transition matrix.
- Discretization effects: Finer spatial discretization can improve transition-matrix resolution, but it also changes estimated eigenfunctions and stationary distributions.Comparing estimated and true eigenvalues provides a model-quality assessment in the four-well example.
- Relation to transfer operators: MSMs arise as indicator-function approximations within VAC or EDMD, while VAMP with indicator functions produces generalized MSMs for time-inhomogeneous dynamics.MSMs can also be converted into CovarianceKoopmanModels using transition matrices and stationary or empirical distributions.
- MSM analysis: MSM transition matrices support computation of mean first passage times, fluxes, implied timescales, and metastable state decompositions.These analyses use the estimated transition matrix and related model statistics.
- Estimation workflow: Deeptime supports MSM estimation from discrete-state trajectories and can discretize continuous-domain data before estimation.Clustering methods assign frames to discrete states, while TransitionCountModel collects transition statistics.
- Estimation workflow: Deeptime provides maximum-likelihood and Bayesian MSM estimation, yielding MarkovStateModel and BayesianPosterior model instances.Models may contain transition matrices and, when available, transition-count statistics.
- Estimation workflow: TransitionCountModel instances can restrict analysis to a state subset, including an ergodic subset or states with populated transitions.This restriction is performed before estimating the MSM.
5 Sparse identification of nonlinear dynamics
SINDy discovers nonlinear dynamical systems from measurement data by fitting sparse combinations of candidate functions. Deeptime provides estimation, modeling, simulation, scoring, and compatibility with related dynamical-system methods.
- Method: SINDy approximates nonlinear dynamical systems as sparse linear combinations of candidate library functions.The sparse coefficient matrix selects which library terms are active in the dynamics.
- Method: The method estimates sparse coefficients by solving a derivative-fitting optimization problem with a sparsity-promoting penalty.The objective balances model error against the number of nonzero coefficients.
- Extensions: SINDy also applies to discrete-time systems, where setting λ = 0 and using Θ(x) = x recovers the DMD approximation.In discrete time, derivatives need not be estimated.
- Implementation: Deeptime’s SINDy estimator uses sequentially thresholded least squares by default and estimates derivatives with first-order finite differences when needed.The estimator accepts the library, data, and optionally measured derivatives.
- Implementation: The resulting SINDyModel predicts derivatives, simulates trajectories from new initial conditions, and scores predictions against ground-truth data.The implementation is API-compatible with PySINDy and can use its broader optimizer range.
6 Datasets
Deeptime supplies configurable, non-domain-specific data generators, including stochastic differential-equation examples implemented with extensible C++ components. The dataset infrastructure supports performance comparisons between Python and compiled implementations.
- Dataset design: Deeptime’s datasets are non-domain-specific data generators whose parameters can vary, keeping the repository and package small.Performance-critical generation components are implemented in C++.
- SDE examples: The library implements example SDEs integrated with Euler–Maruyama and allows C++-inexperienced users to define their own systems.The SDE interface exposes F, the Wiener process, and the diffusion matrix σ.
- Double-well example: The two-dimensional double-well example uses σ = diag(0.7, 0.7) and provides trajectory and potential-landscape visualizations.The example is implemented through a struct defining the right-hand side.
- Performance: Roughly one order of magnitude in evaluation performance is gained at each step from native Python to mixed Python/C++ and from mixed implementation to native C++.The comparison includes native C++, mixed Python/C++, and native Python implementations.
- Trade-off: Mixed Python/C++ implementations require the state-space dimension to be predefined when generating Python bindings.This compile-time constraint improves performance but limits dimension flexibility.
7 Discussion and outlook
The discussion positions deeptime’s API and transfer-operator methods as a unified basis for several dynamical-data analyses. The outlook emphasizes extending methods, datasets, experimental-data support, and streaming capabilities.
- Discussion: Transfer-operator methods support dimension reduction, coherent-set detection, kinetic-quantity analysis, and discovery of governing dynamics.The paper demonstrates these application areas with respective examples.
- Future development: Planned extensions include experimental-data support for VAMPNets, neural-network-based SINDy dynamics estimation, richer HMM output models, and more example datasets.The authors describe these as future development directions for the library.
- Future development: The project also plans time-series-specific chunking and streaming so online-learning methods can work more easily with data streams.