# samperochon/smartflat architecture

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

- Interactive diagram: https://gitdiagram.com/samperochon/smartflat
- Repository: https://github.com/samperochon/smartflat

## Overview

Smartflat is a research framework for multimodal healthcare video analysis. Its principal workflow turns recordings and annotations into extracted features, clusters and validates behavioral prototypes, segments time series, assembles symbolic sequences, and supports barycenter and clinical analyses. The graph also preserves the modality-specific extraction branches and annotation/configuration support. The README documents the overall notebook sequence; source excerpts are partial, so internal links not established by those sources are omitted.

Main entry points: [`smartflat/datasets/build.py`](https://github.com/samperochon/smartflat/blob/main/smartflat/datasets/build.py) (Dataset preparation), [`smartflat/features/symbolization/main.py`](https://github.com/samperochon/smartflat/blob/main/smartflat/features/symbolization/main.py) (Recursive prototyping), [`smartflat/engine/clustering.py`](https://github.com/samperochon/smartflat/blob/main/smartflat/engine/clustering.py) (Prototype clustering), [`smartflat/datasets/loader.py`](https://github.com/samperochon/smartflat/blob/main/smartflat/datasets/loader.py) (Dataset loading)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Data preparation"]
  node_dataset["Dataset preparation<br/>[build.py]"]
  node_annotations["Clinical annotations"]
  node_dataset_loader["Dataset loading<br/>[loader.py]"]
end

subgraph group_extract["Feature extraction"]
  node_video_features["Video features<br/>[main.py]"]
  node_audio_features["Speech features<br/>[main.py]"]
  node_gaze_features["Gaze features<br/>[main.py]"]
  node_hands_features["Hand features<br/>[main.py]"]
  node_skeleton_features["Pose features<br/>[main.py]"]
  node_hands_processing["Hand processing<br/>[main.py]"]
end

subgraph group_analysis["Behavioral analysis"]
  node_clustering["Prototype clustering<br/>[clustering.py]"]
  node_builders["Model builders<br/>[builders.py]"]
  node_segmentation["Change-point detection"]
end

subgraph group_symbolic["Symbolic analysis"]
  node_symbolization["Recursive prototyping<br/>[main.py]"]
  node_symbolic_inference["Symbolic inference<br/>[inference.py]"]
  node_distances["Temporal distances<br/>[_rtwe.py]"]
  node_barycenter["Barycenter averaging<br/>[main.py]"]
end

subgraph group_support["Study support"]
  node_metrics["Clinical metrics<br/>[metrics.py]"]
  node_configs["Analysis configuration<br/>[loader.py]"]
end

node_researcher(("Researcher"))
node_recordings["Study recordings"]
node_data_root["Study data files"]

node_researcher -->|"provides"| node_recordings
node_recordings -->|"preprocesses"| node_dataset
node_dataset -.->|"reads and writes"| node_data_root
node_annotations -.->|"supports"| node_dataset
node_recordings -->|"extracts representations"| node_video_features
node_recordings -->|"extracts speech"| node_audio_features
node_recordings -->|"extracts gaze"| node_gaze_features
node_recordings -->|"extracts landmarks"| node_hands_features
node_recordings -->|"extracts pose"| node_skeleton_features
node_hands_features -.->|"processes landmarks"| node_hands_processing
node_dataset -.->|"loads prepared data"| node_dataset_loader
node_dataset_loader -->|"supplies datasets"| node_clustering
node_configs -->|"configures"| node_clustering
node_builders -->|"builds components"| node_clustering
node_clustering -->|"prototypes feed"| node_symbolization
node_dataset -->|"provides feature sequences"| node_segmentation
node_segmentation -->|"segments feed"| node_symbolization
node_symbolization -->|"supports inference"| node_symbolic_inference
node_symbolic_inference -->|"sequences analyzed"| node_barycenter
node_distances -->|"computes temporal distance"| node_barycenter
node_symbolization -->|"supports group analysis"| node_metrics
node_researcher -->|"examines results"| node_metrics

click node_dataset "https://github.com/samperochon/smartflat/blob/main/smartflat/datasets/build.py"
click node_annotations "https://github.com/samperochon/smartflat/blob/main/smartflat/annotation_smartflat.py"
click node_dataset_loader "https://github.com/samperochon/smartflat/blob/main/smartflat/datasets/loader.py"
click node_video_features "https://github.com/samperochon/smartflat/blob/main/smartflat/features/video/main.py"
click node_audio_features "https://github.com/samperochon/smartflat/blob/main/smartflat/features/audio/main.py"
click node_gaze_features "https://github.com/samperochon/smartflat/blob/main/smartflat/features/gaze/main.py"
click node_hands_features "https://github.com/samperochon/smartflat/blob/main/smartflat/features/hands/main.py"
click node_skeleton_features "https://github.com/samperochon/smartflat/blob/main/smartflat/features/skeleton/main.py"
click node_hands_processing "https://github.com/samperochon/smartflat/blob/main/smartflat/features/hands_processing/main.py"
click node_clustering "https://github.com/samperochon/smartflat/blob/main/smartflat/engine/clustering.py"
click node_builders "https://github.com/samperochon/smartflat/blob/main/smartflat/engine/builders.py"
click node_segmentation "https://github.com/samperochon/smartflat/blob/main/smartflat/engine/change_point_detection.py"
click node_symbolization "https://github.com/samperochon/smartflat/blob/main/smartflat/features/symbolization/main.py"
click node_symbolic_inference "https://github.com/samperochon/smartflat/blob/main/smartflat/features/symbolization/inference.py"
click node_distances "https://github.com/samperochon/smartflat/blob/main/smartflat/engine/distances/_rtwe.py"
click node_barycenter "https://github.com/samperochon/smartflat/blob/main/smartflat/features/symbolic_barycenter/main.py"
click node_metrics "https://github.com/samperochon/smartflat/blob/main/smartflat/metrics.py"
click node_configs "https://github.com/samperochon/smartflat/blob/main/smartflat/configs/loader.py"

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_dataset,node_annotations,node_dataset_loader toneBlue
class node_video_features,node_audio_features,node_gaze_features,node_hands_features,node_skeleton_features,node_hands_processing toneAmber
class node_clustering,node_builders,node_segmentation toneMint
class node_symbolization,node_symbolic_inference,node_distances,node_barycenter toneRose
class node_metrics,node_configs,node_researcher,node_recordings,node_data_root toneIndigo
```

## Components

### Data preparation

- [Dataset preparation](https://github.com/samperochon/smartflat/blob/main/smartflat/datasets/build.py): `smartflat/datasets/build.py`
- [Clinical annotations](https://github.com/samperochon/smartflat/blob/main/smartflat/annotation_smartflat.py): `smartflat/annotation_smartflat.py`
- [Dataset loading](https://github.com/samperochon/smartflat/blob/main/smartflat/datasets/loader.py): `smartflat/datasets/loader.py`

### Feature extraction

- [Video features](https://github.com/samperochon/smartflat/blob/main/smartflat/features/video/main.py): `smartflat/features/video/main.py`
- [Speech features](https://github.com/samperochon/smartflat/blob/main/smartflat/features/audio/main.py): `smartflat/features/audio/main.py`
- [Gaze features](https://github.com/samperochon/smartflat/blob/main/smartflat/features/gaze/main.py): `smartflat/features/gaze/main.py`
- [Hand features](https://github.com/samperochon/smartflat/blob/main/smartflat/features/hands/main.py): `smartflat/features/hands/main.py`
- [Pose features](https://github.com/samperochon/smartflat/blob/main/smartflat/features/skeleton/main.py): `smartflat/features/skeleton/main.py`
- [Hand processing](https://github.com/samperochon/smartflat/blob/main/smartflat/features/hands_processing/main.py): `smartflat/features/hands_processing/main.py`

### Behavioral analysis

- [Prototype clustering](https://github.com/samperochon/smartflat/blob/main/smartflat/engine/clustering.py): `smartflat/engine/clustering.py`
- [Model builders](https://github.com/samperochon/smartflat/blob/main/smartflat/engine/builders.py): `smartflat/engine/builders.py`
- [Change-point detection](https://github.com/samperochon/smartflat/blob/main/smartflat/engine/change_point_detection.py): `smartflat/engine/change_point_detection.py`

### Symbolic analysis

- [Recursive prototyping](https://github.com/samperochon/smartflat/blob/main/smartflat/features/symbolization/main.py): `smartflat/features/symbolization/main.py`
- [Symbolic inference](https://github.com/samperochon/smartflat/blob/main/smartflat/features/symbolization/inference.py): `smartflat/features/symbolization/inference.py`
- [Temporal distances](https://github.com/samperochon/smartflat/blob/main/smartflat/engine/distances/_rtwe.py): `smartflat/engine/distances/_rtwe.py`
- [Barycenter averaging](https://github.com/samperochon/smartflat/blob/main/smartflat/features/symbolic_barycenter/main.py): `smartflat/features/symbolic_barycenter/main.py`

### Study support

- [Clinical metrics](https://github.com/samperochon/smartflat/blob/main/smartflat/metrics.py): `smartflat/metrics.py`
- [Analysis configuration](https://github.com/samperochon/smartflat/blob/main/smartflat/configs/loader.py): `smartflat/configs/loader.py`

### Other components

- **Researcher**
- **Study recordings**
- **Study data files**

## Connections

- Researcher → Study recordings: provides (evidence: `README.md`)
- Study recordings → Dataset preparation: preprocesses (evidence: `README.md`)
- Dataset preparation → Study data files: reads and writes
- Clinical annotations → Dataset preparation: supports (evidence: `smartflat/datasets/build.py`)
- Study recordings → Video features: extracts representations (evidence: `README.md`)
- Study recordings → Speech features: extracts speech (evidence: `README.md`)
- Study recordings → Gaze features: extracts gaze (evidence: `README.md`)
- Study recordings → Hand features: extracts landmarks (evidence: `README.md`)
- Study recordings → Pose features: extracts pose (evidence: `README.md`)
- Hand features → Hand processing: processes landmarks
- Dataset preparation → Dataset loading: loads prepared data
- Dataset loading → Prototype clustering: supplies datasets (evidence: `smartflat/engine/clustering.py`)
- Analysis configuration → Prototype clustering: configures (evidence: `smartflat/engine/clustering.py`)
- Model builders → Prototype clustering: builds components (evidence: `smartflat/engine/clustering.py`)
- Prototype clustering → Recursive prototyping: prototypes feed (evidence: `README.md`)
- Dataset preparation → Change-point detection: provides feature sequences (evidence: `README.md`)
- Change-point detection → Recursive prototyping: segments feed (evidence: `README.md`)
- Recursive prototyping → Symbolic inference: supports inference (evidence: `smartflat/features/symbolization/inference.py`)
- Symbolic inference → Barycenter averaging: sequences analyzed (evidence: `README.md`)
- Temporal distances → Barycenter averaging: computes temporal distance (evidence: `smartflat/features/symbolic_barycenter/main.py`)
- Recursive prototyping → Clinical metrics: supports group analysis (evidence: `README.md`)
- Researcher → Clinical metrics: examines results (evidence: `README.md`)
