Skip to content

Quickstart

Five commands from pip install to a working atlas served on localhost:18901, using the public 10X Genomics PBMC 3K dataset as the input. Total wall-clock: ~3 minutes the first time, ~30 seconds on rebuilds.

For a longer narrated walkthrough with explanations between each step, see the PBMC 3K recipe.

Starting from Seurat instead?

If your project lives as a .rds (Seurat object), skip ahead to Recipes → From a Seurat object. The five-command shape is identical — STELLAR auto-converts the .rds on first ingest via R + SeuratDisk.

Prerequisites

  • Python 3.11+ (3.12 recommended)
  • A local clone of the STELLAR repo if you want the examples/pbmc_3k/ bootstrap script (or you can substitute any other h5ad)

1. Install

pip install 'stellar-atlas[dev]' scanpy

The [dev] extra pulls in pytest + httpx for the example's bootstrap.py; plain scanpy brings the PBMC 3K loader.

Just want the core?

A bare pip install stellar-atlas is enough to serve any h5ad you already have. The extras above are only for fetching the PBMC 3K example data.

2. Build the example h5ad

python examples/pbmc_3k/bootstrap.py

Fetches the 10X PBMC 3K dataset via scanpy, runs the standard tutorial preprocessing (HVGs, leiden clustering, UMAP) and writes data/raw/pbmc_3k.h5ad. ~30 s, ~6 MB on disk.

3. Ingest

stellar ingest --config examples/pbmc_3k/stellar.yaml

Reads the h5ad and builds:

  • data/lance/<matrix>.lance/ — gene-major LanceDB store (one per entry in input.matrices; the PBMC example uses just primary.lance)
  • data/lance/<matrix>_cells.lance/ — sibling row_idx ↔ cell_id catalog
  • data/parquet/ — cells.parquet, genes.parquet, donors.parquet, plus one parquet per enabled module
  • data/atlas.duckdb — single embedded analytical store, bulk-loaded from every parquet under data/parquet/

The step is idempotent — re-running drops and recreates the stores.

Before serving, sanity-check the build:

stellar doctor --config examples/pbmc_3k/stellar.yaml

A clean atlas prints:

stellar doctor: 0 issues — your project is healthy.

doctor catches missing inputs, typo'd cohort columns, stale builds, and missing module source files. Exit code 0 = no errors; 1 = at least one. See Troubleshooting for what each diagnostic means.

5. Serve

stellar serve --config examples/pbmc_3k/stellar.yaml

Starts uvicorn on 127.0.0.1:18901. The pre-built SPA is mounted at /pbmc_3k/ (the base_url from stellar.yaml); the API lives under /api/.

6. Hit it

curl -s http://localhost:18901/api/config | python -m json.tool

You should see your project's title, branding colors, the matrix descriptors, and an empty modules block (the PBMC 3K example has no optional modules enabled). Pop open http://localhost:18901/pbmc_3k/ in a browser to see the UMAP.

What stellar --help looks like

stellar <command> [options]

Commands:
  init <slug>      Scaffold a new project (writes stellar.yaml + dirs)
  ingest           Build LanceDB + DuckDB stores from raw inputs
  serve            Run uvicorn against the configured project
  build-frontend   Build the React SPA with project branding
  deploy           rsync to the configured deploy target + emit nginx/systemd
  doctor           Validate stellar.yaml against the data directory

Common options:
  --config PATH    Path to stellar.yaml (default: ./stellar.yaml)
  --version        Print version and exit
  -h, --help       Show this help

Full per-command reference at CLI.

When something goes wrong

  • stellar doctor is the first place to look — it surfaces the vast majority of "why did this fail" problems with a one-line diagnostic.
  • Specific symptoms → fixes: Troubleshooting.
  • Conceptual questions ("does the copilot send my data to Anthropic?", "why LanceDB + DuckDB?"): FAQ.

Next

  • Enable an analysis module: read its page under Modules, add it to stellar.yaml, re-run stellar ingest.
  • Wire up your own atlas: stellar init my_atlas scaffolds a fresh project. Then edit stellar.yaml against the configuration reference.
  • Deploy behind nginx: see Deploy.