How ericktoque/bioclite-pucp works
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 Results · experiments Experiment runner · main.tex Paper project · features Features
Components 19
Data boundary
Raw smartwatch inputs and metadata used for model development and transfer evaluation.
Core pipeline
Reusable code for loading, features, models, experiments, evaluation, transfer, explainability, and publication.
- Loader · Reads and organizes raw participant recordings.
src/data/loader.py - Preprocessor · Cleans, segments, and standardizes sensor streams before modeling.
src/data/preprocessor.py - Features · Transforms preprocessed signals into model-ready representations.
src/features - Classical ML · Engineered-feature models and supervised training baseline centered on classical learning.
src/experiments/train_supervised.py - Deep learning · Neural models for time-series classification.
src/models/deep_learning.py - Transfer learning · Bridges clinical supervised training to home-context evaluation across exercises and settings.
src/experiments/transfer_learning.py - Experiment runner · Coordinates cross-validation, advanced models, ensemble voting, final training, and window optimization.
src/experiments - Evaluation · Computes model performance and supports stricter validation flows.
src/evaluation - Explainability · Produces feature-level importance and model explanations.
src/xai/shap_analysis.py - Figures export · 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 · Consumes experiment outputs to compare models, test significance, and summarize hyperparameters.
analysis/statistical - Clinical analysis · Clinical decision rules, nomogram work, and UPDRS inconsistency analysis.
analysis/clinical - Feature analysis · Feature selection, redundancy, and importance studies.
analysis/feature_selection - Validation analysis · Fixed and leave-one-subject-out validation diagnostics.
analysis/validation - Specialized studies · Biomechanical, symptom, patient, preprocessing, leakage, and window analyses.
analysis
Artifacts
Persisted metrics, tables, figures, and paper-ready outputs.
- Results · Central persistence layer for metrics, comparisons, and publication-ready tables.
results - Paper project · Manuscript assembly with tables and figures fed from analysis outputs.
BIOCLITE-PAPER-V2/main.tex
Connections 25
- 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.