# rainingsherry/topogate architecture

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

## Overview

TopoGate is a research codebase for comparing graph-aware clustering methods on caller-supplied datasets. The principal workflow is to select a version and configuration, provide data, run a variant’s preprocessing and graph/model training, then inspect clustering metrics and audit artifacts. The repository also contains independent mechanism and validation studies. The tree and README establish the broader variant portfolio; sampled excerpts support only some internal call relationships, so uncertain wiring is omitted.

Main entry points: [`scripts/V11`](https://github.com/rainingsherry/topogate/tree/main/scripts/V11) (Version runners), [`scripts/ACCG`](https://github.com/rainingsherry/topogate/tree/main/scripts/ACCG) (ACCG runners), [`scripts/V26`](https://github.com/rainingsherry/topogate/tree/main/scripts/V26) (V26 runners), [`methods/DeepLearning/scMAE_family.py`](https://github.com/rainingsherry/topogate/blob/main/methods/DeepLearning/scMAE_family.py) (scMAE data prep)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs and backbone"]
  node_scmae["scMAE backbone<br/>[model.py]"]
  node_scmae_data["scMAE data prep<br/>[scMAE_family.py]"]
end

subgraph group_variants["TopoGate variants"]
  node_classic["Early gate variants"]
  node_v10["Reliable graph"]
  node_v11["V11 counterfactual"]
  node_v15["V15 counterfactual"]
  node_v17["V17 relation native"]
  node_v18_22["V18–V22 variants"]
  node_accg["ACCG constrained gate"]
  node_v26["V26 support oracle"]
end

subgraph group_studies["Studies and protocols"]
  node_mechanism["Mechanism studies"]
  node_validation["Validation studies"]
  node_corruption["Corruption studies"]
  node_consumer["Representation study"]
end

subgraph group_evaluation["Experiment evaluation"]
  node_runner["Version runners"]
  node_accg_runner["ACCG runners"]
  node_v26_runner["V26 runners"]
  node_results[("Curated results")]
end

node_researcher(("Researcher"))
node_dataset["Input dataset"]
node_output["Run outputs"]

node_researcher -->|"supplies"| node_dataset
node_researcher -->|"selects and runs"| node_runner
node_dataset -->|"loads and prepares"| node_scmae_data
node_scmae_data -->|"provides inputs"| node_scmae
node_runner -->|"runs variant"| node_v11
node_runner -.->|"runs variant"| node_v10
node_runner -.->|"runs variant"| node_v17
node_runner -.->|"runs variant"| node_v15
node_runner -.->|"runs variant"| node_v18_22
node_runner -.->|"runs variant"| node_classic
node_v11 -->|"uses backbone"| node_scmae
node_accg_runner -->|"runs protocol"| node_accg
node_v26_runner -->|"runs study"| node_v26
node_mechanism -.->|"reuses V21 primitives"| node_v18_22
node_accg -.->|"inherits matched protocol"| node_mechanism
node_researcher -.->|"runs preflight"| node_validation
node_researcher -.->|"runs study"| node_corruption
node_researcher -.->|"runs study"| node_consumer
node_runner -.->|"summarizes results"| node_results
node_accg_runner -.->|"writes artifacts"| node_output
node_v26_runner -.->|"writes summaries"| node_output

click node_scmae "https://github.com/rainingsherry/topogate/blob/main/methods/NeighborMix_scMAE/model.py"
click node_scmae_data "https://github.com/rainingsherry/topogate/blob/main/methods/DeepLearning/scMAE_family.py"
click node_classic "https://github.com/rainingsherry/topogate/tree/main/methods/TopoGate/learnable_gate"
click node_v10 "https://github.com/rainingsherry/topogate/tree/main/methods/TopoGate/v10_reliable_graph"
click node_v11 "https://github.com/rainingsherry/topogate/tree/main/methods/TopoGate/V11"
click node_v15 "https://github.com/rainingsherry/topogate/tree/main/methods/TopoGate/V15_counterfactual_gate"
click node_v17 "https://github.com/rainingsherry/topogate/tree/main/methods/TopoGate/V17_topology_native"
click node_v18_22 "https://github.com/rainingsherry/topogate/tree/main/methods/TopoGate/V18_scmae_latent_gate"
click node_accg "https://github.com/rainingsherry/topogate/tree/main/methods/TopoGate/ACCG_action_constrained_gate"
click node_v26 "https://github.com/rainingsherry/topogate/tree/main/methods/TopoGate/V26_support_oracle"
click node_mechanism "https://github.com/rainingsherry/topogate/tree/main/methods/TopoGate/V25_systematic_mechanism_study"
click node_validation "https://github.com/rainingsherry/topogate/tree/main/scripts/support_target_validation_probe"
click node_corruption "https://github.com/rainingsherry/topogate/tree/main/scripts/sparse_corruption_principle_probe"
click node_consumer "https://github.com/rainingsherry/topogate/tree/main/scripts/representation_consumer_probe"
click node_runner "https://github.com/rainingsherry/topogate/tree/main/scripts/V11"
click node_accg_runner "https://github.com/rainingsherry/topogate/tree/main/scripts/ACCG"
click node_v26_runner "https://github.com/rainingsherry/topogate/tree/main/scripts/V26"
click node_results "https://github.com/rainingsherry/topogate/tree/main/result/final_results"

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_scmae,node_scmae_data toneBlue
class node_classic,node_v10,node_v11,node_v15,node_v17,node_v18_22,node_accg,node_v26 toneAmber
class node_mechanism,node_validation,node_corruption,node_consumer toneMint
class node_runner,node_accg_runner,node_v26_runner,node_results toneRose
class node_researcher,node_dataset,node_output toneIndigo
```

## Components

### Inputs and backbone

- [scMAE backbone](https://github.com/rainingsherry/topogate/blob/main/methods/NeighborMix_scMAE/model.py): `methods/NeighborMix_scMAE/model.py`
- [scMAE data prep](https://github.com/rainingsherry/topogate/blob/main/methods/DeepLearning/scMAE_family.py): `methods/DeepLearning/scMAE_family.py`

### TopoGate variants

- [Early gate variants](https://github.com/rainingsherry/topogate/tree/main/methods/TopoGate/learnable_gate): `methods/TopoGate/learnable_gate`
- [Reliable graph](https://github.com/rainingsherry/topogate/tree/main/methods/TopoGate/v10_reliable_graph): `methods/TopoGate/v10_reliable_graph`
- [V11 counterfactual](https://github.com/rainingsherry/topogate/tree/main/methods/TopoGate/V11): `methods/TopoGate/V11`
- [V15 counterfactual](https://github.com/rainingsherry/topogate/tree/main/methods/TopoGate/V15_counterfactual_gate): `methods/TopoGate/V15_counterfactual_gate`
- [V17 relation native](https://github.com/rainingsherry/topogate/tree/main/methods/TopoGate/V17_topology_native): `methods/TopoGate/V17_topology_native`
- [V18–V22 variants](https://github.com/rainingsherry/topogate/tree/main/methods/TopoGate/V18_scmae_latent_gate): `methods/TopoGate/V18_scmae_latent_gate`
- [ACCG constrained gate](https://github.com/rainingsherry/topogate/tree/main/methods/TopoGate/ACCG_action_constrained_gate): `methods/TopoGate/ACCG_action_constrained_gate`
- [V26 support oracle](https://github.com/rainingsherry/topogate/tree/main/methods/TopoGate/V26_support_oracle): `methods/TopoGate/V26_support_oracle`

### Studies and protocols

- [Mechanism studies](https://github.com/rainingsherry/topogate/tree/main/methods/TopoGate/V25_systematic_mechanism_study): `methods/TopoGate/V25_systematic_mechanism_study`
- [Validation studies](https://github.com/rainingsherry/topogate/tree/main/scripts/support_target_validation_probe): `scripts/support_target_validation_probe`
- [Corruption studies](https://github.com/rainingsherry/topogate/tree/main/scripts/sparse_corruption_principle_probe): `scripts/sparse_corruption_principle_probe`
- [Representation study](https://github.com/rainingsherry/topogate/tree/main/scripts/representation_consumer_probe): `scripts/representation_consumer_probe`

### Experiment evaluation

- [Version runners](https://github.com/rainingsherry/topogate/tree/main/scripts/V11): `scripts/V11`
- [ACCG runners](https://github.com/rainingsherry/topogate/tree/main/scripts/ACCG): `scripts/ACCG`
- [V26 runners](https://github.com/rainingsherry/topogate/tree/main/scripts/V26): `scripts/V26`
- [Curated results](https://github.com/rainingsherry/topogate/tree/main/result/final_results): `result/final_results`

### Other components

- **Researcher**
- **Input dataset**
- **Run outputs**

## Connections

- Researcher → Input dataset: supplies
- Researcher → Version runners: selects and runs
- Input dataset → scMAE data prep: loads and prepares
- scMAE data prep → scMAE backbone: provides inputs
- Version runners → V11 counterfactual: runs variant
- Version runners → Reliable graph: runs variant
- Version runners → V17 relation native: runs variant
- Version runners → V15 counterfactual: runs variant
- Version runners → V18–V22 variants: runs variant
- Version runners → Early gate variants: runs variant
- V11 counterfactual → scMAE backbone: uses backbone
- ACCG runners → ACCG constrained gate: runs protocol
- V26 runners → V26 support oracle: runs study
- Mechanism studies → V18–V22 variants: reuses V21 primitives
- ACCG constrained gate → Mechanism studies: inherits matched protocol
- Researcher → Validation studies: runs preflight
- Researcher → Corruption studies: runs study
- Researcher → Representation study: runs study
- Version runners → Curated results: summarizes results
- ACCG runners → Run outputs: writes artifacts
- V26 runners → Run outputs: writes summaries