# mcmc1906/penalty-biomechanics architecture

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

- Interactive diagram: https://gitdiagram.com/mcmc1906/penalty-biomechanics
- Repository: https://github.com/mcmc1906/penalty-biomechanics

## Overview

Penalty Biomechanics is a research workflow that turns penalty videos into clips and body-relative measurements, then tests whether those measurements explain kick behavior. The principal path runs from video extraction through pose and kinematics to statistical analysis and predictive models. The README also documents interpretation, practical/anticipation analyses, and deep-learning comparisons. Some links are based on README descriptions or import references rather than inspected call sites; those limits are reflected in the evidence.

Main entry points: [`data/sample/clips_master_sample.csv`](https://github.com/mcmc1906/penalty-biomechanics/blob/main/data/sample/clips_master_sample.csv) (Clip Metadata), [`02_biomechanics/run_biomechanics.py`](https://github.com/mcmc1906/penalty-biomechanics/blob/main/02_biomechanics/run_biomechanics.py) (Biomechanics Pipeline), [`04_models/reg_cross_analysis.py`](https://github.com/mcmc1906/penalty-biomechanics/blob/main/04_models/reg_cross_analysis.py) (Natural-Crossed Modeling), [`03_statistical_analysis/statistical_tests_fase1.py`](https://github.com/mcmc1906/penalty-biomechanics/blob/main/03_statistical_analysis/statistical_tests_fase1.py) (Feature Tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Video Capture"]
  node_clip_extraction["Clip Extraction<br/>[clips_creator.py]"]
  node_clip_master["Clip Master Builder"]
  node_clips_data["Clip Metadata"]
end

subgraph group_biomechanics["Biomechanics"]
  node_pose["Pose Estimation<br/>[pose_extractor.py]"]
  node_filter["Signal Filtering<br/>[signal_filter.py]"]
  node_kinematics["Kinematics<br/>[kinematics.py]"]
  node_biomech_runner["Biomechanics Pipeline"]
  node_frame_data["Frame Measurements<br/>[dataset_sample.csv]"]
end

subgraph group_statistics["Statistical Analysis"]
  node_stat_tests["Feature Tests"]
  node_phase2_tests["Phase Two Tests"]
  node_phase3_tests["Phase Three Tests"]
  node_natural_crossed_stats["Natural-Crossed Tests<br/>[reg_cros.py]"]
  node_bio_analysis["Biomechanics Analysis<br/>[bio_analysis.py]"]
  node_practical["Practical Insights"]
  node_stat_utils["Statistical Utilities<br/>[stats_utils.py]"]
end

subgraph group_models["Modeling and Interpretation"]
  node_tabular["Tabular Models<br/>[tabular_models.py]"]
  node_deep_learning["Deep Learning"]
  node_model_compare["Model Comparison"]
  node_evaluation["Evaluation Utilities<br/>[eval_utils.py]"]
  node_interpretable["Interpretable Models"]
  node_cross_analysis["Natural-Crossed Modeling"]
  node_model_stats["Model Statistics<br/>[stats_utils.py]"]
end

node_video_source(("Penalty Videos"))
node_analyst(("Researcher"))

node_video_source -->|"provides video"| node_clip_extraction
node_clip_extraction -.->|"feeds clips"| node_clip_master
node_clip_master -.->|"builds metadata"| node_clips_data
node_clips_data -->|"supplies clip metadata"| node_biomech_runner
node_biomech_runner -->|"extracts landmarks"| node_pose
node_biomech_runner -->|"filters landmarks"| node_filter
node_biomech_runner -->|"computes measures"| node_kinematics
node_kinematics -->|"uses keypoint map"| node_pose
node_biomech_runner -.->|"writes measurements"| node_frame_data
node_clips_data -->|"supplies analysis data"| node_stat_tests
node_clips_data -.->|"supplies analysis data"| node_phase2_tests
node_clips_data -->|"supplies analysis data"| node_phase3_tests
node_clips_data -->|"supplies analysis data"| node_natural_crossed_stats
node_clips_data -->|"supplies analysis data"| node_bio_analysis
node_clips_data -->|"supplies analysis data"| node_practical
node_stat_tests -->|"uses shared tests"| node_stat_utils
node_phase2_tests -->|"uses shared tests"| node_stat_utils
node_phase3_tests -->|"uses shared tests"| node_stat_utils
node_natural_crossed_stats -->|"uses shared definitions"| node_model_stats
node_practical -->|"uses shared definitions"| node_model_stats
node_clips_data -.->|"supplies model features"| node_tabular
node_clips_data -.->|"supplies model features"| node_deep_learning
node_clips_data -.->|"supplies model features"| node_model_compare
node_tabular -->|"uses evaluation"| node_evaluation
node_interpretable -->|"uses evaluation"| node_evaluation
node_cross_analysis -->|"uses evaluation"| node_evaluation
node_cross_analysis -->|"uses statistics"| node_model_stats
node_clips_data -->|"supplies model features"| node_interpretable
node_clips_data -->|"supplies analysis data"| node_cross_analysis
node_analyst -.->|"runs pipeline"| node_biomech_runner
node_analyst -.->|"runs analyses"| node_stat_tests
node_analyst -.->|"runs models"| node_tabular

click node_clip_extraction "https://github.com/mcmc1906/penalty-biomechanics/blob/main/01_extraction/clips_creator.py"
click node_clip_master "https://github.com/mcmc1906/penalty-biomechanics/blob/main/02_biomechanics/build_clips_master.py"
click node_clips_data "https://github.com/mcmc1906/penalty-biomechanics/blob/main/data/sample/clips_master_sample.csv"
click node_pose "https://github.com/mcmc1906/penalty-biomechanics/blob/main/02_biomechanics/pose_extractor.py"
click node_filter "https://github.com/mcmc1906/penalty-biomechanics/blob/main/02_biomechanics/signal_filter.py"
click node_kinematics "https://github.com/mcmc1906/penalty-biomechanics/blob/main/02_biomechanics/kinematics.py"
click node_biomech_runner "https://github.com/mcmc1906/penalty-biomechanics/blob/main/02_biomechanics/run_biomechanics.py"
click node_frame_data "https://github.com/mcmc1906/penalty-biomechanics/blob/main/data/sample/dataset_sample.csv"
click node_stat_tests "https://github.com/mcmc1906/penalty-biomechanics/blob/main/03_statistical_analysis/statistical_tests_fase1.py"
click node_phase2_tests "https://github.com/mcmc1906/penalty-biomechanics/blob/main/03_statistical_analysis/statistical_tests_fase2.py"
click node_phase3_tests "https://github.com/mcmc1906/penalty-biomechanics/blob/main/03_statistical_analysis/statistical_tests_fase3.py"
click node_natural_crossed_stats "https://github.com/mcmc1906/penalty-biomechanics/blob/main/03_statistical_analysis/reg_cros.py"
click node_bio_analysis "https://github.com/mcmc1906/penalty-biomechanics/blob/main/03_statistical_analysis/bio_analysis.py"
click node_practical "https://github.com/mcmc1906/penalty-biomechanics/blob/main/03_statistical_analysis/practical_insights.py"
click node_stat_utils "https://github.com/mcmc1906/penalty-biomechanics/blob/main/03_statistical_analysis/stats_utils.py"
click node_tabular "https://github.com/mcmc1906/penalty-biomechanics/blob/main/04_models/tabular_models.py"
click node_deep_learning "https://github.com/mcmc1906/penalty-biomechanics/blob/main/04_models/deep_learning_models.py"
click node_model_compare "https://github.com/mcmc1906/penalty-biomechanics/blob/main/04_models/model_comparison.py"
click node_evaluation "https://github.com/mcmc1906/penalty-biomechanics/blob/main/04_models/eval_utils.py"
click node_interpretable "https://github.com/mcmc1906/penalty-biomechanics/blob/main/04_models/interpretable_model.py"
click node_cross_analysis "https://github.com/mcmc1906/penalty-biomechanics/blob/main/04_models/reg_cross_analysis.py"
click node_model_stats "https://github.com/mcmc1906/penalty-biomechanics/blob/main/04_models/stats_utils.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_clip_extraction,node_clip_master,node_clips_data toneBlue
class node_pose,node_filter,node_kinematics,node_biomech_runner,node_frame_data toneAmber
class node_stat_tests,node_phase2_tests,node_phase3_tests,node_natural_crossed_stats,node_bio_analysis,node_practical,node_stat_utils toneMint
class node_tabular,node_deep_learning,node_model_compare,node_evaluation,node_interpretable,node_cross_analysis,node_model_stats toneRose
class node_video_source,node_analyst toneIndigo
```

## Components

### Video Capture

- [Clip Extraction](https://github.com/mcmc1906/penalty-biomechanics/blob/main/01_extraction/clips_creator.py): `01_extraction/clips_creator.py`
- [Clip Master Builder](https://github.com/mcmc1906/penalty-biomechanics/blob/main/02_biomechanics/build_clips_master.py): `02_biomechanics/build_clips_master.py`
- [Clip Metadata](https://github.com/mcmc1906/penalty-biomechanics/blob/main/data/sample/clips_master_sample.csv): `data/sample/clips_master_sample.csv`

### Biomechanics

- [Pose Estimation](https://github.com/mcmc1906/penalty-biomechanics/blob/main/02_biomechanics/pose_extractor.py): `02_biomechanics/pose_extractor.py`
- [Signal Filtering](https://github.com/mcmc1906/penalty-biomechanics/blob/main/02_biomechanics/signal_filter.py): `02_biomechanics/signal_filter.py`
- [Kinematics](https://github.com/mcmc1906/penalty-biomechanics/blob/main/02_biomechanics/kinematics.py): `02_biomechanics/kinematics.py`
- [Biomechanics Pipeline](https://github.com/mcmc1906/penalty-biomechanics/blob/main/02_biomechanics/run_biomechanics.py): `02_biomechanics/run_biomechanics.py`
- [Frame Measurements](https://github.com/mcmc1906/penalty-biomechanics/blob/main/data/sample/dataset_sample.csv): `data/sample/dataset_sample.csv`

### Statistical Analysis

- [Feature Tests](https://github.com/mcmc1906/penalty-biomechanics/blob/main/03_statistical_analysis/statistical_tests_fase1.py): `03_statistical_analysis/statistical_tests_fase1.py`
- [Phase Two Tests](https://github.com/mcmc1906/penalty-biomechanics/blob/main/03_statistical_analysis/statistical_tests_fase2.py): `03_statistical_analysis/statistical_tests_fase2.py`
- [Phase Three Tests](https://github.com/mcmc1906/penalty-biomechanics/blob/main/03_statistical_analysis/statistical_tests_fase3.py): `03_statistical_analysis/statistical_tests_fase3.py`
- [Natural-Crossed Tests](https://github.com/mcmc1906/penalty-biomechanics/blob/main/03_statistical_analysis/reg_cros.py): `03_statistical_analysis/reg_cros.py`
- [Biomechanics Analysis](https://github.com/mcmc1906/penalty-biomechanics/blob/main/03_statistical_analysis/bio_analysis.py): `03_statistical_analysis/bio_analysis.py`
- [Practical Insights](https://github.com/mcmc1906/penalty-biomechanics/blob/main/03_statistical_analysis/practical_insights.py): `03_statistical_analysis/practical_insights.py`
- [Statistical Utilities](https://github.com/mcmc1906/penalty-biomechanics/blob/main/03_statistical_analysis/stats_utils.py): `03_statistical_analysis/stats_utils.py`

### Modeling and Interpretation

- [Tabular Models](https://github.com/mcmc1906/penalty-biomechanics/blob/main/04_models/tabular_models.py): `04_models/tabular_models.py`
- [Deep Learning](https://github.com/mcmc1906/penalty-biomechanics/blob/main/04_models/deep_learning_models.py): `04_models/deep_learning_models.py`
- [Model Comparison](https://github.com/mcmc1906/penalty-biomechanics/blob/main/04_models/model_comparison.py): `04_models/model_comparison.py`
- [Evaluation Utilities](https://github.com/mcmc1906/penalty-biomechanics/blob/main/04_models/eval_utils.py): `04_models/eval_utils.py`
- [Interpretable Models](https://github.com/mcmc1906/penalty-biomechanics/blob/main/04_models/interpretable_model.py): `04_models/interpretable_model.py`
- [Natural-Crossed Modeling](https://github.com/mcmc1906/penalty-biomechanics/blob/main/04_models/reg_cross_analysis.py): `04_models/reg_cross_analysis.py`
- [Model Statistics](https://github.com/mcmc1906/penalty-biomechanics/blob/main/04_models/stats_utils.py): `04_models/stats_utils.py`

### Other components

- **Penalty Videos**
- **Researcher**

## Connections

- Penalty Videos → Clip Extraction: provides video (evidence: `README.md`)
- Clip Extraction → Clip Master Builder: feeds clips
- Clip Master Builder → Clip Metadata: builds metadata
- Clip Metadata → Biomechanics Pipeline: supplies clip metadata (evidence: `02_biomechanics/run_biomechanics.py`)
- Biomechanics Pipeline → Pose Estimation: extracts landmarks (evidence: `02_biomechanics/run_biomechanics.py`)
- Biomechanics Pipeline → Signal Filtering: filters landmarks (evidence: `02_biomechanics/run_biomechanics.py`)
- Biomechanics Pipeline → Kinematics: computes measures (evidence: `02_biomechanics/run_biomechanics.py`)
- Kinematics → Pose Estimation: uses keypoint map (evidence: `02_biomechanics/kinematics.py`)
- Biomechanics Pipeline → Frame Measurements: writes measurements
- Clip Metadata → Feature Tests: supplies analysis data (evidence: `03_statistical_analysis/statistical_tests_fase1.py`)
- Clip Metadata → Phase Two Tests: supplies analysis data
- Clip Metadata → Phase Three Tests: supplies analysis data (evidence: `03_statistical_analysis/statistical_tests_fase3.py`)
- Clip Metadata → Natural-Crossed Tests: supplies analysis data (evidence: `03_statistical_analysis/reg_cros.py`)
- Clip Metadata → Biomechanics Analysis: supplies analysis data (evidence: `03_statistical_analysis/bio_analysis.py`)
- Clip Metadata → Practical Insights: supplies analysis data (evidence: `03_statistical_analysis/practical_insights.py`)
- Feature Tests → Statistical Utilities: uses shared tests (evidence: `03_statistical_analysis/statistical_tests_fase1.py`)
- Phase Two Tests → Statistical Utilities: uses shared tests (evidence: `03_statistical_analysis/statistical_tests_fase2.py`)
- Phase Three Tests → Statistical Utilities: uses shared tests (evidence: `03_statistical_analysis/statistical_tests_fase3.py`)
- Natural-Crossed Tests → Model Statistics: uses shared definitions (evidence: `03_statistical_analysis/reg_cros.py`)
- Practical Insights → Model Statistics: uses shared definitions (evidence: `03_statistical_analysis/practical_insights.py`)
- Clip Metadata → Tabular Models: supplies model features
- Clip Metadata → Deep Learning: supplies model features
- Clip Metadata → Model Comparison: supplies model features
- Tabular Models → Evaluation Utilities: uses evaluation (evidence: `04_models/tabular_models.py`)
- Interpretable Models → Evaluation Utilities: uses evaluation (evidence: `04_models/interpretable_model.py`)
- Natural-Crossed Modeling → Evaluation Utilities: uses evaluation (evidence: `04_models/reg_cross_analysis.py`)
- Natural-Crossed Modeling → Model Statistics: uses statistics (evidence: `04_models/reg_cross_analysis.py`)
- Clip Metadata → Interpretable Models: supplies model features (evidence: `04_models/interpretable_model.py`)
- Clip Metadata → Natural-Crossed Modeling: supplies analysis data (evidence: `04_models/reg_cross_analysis.py`)
- Researcher → Biomechanics Pipeline: runs pipeline
- Researcher → Feature Tests: runs analyses
- Researcher → Tabular Models: runs models
