# swidler/roam-python architecture

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

## Overview

RoAM is a Python genomics tool with two user-facing workflows: reconstructing ancient-DNA methylation from BAM reads, and detecting differentially methylated regions between sample groups. The reconstruction workflow prepares CpG coordinates and sample data, then processes and filters methylation data; the DMR workflow combines sample data and analyzes group differences, with optional genomic annotation. The graph preserves the shared genomic data model and utilities. Some subsystem details come from README descriptions and source-index references; unsampled implementation links are omitted where their runtime wiring is not shown.

Main entry points: [`run_roam.py`](https://github.com/swidler/roam-python/blob/master/run_roam.py) (RoAM runner), [`DMRs.py`](https://github.com/swidler/roam-python/blob/master/DMRs.py) (DMR analysis), [`mmsample.py`](https://github.com/swidler/roam-python/blob/master/mmsample.py) (Modern sample processing), [`run_DMRs.py`](https://github.com/swidler/roam-python/blob/master/run_DMRs.py) (DMR runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ancient["Ancient reconstruction"]
  node_ancient_cli["RoAM runner<br/>[run_roam.py]"]
  node_parallel["Chromosome workers"]
  node_ancient_sample["Ancient sample processing<br/>[amsample.py]"]
end

subgraph group_dmr["DMR analysis"]
  node_dmr_cli["DMR runner<br/>[run_DMRs.py]"]
  node_dmr_engine["DMR analysis<br/>[DMRs.py]"]
  node_chrom_dmrs["Chromosome DMRs<br/>[cDMRs.py]"]
  node_prepared_files["DMR sample preparation"]
end

subgraph group_genome["Genomic data model"]
  node_cpg["CpG coordinates<br/>[gcoordinates.py]"]
  node_modern_sample["Modern sample processing<br/>[mmsample.py]"]
  node_chrom["Chromosome model<br/>[chroms.py]"]
  node_intervals["Genomic intervals<br/>[gintervals.py]"]
end

subgraph group_shared["Shared utilities"]
  node_helpers["Shared tools<br/>[tools.py]"]
end

node_user(("Researcher"))
node_bam[("Ancient BAM input")]
node_fasta["Reference FASTA"]
node_modernmap["Modern methylation map"]
node_dmr_results["DMR outputs"]
node_reconstruction_results["Reconstruction outputs"]

node_user -->|"configures and runs"| node_ancient_cli
node_bam -->|"provides reads"| node_ancient_cli
node_fasta -->|"provides assembly"| node_ancient_cli
node_ancient_cli -->|"creates coordinates"| node_cpg
node_ancient_cli -.->|"dispatches workers"| node_parallel
node_ancient_cli -->|"processes BAM"| node_ancient_sample
node_parallel -->|"builds partial samples"| node_ancient_sample
node_modernmap -->|"provides reference"| node_ancient_cli
node_ancient_cli -->|"loads reference map"| node_modern_sample
node_ancient_cli -->|"writes reconstruction"| node_reconstruction_results
node_user -->|"configures and runs"| node_dmr_cli
node_dmr_cli -->|"loads modern samples"| node_modern_sample
node_dmr_cli -->|"runs analysis"| node_dmr_engine
node_dmr_cli -.->|"produces DMR results"| node_dmr_results
node_prepared_files -->|"converts Bismark data"| node_modern_sample
node_dmr_engine -->|"uses chromosome DMRs"| node_chrom_dmrs
node_dmr_engine -->|"uses coordinates"| node_cpg
node_dmr_engine -->|"uses intervals"| node_intervals
node_ancient_sample -->|"inherits chromosome methods"| node_chrom
node_modern_sample -->|"inherits chromosome methods"| node_chrom
node_intervals -->|"inherits chromosome methods"| node_chrom
node_cpg -->|"inherits chromosome methods"| node_chrom
node_ancient_sample -->|"uses utilities"| node_helpers
node_modern_sample -->|"uses utilities"| node_helpers
node_dmr_engine -->|"uses utilities"| node_helpers

click node_ancient_cli "https://github.com/swidler/roam-python/blob/master/run_roam.py"
click node_cpg "https://github.com/swidler/roam-python/blob/master/gcoordinates.py"
click node_parallel "https://github.com/swidler/roam-python/blob/master/amsample_parallel.py"
click node_ancient_sample "https://github.com/swidler/roam-python/blob/master/amsample.py"
click node_modern_sample "https://github.com/swidler/roam-python/blob/master/mmsample.py"
click node_chrom "https://github.com/swidler/roam-python/blob/master/chroms.py"
click node_intervals "https://github.com/swidler/roam-python/blob/master/gintervals.py"
click node_dmr_cli "https://github.com/swidler/roam-python/blob/master/run_DMRs.py"
click node_dmr_engine "https://github.com/swidler/roam-python/blob/master/DMRs.py"
click node_chrom_dmrs "https://github.com/swidler/roam-python/blob/master/cDMRs.py"
click node_helpers "https://github.com/swidler/roam-python/blob/master/tools.py"
click node_prepared_files "https://github.com/swidler/roam-python/blob/master/create_files_for_DMRs.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_ancient_cli,node_parallel,node_ancient_sample toneBlue
class node_dmr_cli,node_dmr_engine,node_chrom_dmrs,node_prepared_files,node_bam toneAmber
class node_cpg,node_modern_sample,node_chrom,node_intervals toneMint
class node_helpers toneRose
class node_user,node_fasta,node_modernmap,node_dmr_results,node_reconstruction_results toneIndigo
```

## Components

### Ancient reconstruction

- [RoAM runner](https://github.com/swidler/roam-python/blob/master/run_roam.py): `run_roam.py`
- [Chromosome workers](https://github.com/swidler/roam-python/blob/master/amsample_parallel.py): `amsample_parallel.py`
- [Ancient sample processing](https://github.com/swidler/roam-python/blob/master/amsample.py): `amsample.py`

### DMR analysis

- [DMR runner](https://github.com/swidler/roam-python/blob/master/run_DMRs.py): `run_DMRs.py`
- [DMR analysis](https://github.com/swidler/roam-python/blob/master/DMRs.py): `DMRs.py`
- [Chromosome DMRs](https://github.com/swidler/roam-python/blob/master/cDMRs.py): `cDMRs.py`
- [DMR sample preparation](https://github.com/swidler/roam-python/blob/master/create_files_for_DMRs.py): `create_files_for_DMRs.py`

### Genomic data model

- [CpG coordinates](https://github.com/swidler/roam-python/blob/master/gcoordinates.py): `gcoordinates.py`
- [Modern sample processing](https://github.com/swidler/roam-python/blob/master/mmsample.py): `mmsample.py`
- [Chromosome model](https://github.com/swidler/roam-python/blob/master/chroms.py): `chroms.py`
- [Genomic intervals](https://github.com/swidler/roam-python/blob/master/gintervals.py): `gintervals.py`

### Shared utilities

- [Shared tools](https://github.com/swidler/roam-python/blob/master/tools.py): `tools.py`

### Other components

- **Researcher**
- **Ancient BAM input**
- **Reference FASTA**
- **Modern methylation map**
- **DMR outputs**
- **Reconstruction outputs**

## Connections

- Researcher → RoAM runner: configures and runs (evidence: `README.md`)
- Ancient BAM input → RoAM runner: provides reads (evidence: `README.md`)
- Reference FASTA → RoAM runner: provides assembly (evidence: `README.md`)
- RoAM runner → CpG coordinates: creates coordinates (evidence: `run_roam.py`)
- RoAM runner → Chromosome workers: dispatches workers (evidence: `run_roam.py`)
- RoAM runner → Ancient sample processing: processes BAM (evidence: `run_roam.py`)
- Chromosome workers → Ancient sample processing: builds partial samples (evidence: `amsample_parallel.py`)
- Modern methylation map → RoAM runner: provides reference (evidence: `README.md`)
- RoAM runner → Modern sample processing: loads reference map (evidence: `run_roam.py`)
- RoAM runner → Reconstruction outputs: writes reconstruction (evidence: `README.md`)
- Researcher → DMR runner: configures and runs (evidence: `README.md`)
- DMR runner → Modern sample processing: loads modern samples (evidence: `run_DMRs.py`)
- DMR runner → DMR analysis: runs analysis (evidence: `run_DMRs.py`)
- DMR runner → DMR outputs: produces DMR results
- DMR sample preparation → Modern sample processing: converts Bismark data (evidence: `create_files_for_DMRs.py`)
- DMR analysis → Chromosome DMRs: uses chromosome DMRs (evidence: `DMRs.py`)
- DMR analysis → CpG coordinates: uses coordinates (evidence: `DMRs.py`)
- DMR analysis → Genomic intervals: uses intervals (evidence: `DMRs.py`)
- Ancient sample processing → Chromosome model: inherits chromosome methods (evidence: `amsample.py`)
- Modern sample processing → Chromosome model: inherits chromosome methods (evidence: `mmsample.py`)
- Genomic intervals → Chromosome model: inherits chromosome methods (evidence: `gintervals.py`)
- CpG coordinates → Chromosome model: inherits chromosome methods (evidence: `gcoordinates.py`)
- Ancient sample processing → Shared tools: uses utilities (evidence: `amsample.py`)
- Modern sample processing → Shared tools: uses utilities (evidence: `mmsample.py`)
- DMR analysis → Shared tools: uses utilities (evidence: `DMRs.py`)
