From nonlinear data to research-ready insight.

Set up a reproducible environment

python -m pip install pygdis==1.0.0 numpy pandas matplotlib scikit-learn

Pin package versions in your experiment environment file and record the Python version.

Run the built-in Lorenz sweep

from gdis import GDIS
from gdis.benchmarks import LorenzSystem

system = LorenzSystem()
trajectories, parameters = system.generate_sweep()
result = GDIS().fit_transform(
    trajectories, parameters,
    jacobian_function=system.jacobian,
    critical_value=system.critical_value,
)
print(result.to_dataframe().head())
result.plot()

to_dataframe() returns a structured research table, while plot() provides the built-in visualization.

Conda environment

Download environment.yml

conda env create -f environment.yml
conda activate pygdis-tutorial
python -m pip check

Keep this environment separate from other projects such as CTCS.

pip with virtual environment

Download requirements.txt

python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python -m pip check

Required long-format CSV structure

Numbers are illustrative; parameter groups must contain many time steps in real experiments.

Compute from arrays or use the official CSV example

# Each trajectory is a 2D array: (time, observed_variables).
# The parameter values must correspond to the trajectory list.
from gdis import GDIS

result = GDIS().fit_transform(trajectories, parameters)
summary = result.to_dataframe()
summary.to_csv('gdis_results.csv', index=False)
print(summary.head())

Official complete CSV loader ↗

Logistic-map transition atlas

Generate a bifurcation diagram, time-series panels, GDIS and sustained-instability curves, plus a descriptor dashboard.

Download complete logistic-map script

Output: tutorial_output/

Dynamical features for classification

Construct independent synthetic sweep samples; compare a raw-data baseline with pyGDIS-only and combined logistic-regression models.

Download ML classification script

Output: ml_output/

Starter feature extraction

# One independent parameter sweep -> one machine-learning sample.
from gdis import GDIS
import numpy as np

def sweep_features(trajectories, parameters):
    r = GDIS().fit_transform(trajectories, parameters)
    scores = np.asarray(r.gdis, dtype=float)
    return {
        'gdis_mean': float(scores.mean()),
        'gdis_max': float(scores.max()),
        'gdis_std': float(scores.std()),
        'gdis_range': float(np.ptp(scores)),
    }

# Fit the classifier on multiple *independent* sweeps.
# Split by experiment/subject/system BEFORE model selection.

Recommended experimental design

1. Define labels and independent units before looking at results.
2. Divide experiments, subjects, devices, or systems into training and test partitions.
3. Compute features without learning from test labels or using test subjects for normalization.
4. Fit scaling and classifier hyperparameters using training data only.
5. Compare against time-domain, spectral, and established nonlinear-dynamics features.
6. Report balanced accuracy, ROC-AUC where appropriate, confidence intervals, and calibration if probabilities matter.
7. Repeat on a genuinely independent cohort or operating condition.

Experimental and statistical checklist

• Specify the scientific question and target endpoint.
• Predefine the independent evaluation unit and reference controls.
• Record software versions, data provenance, preprocessing and seed.
• Conduct sensitivity analysis for parameter-grid density and time-series length.
• Check noise robustness, missingness, and state-variable scaling.
• Compare against Lyapunov, entropy, spectral, and simple statistical benchmarks.
• Prespecify validation metrics and uncertainty estimation.
• Identify any data-driven transition localization explicitly.

What a study may claim

Supported by a single synthetic example: the pipeline can run and visualize a known dynamical scenario.

Needs controlled benchmark evaluation: sensitivity to particular classes of transitions or robustness across simulation settings.

Needs independent application data: performance in patient data, industrial failure forecasting, or a novel field.

Avoid: describing GDIS as a calibrated risk probability, a proof of chaos, or a clinical diagnostic without independent evidence.