This repository contains code to reproduce the results from the paper Fixation Sequences as Time Series: A Topological Approach to Dyslexia Detection. In that paper, fixation sequences are interpreted as time series, based on which a topological pipeline for dyslexia detection is introduced. The results that this repository creates are obtained by training and evaluating this pipeline on the corpus introduced by Hollenstein et al. and expanded by Reich et al..

---

Requirements

Python 3.11 or higher is required. Other dependencies are specified in pyproject.toml.

---

Data

The CopCo corpus can be downloaded via pymovements or from its OSF repository. For the scripts of this repository to run, the data must be placed in ./data_copco/ according to the following structure:

data_copco/
├── ExtractedFeatures/
│   └── P{subject_id}.csv
└── FixationReports/
    └── FIX_report_P{subject_id}.txt

---

Reproducing results

To reproduce all results from the paper, run python run_experiments.py. This will run all model configurations.

To run individual experiments, use python -m scripts.experiment with the following arguments:

Required arguments (all models):

• --model-name: one of
  • tsh, for "time series homology", the method introduced in the paper;
  • baseline_bjornsdottir for the baseline method introduced by Björnsdottir et al.;
  • baseline_raatikainen for the baseline method introduced by Raatikainen et al.;
  • baseline_bjornsdottir_with_tsh for the hybrid model combining the first baseline above with the features from time series homology; and
  • baseline_raatikainen_with_tsh for the hybrid model combining the second baseline above with the features from time series homology.
• --level: one of trial (for trial-level aggregation) and reader (for reader-level aggregation).
• --classifier: classifier to use (admissible values depend on the model; see below).

Model-specific arguments:

Model	Admissible classifiers	Requires --filtration-type	Supports --use-extended-persistence
tsh	svc	Yes	Yes
baseline_bjornsdottir	rf	No	No
baseline_raatikainen	svc, rf	No	No
baseline_bjornsdottir_with_tsh	rf	Yes	Yes
baseline_raatikainen_with_tsh	svc, rf	Yes	Yes

• --filtration-type: one of horizontal, sloped, sigmoid, arctan.
• --use-extended-persistence: flag to compute extended persistence instead of ordinary persistence (optional for models using TSH).

Optional arguments (all models):

• --exclude-l2: exclude CopCo-L2-readers from the dataset.
• --min-n-fixations: minimum number of fixations for a trial not to be discarded; only relevant for models using TSH (default: 5).
• --n-splits: number of splits for nested CV (default: 10 for trial-level, 5 for reader-level).
• --n-iter: number of iterations for randomized hyperparameter search (default: 200).
• --n-jobs: number of parallel jobs (default: 1).
• --outdir: output directory (default: outfiles).
• --verbose, -v: verbosity level (default: 0).
• --overwrite, -o: overwrite existing output files.
• --seed, -s: random seed (default: 42).

Example:

python -m scripts.experiment --model-name tsh --level trial --classifier svc --filtration-type sloped --n-jobs 8 --verbose 1

Executing the above will create a directory named outfiles that contains the CV results as a JSON file.

---

For users of uv

The environment specified in uv.lock can be recreated by running uv sync.

To reproduce all results from the paper, run uv run run_experiments.py. To run individual experiments, use uv run -m scripts.experiment with arguments as specified above.