# nissankararaothanvitha/liver_graph architecture

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

- Interactive diagram: https://gitdiagram.com/nissankararaothanvitha/liver_graph
- Repository: https://github.com/nissankararaothanvitha/liver_graph

## Overview

This repository implements a research workflow for integrating human liver RNA-sequencing cohorts, discovering fibrosis-stage-associated genes, testing stage patterns and transitions, prioritising candidates, and adding results to OptimusKG. The graph also includes documented pathway enrichment, robustness analyses, independent validation, and graph export. The README documents the overall workflow; sampled source confirms patient-level biopsy handling and selected analysis behavior. Many implementation details and links among unsampled modules are therefore left unspecified.

Main entry points: [`find_progression_genes.py`](https://github.com/nissankararaothanvitha/liver_graph/blob/main/find_progression_genes.py) (Progression genes), [`build_graph_all.py`](https://github.com/nissankararaothanvitha/liver_graph/blob/main/build_graph_all.py) (Integrated graph), [`biopsy_policy.py`](https://github.com/nissankararaothanvitha/liver_graph/blob/main/biopsy_policy.py) (Biopsy policy), [`scripts/high_confidence_genes.py`](https://github.com/nissankararaothanvitha/liver_graph/blob/main/scripts/high_confidence_genes.py) (Gene prioritization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_harmonization["Cohort harmonization"]
  node_expression_parsing["Expression parsing"]
  node_gene_mapping["Gene ID mapping<br/>[map_gene_ids.py]"]
  node_clinical_labels["Clinical labels"]
  node_crosswalk["Sample crosswalk<br/>[build_crosswalk.py]"]
  node_biopsy_policy["Biopsy policy<br/>[biopsy_policy.py]"]
end

subgraph group_analysis["Transcriptomic analysis"]
  node_progression_discovery["Progression genes"]
  node_task1["Gene groups"]
  node_task2["Stage clusters"]
  node_task3["Stage transitions"]
  node_task4["Pathway enrichment"]
  node_mentor_export["Patient summaries"]
end

subgraph group_robustness["Prioritization and validation"]
  node_high_confidence["Gene prioritization"]
  node_matched_transitions["Matched transitions"]
  node_loso["LOSO robustness<br/>[loso_validation.py]"]
  node_external_validation["External validation"]
end

subgraph group_knowledge_graph["Knowledge graph"]
  node_graph_builder["Integrated graph<br/>[build_graph_all.py]"]
  node_optimus_layer["OptimusKG layer"]
  node_progression_edges["Progression links"]
  node_pathway_links["Pathway disease links"]
  node_graph_export["Graph export<br/>[export_graph.py]"]
  node_neo4j[("Neo4j graph")]
end

node_researcher(("Researcher"))

node_researcher -->|"runs analysis"| node_expression_parsing
node_expression_parsing -->|"maps identifiers"| node_gene_mapping
node_gene_mapping -->|"harmonizes cohorts"| node_clinical_labels
node_clinical_labels -->|"provides labels"| node_progression_discovery
node_crosswalk -->|"aligns samples"| node_clinical_labels
node_biopsy_policy -->|"selects biopsies"| node_progression_discovery
node_biopsy_policy -->|"selects biopsies"| node_task2
node_biopsy_policy -->|"selects biopsies"| node_task3
node_biopsy_policy -->|"selects biopsies"| node_mentor_export
node_progression_discovery -->|"supports gene groups"| node_task1
node_progression_discovery -->|"profiles genes"| node_task2
node_progression_discovery -->|"compares stages"| node_task3
node_task2 -->|"provides clusters"| node_task3
node_task2 -->|"supports enrichment"| node_task4
node_progression_discovery -->|"prioritizes candidates"| node_high_confidence
node_high_confidence -->|"tests matched refits"| node_matched_transitions
node_high_confidence -->|"tests robustness"| node_loso
node_high_confidence -->|"validates gene sets"| node_external_validation
node_progression_discovery -->|"supplies expression layer"| node_graph_builder
node_optimus_layer -->|"adds knowledge"| node_graph_builder
node_progression_edges -->|"adds progression links"| node_graph_builder
node_pathway_links -->|"adds pathway links"| node_graph_builder
node_graph_builder -->|"exports graph"| node_graph_export
node_graph_export -->|"supports import"| node_neo4j

click node_expression_parsing "https://github.com/nissankararaothanvitha/liver_graph/blob/main/parse_expression.py"
click node_gene_mapping "https://github.com/nissankararaothanvitha/liver_graph/blob/main/map_gene_ids.py"
click node_clinical_labels "https://github.com/nissankararaothanvitha/liver_graph/blob/main/normalize_clinical.py"
click node_crosswalk "https://github.com/nissankararaothanvitha/liver_graph/blob/main/build_crosswalk.py"
click node_biopsy_policy "https://github.com/nissankararaothanvitha/liver_graph/blob/main/biopsy_policy.py"
click node_progression_discovery "https://github.com/nissankararaothanvitha/liver_graph/blob/main/find_progression_genes.py"
click node_task1 "https://github.com/nissankararaothanvitha/liver_graph/blob/main/paper1_task1_groups.py"
click node_task2 "https://github.com/nissankararaothanvitha/liver_graph/blob/main/paper1_task2_trajectories.py"
click node_task3 "https://github.com/nissankararaothanvitha/liver_graph/blob/main/paper1_task3_transitions.py"
click node_task4 "https://github.com/nissankararaothanvitha/liver_graph/blob/main/paper1_task4_enrichment.py"
click node_mentor_export "https://github.com/nissankararaothanvitha/liver_graph/blob/main/export_for_mentor.py"
click node_high_confidence "https://github.com/nissankararaothanvitha/liver_graph/blob/main/scripts/high_confidence_genes.py"
click node_matched_transitions "https://github.com/nissankararaothanvitha/liver_graph/blob/main/scripts/powermatched_transitions.py"
click node_loso "https://github.com/nissankararaothanvitha/liver_graph/blob/main/scripts/loso_validation.py"
click node_external_validation "https://github.com/nissankararaothanvitha/liver_graph/tree/main/independent_validation/scripts"
click node_graph_builder "https://github.com/nissankararaothanvitha/liver_graph/blob/main/build_graph_all.py"
click node_optimus_layer "https://github.com/nissankararaothanvitha/liver_graph/blob/main/build_optimuskg_layer.py"
click node_progression_edges "https://github.com/nissankararaothanvitha/liver_graph/blob/main/build_progression_edges.py"
click node_pathway_links "https://github.com/nissankararaothanvitha/liver_graph/blob/main/scripts/build_pathway_nafld_links.py"
click node_graph_export "https://github.com/nissankararaothanvitha/liver_graph/blob/main/scripts/export_graph.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_expression_parsing,node_gene_mapping,node_clinical_labels,node_crosswalk,node_biopsy_policy toneBlue
class node_progression_discovery,node_task1,node_task2,node_task3,node_task4,node_mentor_export toneAmber
class node_high_confidence,node_matched_transitions,node_loso,node_external_validation toneMint
class node_graph_builder,node_optimus_layer,node_progression_edges,node_pathway_links,node_graph_export,node_neo4j toneRose
class node_researcher toneIndigo
```

## Components

### Cohort harmonization

- [Expression parsing](https://github.com/nissankararaothanvitha/liver_graph/blob/main/parse_expression.py): `parse_expression.py`
- [Gene ID mapping](https://github.com/nissankararaothanvitha/liver_graph/blob/main/map_gene_ids.py): `map_gene_ids.py`
- [Clinical labels](https://github.com/nissankararaothanvitha/liver_graph/blob/main/normalize_clinical.py): `normalize_clinical.py`
- [Sample crosswalk](https://github.com/nissankararaothanvitha/liver_graph/blob/main/build_crosswalk.py): `build_crosswalk.py`
- [Biopsy policy](https://github.com/nissankararaothanvitha/liver_graph/blob/main/biopsy_policy.py): `biopsy_policy.py`

### Transcriptomic analysis

- [Progression genes](https://github.com/nissankararaothanvitha/liver_graph/blob/main/find_progression_genes.py): `find_progression_genes.py`
- [Gene groups](https://github.com/nissankararaothanvitha/liver_graph/blob/main/paper1_task1_groups.py): `paper1_task1_groups.py`
- [Stage clusters](https://github.com/nissankararaothanvitha/liver_graph/blob/main/paper1_task2_trajectories.py): `paper1_task2_trajectories.py`
- [Stage transitions](https://github.com/nissankararaothanvitha/liver_graph/blob/main/paper1_task3_transitions.py): `paper1_task3_transitions.py`
- [Pathway enrichment](https://github.com/nissankararaothanvitha/liver_graph/blob/main/paper1_task4_enrichment.py): `paper1_task4_enrichment.py`
- [Patient summaries](https://github.com/nissankararaothanvitha/liver_graph/blob/main/export_for_mentor.py): `export_for_mentor.py`

### Prioritization and validation

- [Gene prioritization](https://github.com/nissankararaothanvitha/liver_graph/blob/main/scripts/high_confidence_genes.py): `scripts/high_confidence_genes.py`
- [Matched transitions](https://github.com/nissankararaothanvitha/liver_graph/blob/main/scripts/powermatched_transitions.py): `scripts/powermatched_transitions.py`
- [LOSO robustness](https://github.com/nissankararaothanvitha/liver_graph/blob/main/scripts/loso_validation.py): `scripts/loso_validation.py`
- [External validation](https://github.com/nissankararaothanvitha/liver_graph/tree/main/independent_validation/scripts): `independent_validation/scripts`

### Knowledge graph

- [Integrated graph](https://github.com/nissankararaothanvitha/liver_graph/blob/main/build_graph_all.py): `build_graph_all.py`
- [OptimusKG layer](https://github.com/nissankararaothanvitha/liver_graph/blob/main/build_optimuskg_layer.py): `build_optimuskg_layer.py`
- [Progression links](https://github.com/nissankararaothanvitha/liver_graph/blob/main/build_progression_edges.py): `build_progression_edges.py`
- [Pathway disease links](https://github.com/nissankararaothanvitha/liver_graph/blob/main/scripts/build_pathway_nafld_links.py): `scripts/build_pathway_nafld_links.py`
- [Graph export](https://github.com/nissankararaothanvitha/liver_graph/blob/main/scripts/export_graph.py): `scripts/export_graph.py`
- **Neo4j graph**

### Other components

- **Researcher**

## Connections

- Researcher → Expression parsing: runs analysis (evidence: `README.md`)
- Expression parsing → Gene ID mapping: maps identifiers (evidence: `README.md`)
- Gene ID mapping → Clinical labels: harmonizes cohorts (evidence: `README.md`)
- Clinical labels → Progression genes: provides labels (evidence: `README.md`)
- Sample crosswalk → Clinical labels: aligns samples (evidence: `README.md`)
- Biopsy policy → Progression genes: selects biopsies (evidence: `find_progression_genes.py`)
- Biopsy policy → Stage clusters: selects biopsies (evidence: `paper1_task2_trajectories.py`)
- Biopsy policy → Stage transitions: selects biopsies (evidence: `paper1_task3_transitions.py`)
- Biopsy policy → Patient summaries: selects biopsies (evidence: `export_for_mentor.py`)
- Progression genes → Gene groups: supports gene groups (evidence: `README.md`)
- Progression genes → Stage clusters: profiles genes (evidence: `README.md`)
- Progression genes → Stage transitions: compares stages (evidence: `README.md`)
- Stage clusters → Stage transitions: provides clusters (evidence: `paper1_task3_transitions.py`)
- Stage clusters → Pathway enrichment: supports enrichment (evidence: `README.md`)
- Progression genes → Gene prioritization: prioritizes candidates (evidence: `README.md`)
- Gene prioritization → Matched transitions: tests matched refits (evidence: `README.md`)
- Gene prioritization → LOSO robustness: tests robustness (evidence: `scripts/loso_validation.py`)
- Gene prioritization → External validation: validates gene sets (evidence: `README.md`)
- Progression genes → Integrated graph: supplies expression layer (evidence: `README.md`)
- OptimusKG layer → Integrated graph: adds knowledge (evidence: `README.md`)
- Progression links → Integrated graph: adds progression links (evidence: `README.md`)
- Pathway disease links → Integrated graph: adds pathway links (evidence: `README.md`)
- Integrated graph → Graph export: exports graph (evidence: `README.md`)
- Graph export → Neo4j graph: supports import (evidence: `README.md`)
