# pratik-337/heart-pumping-efficiency-estimator architecture

> Architecture diagram of the GitHub repository pratik-337/heart-pumping-efficiency-estimator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pratik-337/heart-pumping-efficiency-estimator
- Repository: https://github.com/pratik-337/heart-pumping-efficiency-estimator

## Overview

EchoEF is a research prototype that estimates left-ventricular ejection fraction from echocardiogram videos and studies accuracy versus frame count, compute cost, and explanation quality. Its main workflow verifies and preprocesses EchoNet-Dynamic data, trains configured R(2+1)D-18 regressors, predicts on evaluation splits, and analyzes results; a local Gradio demo offers video inference. The README also documents cost/memory probes, XAI, and result reporting. Several links for unsampled CLI subsystems are documented rather than source-verified, so those edges cite the README.

Main entry points: [`src/echoef/data/dataset.py`](https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/data/dataset.py) (Clip dataset), [`src/echoef/xai/pipeline.py`](https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/xai/pipeline.py) (Explanation pipeline), [`src/echoef/train/trainer.py`](https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/train/trainer.py) (Run trainer), [`app/inference.py`](https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/app/inference.py) (Demo inference)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_processed[("Processed cache")]
  node_verify["Dataset verification<br/>[verify_dataset.py]"]
  node_preprocess["Video preprocessing<br/>[preprocess.py]"]
  node_tracings["Tracing data<br/>[tracings.py]"]
  node_dataset["Clip dataset<br/>[dataset.py]"]
  node_sampling["Clip sampling<br/>[sampling.py]"]
end

subgraph group_model["Training and inference"]
  node_config["Experiment configuration<br/>[config.py]"]
  node_model_factory["EF regressor<br/>[factory.py]"]
  node_steps["Training steps<br/>[steps.py]"]
  node_trainer["Run trainer<br/>[trainer.py]"]
  node_sweep["Training sweep<br/>[sweep.py]"]
end

subgraph group_analysis["Evaluation and reporting"]
  node_evaluation["Split evaluation<br/>[evaluation.py]"]
  node_prediction["Video predictions<br/>[predict.py]"]
  node_cost["Cost benchmark<br/>[cost.py]"]
  node_aggregate["Results aggregation<br/>[aggregate.py]"]
  node_figures["Figures and tables<br/>[figures.py]"]
end

subgraph group_xai["Explanations"]
  node_xai_pipeline["Explanation pipeline<br/>[pipeline.py]"]
  node_attribution["Attribution methods<br/>[attribution.py]"]
  node_xai_render["Explanation rendering<br/>[render.py]"]
end

subgraph group_demo["Interactive demo"]
  node_gradio["Local demo<br/>[app.py]"]
  node_app_inference["Demo inference<br/>[inference.py]"]
end

node_researcher(("Researcher"))
node_echonet[("EchoNet videos")]

node_researcher -->|"verifies data"| node_verify
node_echonet -->|"provides videos"| node_verify
node_verify -->|"then preprocesses"| node_preprocess
node_preprocess -->|"uses tracings"| node_tracings
node_preprocess -->|"writes cache"| node_processed
node_processed -->|"supplies frames"| node_dataset
node_dataset -->|"uses clip starts"| node_sampling
node_researcher -->|"starts training"| node_sweep
node_sweep -->|"runs configurations"| node_trainer
node_trainer -->|"loads batches"| node_dataset
node_trainer -->|"executes steps"| node_steps
node_trainer -->|"builds model"| node_model_factory
node_researcher -->|"requests evaluation"| node_evaluation
node_evaluation -->|"loads split"| node_dataset
node_evaluation -->|"generates predictions"| node_prediction
node_prediction -->|"selects clips"| node_sampling
node_prediction -->|"loads clips"| node_dataset
node_researcher -->|"probes cost"| node_cost
node_researcher -->|"aggregates runs"| node_aggregate
node_aggregate -.->|"feeds reports"| node_figures
node_researcher -->|"runs explanations"| node_xai_pipeline
node_xai_pipeline -->|"loads video data"| node_dataset
node_xai_pipeline -->|"selects clips"| node_sampling
node_xai_pipeline -->|"computes attributions"| node_attribution
node_xai_pipeline -.->|"renders explanations"| node_xai_render
node_researcher -->|"opens demo"| node_gradio
node_gradio -->|"requests inference"| node_app_inference
node_app_inference -->|"loads checkpoints"| node_model_factory
node_app_inference -->|"uses clip data"| node_dataset
node_app_inference -->|"explains prediction"| node_attribution
node_sweep -->|"loads configuration"| node_config

click node_verify "https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/scripts/verify_dataset.py"
click node_preprocess "https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/data/preprocess.py"
click node_tracings "https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/data/tracings.py"
click node_dataset "https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/data/dataset.py"
click node_sampling "https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/data/sampling.py"
click node_config "https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/config.py"
click node_model_factory "https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/models/factory.py"
click node_steps "https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/train/steps.py"
click node_trainer "https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/train/trainer.py"
click node_sweep "https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/train/sweep.py"
click node_evaluation "https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/eval/evaluation.py"
click node_prediction "https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/eval/predict.py"
click node_cost "https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/eval/cost.py"
click node_aggregate "https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/eval/aggregate.py"
click node_figures "https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/eval/figures.py"
click node_xai_pipeline "https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/xai/pipeline.py"
click node_attribution "https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/xai/attribution.py"
click node_xai_render "https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/xai/render.py"
click node_gradio "https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/app/app.py"
click node_app_inference "https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/app/inference.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_processed,node_verify,node_preprocess,node_tracings,node_dataset,node_sampling toneBlue
class node_config,node_model_factory,node_steps,node_trainer,node_sweep,node_echonet toneAmber
class node_evaluation,node_prediction,node_cost,node_aggregate,node_figures toneMint
class node_xai_pipeline,node_attribution,node_xai_render toneRose
class node_gradio,node_app_inference,node_researcher toneIndigo
```

## Components

### Data preparation

- **Processed cache**
- [Dataset verification](https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/scripts/verify_dataset.py): `scripts/verify_dataset.py`
- [Video preprocessing](https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/data/preprocess.py): `src/echoef/data/preprocess.py`
- [Tracing data](https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/data/tracings.py): `src/echoef/data/tracings.py`
- [Clip dataset](https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/data/dataset.py): `src/echoef/data/dataset.py`
- [Clip sampling](https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/data/sampling.py): `src/echoef/data/sampling.py`

### Training and inference

- [Experiment configuration](https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/config.py): `src/echoef/config.py`
- [EF regressor](https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/models/factory.py): `src/echoef/models/factory.py`
- [Training steps](https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/train/steps.py): `src/echoef/train/steps.py`
- [Run trainer](https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/train/trainer.py): `src/echoef/train/trainer.py`
- [Training sweep](https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/train/sweep.py): `src/echoef/train/sweep.py`

### Evaluation and reporting

- [Split evaluation](https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/eval/evaluation.py): `src/echoef/eval/evaluation.py`
- [Video predictions](https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/eval/predict.py): `src/echoef/eval/predict.py`
- [Cost benchmark](https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/eval/cost.py): `src/echoef/eval/cost.py`
- [Results aggregation](https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/eval/aggregate.py): `src/echoef/eval/aggregate.py`
- [Figures and tables](https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/eval/figures.py): `src/echoef/eval/figures.py`

### Explanations

- [Explanation pipeline](https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/xai/pipeline.py): `src/echoef/xai/pipeline.py`
- [Attribution methods](https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/xai/attribution.py): `src/echoef/xai/attribution.py`
- [Explanation rendering](https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/src/echoef/xai/render.py): `src/echoef/xai/render.py`

### Interactive demo

- [Local demo](https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/app/app.py): `app/app.py`
- [Demo inference](https://github.com/pratik-337/heart-pumping-efficiency-estimator/blob/main/app/inference.py): `app/inference.py`

### Other components

- **Researcher**
- **EchoNet videos**

## Connections

- Researcher → Dataset verification: verifies data (evidence: `README.md`)
- EchoNet videos → Dataset verification: provides videos (evidence: `README.md`)
- Dataset verification → Video preprocessing: then preprocesses (evidence: `README.md`)
- Video preprocessing → Tracing data: uses tracings (evidence: `src/echoef/data/preprocess.py`)
- Video preprocessing → Processed cache: writes cache (evidence: `README.md`)
- Processed cache → Clip dataset: supplies frames (evidence: `src/echoef/data/dataset.py`)
- Clip dataset → Clip sampling: uses clip starts (evidence: `src/echoef/data/dataset.py`)
- Researcher → Training sweep: starts training (evidence: `README.md`)
- Training sweep → Run trainer: runs configurations (evidence: `src/echoef/train/sweep.py`)
- Run trainer → Clip dataset: loads batches (evidence: `src/echoef/train/trainer.py`)
- Run trainer → Training steps: executes steps (evidence: `src/echoef/train/trainer.py`)
- Run trainer → EF regressor: builds model (evidence: `src/echoef/train/trainer.py`)
- Researcher → Split evaluation: requests evaluation (evidence: `README.md`)
- Split evaluation → Clip dataset: loads split (evidence: `src/echoef/eval/evaluation.py`)
- Split evaluation → Video predictions: generates predictions (evidence: `src/echoef/eval/evaluation.py`)
- Video predictions → Clip sampling: selects clips (evidence: `src/echoef/eval/predict.py`)
- Video predictions → Clip dataset: loads clips (evidence: `src/echoef/eval/predict.py`)
- Researcher → Cost benchmark: probes cost (evidence: `README.md`)
- Researcher → Results aggregation: aggregates runs (evidence: `README.md`)
- Results aggregation → Figures and tables: feeds reports
- Researcher → Explanation pipeline: runs explanations (evidence: `README.md`)
- Explanation pipeline → Clip dataset: loads video data (evidence: `src/echoef/xai/pipeline.py`)
- Explanation pipeline → Clip sampling: selects clips (evidence: `src/echoef/xai/pipeline.py`)
- Explanation pipeline → Attribution methods: computes attributions (evidence: `src/echoef/xai/pipeline.py`)
- Explanation pipeline → Explanation rendering: renders explanations
- Researcher → Local demo: opens demo (evidence: `README.md`)
- Local demo → Demo inference: requests inference (evidence: `app/app.py`)
- Demo inference → EF regressor: loads checkpoints (evidence: `app/inference.py`)
- Demo inference → Clip dataset: uses clip data (evidence: `app/inference.py`)
- Demo inference → Attribution methods: explains prediction (evidence: `app/inference.py`)
- Training sweep → Experiment configuration: loads configuration (evidence: `src/echoef/train/sweep.py`)
