# agriby-chaniago/temporal-attribution-audit architecture

> Architecture diagram of the GitHub repository agriby-chaniago/temporal-attribution-audit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agriby-chaniago/temporal-attribution-audit
- Repository: https://github.com/agriby-chaniago/temporal-attribution-audit

## Overview

This repository is a research pipeline auditing temporal attribution in Parkinsonian handwriting classifiers. Its central workflow loads UCI 395 or NewHandPD recordings, engineers model and held-out channels, trains interchangeable sequence encoders, and compares attention maps with WindowSHAP attributions and independent motor markers. Notebook-building scripts run scenario analyses and save results for visualization and later analysis. The README also documents architecture, cohort, seed, and patch-resolution perturbations. Connections involving unsampled analysis modules are included only where the README or SOURCE INDEX supports them; the index does not expose dynamic wiring.

Main entry points: [`src/preprocessing.py`](https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/src/preprocessing.py) (Signal preparation), [`scripts/build_nb_08.py`](https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/scripts/build_nb_08.py) (Attention fidelity), [`scripts/analisis_p4_geser_tugas.py`](https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/scripts/analisis_p4_geser_tugas.py) (Perturbation analysis), [`scripts/build_nb_04.py`](https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/scripts/build_nb_04.py) (Positive control)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Cohort preparation"]
  node_preprocessing["Signal preparation<br/>[preprocessing.py]"]
  node_newhandpd_loader["NewHandPD loader<br/>[newhandpd.py]"]
  node_normalization["Fold normalization<br/>[preprocessing.py]"]
end

subgraph group_modeling["Model pipeline"]
  node_model["Sequence encoders<br/>[model.py]"]
  node_training["Training and prediction<br/>[training.py]"]
end

subgraph group_evaluation["Attribution audit"]
  node_injection["Synthetic tremor control<br/>[injection.py]"]
  node_windowshap["WindowSHAP attribution<br/>[windowshap.py]"]
  node_marker["Motor markers<br/>[marker.py]"]
  node_metrics["Localization metrics<br/>[metrics.py]"]
end

subgraph group_experiments["Study scenarios"]
  node_s1_builder["Positive control<br/>[build_nb_04.py]"]
  node_s6_builder["Attention fidelity<br/>[build_nb_08.py]"]
  node_analysis_ensemble["Seed ensembles"]
  node_analysis_perturb["Perturbation analysis"]
end

subgraph group_results["Results and figures"]
  node_artifact_store["Result artifacts<br/>[artefak.py]"]
  node_visualization["Visualization<br/>[viz.py]"]
  node_paper_figures["Paper figures"]
end

node_uci[("UCI 395")]
node_newhandpd_data[("NewHandPD")]
node_researcher(("Researcher"))

node_uci -->|"loads signals"| node_preprocessing
node_newhandpd_data -->|"loads signals"| node_newhandpd_loader
node_newhandpd_loader -->|"creates recordings"| node_preprocessing
node_preprocessing -->|"provides recordings"| node_normalization
node_normalization -->|"normalizes batches"| node_training
node_model -.->|"trains and predicts"| node_training
node_researcher -->|"runs scenario"| node_s1_builder
node_s1_builder -->|"loads cohort"| node_preprocessing
node_s1_builder -->|"injects tremor"| node_injection
node_s1_builder -.->|"fits classifier"| node_training
node_s1_builder -.->|"evaluates localization"| node_metrics
node_researcher -->|"runs scenario"| node_s6_builder
node_s6_builder -->|"loads cohort"| node_preprocessing
node_s6_builder -->|"constructs encoder"| node_model
node_s6_builder -->|"trains and predicts"| node_training
node_s6_builder -->|"computes attribution"| node_windowshap
node_s6_builder -->|"compares markers"| node_marker
node_s6_builder -->|"saves results"| node_artifact_store
node_analysis_ensemble -->|"uses marker measures"| node_marker
node_analysis_ensemble -->|"uses cohort data"| node_preprocessing
node_analysis_perturb -->|"loads recordings"| node_preprocessing
node_analysis_perturb -->|"compares encoders"| node_model
node_analysis_perturb -->|"trains models"| node_training
node_analysis_perturb -->|"uses second cohort"| node_newhandpd_loader
node_analysis_perturb -->|"uses saved results"| node_artifact_store
node_artifact_store -.->|"supplies plots"| node_visualization
node_preprocessing -->|"supplies data"| node_paper_figures
node_visualization -->|"renders figures"| node_paper_figures

click node_preprocessing "https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/src/preprocessing.py"
click node_newhandpd_loader "https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/src/newhandpd.py"
click node_normalization "https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/src/preprocessing.py"
click node_model "https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/src/model.py"
click node_training "https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/src/training.py"
click node_injection "https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/src/injection.py"
click node_windowshap "https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/src/windowshap.py"
click node_marker "https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/src/marker.py"
click node_metrics "https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/src/metrics.py"
click node_s1_builder "https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/scripts/build_nb_04.py"
click node_s6_builder "https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/scripts/build_nb_08.py"
click node_analysis_ensemble "https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/scripts/analisis_p0_ensemble_peta.py"
click node_analysis_perturb "https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/scripts/analisis_p4_geser_tugas.py"
click node_artifact_store "https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/src/artefak.py"
click node_visualization "https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/src/viz.py"
click node_paper_figures "https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/scripts/build_figur_paper.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_preprocessing,node_newhandpd_loader,node_normalization toneBlue
class node_model,node_training,node_uci,node_newhandpd_data toneAmber
class node_injection,node_windowshap,node_marker,node_metrics toneMint
class node_s1_builder,node_s6_builder,node_analysis_ensemble,node_analysis_perturb toneRose
class node_artifact_store,node_visualization,node_paper_figures,node_researcher toneIndigo
```

## Components

### Cohort preparation

- [Signal preparation](https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/src/preprocessing.py): `src/preprocessing.py`
- [NewHandPD loader](https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/src/newhandpd.py): `src/newhandpd.py`
- [Fold normalization](https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/src/preprocessing.py): `src/preprocessing.py`

### Model pipeline

- [Sequence encoders](https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/src/model.py): `src/model.py`
- [Training and prediction](https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/src/training.py): `src/training.py`

### Attribution audit

- [Synthetic tremor control](https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/src/injection.py): `src/injection.py`
- [WindowSHAP attribution](https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/src/windowshap.py): `src/windowshap.py`
- [Motor markers](https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/src/marker.py): `src/marker.py`
- [Localization metrics](https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/src/metrics.py): `src/metrics.py`

### Study scenarios

- [Positive control](https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/scripts/build_nb_04.py): `scripts/build_nb_04.py`
- [Attention fidelity](https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/scripts/build_nb_08.py): `scripts/build_nb_08.py`
- [Seed ensembles](https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/scripts/analisis_p0_ensemble_peta.py): `scripts/analisis_p0_ensemble_peta.py`
- [Perturbation analysis](https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/scripts/analisis_p4_geser_tugas.py): `scripts/analisis_p4_geser_tugas.py`

### Results and figures

- [Result artifacts](https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/src/artefak.py): `src/artefak.py`
- [Visualization](https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/src/viz.py): `src/viz.py`
- [Paper figures](https://github.com/agriby-chaniago/temporal-attribution-audit/blob/main/scripts/build_figur_paper.py): `scripts/build_figur_paper.py`

### Other components

- **UCI 395**
- **NewHandPD**
- **Researcher**

## Connections

- UCI 395 → Signal preparation: loads signals (evidence: `README.md`)
- NewHandPD → NewHandPD loader: loads signals (evidence: `README.md`)
- NewHandPD loader → Signal preparation: creates recordings (evidence: `src/newhandpd.py`)
- Signal preparation → Fold normalization: provides recordings (evidence: `src/preprocessing.py`)
- Fold normalization → Training and prediction: normalizes batches (evidence: `src/training.py`)
- Sequence encoders → Training and prediction: trains and predicts
- Researcher → Positive control: runs scenario (evidence: `README.md`)
- Positive control → Signal preparation: loads cohort (evidence: `scripts/build_nb_04.py`)
- Positive control → Synthetic tremor control: injects tremor (evidence: `scripts/build_nb_04.py`)
- Positive control → Training and prediction: fits classifier (evidence: `scripts/build_nb_04.py`)
- Positive control → Localization metrics: evaluates localization
- Researcher → Attention fidelity: runs scenario (evidence: `README.md`)
- Attention fidelity → Signal preparation: loads cohort (evidence: `scripts/build_nb_08.py`)
- Attention fidelity → Sequence encoders: constructs encoder (evidence: `scripts/build_nb_08.py`)
- Attention fidelity → Training and prediction: trains and predicts (evidence: `scripts/build_nb_08.py`)
- Attention fidelity → WindowSHAP attribution: computes attribution (evidence: `scripts/build_nb_08.py`)
- Attention fidelity → Motor markers: compares markers
- Attention fidelity → Result artifacts: saves results (evidence: `scripts/build_nb_08.py`)
- Seed ensembles → Motor markers: uses marker measures (evidence: `scripts/analisis_p0_ensemble_peta.py`)
- Seed ensembles → Signal preparation: uses cohort data (evidence: `scripts/analisis_p0_ensemble_peta.py`)
- Perturbation analysis → Signal preparation: loads recordings (evidence: `scripts/analisis_p4_geser_tugas.py`)
- Perturbation analysis → Sequence encoders: compares encoders (evidence: `scripts/analisis_p4_geser_tugas.py`)
- Perturbation analysis → Training and prediction: trains models (evidence: `scripts/analisis_p4_geser_tugas.py`)
- Perturbation analysis → NewHandPD loader: uses second cohort (evidence: `scripts/analisis_p4_geser_tugas.py`)
- Perturbation analysis → Result artifacts: uses saved results (evidence: `scripts/analisis_p4_geser_tugas.py`)
- Result artifacts → Visualization: supplies plots
- Signal preparation → Paper figures: supplies data (evidence: `scripts/build_figur_paper.py`)
- Visualization → Paper figures: renders figures (evidence: `scripts/build_figur_paper.py`)