Note
Go to the end to download the full example code.
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:
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:
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!")

Phase-space embedding reveals the underlying attractor structure!
Creating the PhaseSPDNet Model#
PhaseSPDNet architecture:
PhaseDelay: Applies time-delay embedding
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()

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:
Nonlinear dynamics: The underlying system has complex, nonlinear behavior (e.g., neural oscillations, chaos)
Limited channels: Embedding can extract more information from fewer channels
Temporal structure: Important features span across time (captured by delay coordinates)
Considerations:
Higher
orderincreases model capacity but also parameterslagshould be chosen based on the signal’s autocorrelationReduces effective time dimension:
T_new = T - (order-1) * lag
Summary#
In this tutorial, we demonstrated:
Phase-space embedding theory and visualization
Creating PhaseSPDNet with different embedding parameters
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)