# gifford-lab/prescient architecture

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

- Interactive diagram: https://gitdiagram.com/gifford-lab/prescient
- Repository: https://github.com/gifford-lab/prescient

## Overview

PRESCIENT is a generative model for single-cell time-series. The principal workflow prepares expression data, trains a stochastic neural model, then simulates trajectories; perturbation analysis compares simulations from altered and unaltered expression. The graph also retains documented legacy fate/interpolation analysis modules. Training and simulation relationships are supported by excerpts or the SOURCE INDEX; the README gives only a high-level product description, so unsampled capabilities and connections are not expanded.

Main entry points: [`prescient/train/model.py`](https://github.com/gifford-lab/prescient/blob/master/prescient/train/model.py) (Generator and loss), [`prescient/__main__.py`](https://github.com/gifford-lab/prescient/blob/master/prescient/__main__.py) (Command entry), [`prescient/commands/perturbation_analysis.py`](https://github.com/gifford-lab/prescient/blob/master/prescient/commands/perturbation_analysis.py) (Perturbation analysis), [`prescient/train/run.py`](https://github.com/gifford-lab/prescient/blob/master/prescient/train/run.py) (Training loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_prep["Data processor<br/>[process_data.py]"]
  node_prepared["Prepared data"]
end

subgraph group_model["Model training"]
  node_train_cmd["Training command<br/>[train_model.py]"]
  node_train_run["Training loop<br/>[run.py]"]
  node_model_core["Generator and loss<br/>[model.py]"]
  node_train_util["Training utilities<br/>[util.py]"]
  node_checkpoint["Model checkpoints"]
end

subgraph group_analysis["Simulation analysis"]
  node_sim_cmd["Trajectory command"]
  node_simulator["Trajectory simulator<br/>[sim.py]"]
  node_perturb_cmd["Perturbation analysis"]
  node_perturb_transform["Gene perturbation<br/>[pert.py]"]
end

subgraph group_legacy["Legacy analysis"]
  node_fate_legacy["Fate analysis<br/>[veres.py]"]
  node_interpolation_legacy["Interpolation analysis<br/>[weinreb.py]"]
end

node_user(("Researcher"))
node_cli["Command entry<br/>[__main__.py]"]

node_user -->|"runs commands"| node_cli
node_cli -->|"dispatches to"| node_prep
node_cli -->|"dispatches to"| node_train_cmd
node_cli -->|"dispatches to"| node_sim_cmd
node_cli -->|"dispatches to"| node_perturb_cmd
node_user -->|"supplies expression"| node_prep
node_prep -->|"saves data"| node_prepared
node_user -->|"provides data"| node_train_cmd
node_train_cmd -->|"starts training"| node_train_run
node_train_run -->|"optimizes"| node_model_core
node_train_run -->|"uses helpers"| node_train_util
node_train_run -->|"saves weights"| node_checkpoint
node_user -->|"requests simulation"| node_sim_cmd
node_sim_cmd -->|"loads model"| node_model_core
node_sim_cmd -->|"invokes"| node_simulator
node_simulator -->|"steps model"| node_model_core
node_user -->|"requests comparison"| node_perturb_cmd
node_perturb_cmd -->|"transforms expression"| node_perturb_transform
node_perturb_cmd -->|"loads model"| node_model_core
node_perturb_cmd -->|"runs both conditions"| node_simulator
node_user -->|"runs legacy analysis"| node_fate_legacy
node_user -->|"runs legacy analysis"| node_interpolation_legacy
node_fate_legacy -->|"uses training package"| node_model_core
node_interpolation_legacy -->|"uses training package"| node_model_core

click node_cli "https://github.com/gifford-lab/prescient/blob/master/prescient/__main__.py"
click node_prep "https://github.com/gifford-lab/prescient/blob/master/prescient/commands/process_data.py"
click node_train_cmd "https://github.com/gifford-lab/prescient/blob/master/prescient/commands/train_model.py"
click node_train_run "https://github.com/gifford-lab/prescient/blob/master/prescient/train/run.py"
click node_model_core "https://github.com/gifford-lab/prescient/blob/master/prescient/train/model.py"
click node_train_util "https://github.com/gifford-lab/prescient/blob/master/prescient/train/util.py"
click node_sim_cmd "https://github.com/gifford-lab/prescient/blob/master/prescient/commands/simulate_trajectories.py"
click node_simulator "https://github.com/gifford-lab/prescient/blob/master/prescient/simulate/sim.py"
click node_perturb_cmd "https://github.com/gifford-lab/prescient/blob/master/prescient/commands/perturbation_analysis.py"
click node_perturb_transform "https://github.com/gifford-lab/prescient/blob/master/prescient/perturb/pert.py"
click node_fate_legacy "https://github.com/gifford-lab/prescient/blob/master/depr/veres.py"
click node_interpolation_legacy "https://github.com/gifford-lab/prescient/blob/master/depr/weinreb.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_prep,node_prepared toneBlue
class node_train_cmd,node_train_run,node_model_core,node_train_util,node_checkpoint toneAmber
class node_sim_cmd,node_simulator,node_perturb_cmd,node_perturb_transform toneMint
class node_fate_legacy,node_interpolation_legacy toneRose
class node_user toneIndigo
class node_cli toneTeal
```

## Components

### Data preparation

- [Data processor](https://github.com/gifford-lab/prescient/blob/master/prescient/commands/process_data.py): `prescient/commands/process_data.py`
- **Prepared data**

### Model training

- [Training command](https://github.com/gifford-lab/prescient/blob/master/prescient/commands/train_model.py): `prescient/commands/train_model.py`
- [Training loop](https://github.com/gifford-lab/prescient/blob/master/prescient/train/run.py): `prescient/train/run.py`
- [Generator and loss](https://github.com/gifford-lab/prescient/blob/master/prescient/train/model.py): `prescient/train/model.py`
- [Training utilities](https://github.com/gifford-lab/prescient/blob/master/prescient/train/util.py): `prescient/train/util.py`
- **Model checkpoints**

### Simulation analysis

- [Trajectory command](https://github.com/gifford-lab/prescient/blob/master/prescient/commands/simulate_trajectories.py): `prescient/commands/simulate_trajectories.py`
- [Trajectory simulator](https://github.com/gifford-lab/prescient/blob/master/prescient/simulate/sim.py): `prescient/simulate/sim.py`
- [Perturbation analysis](https://github.com/gifford-lab/prescient/blob/master/prescient/commands/perturbation_analysis.py): `prescient/commands/perturbation_analysis.py`
- [Gene perturbation](https://github.com/gifford-lab/prescient/blob/master/prescient/perturb/pert.py): `prescient/perturb/pert.py`

### Legacy analysis

- [Fate analysis](https://github.com/gifford-lab/prescient/blob/master/depr/veres.py): `depr/veres.py`
- [Interpolation analysis](https://github.com/gifford-lab/prescient/blob/master/depr/weinreb.py): `depr/weinreb.py`

### Other components

- **Researcher**
- [Command entry](https://github.com/gifford-lab/prescient/blob/master/prescient/__main__.py): `prescient/__main__.py`

## Connections

- Researcher → Command entry: runs commands (evidence: `prescient/__main__.py`)
- Command entry → Data processor: dispatches to
- Command entry → Training command: dispatches to
- Command entry → Trajectory command: dispatches to
- Command entry → Perturbation analysis: dispatches to
- Researcher → Data processor: supplies expression (evidence: `prescient/commands/process_data.py`)
- Data processor → Prepared data: saves data (evidence: `prescient/commands/process_data.py`)
- Researcher → Training command: provides data (evidence: `prescient/commands/train_model.py`)
- Training command → Training loop: starts training (evidence: `prescient/commands/train_model.py`)
- Training loop → Generator and loss: optimizes (evidence: `prescient/train/run.py`)
- Training loop → Training utilities: uses helpers (evidence: `prescient/train/run.py`)
- Training loop → Model checkpoints: saves weights (evidence: `prescient/train/run.py`)
- Researcher → Trajectory command: requests simulation (evidence: `prescient/commands/simulate_trajectories.py`)
- Trajectory command → Generator and loss: loads model (evidence: `prescient/commands/simulate_trajectories.py`)
- Trajectory command → Trajectory simulator: invokes (evidence: `prescient/commands/simulate_trajectories.py`)
- Trajectory simulator → Generator and loss: steps model (evidence: `prescient/simulate/sim.py`)
- Researcher → Perturbation analysis: requests comparison (evidence: `prescient/commands/perturbation_analysis.py`)
- Perturbation analysis → Gene perturbation: transforms expression (evidence: `prescient/commands/perturbation_analysis.py`)
- Perturbation analysis → Generator and loss: loads model (evidence: `prescient/commands/perturbation_analysis.py`)
- Perturbation analysis → Trajectory simulator: runs both conditions (evidence: `prescient/commands/perturbation_analysis.py`)
- Researcher → Fate analysis: runs legacy analysis (evidence: `depr/veres.py`)
- Researcher → Interpolation analysis: runs legacy analysis (evidence: `depr/weinreb.py`)
- Fate analysis → Generator and loss: uses training package (evidence: `depr/veres.py`)
- Interpolation analysis → Generator and loss: uses training package (evidence: `depr/weinreb.py`)
