# finucanelab/pops architecture

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

## Overview

PoPS prioritizes genes by combining gene-level GWAS association statistics with gene features, then writes gene predictions, model coefficients, and marginal associations. Its workflow includes a separate feature-munging step that aligns raw feature files to gene annotations and saves chunked matrices. The README documents the inputs and outputs; the sampled source shows feature-matrix munging and several modeling helpers, but not enough of PoPS’s main routine to verify its internal call sequence.

Main entry points: [`pops.py`](https://github.com/finucanelab/pops/blob/master/pops.py) (PoPS workflow), [`munge_feature_directory.py`](https://github.com/finucanelab/pops/blob/master/munge_feature_directory.py) (Feature munging)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Feature preparation"]
  node_raw_features["Raw gene features"]
  node_annotation["Gene annotation"]
  node_munge["Feature munging"]
  node_feature_matrix["Chunked feature matrix"]
end

subgraph group_inputs["Association inputs"]
  node_magma["MAGMA gene scores"]
  node_controls["Control features"]
end

subgraph group_model["PoPS modeling"]
  node_pops["PoPS workflow<br/>[pops.py]"]
  node_feature_load["Feature loading<br/>[pops.py]"]
  node_association["Marginal associations<br/>[pops.py]"]
  node_selection["Feature selection<br/>[pops.py]"]
  node_regression["Gene regression<br/>[pops.py]"]
end

subgraph group_results["Prioritization results"]
  node_predictions["Gene predictions"]
  node_coefficients["Feature coefficients"]
  node_marginals["Marginal results"]
end

node_user(("Analyst"))

node_user -->|"runs preprocessing"| node_munge
node_raw_features -->|"provides features"| node_munge
node_annotation -->|"aligns genes"| node_munge
node_munge -->|"writes chunks"| node_feature_matrix
node_user -->|"runs PoPS"| node_pops
node_feature_matrix -->|"provides features"| node_pops
node_annotation -->|"provides gene data"| node_pops
node_magma -->|"provides scores"| node_pops
node_controls -->|"provides controls"| node_pops
node_pops -.->|"loads matrices"| node_feature_load
node_feature_load -.->|"tests features"| node_association
node_association -.->|"selects features"| node_selection
node_selection -.->|"fits model"| node_regression
node_pops -->|"writes predictions"| node_predictions
node_pops -->|"writes coefficients"| node_coefficients
node_pops -->|"writes marginals"| node_marginals

click node_munge "https://github.com/finucanelab/pops/blob/master/munge_feature_directory.py"
click node_pops "https://github.com/finucanelab/pops/blob/master/pops.py"
click node_feature_load "https://github.com/finucanelab/pops/blob/master/pops.py"
click node_association "https://github.com/finucanelab/pops/blob/master/pops.py"
click node_selection "https://github.com/finucanelab/pops/blob/master/pops.py"
click node_regression "https://github.com/finucanelab/pops/blob/master/pops.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_raw_features,node_annotation,node_munge,node_feature_matrix toneBlue
class node_magma,node_controls toneAmber
class node_pops,node_feature_load,node_association,node_selection,node_regression toneMint
class node_predictions,node_coefficients,node_marginals toneRose
class node_user toneIndigo
```

## Components

### Feature preparation

- **Raw gene features**
- **Gene annotation**
- [Feature munging](https://github.com/finucanelab/pops/blob/master/munge_feature_directory.py): `munge_feature_directory.py`
- **Chunked feature matrix**

### Association inputs

- **MAGMA gene scores**
- **Control features**

### PoPS modeling

- [PoPS workflow](https://github.com/finucanelab/pops/blob/master/pops.py): `pops.py`
- [Feature loading](https://github.com/finucanelab/pops/blob/master/pops.py): `pops.py`
- [Marginal associations](https://github.com/finucanelab/pops/blob/master/pops.py): `pops.py`
- [Feature selection](https://github.com/finucanelab/pops/blob/master/pops.py): `pops.py`
- [Gene regression](https://github.com/finucanelab/pops/blob/master/pops.py): `pops.py`

### Prioritization results

- **Gene predictions**
- **Feature coefficients**
- **Marginal results**

### Other components

- **Analyst**

## Connections

- Analyst → Feature munging: runs preprocessing (evidence: `README.md`)
- Raw gene features → Feature munging: provides features (evidence: `README.md`)
- Gene annotation → Feature munging: aligns genes (evidence: `README.md`)
- Feature munging → Chunked feature matrix: writes chunks (evidence: `README.md`)
- Analyst → PoPS workflow: runs PoPS (evidence: `README.md`)
- Chunked feature matrix → PoPS workflow: provides features (evidence: `README.md`)
- Gene annotation → PoPS workflow: provides gene data (evidence: `README.md`)
- MAGMA gene scores → PoPS workflow: provides scores (evidence: `README.md`)
- Control features → PoPS workflow: provides controls (evidence: `README.md`)
- PoPS workflow → Feature loading: loads matrices (evidence: `pops.py`)
- Feature loading → Marginal associations: tests features (evidence: `pops.py`)
- Marginal associations → Feature selection: selects features (evidence: `pops.py`)
- Feature selection → Gene regression: fits model (evidence: `pops.py`)
- PoPS workflow → Gene predictions: writes predictions (evidence: `README.md`)
- PoPS workflow → Feature coefficients: writes coefficients (evidence: `README.md`)
- PoPS workflow → Marginal results: writes marginals (evidence: `README.md`)
