# pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping architecture

> Architecture diagram of the GitHub repository pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping, 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/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping
- Repository: https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping

## Overview

This is a modular Nextflow DSL2 toolkit that converts biobank phenotype configuration and source tables into per-phenotype outputs, with optional gathering, event-window masking, pregnancy filtering, and risk classification. The principal workflow resolves inherited YAML settings into per-phenotype JSON, preprocesses inputs into long-format TSVs, dispatches them to type-specific phenotype encoders, and optionally gathers results. The graph also shows the documented mask and risk branches. Some wiring is based on README topology; unsampled module internals are not inferred.

Main entry points: [`bin/preprocess.py`](https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/bin/preprocess.py) (Preprocess tables), [`main.nf`](https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/main.nf) (Nextflow workflow), [`bin/event_mask.py`](https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/bin/event_mask.py) (Event mask windows), [`bin/advanced_coded.py`](https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/bin/advanced_coded.py) (Advanced coded)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Pipeline orchestration"]
  node_nextflow["Nextflow workflow<br/>[main.nf]"]
  node_config["Config resolver<br/>[resolve_config.py]"]
  node_resolved_configs["Phenotype JSON configs"]
end

subgraph group_preprocessing["Input preparation"]
  node_preprocess["Preprocess tables<br/>[preprocess.py]"]
  node_long_tsv["Long-format TSVs"]
  node_pregnancy["Pregnancy filter<br/>[main.nf]"]
  node_event_mask["Event mask windows<br/>[event_mask.py]"]
  node_mask_intervals["Mask intervals"]
  node_apply_mask["Apply mask<br/>[apply_mask.py]"]
end

subgraph group_phenotyping["Phenotype processing"]
  node_basic_coded["Basic coded<br/>[basic_coded.py]"]
  node_advanced_coded["Advanced coded<br/>[advanced_coded.py]"]
  node_quantitative["Quantitative encoding"]
  node_categorical["Categorical encoding"]
  node_icd_utils["Code matching utilities<br/>[icd_utils.py]"]
end

subgraph group_outputs["Outputs and analysis"]
  node_phenotypes["Per-phenotype TSVs"]
  node_manifest["Phenotype manifest"]
  node_gather["Gather tables<br/>[gather.py]"]
  node_wide_table["Gathered phenotype table"]
  node_risk["Risk classification"]
  node_risk_outputs["Risk matrix and report"]
end

node_analyst(("Biobank analyst"))

node_analyst -->|"runs pipeline"| node_nextflow
node_nextflow -->|"resolves config"| node_config
node_config -->|"writes configs"| node_resolved_configs
node_nextflow -->|"dispatches jobs"| node_preprocess
node_resolved_configs -->|"configures jobs"| node_preprocess
node_preprocess -->|"writes long TSVs"| node_long_tsv
node_long_tsv -.->|"filters opted data"| node_pregnancy
node_long_tsv -->|"supplies event codes"| node_event_mask
node_event_mask -->|"computes windows"| node_mask_intervals
node_mask_intervals -->|"filters by windows"| node_apply_mask
node_long_tsv -->|"supplies phenotype rows"| node_apply_mask
node_preprocess -->|"fans out codes"| node_basic_coded
node_preprocess -->|"fans out coded data"| node_advanced_coded
node_preprocess -->|"fans out quantitative"| node_quantitative
node_preprocess -->|"fans out categorical"| node_categorical
node_advanced_coded -->|"matches patterns"| node_icd_utils
node_event_mask -->|"matches codes"| node_icd_utils
node_basic_coded -->|"writes phenotype TSVs"| node_phenotypes
node_advanced_coded -->|"writes phenotype TSVs"| node_phenotypes
node_quantitative -->|"writes phenotype TSVs"| node_phenotypes
node_categorical -->|"writes phenotype TSVs"| node_phenotypes
node_phenotypes -->|"indexes output columns"| node_manifest
node_phenotypes -->|"joins phenotype TSVs"| node_gather
node_gather -->|"writes wide table"| node_wide_table
node_wide_table -->|"provides wide input"| node_risk
node_resolved_configs -->|"provides risk rules"| node_risk
node_risk -->|"writes risk results"| node_risk_outputs

click node_nextflow "https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/main.nf"
click node_config "https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/bin/resolve_config.py"
click node_preprocess "https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/bin/preprocess.py"
click node_pregnancy "https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/modules/pregnancy_filter/main.nf"
click node_event_mask "https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/bin/event_mask.py"
click node_apply_mask "https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/bin/apply_mask.py"
click node_basic_coded "https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/bin/basic_coded.py"
click node_advanced_coded "https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/bin/advanced_coded.py"
click node_quantitative "https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/bin/basic_quantitative.py"
click node_categorical "https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/bin/basic_categorical.py"
click node_icd_utils "https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/bin/icd_utils.py"
click node_manifest "https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/bin/phenotype_manifest.py"
click node_gather "https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/bin/gather.py"
click node_risk "https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/bin/risk_classification.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_nextflow,node_config,node_resolved_configs toneBlue
class node_preprocess,node_long_tsv,node_pregnancy,node_event_mask,node_mask_intervals,node_apply_mask toneAmber
class node_basic_coded,node_advanced_coded,node_quantitative,node_categorical,node_icd_utils toneMint
class node_phenotypes,node_manifest,node_gather,node_wide_table,node_risk,node_risk_outputs toneRose
class node_analyst toneIndigo
```

## Components

### Pipeline orchestration

- [Nextflow workflow](https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/main.nf): `main.nf`
- [Config resolver](https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/bin/resolve_config.py): `bin/resolve_config.py`
- **Phenotype JSON configs**

### Input preparation

- [Preprocess tables](https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/bin/preprocess.py): `bin/preprocess.py`
- **Long-format TSVs**
- [Pregnancy filter](https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/modules/pregnancy_filter/main.nf): `modules/pregnancy_filter/main.nf`
- [Event mask windows](https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/bin/event_mask.py): `bin/event_mask.py`
- **Mask intervals**
- [Apply mask](https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/bin/apply_mask.py): `bin/apply_mask.py`

### Phenotype processing

- [Basic coded](https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/bin/basic_coded.py): `bin/basic_coded.py`
- [Advanced coded](https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/bin/advanced_coded.py): `bin/advanced_coded.py`
- [Quantitative encoding](https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/bin/basic_quantitative.py): `bin/basic_quantitative.py`
- [Categorical encoding](https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/bin/basic_categorical.py): `bin/basic_categorical.py`
- [Code matching utilities](https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/bin/icd_utils.py): `bin/icd_utils.py`

### Outputs and analysis

- **Per-phenotype TSVs**
- [Phenotype manifest](https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/bin/phenotype_manifest.py): `bin/phenotype_manifest.py`
- [Gather tables](https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/bin/gather.py): `bin/gather.py`
- **Gathered phenotype table**
- [Risk classification](https://github.com/pmbb-informatics-and-genomics/pmbb-nf-toolkit-phenotyping/blob/main/bin/risk_classification.py): `bin/risk_classification.py`
- **Risk matrix and report**

### Other components

- **Biobank analyst**

## Connections

- Biobank analyst → Nextflow workflow: runs pipeline (evidence: `README.md`)
- Nextflow workflow → Config resolver: resolves config (evidence: `README.md`)
- Config resolver → Phenotype JSON configs: writes configs (evidence: `README.md`)
- Nextflow workflow → Preprocess tables: dispatches jobs (evidence: `README.md`)
- Phenotype JSON configs → Preprocess tables: configures jobs (evidence: `README.md`)
- Preprocess tables → Long-format TSVs: writes long TSVs (evidence: `README.md`)
- Long-format TSVs → Pregnancy filter: filters opted data
- Long-format TSVs → Event mask windows: supplies event codes (evidence: `README.md`)
- Event mask windows → Mask intervals: computes windows (evidence: `README.md`)
- Mask intervals → Apply mask: filters by windows (evidence: `README.md`)
- Long-format TSVs → Apply mask: supplies phenotype rows (evidence: `README.md`)
- Preprocess tables → Basic coded: fans out codes (evidence: `README.md`)
- Preprocess tables → Advanced coded: fans out coded data (evidence: `README.md`)
- Preprocess tables → Quantitative encoding: fans out quantitative (evidence: `README.md`)
- Preprocess tables → Categorical encoding: fans out categorical (evidence: `README.md`)
- Advanced coded → Code matching utilities: matches patterns (evidence: `bin/advanced_coded.py`)
- Event mask windows → Code matching utilities: matches codes (evidence: `bin/event_mask.py`)
- Basic coded → Per-phenotype TSVs: writes phenotype TSVs (evidence: `README.md`)
- Advanced coded → Per-phenotype TSVs: writes phenotype TSVs (evidence: `README.md`)
- Quantitative encoding → Per-phenotype TSVs: writes phenotype TSVs (evidence: `README.md`)
- Categorical encoding → Per-phenotype TSVs: writes phenotype TSVs (evidence: `README.md`)
- Per-phenotype TSVs → Phenotype manifest: indexes output columns (evidence: `README.md`)
- Per-phenotype TSVs → Gather tables: joins phenotype TSVs (evidence: `README.md`)
- Gather tables → Gathered phenotype table: writes wide table (evidence: `README.md`)
- Gathered phenotype table → Risk classification: provides wide input (evidence: `README.md`)
- Phenotype JSON configs → Risk classification: provides risk rules (evidence: `README.md`)
- Risk classification → Risk matrix and report: writes risk results (evidence: `README.md`)
