# aaronkhodami/etformat architecture

> Architecture diagram of the GitHub repository aaronkhodami/etformat, 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/aaronkhodami/etformat
- Repository: https://github.com/aaronkhodami/etformat

## Overview

etformat turns EyeLink EDF recordings into event and sample tables, then provides separate tools for cleaning, trial analysis, quality reporting, metadata and channel inspection, calibration review, and plotting. The main conversion path is documented and supported by source references; some downstream tools accept tables or CSVs independently, so the graph does not imply a shared pipeline among them. Several relationships for unsampled modules are documented in the README rather than verified from their implementations.

Main entry points: [`etformat/edffile.py`](https://github.com/aaronkhodami/etformat/blob/main/etformat/edffile.py) (EDFFile reader), [`etformat/export.py`](https://github.com/aaronkhodami/etformat/blob/main/etformat/export.py) (CSV export), [`etformat/edfdata_containers.py`](https://github.com/aaronkhodami/etformat/blob/main/etformat/edfdata_containers.py) (Table containers), [`etformat/edfinfo.py`](https://github.com/aaronkhodami/etformat/blob/main/etformat/edfinfo.py) (Recording metadata)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["EDF ingestion"]
  node_edf_file["EDFFile reader<br/>[edffile.py]"]
  node_edf_structures["EDF structures<br/>[edfdata.py]"]
  node_table_containers["Table containers"]
end

subgraph group_tables["Table export"]
  node_export["CSV export<br/>[export.py]"]
  node_csv_outputs["Events and samples CSV"]
  node_clean["Data cleaning<br/>[clean.py]"]
end

subgraph group_analysis["Analysis tools"]
  node_report["Trial QC report<br/>[report.py]"]
  node_describe["Trial summaries<br/>[describe.py]"]
  node_saccade_analysis["Saccade amplitudes"]
end

subgraph group_inspection["Inspection and plots"]
  node_metadata["Recording metadata<br/>[edfinfo.py]"]
  node_channels["Channel inspection<br/>[channels.py]"]
  node_calibration["Calibration review<br/>[calibration.py]"]
  node_plot_gaze["Gaze plotting<br/>[plot_gaze.py]"]
  node_plot_saccades["Saccade plotting<br/>[plot_saccades.py]"]
end

node_researcher(("Researcher"))
node_edf_input["EDF recording"]
node_edf_api["EyeLink edfapi"]

node_researcher -->|"requests conversion"| node_export
node_export -->|"loads recording"| node_edf_file
node_edf_input -->|"opens EDF"| node_edf_file
node_edf_file -->|"reads via"| node_edf_api
node_edf_file -->|"uses definitions"| node_edf_structures
node_edf_file -->|"builds tables with"| node_table_containers
node_table_containers -->|"uses definitions"| node_edf_structures
node_export -->|"writes CSVs"| node_csv_outputs
node_researcher -->|"requests cleaning"| node_clean
node_researcher -->|"requests QC"| node_report
node_csv_outputs -->|"reads events and samples"| node_report
node_researcher -->|"requests summaries"| node_describe
node_researcher -->|"requests amplitudes"| node_saccade_analysis
node_researcher -->|"requests metadata"| node_metadata
node_metadata -->|"loads recording"| node_edf_file
node_researcher -->|"requests channels"| node_channels
node_channels -->|"loads recording"| node_edf_file
node_researcher -->|"requests calibration"| node_calibration
node_calibration -->|"loads recording"| node_edf_file
node_researcher -->|"requests plot"| node_plot_gaze
node_researcher -->|"requests plot"| node_plot_saccades

click node_edf_file "https://github.com/aaronkhodami/etformat/blob/main/etformat/edffile.py"
click node_edf_structures "https://github.com/aaronkhodami/etformat/blob/main/etformat/edfdata.py"
click node_table_containers "https://github.com/aaronkhodami/etformat/blob/main/etformat/edfdata_containers.py"
click node_export "https://github.com/aaronkhodami/etformat/blob/main/etformat/export.py"
click node_clean "https://github.com/aaronkhodami/etformat/blob/main/etformat/clean.py"
click node_report "https://github.com/aaronkhodami/etformat/blob/main/etformat/report.py"
click node_describe "https://github.com/aaronkhodami/etformat/blob/main/etformat/describe.py"
click node_saccade_analysis "https://github.com/aaronkhodami/etformat/blob/main/etformat/saccade_analysis.py"
click node_metadata "https://github.com/aaronkhodami/etformat/blob/main/etformat/edfinfo.py"
click node_channels "https://github.com/aaronkhodami/etformat/blob/main/etformat/channels.py"
click node_calibration "https://github.com/aaronkhodami/etformat/blob/main/etformat/calibration.py"
click node_plot_gaze "https://github.com/aaronkhodami/etformat/blob/main/etformat/plot_gaze.py"
click node_plot_saccades "https://github.com/aaronkhodami/etformat/blob/main/etformat/plot_saccades.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_edf_file,node_edf_structures,node_table_containers toneBlue
class node_export,node_csv_outputs,node_clean toneAmber
class node_report,node_describe,node_saccade_analysis,node_edf_api toneMint
class node_metadata,node_channels,node_calibration,node_plot_gaze,node_plot_saccades toneRose
class node_researcher,node_edf_input toneIndigo
```

## Components

### EDF ingestion

- [EDFFile reader](https://github.com/aaronkhodami/etformat/blob/main/etformat/edffile.py): `etformat/edffile.py`
- [EDF structures](https://github.com/aaronkhodami/etformat/blob/main/etformat/edfdata.py): `etformat/edfdata.py`
- [Table containers](https://github.com/aaronkhodami/etformat/blob/main/etformat/edfdata_containers.py): `etformat/edfdata_containers.py`

### Table export

- [CSV export](https://github.com/aaronkhodami/etformat/blob/main/etformat/export.py): `etformat/export.py`
- **Events and samples CSV**
- [Data cleaning](https://github.com/aaronkhodami/etformat/blob/main/etformat/clean.py): `etformat/clean.py`

### Analysis tools

- [Trial QC report](https://github.com/aaronkhodami/etformat/blob/main/etformat/report.py): `etformat/report.py`
- [Trial summaries](https://github.com/aaronkhodami/etformat/blob/main/etformat/describe.py): `etformat/describe.py`
- [Saccade amplitudes](https://github.com/aaronkhodami/etformat/blob/main/etformat/saccade_analysis.py): `etformat/saccade_analysis.py`

### Inspection and plots

- [Recording metadata](https://github.com/aaronkhodami/etformat/blob/main/etformat/edfinfo.py): `etformat/edfinfo.py`
- [Channel inspection](https://github.com/aaronkhodami/etformat/blob/main/etformat/channels.py): `etformat/channels.py`
- [Calibration review](https://github.com/aaronkhodami/etformat/blob/main/etformat/calibration.py): `etformat/calibration.py`
- [Gaze plotting](https://github.com/aaronkhodami/etformat/blob/main/etformat/plot_gaze.py): `etformat/plot_gaze.py`
- [Saccade plotting](https://github.com/aaronkhodami/etformat/blob/main/etformat/plot_saccades.py): `etformat/plot_saccades.py`

### Other components

- **Researcher**
- **EDF recording**
- **EyeLink edfapi**

## Connections

- Researcher → CSV export: requests conversion (evidence: `README.md`)
- CSV export → EDFFile reader: loads recording (evidence: `etformat/export.py`)
- EDF recording → EDFFile reader: opens EDF (evidence: `README.md`)
- EDFFile reader → EyeLink edfapi: reads via (evidence: `README.md`)
- EDFFile reader → EDF structures: uses definitions (evidence: `etformat/edffile.py`)
- EDFFile reader → Table containers: builds tables with (evidence: `etformat/edffile.py`)
- Table containers → EDF structures: uses definitions (evidence: `etformat/edfdata_containers.py`)
- CSV export → Events and samples CSV: writes CSVs (evidence: `README.md`)
- Researcher → Data cleaning: requests cleaning (evidence: `README.md`)
- Researcher → Trial QC report: requests QC (evidence: `README.md`)
- Events and samples CSV → Trial QC report: reads events and samples (evidence: `README.md`)
- Researcher → Trial summaries: requests summaries (evidence: `README.md`)
- Researcher → Saccade amplitudes: requests amplitudes (evidence: `README.md`)
- Researcher → Recording metadata: requests metadata (evidence: `README.md`)
- Recording metadata → EDFFile reader: loads recording (evidence: `etformat/edfinfo.py`)
- Researcher → Channel inspection: requests channels (evidence: `README.md`)
- Channel inspection → EDFFile reader: loads recording (evidence: `etformat/channels.py`)
- Researcher → Calibration review: requests calibration (evidence: `README.md`)
- Calibration review → EDFFile reader: loads recording (evidence: `etformat/calibration.py`)
- Researcher → Gaze plotting: requests plot (evidence: `README.md`)
- Researcher → Saccade plotting: requests plot (evidence: `README.md`)