Phase-Space Embedding with PhaseSPDNet#

This tutorial demonstrates how to use PhaseSPDNet for EEG classification. PhaseSPDNet applies phase-space embedding (time-delay coordinates) to capture nonlinear dynamical structure before SPDNet processing.

Introduction#

PhaseSPDNet [Carrara* et al., 2024] leverages phase-space embedding from dynamical systems theory. The key idea is that a single time series can be “unfolded” into a higher-dimensional space that reveals the underlying dynamics of the system.

Takens’ Embedding Theorem: For a dynamical system, a time-delayed embedding can reconstruct the topology of the original state space:

\[\mathbf{x}(t) \rightarrow [\mathbf{x}(t), \mathbf{x}(t-\tau), \mathbf{x}(t-2\tau), \ldots]\]

This is particularly useful for EEG, where signals reflect complex brain dynamics that may not be fully captured by linear methods.

Setup and Imports#

import warnings

import matplotlib.pyplot as plt
import numpy as np
import torch

from braindecode import EEGClassifier
from moabb.datasets import BNCI2014_001
from moabb.paradigms import MotorImagery
from sklearn.metrics import ConfusionMatrixDisplay, accuracy_score, confusion_matrix
from sklearn.preprocessing import LabelEncoder
from skorch.callbacks import EpochScoring, GradientNormClipping
from skorch.dataset import ValidSplit

from spd_learn.models import PhaseSPDNet


warnings.filterwarnings("ignore")

Loading the Dataset#

dataset = BNCI2014_001()
paradigm = MotorImagery(n_classes=4)

print(f"Dataset: {dataset.code}")
print("Sampling rate: 250 Hz")
Choosing from all possible events
Dataset: BNCI2014-001
Sampling rate: 250 Hz

Understanding Phase-Space Embedding#

For a signal with n_chans channels, phase-space embedding with order=m and lag=τ creates:

\[X_{embedded}(t) = [X(t), X(t-\tau), X(t-2\tau), \ldots, X(t-(m-1)\tau)]\]

This increases the channel dimension by a factor of m: n_chans → n_chans * order

Choosing parameters:

  • order: Embedding dimension (typically 2-5)

  • lag: Time delay in samples (often chosen via autocorrelation)

# Visualize embedding concept
fig, axes = plt.subplots(1, 2, figsize=(12, 4))

# Original 1D signal
t = np.linspace(0, 4 * np.pi, 200)
x = np.sin(t) + 0.5 * np.sin(2 * t)

ax1 = axes[0]
ax1.plot(t, x, "b-", linewidth=2)
ax1.set_xlabel("Time", fontsize=12)
ax1.set_ylabel("Amplitude", fontsize=12)
ax1.set_title("Original Signal", fontsize=14)
ax1.grid(True, alpha=0.3)

# Phase-space embedding (2D)
lag = 15  # samples
x_delayed = x[:-lag]
x_original = x[lag:]

ax2 = axes[1]
ax2.plot(x_original, x_delayed, "b-", linewidth=1, alpha=0.7)
ax2.scatter(x_original[::10], x_delayed[::10], c=t[lag::10], cmap="viridis", s=30)
ax2.set_xlabel("x(t)", fontsize=12)
ax2.set_ylabel("x(t - τ)", fontsize=12)
ax2.set_title("Phase-Space Embedding (2D)", fontsize=14)
ax2.grid(True, alpha=0.3)
ax2.set_aspect("equal")

plt.tight_layout()
plt.show()

print("Phase-space embedding reveals the underlying attractor structure!")
Original Signal, Phase-Space Embedding (2D)
Phase-space embedding reveals the underlying attractor structure!

Creating the PhaseSPDNet Model#

PhaseSPDNet architecture:

  1. PhaseDelay: Applies time-delay embedding

  2. SPDNet: Processes the embedded signals

The embedding expands channels: 22 channels x order 3 = 66 channels

n_chans = 22
n_outputs = 4

# Phase-space parameters
order = 2  # Embedding dimension (lower for stability)
lag = 10  # Time delay (~40ms at 250Hz)

model = PhaseSPDNet(
    n_chans=n_chans,
    n_outputs=n_outputs,
    order=order,
    lag=lag,
    subspacedim=22,  # BiMap output dimension (half of embedded channels)
    threshold=1e-4,
)

print("PhaseSPDNet Configuration:")
print(f"  Original channels: {n_chans}")
print(f"  Embedding order: {order}")
print(f"  Time lag: {lag} samples ({lag / 250 * 1000:.1f} ms)")
print(f"  Embedded channels: {n_chans * order}")
print("  Subspace dimension: 22")
print("\nModel Architecture:")
print(model)
PhaseSPDNet Configuration:
  Original channels: 22
  Embedding order: 2
  Time lag: 10 samples (40.0 ms)
  Embedded channels: 44
  Subspace dimension: 22

Model Architecture:
PhaseSPDNet(
  (phase): PhaseDelay()
  (spdnet): SPDNet(
    (cov): CovLayer()
    (bimap): ParametrizedBiMap(
      (parametrizations): ModuleDict(
        (weight): ParametrizationList(
          (0): _Orthogonal()
        )
      )
    )
    (reeig): ReEig()
    (logeig): LogEig()
    (classifier): Linear(in_features=253, out_features=4, bias=True)
  )
)

Training the Model#

subject_id = 1
batch_size = 32
max_epochs = 100
learning_rate = 1e-4  # Low learning rate for stable SPD learning

device = "cuda" if torch.cuda.is_available() else "cpu"
print(f"\nUsing device: {device}")

# Cache configuration
cache_config = dict(
    save_raw=True,
    save_epochs=True,
    save_array=True,
    use=True,
    overwrite_raw=False,
    overwrite_epochs=False,
    overwrite_array=False,
)

# Load data
X, labels, meta = paradigm.get_data(
    dataset=dataset, subjects=[subject_id], cache_config=cache_config
)

# Encode labels
le = LabelEncoder()
y = le.fit_transform(labels)

# Split by session
train_idx = meta.query("session == '0train'").index.to_numpy()
test_idx = meta.query("session == '1test'").index.to_numpy()

print(f"\nData shape: {X.shape}")
print(
    f"After embedding: ({X.shape[0]}, {n_chans * order}, {X.shape[2] - (order - 1) * lag})"
)
print(f"Training samples: {len(train_idx)}")
print(f"Test samples: {len(test_idx)}")

# Create classifier
# Note: SPD networks benefit from gradient clipping to prevent
# divergence during training on the Riemannian manifold.
clf = EEGClassifier(
    model,
    criterion=torch.nn.CrossEntropyLoss,
    optimizer=torch.optim.Adam,
    optimizer__lr=learning_rate,
    train_split=ValidSplit(0.1, stratified=True, random_state=42),
    batch_size=batch_size,
    max_epochs=max_epochs,
    callbacks=[
        (
            "train_acc",
            EpochScoring(
                "accuracy", lower_is_better=False, on_train=True, name="train_acc"
            ),
        ),
        ("gradient_clip", GradientNormClipping(gradient_clip_value=1.0)),
    ],
    device=device,
    verbose=1,
)

# Train
clf.fit(X[train_idx], y[train_idx])

# Evaluate
y_pred_train = clf.predict(X[train_idx])
y_pred_test = clf.predict(X[test_idx])

train_acc = accuracy_score(y[train_idx], y_pred_train)
test_acc = accuracy_score(y[test_idx], y_pred_test)

print(f"\n{'=' * 50}")
print(f"Results for Subject {subject_id}")
print(f"{'=' * 50}")
print(f"Train Accuracy: {train_acc * 100:.2f}%")
print(f"Test Accuracy:  {test_acc * 100:.2f}%")
Using device: cpu

Data shape: (528, 22, 1001)
After embedding: (528, 44, 991)
Training samples: 240
Test samples: 288
  epoch    train_acc    train_loss    valid_acc    valid_loss     dur
-------  -----------  ------------  -----------  ------------  ------
      1       0.2656        1.3937       0.2500        1.3875  0.1192
      2       0.2656        1.3791       0.2500        1.3768  0.1173
      3       0.2448        1.3810       0.2083        1.3677  0.1021
      4       0.2708        1.3717       0.2500        1.3616  0.0990
      5       0.3229        1.3629       0.3333        1.3563  0.1015
      6       0.3542        1.3589       0.3333        1.3524  0.1064
      7       0.4115        1.3542       0.3333        1.3489  0.1089
      8       0.3854        1.3507       0.3750        1.3455  0.1063
      9       0.3854        1.3497       0.3750        1.3425  0.1164
     10       0.3958        1.3441       0.3333        1.3398  0.1093
     11       0.4427        1.3390       0.4167        1.3368  0.1088
     12       0.4427        1.3340       0.4167        1.3333  0.1103
     13       0.4375        1.3316       0.4583        1.3302  0.1096
     14       0.4479        1.3312       0.4583        1.3272  0.1112
     15       0.5000        1.3264       0.4583        1.3242  0.1072
     16       0.5104        1.3199       0.5000        1.3216  0.1042
     17       0.4896        1.3199       0.4167        1.3186  0.1035
     18       0.5000        1.3154       0.4167        1.3155  0.1017
     19       0.5156        1.3110       0.4583        1.3122  0.1024
     20       0.5260        1.3070       0.4583        1.3090  0.1020
     21       0.5365        1.3047       0.4583        1.3053  0.1009
     22       0.5521        1.2982       0.4583        1.3018  0.1036
     23       0.5208        1.3022       0.4167        1.2989  0.1011
     24       0.5521        1.2944       0.5000        1.2959  0.1024
     25       0.5990        1.2924       0.5000        1.2932  0.1126
     26       0.6198        1.2832       0.4583        1.2906  0.1024
     27       0.5573        1.2839       0.5000        1.2883  0.1031
     28       0.5573        1.2812       0.4583        1.2857  0.1027
     29       0.5938        1.2749       0.4583        1.2830  0.0993
     30       0.6042        1.2743       0.5000        1.2805  0.1003
     31       0.6094        1.2716       0.5000        1.2780  0.1074
     32       0.6094        1.2692       0.5417        1.2757  0.1095
     33       0.6042        1.2661       0.5417        1.2731  0.1123
     34       0.5938        1.2617       0.5000        1.2706  0.1095
     35       0.6146        1.2543       0.5000        1.2683  0.1098
     36       0.6354        1.2556       0.5000        1.2658  0.1124
     37       0.6562        1.2460       0.5000        1.2632  0.1082
     38       0.6406        1.2512       0.5000        1.2606  0.1017
     39       0.6406        1.2463       0.5000        1.2580  0.0994
     40       0.6562        1.2462       0.5000        1.2553  0.1013
     41       0.6510        1.2418       0.5417        1.2525  0.1006
     42       0.6615        1.2364       0.5417        1.2498  0.0994
     43       0.6615        1.2306       0.5000        1.2471  0.0991
     44       0.6250        1.2315       0.5000        1.2446  0.0987
     45       0.6354        1.2314       0.5417        1.2419  0.0992
     46       0.6667        1.2221       0.5417        1.2395  0.0995
     47       0.6510        1.2258       0.5000        1.2370  0.1002
     48       0.6562        1.2187       0.5000        1.2348  0.0986
     49       0.6615        1.2162       0.4583        1.2328  0.1012
     50       0.6354        1.2166       0.4583        1.2307  0.1006
     51       0.6667        1.2080       0.4583        1.2286  0.0980
     52       0.6615        1.2073       0.4583        1.2263  0.1014
     53       0.6354        1.2013       0.4583        1.2240  0.1033
     54       0.6198        1.2027       0.4583        1.2213  0.1088
     55       0.6719        1.1984       0.5833        1.2186  0.1092
     56       0.6406        1.1985       0.5833        1.2162  0.1063
     57       0.6771        1.1930       0.5833        1.2139  0.1117
     58       0.6667        1.1925       0.4583        1.2118  0.1077
     59       0.7031        1.1861       0.4583        1.2096  0.1083
     60       0.6562        1.1910       0.5000        1.2075  0.1090
     61       0.6719        1.1856       0.5000        1.2053  0.1047
     62       0.6979        1.1745       0.5000        1.2031  0.1059
     63       0.6875        1.1768       0.5833        1.2008  0.1013
     64       0.7031        1.1737       0.5833        1.1984  0.1000
     65       0.6771        1.1741       0.5833        1.1960  0.1003
     66       0.7083        1.1707       0.5000        1.1938  0.1027
     67       0.6927        1.1690       0.5417        1.1919  0.1016
     68       0.6719        1.1639       0.5417        1.1901  0.1005
     69       0.6875        1.1632       0.5000        1.1877  0.1027
     70       0.7031        1.1634       0.5000        1.1857  0.1020
     71       0.7188        1.1560       0.5000        1.1838  0.1006
     72       0.7031        1.1548       0.5000        1.1818  0.1029
     73       0.7240        1.1576       0.5000        1.1794  0.1018
     74       0.7188        1.1460       0.5000        1.1772  0.1016
     75       0.7344        1.1458       0.5000        1.1749  0.0988
     76       0.6927        1.1430       0.5000        1.1732  0.1013
     77       0.6823        1.1472       0.5000        1.1716  0.1121
     78       0.6979        1.1395       0.5000        1.1694  0.1093
     79       0.7292        1.1366       0.5833        1.1675  0.1083
     80       0.7344        1.1323       0.5833        1.1652  0.1078
     81       0.7240        1.1345       0.5417        1.1631  0.1092
     82       0.7188        1.1168       0.5000        1.1607  0.1106
     83       0.7240        1.1273       0.5417        1.1587  0.1030
     84       0.7135        1.1245       0.5000        1.1566  0.0999
     85       0.6823        1.1205       0.5000        1.1544  0.1007
     86       0.6979        1.1145       0.5000        1.1524  0.0998
     87       0.7083        1.1211       0.5000        1.1505  0.0975
     88       0.7500        1.1123       0.5417        1.1490  0.0986
     89       0.7500        1.1148       0.5417        1.1475  0.0974
     90       0.7396        1.1139       0.5417        1.1458  0.1030
     91       0.7448        1.1047       0.5417        1.1436  0.0995
     92       0.7135        1.1119       0.5417        1.1415  0.1002
     93       0.7500        1.0995       0.5833        1.1395  0.1008
     94       0.7500        1.0977       0.5833        1.1375  0.1094
     95       0.7604        1.1002       0.5833        1.1355  0.0994
     96       0.7552        1.0931       0.5833        1.1335  0.0988
     97       0.7552        1.0898       0.5833        1.1317  0.1012
     98       0.7448        1.0877       0.5417        1.1297  0.0998
     99       0.7500        1.0892       0.5417        1.1277  0.1046
    100       0.7500        1.0817       0.5417        1.1259  0.1089

==================================================
Results for Subject 1
==================================================
Train Accuracy: 72.92%
Test Accuracy:  66.67%

Visualizing Results#

fig, axes = plt.subplots(1, 3, figsize=(15, 4))

# Training curves
history = clf.history
epochs = range(1, len(history) + 1)

ax1 = axes[0]
ax1.plot(epochs, history[:, "train_loss"], "b-", label="Train Loss", linewidth=2)
ax1.plot(epochs, history[:, "valid_loss"], "r--", label="Valid Loss", linewidth=2)
ax1.set_xlabel("Epoch", fontsize=12)
ax1.set_ylabel("Loss", fontsize=12)
ax1.set_title("Training and Validation Loss", fontsize=14)
ax1.legend(fontsize=10)
ax1.grid(True, alpha=0.3)

ax2 = axes[1]
ax2.plot(epochs, history[:, "train_acc"], "b-", label="Train Acc", linewidth=2)
ax2.plot(epochs, history[:, "valid_acc"], "r--", label="Valid Acc", linewidth=2)
ax2.set_xlabel("Epoch", fontsize=12)
ax2.set_ylabel("Accuracy", fontsize=12)
ax2.set_title("Training and Validation Accuracy", fontsize=14)
ax2.legend(fontsize=10)
ax2.grid(True, alpha=0.3)
ax2.set_ylim([0, 1])

# Confusion matrix
ax3 = axes[2]
cm = confusion_matrix(y[test_idx], y_pred_test)
disp = ConfusionMatrixDisplay(confusion_matrix=cm, display_labels=le.classes_)
disp.plot(ax=ax3, cmap="Blues", values_format="d")
ax3.set_title(f"Confusion Matrix\nAccuracy: {test_acc * 100:.1f}%", fontsize=14)

plt.tight_layout()
plt.show()
Training and Validation Loss, Training and Validation Accuracy, Confusion Matrix Accuracy: 66.7%

Comparing Different Embedding Parameters#

The choice of order and lag affects performance. Let’s compare different configurations.

print("\nComparing embedding parameters:")
print("-" * 50)

configs = [
    {"order": 2, "lag": 5, "name": "order=2, lag=5"},
    {"order": 2, "lag": 10, "name": "order=2, lag=10"},
    {"order": 3, "lag": 5, "name": "order=3, lag=5"},
    {"order": 3, "lag": 10, "name": "order=3, lag=10"},
]

for config in configs:
    embedded_chans = n_chans * config["order"]
    reduced_time = X.shape[2] - (config["order"] - 1) * config["lag"]
    cov_size = embedded_chans * (embedded_chans + 1) // 2
    print(
        f"{config['name']:20s}: {embedded_chans} channels, "
        f"{reduced_time} time points, {cov_size} features"
    )
Comparing embedding parameters:
--------------------------------------------------
order=2, lag=5      : 44 channels, 996 time points, 990 features
order=2, lag=10     : 44 channels, 991 time points, 990 features
order=3, lag=5      : 66 channels, 991 time points, 2211 features
order=3, lag=10     : 66 channels, 981 time points, 2211 features

When to Use Phase-Space Embedding#

PhaseSPDNet is particularly effective when:

  1. Nonlinear dynamics: The underlying system has complex, nonlinear behavior (e.g., neural oscillations, chaos)

  2. Limited channels: Embedding can extract more information from fewer channels

  3. Temporal structure: Important features span across time (captured by delay coordinates)

Considerations:

  • Higher order increases model capacity but also parameters

  • lag should be chosen based on the signal’s autocorrelation

  • Reduces effective time dimension: T_new = T - (order-1) * lag

Summary#

In this tutorial, we demonstrated:

  1. Phase-space embedding theory and visualization

  2. Creating PhaseSPDNet with different embedding parameters

  3. Training and evaluating on motor imagery data

PhaseSPDNet offers a principled way to incorporate dynamical systems perspectives into EEG classification, potentially capturing nonlinear brain dynamics that linear methods miss.

Total running time of the script: (0 minutes 12.050 seconds)