🧠 TMT Analysis

TMT Analysis is a complete pipeline for analyzing digital versions of the Trail Making Test (TMT) to identify fine-grained motor and cognitive markers of impairment.
It integrates data preprocessing, feature extraction, and machine learning analysis using the NeuroTask and Pyxations libraries.

---

🚀 Overview

This repository provides a reproducible workflow for digital neuropsychology research, including:

• ⌛ Data preprocessing and synchronization of Pyxations exports.
• 🖱️ Feature extraction from mouse trajectories using the NeuroTask library.
• 🧩 Machine learning models for classification (e.g., MCI vs. Control) and regression (e.g., predicting neuropsychological scores).
• 🔁 Nested cross-validation and permutation testing for robust performance estimation.
• 🧠 Explainable AI with SHAP-based feature importance analysis.

All scripts are modular and can be easily adapted to other computerized neuropsychological tests.

---

📦 Installation

Clone the repository and install dependencies:

git clone https://github.com/NeuroLIAA/tmt-analysis.git
cd tmt-analysis
pip install -r requirements.txt

Install the development versions of Pyxations and NeuroTask directly from GitHub to ensure compatibility:

pip install -e git+https://github.com/NeuroLIAA/pyxations.git#egg=pyxations
pip install -e git+https://github.com/NeuroLIAA/neurotask.git#egg=neurotask

---

⚙️ Configuration

All project paths and parameters are defined in config.py.
Before running the analysis, update the following variables:

RAW_DATA_DIR = "data/raw"
ANALYSIS_PATH = "data/results"
METADATA_CSV = os.path.join("data", "metadata", "metadata.csv")

---

📂 Project Structure

tmt-analysis/
│
├── src/
│   ├── data_processing/
│   │   ├── process.py
│   │   ├── preprocessing_utils.py
│   │   └── __init__.py
│   │
│   ├── hand_analysis/
│   │   ├── loader/
│   │   │   ├── analysis_loader.py
│   │   │   ├── data_loader.py
│   │   │   └── __init__.py
│   │   ├── metrics/
│   │   │   ├── trajectory_metrics.py
│   │   │   ├── temporal_metrics.py
│   │   │   ├── spatial_metrics.py
│   │   │   └── __init__.py
│   │   └── __init__.py
│   │
│   ├── model/
│   │   ├── run_models.py
│   │   ├── cross_validation.py
│   │   ├── permutation_tests.py
│   │   ├── shap/
│   │   │   ├── run_shap.py
│   │   │   ├── extract_explanations.py
│   │   │   ├── shap_utils.py
│   │   │   └── __init__.py
│   │   └── __init__.py
│   │
│   ├── utils/
│   │   ├── plotting.py
│   │   ├── io_utils.py
│   │   ├── stats_utils.py
│   │   ├── config_loader.py
│   │   └── __init__.py
│   │
│   └── __init__.py
│
├── data/
│   ├── raw/
│   ├── processed/
│   ├── features/
│   ├── results/
│   └── metadata/
│
├── notebooks/
│
├── config.py
├── requirements.txt
└── README.md

---

🧩 Usage

1. Add Pyxations Data

Place your Pyxations output files inside data/raw/.
Update the RAW_DATA_DIR variable in config.py to match your path.

2. Process the Data

Run the preprocessing pipeline to clean and prepare your dataset:

python -m src.data_processing.process

3. Run the Analysis

Execute the main analysis, including feature extraction and model training:

python -m src.hand_analysis.loader.analysis_loader

Results will be automatically saved to the directory defined by ANALYSIS_PATH in config.py.

---

📈 Outputs

After a full run, you’ll obtain:

• Processed data (data/processed/)
• Model evaluation results (data/results/)
• SHAP visualizations (data/figures)
• Logs and summaries for reproducibility

---

🧠 Citation

Submitted ...

📚 Related Repositories

• NeuroTask: feature extraction and digital test library.
• Pyxations: input event recording and synchronization framework.

---

🧑‍💻 Authors and Contact

Developed by Gianluca Capelo, Gustavo Juantorena and Juan Kamienkowski from the Laboratorio de Inteligencia Artificial Aplicada (University of Buenos Aires, Argentina)