📖 Overview

Glio-Cartography is a research-grade computational platform for the spatial characterization of the glioblastoma (GBM) tumor microenvironment. It integrates spot-resolution spatial transcriptomics, single-cell RNA-seq (scRNA-seq) reference deconvolution, and a graph neural network (GNN) classifier into a single reproducible five-stage pipeline, producing publication-ready quantification of histological zone architecture and oncogenic pathway activity.

Scope

The current validated input path accepts 10x Genomics Visium output paired with a compatible sc/snRNA-seq reference. It returns exploratory per-spot cell-composition estimates, Ivy GAP-inspired transcriptional zone signatures, pathway-expression proxies, and a research-use PDF. These outputs are computational hypotheses, not histopathology, molecular-test, prognostic, or treatment results.

Intended Use

The pipeline is intended for hypothesis-generating research on archived, de-identified, or investigator-generated spatial transcriptomic data by qualified personnel operating under appropriate institutional oversight (see Data & Research Ethics).

Pipeline at a Glance

Data flow through five sequential, independently re-runnable stages:

Raw input (10x Visium + compatible sc/snRNA-seq reference)
        │
        ▼
[1] Preprocessing & QC  ──▶  [2] Deconvolution  ──▶  [3] GNN Zone Classification
                                                              │
                                                              ▼
                                            [5] Report Generation  ◀──  [4] Pathway Analysis

System Requirements

🚀 Quick Start

Get your first spatial GBM analysis running in under 10 minutes.

1. Download and Install

Download the Glio-Cartography installer for your operating system from the Downloads page. Run the installer and follow the on-screen instructions.

2. Activate your License

Open Glio-Cartography → Settings → License. Copy your Machine ID and request a license on this website. Your account will be active once approved by the admin.

3. Load your data

Click New Analysis, select your 10x Visium output directory, and add a compatible sc/snRNA-seq reference (.h5ad or 10x HDF5).

4. Run the pipeline

Configure QC thresholds, select Tangram or the documented fallback, and click Run Pipeline. The five-stage pipeline runs locally.

5. Export Report

Navigate to Report tab and click Export PDF. The publication-quality report includes all spatial maps, pathway scores, and zone classifications.

Installation

Glio-Cartography is a standalone desktop application. It bundles its own Python environment — no conda or pip required.

macOS

1. Download GlioCartography-mac.dmg
2. Open the DMG and drag Glio-Cartography to Applications
3. If macOS Gatekeeper blocks the app: System Settings → Privacy & Security → Open Anyway

Windows

1. Download and run GlioCartography-win.exe
2. Follow the installation wizard
3. Windows Defender SmartScreen: click More info → Run anyway

Linux (AppImage)

You can run and download the desktop app via terminal commands:

# 1. Fetch AppImage from website
wget https://gliocartography.com/download/linux -O GlioCartography.AppImage

# 2. Add execution permission
chmod +x GlioCartography.AppImage

# 3. Launch AppImage
./GlioCartography.AppImage

On some distributions you may need to install libfuse2 (e.g. sudo apt install libfuse2).

License Activation

Each license is tied to one Machine ID (a cryptographic fingerprint of your hardware). To activate:

1. Open Glio-Cartography
2. Go to Settings → License
3. Copy the displayed Machine ID
4. Request a license on this website, entering your Machine ID
5. Your account will be activated manually by the administrator
6. Once approved, copy the license key received and paste it in the License Key field, then click Activate

Stage 1 — Preprocessing

Loads and quality-controls both spatial (Visium) and single-cell (scRNA-seq) data.

Spatial QC Filters

• min_counts — minimum UMI counts per spot (default: adaptive MAD-based)
• min_genes — minimum detected genes per spot
• max_mito_pct — maximum mitochondrial gene percentage (default: median + 3×MAD)

scRNA-seq QC Filters

• Adaptive MT threshold: median + 3×MAD
• Doublet detection by count outliers
• Minimum 200 genes per cell

Supported Input Formats

• 10x Visium: spatial/ directory with filtered_feature_bc_matrix.h5
• scRNA-seq: 10x HDF5 .h5, AnnData .h5ad

Stage 2 — Deconvolution

Because each Visium spot (55 µm diameter) typically overlaps multiple cells, Stage 2 decomposes the mixed transcriptomic signal of every spot into a probability-weighted composition over reference cell types, using a paired scRNA-seq atlas as the compositional basis.

Methods

• Tangram — maps reference cell profiles to spatial spots using shared genes and annotated reference groups.
• NNLS comparison — provides an independent non-negative least-squares estimate used to report cross-method concordance.

Reference/query compatibility is essential. Low marker coverage or weak Tangram–NNLS concordance is reported as uncertainty and should limit downstream interpretation.

Figure 2.1: Deconvolution infographic showing spatial cellular mapping of astrocytes, microglia, oligodendrocytes, and neoplastic cell densities.

Cell Type Markers (configurable)

# configs/config.yaml
cell_type_markers:
  Tumor:         [TOP2A, MKI67, CDK4]
  Astrocyte:     [GFAP, AQP4, S100B]
  Microglia:     [IBA1, CX3CR1, P2RY12]
  Oligodendrocyte: [MBP, OLIG2, MOG]
  Endothelial:   [CD31, VWF, CLDN5]

Stage 3 — GNN Tumor Zone Classification

A graph neural network combines spatial and transcriptomic features to estimate five Ivy GAP-inspired transcriptional zone signatures. They are model-derived research labels and must not be presented as pathologist-confirmed histological regions:

• Pseudopalisading Necrosis — Hypoxic necrotic core
• Microvascular Proliferation (MVP) — Angiogenic region
• Cellular Tumor — Densely packed neoplastic cells
• Infiltrating Tumor — Tumor cells infiltrating normal brain
• Leading Edge — Peripheral invasion front

Graph Construction

Each spot is a graph node. Edges connect the k nearest spatial neighbors (default k=6, matching the Visium hexagonal lattice), weighted by a composite of physical proximity and transcriptional similarity:

w(i, j) = exp(−dist(i, j)² / 2σ²) · cos_sim(x_i, x_j)

where dist(i, j) is Euclidean distance in tissue coordinates, σ is a bandwidth set to the median nearest-neighbor distance, and cos_sim(x_i, x_j) is the cosine similarity between the (deconvolution-informed) expression vectors of spots i and j. This down-weights edges between spatially adjacent but transcriptionally dissimilar spots (e.g., across a sharp necrotic boundary).

Training & Evaluation

The network is optimized against computational cell-composition and signature-derived targets. Held-out errors measure internal consistency only. The current release does not contain a pathologist-labelled multi-section ground-truth cohort and therefore does not claim clinical zone-classification accuracy.

Figure 3.1: GNN-predicted microenvironment zones (Necrosis, MVP, Cellular Tumor, Infiltrating Edge) overlaid on H&E histology coordinates.

Figure 3.2: GraphSAGE classifier confusion matrix for histology validation sets.

Stage 4 — Pathway Analysis

Scores four oncogenic signaling pathways per spot using curated gene signatures:

• PI3K / AKT / mTOR
• MAPK / ERK
• JAK / STAT
• NFκB

For each pathway, a per-spot score is computed as the mean log-normalized expression of its member genes minus that of a size-matched, randomly sampled control gene set (an approach analogous to Seurat's AddModuleScore / scanpy's score_genes), then z-scaled within-sample to make scores comparable across pathways and sections.

Statistical Testing

Displayed pathway values are exploratory transcriptional signature scores. They do not measure phosphorylation, protein abundance, pathway flux, drug sensitivity, or clinical response.

Figure 4.1: Ligand-Receptor pathway communication heatmap scored across the predicted zones.

Stage 5 — Report Generation

Generates a multi-page PDF report including:

• Sample QC summary
• Spatial UMAP and tissue section overlays
• Deconvolution pie charts per zone
• GNN zone classification map
• Pathway activation heatmap and zonal contrast plots
• Top differentially expressed genes per zone
• Enrichment analysis results

Methodology & Validation

This section summarizes how pipeline outputs were validated and the scope of applicability of that validation, so that results can be interpreted with appropriate statistical caution.

Current Validation Evidence

The full pipeline has been exercised on independent public 10x Visium cohorts. Validation reports preprocessing counts, method fallbacks, Tangram–NNLS concordance, held-out internal error, and external atlas gene-signature correspondence. None of these substitutes for specimen-matched pathologist ground truth.

Reported Metrics

• Cross-method concordance — agreement between Tangram and NNLS cell-composition estimates.
• Held-out composition MSE — internal consistency for computational targets, not clinical accuracy.
• External atlas correspondence — gene-signature alignment with Ivy GAP references, not specimen-level histology validation.

Known Limitations

• Zone signatures are not pathologist-confirmed labels; Visium spots average several cells and blur biological boundaries.
• Deconvolution accuracy depends on reference/query compatibility; an scRNA-seq reference from a discordant tumor subtype or a different sequencing chemistry will bias composition estimates.
• The five-zone taxonomy, while widely used, is a simplification of a continuous biological gradient; borderline spots should be interpreted as such rather than as hard class boundaries.
• Pathway scores are transcriptional proxies, not direct measurements of protein activity or phosphorylation state.

Users publishing results derived from this pipeline are encouraged to report the software version, configuration file, and reference dataset used, per the citation guidance below.

Glossary

How to Cite

If Glio-Cartography contributes to a publication, thesis, or report, cite the software and the methods actually selected for that run (including Tangram and the graph architecture; see References).

Glio-Cartography [Computer software]. Version 1.0.
Spatial tumor microenvironment platform for glioblastoma.
Retrieved from https://gliocartography.com

BibTeX:

@software{gliocartography,
  title  = {Glio-Cartography: A Spatial Tumor Microenvironment
            Platform for Glioblastoma},
  author = {{Glio-Cartography Team}},
  year   = {2026},
  url    = {https://gliocartography.com},
  note   = {Software, Version 1.0}
}

References

1. Cable, D. M., Murray, E., Zou, L. S., et al. (2022). Robust decomposition of cell type mixtures in spatial transcriptomics. Nature Biotechnology, 40, 517–526.
2. Lee, D. D., & Seung, H. S. (1999). Learning the parts of objects by non-negative matrix factorization. Nature, 401, 788–791.
3. Korsunsky, I., Millard, N., Fan, J., et al. (2019). Fast, sensitive and accurate integration of single-cell data with Harmony. Nature Methods, 16, 1289–1296.
4. Hamilton, W. L., Ying, R., & Leskovec, J. (2017). Inductive Representation Learning on Large Graphs. Advances in Neural Information Processing Systems (NeurIPS), 30.
5. Veličković, P., Cucurull, G., Casanova, A., et al. (2018). Graph Attention Networks. International Conference on Learning Representations (ICLR).
6. Puchalski, R. B., Shah, N., Miller, J., et al. (2018). An anatomic transcriptional atlas of human glioblastoma. Science, 360(6389), 660–663.
7. Benjamini, Y., & Hochberg, Y. (1995). Controlling the False Discovery Rate: A Practical and Powerful Approach to Multiple Testing. Journal of the Royal Statistical Society: Series B, 57(1), 289–300.

Configuration

All pipeline parameters can be customized via configs/config.yaml:

spatial_qc:
  min_counts: 500
  min_genes: 200
  max_counts: 50000

scrna_qc:
  min_genes: 200
  max_genes: 6000

deconvolution:
  method: tangram
  n_components: 10

gnn:
  n_neighbors: 6
  n_epochs: 50
  hidden_dim: 128

pathways:
  pi3k_akt_mtor: [PIK3CA, AKT1, MTOR, PTEN, RPS6KB1]
  mapk_erk:      [BRAF, MAP2K1, MAPK1, MAPK3, RAS]
  jak_stat:      [JAK1, JAK2, STAT3, STAT5A, IL6]
  nfkb:          [RELA, NFKB1, IKBKB, TNFAIP3]

Supported Formats

API Reference & CLI Reference

Analyze spatial glioblastoma data programmatically using the built-in CLI command-line tool or integrated HTTP API endpoints.

CLI Commands

Run the 5-stage pipeline directly in your terminal or compute cluster (HPC):

# Run the entire pipeline with a custom configuration file
gliocarto run --config configs/config.yaml --input data/sample_001/

# Run specific stages (e.g., Stage 1 and Stage 2 only)
gliocarto run --stages 1,2 --config configs/config.yaml

# Verify a signed license key locally
gliocarto verify --key "GCARTO-XXXX-XXXX-XXXX" --machine "YOUR-MACHINE-ID"

HTTP API Endpoints

Data & Research Ethics

Glio-Cartography processes molecular data derived from human tissue. Responsibility for lawful and ethical data handling rests with the investigator and their institution, not with the software; the following notes describe what the platform does and does not do on your behalf.

What the Software Does

• Runs entirely on the desktop application's local compute — input spatial/scRNA-seq data files are not uploaded to Glio-Cartography servers at any point in the analysis pipeline.
• Does not perform patient re-identification, linkage, or any operation on data beyond the transcriptomic quantification and classification described in this document.
• Website accounts and license activation involve only researcher contact/registration details (see our Privacy Policy) — never tissue or sequencing data.

Investigator Responsibilities

• Obtain and document appropriate ethics committee / Institutional Review Board (IRB) approval, and informed consent where applicable, before analyzing patient-derived tissue.
• Ensure input data have been de-identified in accordance with your institution's policy and applicable law (e.g., HIPAA, GDPR, KVKK) prior to loading them into the pipeline.
• Verify local data residency and export-control requirements before transferring raw data files between sites or collaborators.

FAQ

My pipeline fails at Stage 2 (Deconvolution)

Ensure the sc/snRNA-seq reference has sufficient shared genes and representative cells per intended cell group. Rare groups may be retained in mapping but omitted from marker ranking when statistical replication is insufficient.

GNN zones look uniform / no contrast

Try increasing gnn.n_epochs in config and ensuring your spatial data has good QC coverage (>500 spots after filtering).

Pathway scores are all near zero

Check that your data is normalized (the pipeline auto-detects raw vs normalized). If manually pre-processed, ensure log1p normalization has been applied.

Can I use Glio-Cartography on an HPC cluster?

The Python backend stages can be run headlessly using the CLI: gliocarto run --config config.yaml --input data/. See the CLI reference in the next release notes.