# oxwearables/ssl-wearables architecture

> Architecture diagram of the GitHub repository oxwearables/ssl-wearables, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oxwearables/ssl-wearables
- Repository: https://github.com/oxwearables/ssl-wearables

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Components
    RawData[(Raw Wearable Data)]:::data
    DataParsing["Data Parsing Scripts"]:::data
    StandardizedData[(Standardized .npy Dataset)]:::data

    RawData -->|"raw files"| DataParsing
    DataParsing -->|"npy files"| StandardizedData

    %% Configuration
    Config[/conf/*.yaml/]:::config

    %% Core Library
    subgraph "Core Library (sslearning/)"
        DataLoader["data_loader.py"]:::core
        DataTransform["data_transformation.py"]:::core
        Models["sslearning/models/"]:::core
        PyTool["pytorchtools.py"]:::core
        Utils["utils & scores"]:::core
    end

    %% Data Loader & Augmentation
    StandardizedData -->|"loads npy"| DataLoader
    Config -->|"dataloader params\naugmentation"| DataLoader
    DataLoader -->|"augmented batch"| DataTransform
    DataTransform -->|"batch"| MTL
    DataTransform -->|"batch"| AETrainer
    DataTransform -->|"batch"| SimCLRTrainer

    %% Pre-training & SSL
    subgraph "SSL Pre-training"
        MTL["mtl.py"]:::model
        AETrainer["train_ae.py"]:::model
        SimCLRTrainer["train_simclr.py"]:::model
    end
    Config -->|"SSL task configs"| MTL
    Config -->|"AE configs"| AETrainer
    Config -->|"SimCLR configs"| SimCLRTrainer

    MTL -->|"pretrained weights"| CheckpointStore
    AETrainer -->|"ae weights"| CheckpointStore
    SimCLRTrainer -->|"simclr weights"| CheckpointStore
    MTL --> PyTool
    AETrainer --> PyTool
    SimCLRTrainer --> PyTool

    %% Checkpoint Store
    CheckpointStore[(model_check_point/)]:::data

    %% Downstream Fine-tuning
    Downstream["downstream_task_evaluation.py"]:::model
    Config -->|"downstream configs"| Downstream
    CheckpointStore -->|"pretrained weights"| Downstream
    StandardizedData -->|"npy data"| Downstream
    Downstream -->|"evaluation report\n& models"| CheckpointStore

    %% Interpretability & Visualization
    Interpret["interpretability/"]:::iv
    Plots["plots/"]:::iv
    CheckpointStore -->|"trained model"| Interpret
    StandardizedData -->|"data loader"| Interpret
    Interpret -->|"attribution maps\nclustering\nUMAP"| Plots

    %% Torch Hub Integration
    Hub["hubconf.py"]:::core
    Models --> Hub

    %% Click Events
    click DataParsing "https://github.com/oxwearables/ssl-wearables/tree/main/data_parsing/"
    click Config "https://github.com/oxwearables/ssl-wearables/tree/main/conf/"
    click DataLoader "https://github.com/oxwearables/ssl-wearables/blob/main/sslearning/data/data_loader.py"
    click DataTransform "https://github.com/oxwearables/ssl-wearables/blob/main/sslearning/data/data_transformation.py"
    click MTL "https://github.com/oxwearables/ssl-wearables/blob/main/mtl.py"
    click AETrainer "https://github.com/oxwearables/ssl-wearables/blob/main/train_ae.py"
    click SimCLRTrainer "https://github.com/oxwearables/ssl-wearables/blob/main/train_simclr.py"
    click Models "https://github.com/oxwearables/ssl-wearables/tree/main/sslearning/models/"
    click PyTool "https://github.com/oxwearables/ssl-wearables/blob/main/sslearning/pytorchtools.py"
    click Downstream "https://github.com/oxwearables/ssl-wearables/blob/main/downstream_task_evaluation.py"
    click Interpret "https://github.com/oxwearables/ssl-wearables/tree/main/interpretability/"
    click Plots "https://github.com/oxwearables/ssl-wearables/tree/main/plots/"
    click Hub "https://github.com/oxwearables/ssl-wearables/blob/main/hubconf.py"
    click CheckpointStore "https://github.com/oxwearables/ssl-wearables/tree/main/model_check_point/"

    %% Styling
    classDef data fill:#cce5ff,stroke:#004085
    classDef config fill:#d4edda,stroke:#155724
    classDef core fill:#ffe5b4,stroke:#996600
    classDef model fill:#f8d7da,stroke:#721c24
    classDef iv fill:#e2e3f3,stroke:#3a3a8c
```
