# carinerey/pcoc architecture

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

## Overview

PCOC supports two user-facing workflows: detecting convergent substitutions in an existing alignment/tree and simulating alignments to assess detection power. The detection workflow includes manual transition annotation, model estimation, site scoring/filtering, and optional visualization; simulation includes scenario construction, sequence generation, and benchmarking. Source excerpts confirm key CLI-to-library calls, but omit portions of both drivers, so uncertain internal wiring is not shown.

Main entry points: [`src/pcoc_det.py`](https://github.com/carinerey/pcoc/blob/master/src/pcoc_det.py) (Detection runner), [`src/pcoc_sim.py`](https://github.com/carinerey/pcoc/blob/master/src/pcoc_sim.py) (Simulation runner), [`src/bpp_lib.py`](https://github.com/carinerey/pcoc/blob/master/src/bpp_lib.py) (BPP model runner), [`src/pcoc_num_tree.py`](https://github.com/carinerey/pcoc/blob/master/src/pcoc_num_tree.py) (Tree numbering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_detection["Empirical detection"]
  node_detection_cli["Detection runner<br/>[pcoc_det.py]"]
  node_tree_numbering["Tree numbering<br/>[pcoc_num_tree.py]"]
end

subgraph group_simulation["Power simulation"]
  node_simulation_cli["Simulation runner<br/>[pcoc_sim.py]"]
  node_scenario_placement["Scenario placement<br/>[placing.py]"]
  node_simulation_results["Simulated data and benchmarks<br/>[pcoc_sim.py]"]
end

subgraph group_core["Phylogenetic models"]
  node_event_placement["Event annotation<br/>[events_placing.py]"]
  node_profile_config["Profile handling<br/>[profile_tools.py]"]
  node_model_runner["BPP model runner<br/>[bpp_lib.py]"]
end

subgraph group_results["Analysis outputs"]
  node_site_analysis["Likelihood analysis<br/>[estim_data.py]"]
  node_visualization["Tree and score plots<br/>[plot_data.py]"]
  node_detection_results["Site scores and plots<br/>[pcoc_det.py]"]
end

node_researcher(("Researcher"))
node_alignment["Amino-acid alignment"]
node_gene_tree["Gene tree"]
node_bpp_suite["BPP suite"]

node_researcher -->|"numbers tree"| node_tree_numbering
node_gene_tree -->|"supplies tree"| node_tree_numbering
node_researcher -->|"starts analysis"| node_detection_cli
node_alignment -->|"supplies alignment"| node_detection_cli
node_gene_tree -->|"supplies tree"| node_detection_cli
node_tree_numbering -->|"returns node labels"| node_researcher
node_detection_cli -->|"annotates events"| node_event_placement
node_detection_cli -->|"configures profiles"| node_profile_config
node_detection_cli -->|"requests estimates"| node_model_runner
node_model_runner -->|"runs model fitting"| node_bpp_suite
node_detection_cli -->|"analyzes likelihoods"| node_site_analysis
node_detection_cli -.->|"requests plots"| node_visualization
node_detection_cli -->|"writes scores"| node_detection_results
node_visualization -.->|"renders figures"| node_detection_results
node_researcher -->|"starts simulation"| node_simulation_cli
node_simulation_cli -->|"configures profiles"| node_profile_config
node_simulation_cli -->|"places transitions"| node_scenario_placement
node_simulation_cli -->|"builds event models"| node_event_placement
node_simulation_cli -->|"requests simulations"| node_model_runner
node_model_runner -->|"runs sequence models"| node_bpp_suite
node_simulation_cli -->|"benchmarks methods"| node_site_analysis
node_simulation_cli -->|"writes alignments and metrics"| node_simulation_results

click node_detection_cli "https://github.com/carinerey/pcoc/blob/master/src/pcoc_det.py"
click node_tree_numbering "https://github.com/carinerey/pcoc/blob/master/src/pcoc_num_tree.py"
click node_event_placement "https://github.com/carinerey/pcoc/blob/master/src/events_placing.py"
click node_profile_config "https://github.com/carinerey/pcoc/blob/master/src/profile_tools.py"
click node_model_runner "https://github.com/carinerey/pcoc/blob/master/src/bpp_lib.py"
click node_site_analysis "https://github.com/carinerey/pcoc/blob/master/src/estim_data.py"
click node_visualization "https://github.com/carinerey/pcoc/blob/master/src/plot_data.py"
click node_detection_results "https://github.com/carinerey/pcoc/blob/master/src/pcoc_det.py"
click node_simulation_cli "https://github.com/carinerey/pcoc/blob/master/src/pcoc_sim.py"
click node_scenario_placement "https://github.com/carinerey/pcoc/blob/master/src/placing.py"
click node_simulation_results "https://github.com/carinerey/pcoc/blob/master/src/pcoc_sim.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_detection_cli,node_tree_numbering toneBlue
class node_simulation_cli,node_scenario_placement,node_simulation_results toneAmber
class node_event_placement,node_profile_config,node_model_runner toneMint
class node_site_analysis,node_visualization,node_detection_results toneRose
class node_researcher,node_alignment,node_gene_tree,node_bpp_suite toneIndigo
```

## Components

### Empirical detection

- [Detection runner](https://github.com/carinerey/pcoc/blob/master/src/pcoc_det.py): `src/pcoc_det.py`
- [Tree numbering](https://github.com/carinerey/pcoc/blob/master/src/pcoc_num_tree.py): `src/pcoc_num_tree.py`

### Power simulation

- [Simulation runner](https://github.com/carinerey/pcoc/blob/master/src/pcoc_sim.py): `src/pcoc_sim.py`
- [Scenario placement](https://github.com/carinerey/pcoc/blob/master/src/placing.py): `src/placing.py`
- [Simulated data and benchmarks](https://github.com/carinerey/pcoc/blob/master/src/pcoc_sim.py): `src/pcoc_sim.py`

### Phylogenetic models

- [Event annotation](https://github.com/carinerey/pcoc/blob/master/src/events_placing.py): `src/events_placing.py`
- [Profile handling](https://github.com/carinerey/pcoc/blob/master/src/profile_tools.py): `src/profile_tools.py`
- [BPP model runner](https://github.com/carinerey/pcoc/blob/master/src/bpp_lib.py): `src/bpp_lib.py`

### Analysis outputs

- [Likelihood analysis](https://github.com/carinerey/pcoc/blob/master/src/estim_data.py): `src/estim_data.py`
- [Tree and score plots](https://github.com/carinerey/pcoc/blob/master/src/plot_data.py): `src/plot_data.py`
- [Site scores and plots](https://github.com/carinerey/pcoc/blob/master/src/pcoc_det.py): `src/pcoc_det.py`

### Other components

- **Researcher**
- **Amino-acid alignment**
- **Gene tree**
- **BPP suite**

## Connections

- Researcher → Tree numbering: numbers tree
- Gene tree → Tree numbering: supplies tree
- Researcher → Detection runner: starts analysis
- Amino-acid alignment → Detection runner: supplies alignment
- Gene tree → Detection runner: supplies tree
- Tree numbering → Researcher: returns node labels
- Detection runner → Event annotation: annotates events
- Detection runner → Profile handling: configures profiles
- Detection runner → BPP model runner: requests estimates
- BPP model runner → BPP suite: runs model fitting
- Detection runner → Likelihood analysis: analyzes likelihoods
- Detection runner → Tree and score plots: requests plots
- Detection runner → Site scores and plots: writes scores
- Tree and score plots → Site scores and plots: renders figures
- Researcher → Simulation runner: starts simulation
- Simulation runner → Profile handling: configures profiles
- Simulation runner → Scenario placement: places transitions
- Simulation runner → Event annotation: builds event models
- Simulation runner → BPP model runner: requests simulations
- BPP model runner → BPP suite: runs sequence models
- Simulation runner → Likelihood analysis: benchmarks methods
- Simulation runner → Simulated data and benchmarks: writes alignments and metrics