How oxwearables/ssl-wearables works
Project type and purpose
• This is an open-source self-supervised learning toolkit for Human Activity Recognition (HAR) using wearable sensor data.
• It provides pipelines for pre-training (multi-task SSL), fine-tuning on downstream tasks, interpretability, and visualization.
File structure analysis
• Top-level scripts:
• mtl.py – orchestrates self-supervised (pre-)training using multi-task losses
• downstream_task_evaluation.py – runs fine-tuning and evaluation on standard HAR benchmarks
• train_ae.py, train_simclr.py – standalone pretext task trainers
• Configuration directory (conf/): hierarchical YAML configs for data sources, augmentation, tasks, models, evaluation, dataloader parameters
• Data parsing (data_parsing/): scripts to ingest raw datasets, preprocess and export standardized .npy files
• Core library (sslearning/):
• data/ – DataLoader implementations, transforms and utilities
• models/ – network definitions (ResNet, CNN-LSTM, VGG, flip-net, etc.), weight initialization
• pytorchtools.py – checkpointing, callbacks
• utils.py, scores.py – training helpers, metric calculations
• Interpretability (interpretability/): attribution, clustering analyses, XAI inference pipelines
• Checkpoints and pretrained models (model_check_point/)
• Visualization notebooks and plots (plots/)
a. Data ingestion & preprocessing
• Raw wearable data → data_parsing scripts → standardized NumPy datasets
b. Configuration management
• conf/*.yaml – directs data paths, augmentation strategies, SSL task choices, model architectures, hyperparameters
c. Data loader & augmentation
• sslearning/data/data_loader + data_transformation → batches of augmented windows
d. Feature extractor & pretext tasks (mtl.py)
• Shared backbone (ResNet/CNN-LSTM)
• Loss aggregation and optimizer
• Checkpointing via pytorchtools
e. Fine-tuning & downstream evaluation
• downstream_task_evaluation.py loads pretrained feature_extractor
• Attaches classifier head, runs supervised training on downstream HAR datasets
• Generates reports, saved models
f. Interpretability & visualization
• interpretability/*.py consumes trained models + data loader → attribution maps, clustering, UMAP plots
g. Torch Hub integration
• hubconf.py exposes harnet10/30/5 models for easy loading
Relationships and interactions
• Raw data → data_parsing → standardized data store
• conf files → control parameters for data loader, augmentation, model, tasks
• Data loader → feeds model training scripts
• mtl.py → model_check_point (pretrained weights)
• downstream_task_evaluation.py → uses pretrained weights + data → evaluation reports
• Interpretability scripts → consume checkpoints + data
• All components import from sslearning/ core library
Architectural patterns and design principles
• Modular pipeline: separation of data ingestion, configuration, model, training, evaluation, interpretability
• Configuration-driven via YAML, allows reproducibility and easy hyperparameter sweeps
• Reusable core library (sslearning/) for data and model utilities
• Notebook-driven visualization layer