# costalab/pilot architecture

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

- Interactive diagram: https://gitdiagram.com/costalab/pilot
- Repository: https://github.com/costalab/pilot

## Overview

PILOT is a Python toolkit for patient-level analysis of single-cell and pathomics data. Its principal workflow extracts sample and cell/structure information, computes sample-to-sample Wasserstein distances with optimal transport, then supports sample-level trajectory or subgroup analysis. Interpretation capabilities include identifying cell- and gene-level changes, differential expression, and plots. Source excerpts show the main analysis modules and plotting imports; broader workflow links are based on the README, so unsampled implementation details are not inferred.

Main entry points: [`pilotpy/tools/Trajectory.py`](https://github.com/costalab/pilot/blob/main/pilotpy/tools/Trajectory.py) (Sample trajectories), [`pilotpy/pl.py`](https://github.com/costalab/pilot/blob/main/pilotpy/pl.py) (Plotting API), [`pilotpy/tools/Cell_gene_selection.py`](https://github.com/costalab/pilot/blob/main/pilotpy/tools/Cell_gene_selection.py) (Cell and gene selection), [`pilotpy/tools/patients_sub_clustering.py`](https://github.com/costalab/pilot/blob/main/pilotpy/tools/patients_sub_clustering.py) (Patient subgroups)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_analysis["Sample analysis"]
  node_data_extract["Data extraction<br/>[Trajectory.py]"]
  node_ot_distances["OT distances<br/>[Trajectory.py]"]
  node_trajectories["Sample trajectories<br/>[Trajectory.py]"]
  node_subgroups["Patient subgroups"]
end

subgraph group_interpretation["Biological interpretation"]
  node_cell_gene_selection["Cell and gene selection"]
  node_gene_cluster_diff["Cluster differentiation"]
  node_model_fitting["Expression models"]
  node_pseudobulk_de["Pseudobulk DE"]
end

subgraph group_visualization["Plots and reports"]
  node_trajectory_plots["Trajectory plots<br/>[ploting.py]"]
  node_gene_selection_plots["Gene analysis plots"]
  node_curve_metrics["Curve metrics<br/>[curve_activity.py]"]
  node_reports["DE and enrichment plots"]
end

subgraph group_api["Python API"]
  node_api_tools["Analysis API<br/>[tl.py]"]
  node_api_plots["Plotting API<br/>[pl.py]"]
end

node_researcher(("Researcher"))
node_annotated_data["Annotated data"]

node_researcher -->|"provides"| node_annotated_data
node_researcher -->|"runs analysis"| node_api_tools
node_api_tools -->|"exposes tools"| node_data_extract
node_annotated_data -.->|"supplies input"| node_data_extract
node_data_extract -.->|"prepares samples"| node_ot_distances
node_ot_distances -->|"supports analysis"| node_trajectories
node_ot_distances -->|"supports analysis"| node_subgroups
node_trajectories -->|"interprets changes"| node_cell_gene_selection
node_subgroups -->|"ranks features"| node_cell_gene_selection
node_trajectories -.->|"compares clusters"| node_gene_cluster_diff
node_gene_cluster_diff -->|"fits models"| node_model_fitting
node_trajectories -->|"enables DE"| node_pseudobulk_de
node_api_plots -->|"exposes plots"| node_trajectory_plots
node_api_plots -->|"exposes plots"| node_gene_selection_plots
node_api_plots -->|"exposes metrics"| node_curve_metrics
node_api_plots -->|"exposes reports"| node_reports
node_trajectories -->|"visualizes results"| node_trajectory_plots
node_cell_gene_selection -.->|"visualizes results"| node_gene_selection_plots
node_pseudobulk_de -->|"produces results"| node_reports

click node_api_tools "https://github.com/costalab/pilot/blob/main/pilotpy/tl.py"
click node_api_plots "https://github.com/costalab/pilot/blob/main/pilotpy/pl.py"
click node_data_extract "https://github.com/costalab/pilot/blob/main/pilotpy/tools/Trajectory.py"
click node_ot_distances "https://github.com/costalab/pilot/blob/main/pilotpy/tools/Trajectory.py"
click node_trajectories "https://github.com/costalab/pilot/blob/main/pilotpy/tools/Trajectory.py"
click node_subgroups "https://github.com/costalab/pilot/blob/main/pilotpy/tools/patients_sub_clustering.py"
click node_cell_gene_selection "https://github.com/costalab/pilot/blob/main/pilotpy/tools/Cell_gene_selection.py"
click node_gene_cluster_diff "https://github.com/costalab/pilot/blob/main/pilotpy/tools/Gene_cluster_specific.py"
click node_model_fitting "https://github.com/costalab/pilot/blob/main/pilotpy/tools/Gene_cluster_specific_functions.py"
click node_pseudobulk_de "https://github.com/costalab/pilot/blob/main/pilotpy/plot/pseudobulk_DE_analysis.py"
click node_trajectory_plots "https://github.com/costalab/pilot/blob/main/pilotpy/plot/ploting.py"
click node_gene_selection_plots "https://github.com/costalab/pilot/blob/main/pilotpy/plot/gene_selection_analysis.py"
click node_curve_metrics "https://github.com/costalab/pilot/blob/main/pilotpy/plot/curve_activity.py"
click node_reports "https://github.com/costalab/pilot/blob/main/pilotpy/plot/pseudobulk_DE_analysis.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_data_extract,node_ot_distances,node_trajectories,node_subgroups toneBlue
class node_cell_gene_selection,node_gene_cluster_diff,node_model_fitting,node_pseudobulk_de toneAmber
class node_trajectory_plots,node_gene_selection_plots,node_curve_metrics,node_reports toneMint
class node_api_tools,node_api_plots toneRose
class node_researcher,node_annotated_data toneIndigo
```

## Components

### Sample analysis

- [Data extraction](https://github.com/costalab/pilot/blob/main/pilotpy/tools/Trajectory.py): `pilotpy/tools/Trajectory.py`
- [OT distances](https://github.com/costalab/pilot/blob/main/pilotpy/tools/Trajectory.py): `pilotpy/tools/Trajectory.py`
- [Sample trajectories](https://github.com/costalab/pilot/blob/main/pilotpy/tools/Trajectory.py): `pilotpy/tools/Trajectory.py`
- [Patient subgroups](https://github.com/costalab/pilot/blob/main/pilotpy/tools/patients_sub_clustering.py): `pilotpy/tools/patients_sub_clustering.py`

### Biological interpretation

- [Cell and gene selection](https://github.com/costalab/pilot/blob/main/pilotpy/tools/Cell_gene_selection.py): `pilotpy/tools/Cell_gene_selection.py`
- [Cluster differentiation](https://github.com/costalab/pilot/blob/main/pilotpy/tools/Gene_cluster_specific.py): `pilotpy/tools/Gene_cluster_specific.py`
- [Expression models](https://github.com/costalab/pilot/blob/main/pilotpy/tools/Gene_cluster_specific_functions.py): `pilotpy/tools/Gene_cluster_specific_functions.py`
- [Pseudobulk DE](https://github.com/costalab/pilot/blob/main/pilotpy/plot/pseudobulk_DE_analysis.py): `pilotpy/plot/pseudobulk_DE_analysis.py`

### Plots and reports

- [Trajectory plots](https://github.com/costalab/pilot/blob/main/pilotpy/plot/ploting.py): `pilotpy/plot/ploting.py`
- [Gene analysis plots](https://github.com/costalab/pilot/blob/main/pilotpy/plot/gene_selection_analysis.py): `pilotpy/plot/gene_selection_analysis.py`
- [Curve metrics](https://github.com/costalab/pilot/blob/main/pilotpy/plot/curve_activity.py): `pilotpy/plot/curve_activity.py`
- [DE and enrichment plots](https://github.com/costalab/pilot/blob/main/pilotpy/plot/pseudobulk_DE_analysis.py): `pilotpy/plot/pseudobulk_DE_analysis.py`

### Python API

- [Analysis API](https://github.com/costalab/pilot/blob/main/pilotpy/tl.py): `pilotpy/tl.py`
- [Plotting API](https://github.com/costalab/pilot/blob/main/pilotpy/pl.py): `pilotpy/pl.py`

### Other components

- **Researcher**
- **Annotated data**

## Connections

- Researcher → Annotated data: provides (evidence: `README.md`)
- Researcher → Analysis API: runs analysis (evidence: `README.md`)
- Analysis API → Data extraction: exposes tools (evidence: `pilotpy/tl.py`)
- Annotated data → Data extraction: supplies input
- Data extraction → OT distances: prepares samples (evidence: `pilotpy/tools/Trajectory.py`)
- OT distances → Sample trajectories: supports analysis (evidence: `README.md`)
- OT distances → Patient subgroups: supports analysis (evidence: `README.md`)
- Sample trajectories → Cell and gene selection: interprets changes (evidence: `README.md`)
- Patient subgroups → Cell and gene selection: ranks features (evidence: `README.md`)
- Sample trajectories → Cluster differentiation: compares clusters (evidence: `pilotpy/tools/Trajectory.py`)
- Cluster differentiation → Expression models: fits models (evidence: `pilotpy/tools/Gene_cluster_specific.py`)
- Sample trajectories → Pseudobulk DE: enables DE (evidence: `README.md`)
- Plotting API → Trajectory plots: exposes plots (evidence: `pilotpy/pl.py`)
- Plotting API → Gene analysis plots: exposes plots (evidence: `pilotpy/pl.py`)
- Plotting API → Curve metrics: exposes metrics
- Plotting API → DE and enrichment plots: exposes reports
- Sample trajectories → Trajectory plots: visualizes results (evidence: `pilotpy/tools/Trajectory.py`)
- Cell and gene selection → Gene analysis plots: visualizes results
- Pseudobulk DE → DE and enrichment plots: produces results (evidence: `pilotpy/plot/pseudobulk_DE_analysis.py`)
