# twilightsail/citrusnce architecture

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

- Interactive diagram: https://gitdiagram.com/twilightsail/citrusnce
- Repository: https://github.com/twilightsail/citrusnce

## Overview

citrusnce is a chromosome-syntenic conserved-noncoding-element discovery and analysis pipeline for Citrus. Its main workflow prepares genome and annotation indexes, aligns assemblies by chromosome, builds constraint-leaf alignments, fits a neutral model, calls conserved elements, projects their presence across assemblies, and annotates the catalog. Published capabilities also include model diagnostics, lineage and acceleration analyses, ancestral-fate analyses, and catalog comparisons. The README documents these analysis branches; their individual implementations are not sampled here, so links are limited to paths present in the tree.

Main entry points: [`cmd/citrusnce/main.go`](https://github.com/twilightsail/citrusnce/blob/master/cmd/citrusnce/main.go) (Command dispatcher), [`internal/callstage/call.go`](https://github.com/twilightsail/citrusnce/blob/master/internal/callstage/call.go) (Conserved-element calling), [`internal/mapstage/map.go`](https://github.com/twilightsail/citrusnce/blob/master/internal/mapstage/map.go) (Chromosome mapping), [`internal/modelstage/model.go`](https://github.com/twilightsail/citrusnce/blob/master/internal/modelstage/model.go) (Neutral model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Configuration and runs"]
  node_config["Run configuration<br/>[config.go]"]
  node_runstate["Run layout and status<br/>[layout.go]"]
  node_prep["Genome preparation<br/>[prep.go]"]
end

subgraph group_discovery["Element discovery"]
  node_mapping["Chromosome mapping<br/>[map.go]"]
  node_coverage["Mapping coverage<br/>[coverage.go]"]
  node_msa["Constraint alignment<br/>[msa.go]"]
  node_model["Neutral model<br/>[model.go]"]
  node_modelqc["Model diagnostics<br/>[model.go]"]
  node_call["Conserved-element calling<br/>[call.go]"]
  node_mask["Coding and UTR masks<br/>[gff.go]"]
end

subgraph group_catalog["Presence and annotation"]
  node_lift["Presence projection<br/>[lift.go]"]
  node_annotate["Catalog annotation<br/>[annotate.go]"]
  node_catalogout["Catalog and tracks"]
end

subgraph group_analyses["Downstream analyses"]
  node_lineage["Lineage branch tests<br/>[phyloacc_nce.py]"]
  node_loo["LOO acceleration tests<br/>[loo_nce.py]"]
  node_fate["Ancestral fate<br/>[ancestral_fate.py]"]
  node_comparison["Catalog benchmarks"]
  node_analysisout["Analysis outputs"]
end

subgraph group_external["External tools"]
  node_aligners["Alignment tools"]
  node_phastcons["phastCons and phyloP"]
end

node_user(("Pipeline user"))
node_cli["Command dispatcher<br/>[main.go]"]
node_assemblies["Genome FASTA and GFF"]
node_tracks["Optional annotation tracks"]

node_user -->|"issues commands"| node_cli
node_cli -->|"loads configuration"| node_config
node_cli -->|"selects run"| node_runstate
node_cli -->|"dispatches prep"| node_prep
node_cli -->|"dispatches stage"| node_mapping
node_cli -->|"dispatches stage"| node_msa
node_cli -->|"dispatches stage"| node_model
node_cli -->|"dispatches stage"| node_call
node_cli -->|"dispatches stage"| node_lift
node_cli -->|"dispatches stage"| node_annotate
node_prep -->|"indexes inputs"| node_assemblies
node_prep -->|"records preparation"| node_runstate
node_mapping -->|"aligns genomes"| node_assemblies
node_mapping -->|"runs alignment"| node_aligners
node_mapping -->|"summarizes mappings"| node_coverage
node_mapping -->|"writes chromosome PAFs"| node_msa
node_msa -->|"extracts sequences"| node_assemblies
node_msa -->|"writes constraint MSA"| node_model
node_model -->|"uses CDS annotations"| node_mask
node_model -->|"writes fitted model"| node_call
node_model -->|"reports fit diagnostics"| node_modelqc
node_call -->|"reads alignments"| node_msa
node_call -->|"uses coding masks"| node_mask
node_call -->|"runs conservation tools"| node_phastcons
node_call -->|"publishes NCEs"| node_catalogout
node_lift -->|"projects NCE presence"| node_catalogout
node_lift -->|"uses assembly mappings"| node_assemblies
node_annotate -->|"reads NCEs and writes annotations"| node_catalogout
node_annotate -.->|"reads optional overlaps"| node_tracks
node_lineage -->|"analyzes catalog"| node_catalogout
node_loo -->|"tests acceleration"| node_catalogout
node_fate -->|"evaluates homolog states"| node_catalogout
node_comparison -->|"compares coordinates"| node_catalogout
node_lineage -->|"writes branch results"| node_analysisout
node_loo -->|"writes test results"| node_analysisout
node_fate -->|"writes fate results"| node_analysisout
node_comparison -->|"writes benchmarks"| node_analysisout

click node_cli "https://github.com/twilightsail/citrusnce/blob/master/cmd/citrusnce/main.go"
click node_config "https://github.com/twilightsail/citrusnce/blob/master/internal/config/config.go"
click node_runstate "https://github.com/twilightsail/citrusnce/blob/master/internal/run/layout.go"
click node_prep "https://github.com/twilightsail/citrusnce/blob/master/internal/prep/prep.go"
click node_mapping "https://github.com/twilightsail/citrusnce/blob/master/internal/mapstage/map.go"
click node_coverage "https://github.com/twilightsail/citrusnce/blob/master/internal/mapstage/coverage.go"
click node_msa "https://github.com/twilightsail/citrusnce/blob/master/internal/msastage/msa.go"
click node_model "https://github.com/twilightsail/citrusnce/blob/master/internal/modelstage/model.go"
click node_modelqc "https://github.com/twilightsail/citrusnce/blob/master/internal/modelstage/model.go"
click node_call "https://github.com/twilightsail/citrusnce/blob/master/internal/callstage/call.go"
click node_mask "https://github.com/twilightsail/citrusnce/blob/master/internal/mask/gff.go"
click node_lift "https://github.com/twilightsail/citrusnce/blob/master/internal/liftstage/lift.go"
click node_annotate "https://github.com/twilightsail/citrusnce/blob/master/internal/annotatestage/annotate.go"
click node_lineage "https://github.com/twilightsail/citrusnce/blob/master/tools/phyloacc_nce.py"
click node_loo "https://github.com/twilightsail/citrusnce/blob/master/tools/loo_nce.py"
click node_fate "https://github.com/twilightsail/citrusnce/blob/master/tools/ancestral_fate.py"
click node_comparison "https://github.com/twilightsail/citrusnce/blob/master/tools/benchmark_catalogs.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_config,node_runstate,node_prep,node_user toneBlue
class node_mapping,node_coverage,node_msa,node_model,node_modelqc,node_call,node_mask toneAmber
class node_lift,node_annotate,node_catalogout toneMint
class node_lineage,node_loo,node_fate,node_comparison,node_analysisout toneRose
class node_aligners,node_phastcons,node_assemblies,node_tracks toneIndigo
class node_cli toneTeal
```

## Components

### Configuration and runs

- [Run configuration](https://github.com/twilightsail/citrusnce/blob/master/internal/config/config.go): `internal/config/config.go`
- [Run layout and status](https://github.com/twilightsail/citrusnce/blob/master/internal/run/layout.go): `internal/run/layout.go`
- [Genome preparation](https://github.com/twilightsail/citrusnce/blob/master/internal/prep/prep.go): `internal/prep/prep.go`

### Element discovery

- [Chromosome mapping](https://github.com/twilightsail/citrusnce/blob/master/internal/mapstage/map.go): `internal/mapstage/map.go`
- [Mapping coverage](https://github.com/twilightsail/citrusnce/blob/master/internal/mapstage/coverage.go): `internal/mapstage/coverage.go`
- [Constraint alignment](https://github.com/twilightsail/citrusnce/blob/master/internal/msastage/msa.go): `internal/msastage/msa.go`
- [Neutral model](https://github.com/twilightsail/citrusnce/blob/master/internal/modelstage/model.go): `internal/modelstage/model.go`
- [Model diagnostics](https://github.com/twilightsail/citrusnce/blob/master/internal/modelstage/model.go): `internal/modelstage/model.go`
- [Conserved-element calling](https://github.com/twilightsail/citrusnce/blob/master/internal/callstage/call.go): `internal/callstage/call.go`
- [Coding and UTR masks](https://github.com/twilightsail/citrusnce/blob/master/internal/mask/gff.go): `internal/mask/gff.go`

### Presence and annotation

- [Presence projection](https://github.com/twilightsail/citrusnce/blob/master/internal/liftstage/lift.go): `internal/liftstage/lift.go`
- [Catalog annotation](https://github.com/twilightsail/citrusnce/blob/master/internal/annotatestage/annotate.go): `internal/annotatestage/annotate.go`
- **Catalog and tracks**

### Downstream analyses

- [Lineage branch tests](https://github.com/twilightsail/citrusnce/blob/master/tools/phyloacc_nce.py): `tools/phyloacc_nce.py`
- [LOO acceleration tests](https://github.com/twilightsail/citrusnce/blob/master/tools/loo_nce.py): `tools/loo_nce.py`
- [Ancestral fate](https://github.com/twilightsail/citrusnce/blob/master/tools/ancestral_fate.py): `tools/ancestral_fate.py`
- [Catalog benchmarks](https://github.com/twilightsail/citrusnce/blob/master/tools/benchmark_catalogs.py): `tools/benchmark_catalogs.py`
- **Analysis outputs**

### External tools

- **Alignment tools**
- **phastCons and phyloP**

### Other components

- **Pipeline user**
- [Command dispatcher](https://github.com/twilightsail/citrusnce/blob/master/cmd/citrusnce/main.go): `cmd/citrusnce/main.go`
- **Genome FASTA and GFF**
- **Optional annotation tracks**

## Connections

- Pipeline user → Command dispatcher: issues commands
- Command dispatcher → Run configuration: loads configuration
- Command dispatcher → Run layout and status: selects run
- Command dispatcher → Genome preparation: dispatches prep
- Command dispatcher → Chromosome mapping: dispatches stage
- Command dispatcher → Constraint alignment: dispatches stage
- Command dispatcher → Neutral model: dispatches stage
- Command dispatcher → Conserved-element calling: dispatches stage
- Command dispatcher → Presence projection: dispatches stage
- Command dispatcher → Catalog annotation: dispatches stage
- Genome preparation → Genome FASTA and GFF: indexes inputs
- Genome preparation → Run layout and status: records preparation
- Chromosome mapping → Genome FASTA and GFF: aligns genomes
- Chromosome mapping → Alignment tools: runs alignment
- Chromosome mapping → Mapping coverage: summarizes mappings
- Chromosome mapping → Constraint alignment: writes chromosome PAFs
- Constraint alignment → Genome FASTA and GFF: extracts sequences
- Constraint alignment → Neutral model: writes constraint MSA
- Neutral model → Coding and UTR masks: uses CDS annotations
- Neutral model → Conserved-element calling: writes fitted model
- Neutral model → Model diagnostics: reports fit diagnostics
- Conserved-element calling → Constraint alignment: reads alignments
- Conserved-element calling → Coding and UTR masks: uses coding masks
- Conserved-element calling → phastCons and phyloP: runs conservation tools
- Conserved-element calling → Catalog and tracks: publishes NCEs
- Presence projection → Catalog and tracks: projects NCE presence
- Presence projection → Genome FASTA and GFF: uses assembly mappings
- Catalog annotation → Catalog and tracks: reads NCEs and writes annotations
- Catalog annotation → Optional annotation tracks: reads optional overlaps
- Lineage branch tests → Catalog and tracks: analyzes catalog
- LOO acceleration tests → Catalog and tracks: tests acceleration
- Ancestral fate → Catalog and tracks: evaluates homolog states
- Catalog benchmarks → Catalog and tracks: compares coordinates
- Lineage branch tests → Analysis outputs: writes branch results
- LOO acceleration tests → Analysis outputs: writes test results
- Ancestral fate → Analysis outputs: writes fate results
- Catalog benchmarks → Analysis outputs: writes benchmarks