# ericktoque/bioclite-pucp architecture

> Architecture diagram of the GitHub repository ericktoque/bioclite-pucp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ericktoque/bioclite-pucp
- Repository: https://github.com/ericktoque/bioclite-pucp

## Overview

1. **Project purpose and core boundary**
   - This repository is built around **transfer learning for bradykinesia detection** in Parkinson’s disease.
   - The key architectural boundary is between **labeled clinical data** used for model development and **home-context data** used for transfer/validation.
   - The system operates on smartwatch time-series from **40 participants**, **8 MDS-UPDRS exercises**, sampled at **50 Hz**.

2. **Data layer**
   - Raw inputs live under `data/raw/`, with metadata in `data/data_info.md`.
   - `src/data/loader.py` and `src/data/preprocessor.py` form the main ingestion/preprocessing boundary.
   - A notebook in `notebooks/01_EDA_y_Preprocesamiento.ipynb` suggests exploratory cleaning and preprocessing were initially validated interactively before being operationalized.

3. **Feature and model representation**
   - `src/features/` is the feature-engineering boundary, where raw sensor streams are likely turned into engineered inputs for classical ML.
   - `src/models/deep_learning.py` holds the deep learning side, while the README indicates a strong classical baseline centered on **Random Forest**.
   - This implies two model families: **engineered-feature classical models** and **sequence-based deep learning models**.

4. **Experiment orchestration**
   - `src/experiments/` is the main execution layer for model training and comparison.
   - It includes dedicated scripts for:
     - supervised training,
     - cross-validation,
     - advanced models,
     - ensemble voting,
     - rigorous/fixed validation,
     - transfer learning variants,
     - final training,
     - window optimization.
   - This directory is the primary “runner” layer that turns data/features into experiment outputs.

5. **Transfer-learning subsystem**
   - `src/transfer/` and the transfer-learning experiment scripts are the architectural center of the repo.
   - The project explicitly moves knowledge from **clinical supervised settings** to **home unsupervised settings**.
   - Transfer-learning variants include:
     - `transfer_learning.py`
     - `transfer_learning_complete.py`
     - `transfer_learning_all_8_exercises.py`
     - `transfer_learning_8_exercises.csv` / `transfer_learning_complete_results.csv` in `results/`
   - For a diagram, this is the main bridge between domain-specific training and deployment-style evaluation.

6. **Validation and evaluation layer**
   - `src/evaluation/` provides the evaluation boundary, while `src/experiments/rigorous_validation.py` and `src/experiments/fixed_validation.py` handle stricter validation flows.
   - The repository also includes `analysis/validation/diagnose_loso.py`, indicating leave-one-subject-out style validation is important.
   - Validation outputs are persisted in CSVs such as `results/rigorous_validation_results.csv` and `analysis/fixed_validation_results.csv`.

7. **Statistical and ablation analysis**
   - `analysis/statistical/` contains significance testing, ablation studies, model-comparison statistics, and hyperparameter summaries.
   - This layer is separate from training: it consumes experiment outputs and produces evidence for the paper.
   - Key outputs include `ablation_results.csv`, `model_comparison_stats.csv`, and `hyperparameter_results.csv`.

8. **Clinical interpretation and domain rules**
   - `analysis/clinical/` focuses on interpretability in the clinical domain.
   - It includes decision rules, nomogram analysis, UPDRS inconsistency analysis, and clinical classification outputs.
   - This is the main “clinical reasoning” layer, distinct from pure prediction, and likely feeds the paper’s explainable/clinical narrative.

9. **Explainability and feature importance**
   - `src/xai/shap_analysis.py` and `analysis/feature_selection/` provide model explainability and redundancy/importance analysis.
   - SHAP outputs are materialized into `results/tables/shap_feature_importance.csv`.
   - This is the architecture boundary where model predictions are translated into feature-level explanations.

10. **Specialized analytical subsystems**
   - Several analysis folders are domain-focused and should be treated as downstream consumers of experiment outputs:
     - `analysis/biomechanical/`
     - `analysis/symptoms/`
     - `analysis/patient_analysis/`
     - `analysis/preprocessing/`
     - `analysis/data_leakage/`
     - `analysis/window_optimization/`
   - These do not form the main training pipeline; they are evaluation/interpretation branches used to validate assumptions and produce paper-ready findings.

11. **Utilities and operational scripts**
   - `scripts/` contains support tools such as:
     - `pca_domain_shift.py` for domain-shift inspection,
     - `save_best_model.py` and `update_best_model.py` for model artifact management,
     - `window_level_performance.py` for post-hoc performance breakdowns.
   - These are operational helpers rather than core pipeline components.

12. **Artifacts and output boundaries**
   - `results/` is the main persistence layer for experiment outputs, metrics, tables, and figures.
   - It stores the numeric products used by downstream analysis and publication, including:
     - `results_supervised_models.csv`
     - `results_fixed.csv`
     - `home_predictions_final.csv`
     - `table1_demographics.csv`
     - `table2_performance.csv`
   - `results/tables/` and `results/figures/` are the curated publication-ready outputs.

13. **Publication pipeline**
   - `src/publication/generate_figures.py` and the `BIOCLITE-PAPER-V2/` LaTeX project form the publication layer.
   - The paper directory contains `main.tex` plus table inputs under `tables/`, meaning the repo is designed to feed manuscript generation directly from analysis outputs.
   - This is a distinct final boundary: experimental results become paper tables/figures.

14. **Overall architecture flow**
   - The repo’s end-to-end flow is:
     - raw smartwatch data → loading/preprocessing → feature extraction/model input → supervised and transfer-learning experiments → validation/statistics/XAI/clinical analyses → results artifacts → publication tables/figures.
   - The most important architectural split is between **training/evaluation code in `src/`** and **post-processing/interpretation in `analysis/` + `results/` + `BIOCLITE-PAPER-V2/`**.

Main entry points: [`results`](https://github.com/ericktoque/bioclite-pucp/tree/main/results) (Results), [`src/experiments`](https://github.com/ericktoque/bioclite-pucp/tree/main/src/experiments) (Experiment runner), [`BIOCLITE-PAPER-V2/main.tex`](https://github.com/ericktoque/bioclite-pucp/blob/main/BIOCLITE-PAPER-V2/main.tex) (Paper project), [`src/features`](https://github.com/ericktoque/bioclite-pucp/tree/main/src/features) (Features)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data boundary"]
  node_data_raw[("Raw data<br/>smartwatch time-series")]
  node_data_info["Data info<br/>dataset metadata<br/>[data_info.md]"]
end

subgraph group_src["Core pipeline"]
  node_loader["Loader<br/>ingestion<br/>[loader.py]"]
  node_preprocessor["Preprocessor<br/>cleaning pipeline<br/>[preprocessor.py]"]
  node_features["Features<br/>feature engineering"]
  node_supervised_models["Classical ML<br/>RF baseline"]
  node_deep_models["Deep learning<br/>sequence models<br/>[deep_learning.py]"]
  node_transfer_system["Transfer learning<br/>domain transfer"]
  node_experiment_runner["Experiment runner<br/>orchestration"]
  node_evaluation["Evaluation<br/>metrics and validation"]
  node_xai["Explainability<br/>SHAP analysis<br/>[shap_analysis.py]"]
  node_publication["Figures export<br/>publication prep"]
end

subgraph group_analysis["Analysis layer"]
  node_statistical_analysis["Statistical analysis<br/>ablation and significance"]
  node_clinical_analysis["Clinical analysis<br/>interpretation"]
  node_feature_analysis["Feature analysis<br/>importance and redundancy"]
  node_validation_analysis["Validation analysis<br/>LOSO checks"]
  node_specialized_analysis["Specialized studies<br/>domain analyses"]
end

subgraph group_artifacts["Artifacts"]
  node_results_store[("Results<br/>metrics tables")]
  node_paper["Paper project<br/>LaTeX manuscript<br/>[main.tex]"]
end

node_data_raw -->|"read"| node_loader
node_data_info -->|"schema"| node_loader
node_loader -->|"clean"| node_preprocessor
node_preprocessor -->|"derive"| node_features
node_features -->|"train"| node_supervised_models
node_features -->|"train"| node_deep_models
node_supervised_models -->|"run"| node_experiment_runner
node_deep_models -->|"run"| node_experiment_runner
node_experiment_runner -->|"branch"| node_transfer_system
node_experiment_runner -->|"score"| node_evaluation
node_transfer_system -->|"validate"| node_evaluation
node_evaluation -->|"persist"| node_results_store
node_experiment_runner -->|"persist"| node_results_store
node_results_store -->|"analyze"| node_statistical_analysis
node_results_store -->|"interpret"| node_clinical_analysis
node_results_store -->|"rank"| node_feature_analysis
node_results_store -->|"diagnose"| node_validation_analysis
node_results_store -->|"probe"| node_specialized_analysis
node_results_store -->|"explain"| node_xai
node_xai -->|"export"| node_results_store
node_statistical_analysis -->|"feed"| node_paper
node_clinical_analysis -->|"feed"| node_paper
node_xai -->|"feed"| node_paper
node_publication -->|"assemble"| node_paper
node_results_store -->|"render"| node_publication

click node_data_raw "https://github.com/ericktoque/bioclite-pucp/tree/main/data/raw"
click node_data_info "https://github.com/ericktoque/bioclite-pucp/blob/main/data/data_info.md"
click node_loader "https://github.com/ericktoque/bioclite-pucp/blob/main/src/data/loader.py"
click node_preprocessor "https://github.com/ericktoque/bioclite-pucp/blob/main/src/data/preprocessor.py"
click node_features "https://github.com/ericktoque/bioclite-pucp/tree/main/src/features"
click node_supervised_models "https://github.com/ericktoque/bioclite-pucp/blob/main/src/experiments/train_supervised.py"
click node_deep_models "https://github.com/ericktoque/bioclite-pucp/blob/main/src/models/deep_learning.py"
click node_transfer_system "https://github.com/ericktoque/bioclite-pucp/blob/main/src/experiments/transfer_learning.py"
click node_experiment_runner "https://github.com/ericktoque/bioclite-pucp/tree/main/src/experiments"
click node_evaluation "https://github.com/ericktoque/bioclite-pucp/tree/main/src/evaluation"
click node_xai "https://github.com/ericktoque/bioclite-pucp/blob/main/src/xai/shap_analysis.py"
click node_publication "https://github.com/ericktoque/bioclite-pucp/blob/main/src/publication/generate_figures.py"
click node_statistical_analysis "https://github.com/ericktoque/bioclite-pucp/tree/main/analysis/statistical"
click node_clinical_analysis "https://github.com/ericktoque/bioclite-pucp/tree/main/analysis/clinical"
click node_feature_analysis "https://github.com/ericktoque/bioclite-pucp/tree/main/analysis/feature_selection"
click node_validation_analysis "https://github.com/ericktoque/bioclite-pucp/tree/main/analysis/validation"
click node_specialized_analysis "https://github.com/ericktoque/bioclite-pucp/tree/main/analysis"
click node_results_store "https://github.com/ericktoque/bioclite-pucp/tree/main/results"
click node_paper "https://github.com/ericktoque/bioclite-pucp/blob/main/BIOCLITE-PAPER-V2/main.tex"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_data_raw,node_data_info toneBlue
class node_loader,node_preprocessor,node_features,node_supervised_models,node_deep_models,node_transfer_system,node_experiment_runner,node_evaluation,node_xai,node_publication toneAmber
class node_statistical_analysis,node_clinical_analysis,node_feature_analysis,node_validation_analysis,node_specialized_analysis toneMint
class node_results_store,node_paper toneRose
```

## Components

### Data boundary

Raw smartwatch inputs and metadata used for model development and transfer evaluation.

- [Raw data](https://github.com/ericktoque/bioclite-pucp/tree/main/data/raw): smartwatch time-series · Clinical and home-context recordings stored under the raw data boundary. · `data/raw`
- [Data info](https://github.com/ericktoque/bioclite-pucp/blob/main/data/data_info.md): dataset metadata · Dataset documentation and schema notes. · `data/data_info.md`

### Core pipeline

Reusable code for loading, features, models, experiments, evaluation, transfer, explainability, and publication.

- [Loader](https://github.com/ericktoque/bioclite-pucp/blob/main/src/data/loader.py): ingestion · Reads and organizes raw participant recordings. · `src/data/loader.py`
- [Preprocessor](https://github.com/ericktoque/bioclite-pucp/blob/main/src/data/preprocessor.py): cleaning pipeline · Cleans, segments, and standardizes sensor streams before modeling. · `src/data/preprocessor.py`
- [Features](https://github.com/ericktoque/bioclite-pucp/tree/main/src/features): feature engineering · Transforms preprocessed signals into model-ready representations. · `src/features`
- [Classical ML](https://github.com/ericktoque/bioclite-pucp/blob/main/src/experiments/train_supervised.py): RF baseline · Engineered-feature models and supervised training baseline centered on classical learning. · `src/experiments/train_supervised.py`
- [Deep learning](https://github.com/ericktoque/bioclite-pucp/blob/main/src/models/deep_learning.py): sequence models · Neural models for time-series classification. · `src/models/deep_learning.py`
- [Transfer learning](https://github.com/ericktoque/bioclite-pucp/blob/main/src/experiments/transfer_learning.py): domain transfer · Bridges clinical supervised training to home-context evaluation across exercises and settings. · `src/experiments/transfer_learning.py`
- [Experiment runner](https://github.com/ericktoque/bioclite-pucp/tree/main/src/experiments): orchestration · Coordinates cross-validation, advanced models, ensemble voting, final training, and window optimization. · `src/experiments`
- [Evaluation](https://github.com/ericktoque/bioclite-pucp/tree/main/src/evaluation): metrics and validation · Computes model performance and supports stricter validation flows. · `src/evaluation`
- [Explainability](https://github.com/ericktoque/bioclite-pucp/blob/main/src/xai/shap_analysis.py): SHAP analysis · Produces feature-level importance and model explanations. · `src/xai/shap_analysis.py`
- [Figures export](https://github.com/ericktoque/bioclite-pucp/blob/main/src/publication/generate_figures.py): publication prep · Generates figures and table inputs for the manuscript. · `src/publication/generate_figures.py`

### Analysis layer

Downstream statistical, clinical, and specialized analyses that consume experiment outputs.

- [Statistical analysis](https://github.com/ericktoque/bioclite-pucp/tree/main/analysis/statistical): ablation and significance · Consumes experiment outputs to compare models, test significance, and summarize hyperparameters. · `analysis/statistical`
- [Clinical analysis](https://github.com/ericktoque/bioclite-pucp/tree/main/analysis/clinical): interpretation · Clinical decision rules, nomogram work, and UPDRS inconsistency analysis. · `analysis/clinical`
- [Feature analysis](https://github.com/ericktoque/bioclite-pucp/tree/main/analysis/feature_selection): importance and redundancy · Feature selection, redundancy, and importance studies. · `analysis/feature_selection`
- [Validation analysis](https://github.com/ericktoque/bioclite-pucp/tree/main/analysis/validation): LOSO checks · Fixed and leave-one-subject-out validation diagnostics. · `analysis/validation`
- [Specialized studies](https://github.com/ericktoque/bioclite-pucp/tree/main/analysis): domain analyses · Biomechanical, symptom, patient, preprocessing, leakage, and window analyses. · `analysis`

### Artifacts

Persisted metrics, tables, figures, and paper-ready outputs.

- [Results](https://github.com/ericktoque/bioclite-pucp/tree/main/results): metrics tables · Central persistence layer for metrics, comparisons, and publication-ready tables. · `results`
- [Paper project](https://github.com/ericktoque/bioclite-pucp/blob/main/BIOCLITE-PAPER-V2/main.tex): LaTeX manuscript · Manuscript assembly with tables and figures fed from analysis outputs. · `BIOCLITE-PAPER-V2/main.tex`

## Connections

- Raw data → Loader: read · Raw smartwatch recordings are ingested.
- Data info → Loader: schema · Metadata guides loading and cohort structure.
- Loader → Preprocessor: clean · Loaded signals are normalized and prepared.
- Preprocessor → Features: derive · Prepared streams are converted into model inputs.
- Features → Classical ML: train · Engineered features feed classical classifiers.
- Features → Deep learning: train · Feature-rich or sequence representations feed neural models.
- Classical ML → Experiment runner: run · Supervised training is orchestrated through experiment scripts.
- Deep learning → Experiment runner: run · Deep learning experiments are orchestrated through the runner layer.
- Experiment runner → Transfer learning: branch · Transfer-learning variants are executed as core experiments.
- Experiment runner → Evaluation: score · Experiments are evaluated through validation and metric computation.
- Transfer learning → Evaluation: validate · Transfer-learning models are validated against home-context data.
- Evaluation → Results: persist · Validation metrics and comparisons are written to result tables.
- Experiment runner → Results: persist · Training and comparison outputs are stored for later analysis.
- Results → Statistical analysis: analyze · Stored results are consumed for significance and ablation studies.
- Results → Clinical analysis: interpret · Performance outputs are translated into clinical reasoning artifacts.
- Results → Feature analysis: rank · Feature and redundancy studies summarize model inputs.
- Results → Validation analysis: diagnose · Validation summaries support LOSO and fixed-validation checks.
- Results → Specialized studies: probe · Domain-specific studies inspect leakage, symptoms, patients, and windows.
- Results → Explainability: explain · Model outputs are converted into SHAP-style explanations.
- Explainability → Results: export · Explanation tables are persisted for reporting.
- Statistical analysis → Paper project: feed · Statistical summaries are packaged into manuscript tables.
- Clinical analysis → Paper project: feed · Clinical interpretation outputs feed the paper narrative.
- Explainability → Paper project: feed · Feature importance and explanation figures are prepared for publication.
- Figures export → Paper project: assemble · Generated figures are assembled into the manuscript project.
- Results → Figures export: render · Publication assets are generated from curated results.
