Here is Temporal Mapper 2 developed by Mengsen Zhang. This version improves upon the original toolbox by adding a few new parameters to accommodate application across disciplines and data types. While the original Temporal Mapper was designed for fMRI data, it turns out to be also useful to understanding dynamics in other systems and modalities. Thus, Temporal Mapper is designed to be a more general-purpose tool for characterizing complex dynamics.

Technical details can be found in the paper. Briefly, Temporal Mapper is designed to capture attractor (stable state) and phase transitions in high-dimensional dynamical systems as an attractor transition network from only time series data. In the transition network, each node represent an attractor. The weight of the node indicates the local stability of the attractor. Each edge reflect an transition from one attractor to another. The computation takes two steps:

You will first need a distance matrix D which gives the pairwise distance between every two time points. k is the maximal number of spatial neighbors each time point will have. tidx is integer indices of each time point. By calling the function below, you will get a directed graph g, where each node is a time point. This is the spatiotemporal neighborhood graph.

g = tknndigraph (D,k,tidx);

If you just have the time series X (rows: time points, columns: state variables), you can get Euclidean distance matrix D as below.

D = pdist2(X,X);

In a second step, time points that are closely connected to each other (within a distance d) in the spatiotemporal neighborhood graph g get contracted to a single node.

[g_simp, members] = filtergraph(g,d);

You will get the simplied graph g_simp as the attractor transition networks. members tell you which time points is mapped to each node.

Once you have the graph, you can plot it with plottmgraph as below. To make it more interest, you want to have a coloring variable colorvar, which assigns each time point a scaler value (this could be simply one of the state variables.)

figure;
plottmgraph(g_simp,colorvar,members);

You will get some that look like this.

You can follow the full tutorial code to generate this picture yourself!

The code has been tested on MATLAB 2024a.

If you have used the code for your project, please cite:

Zhang, M., Chowdhury, S., & Saggar, M. (2023). Temporal Mapper: transition networks in simulated and real neural dynamics. Network Neuroscience, 7 (2): 431–460.

The original version of the Temporal Mapper can be found here.