Configuration reference¶

Every project-specific choice — paths, cohort vocabulary, enabled modules, branding, deploy target — lives in a single stellar.yaml file at the project root. The schema is pydantic, which means:

Unknown keys raise. A typo like modues: fails at startup with a precise pointer instead of silently being ignored.
Paths stay relative. Resolution happens at runtime against the directory containing stellar.yaml, so a project can move.
Module sub-blocks are open. The core only reads enabled; module-specific keys (e.g. source_dir) are forwarded to the module as-is.

This page is auto-generated from the pydantic models in stellar/config.py — if you change a model, the docs change with it.

Minimal example¶

The smallest valid stellar.yaml: a project identity, one matrix, a cohort that points at the obs columns, no modules enabled.

project:
  slug: my_atlas
  title: "My atlas"

input:
  matrices:
    - name: primary
      path: data/raw/my.h5ad
      role: primary

cohort:
  cell_type_column: cell_type
  condition_column: condition
  donor_column:     donor_id
  umap:
    obsm_key: X_umap

Full example¶

Every field, every module enabled — the kitchen-sink template.

project:
  slug: my_atlas
  title: "My atlas — snRNA-seq"
  description: "Integrated single-nucleus atlas of human cortex."
  base_url: "/my_atlas/"
  lab:
    name: "My Lab"
    url:  "https://example.edu/my-lab"

input:
  matrices:
    - name: primary
      path: data/raw/my_hvg.h5ad
      role: primary
      layer: null              # null → use .X; or e.g. "log1p"
    - name: wide
      path: data/raw/my_wide.h5ad
      role: wide

cohort:
  cell_type_column:    cell_type
  cell_subtype_column: cell_subtype
  condition_column:    condition
  condition_remap:
    "NCI":         Control
    "No Dementia": Control
  condition_order: [Control, Mild, Severe]
  exclude_conditions: [Other]
  donor_column: donor_id
  sample_column: sample_id
  umap:
    obsm_key: X_umap        # or null + x_col/y_col
    x_col:    null
    y_col:    null

modules:
  de:
    enabled: true
    source_dir: data/external/de
  hdwgcna:
    enabled: true
    source_dir: data/external/hdwgcna
  cellchat:
    enabled: true
    source_dir: data/external/cellchat
  milo:
    enabled: true
    source_dir: data/external/milo
  enrichment:
    enabled: true
  copilot:
    enabled: true
    anthropic_api_key_env: ANTHROPIC_API_KEY
    literature:
      enabled: true
      ncbi_api_key_env: NCBI_API_KEY
      # scope.diseases is the project-configurable disease focus
      # — see modules/copilot.md for the full options.
      scope:
        diseases:   []
        techniques: [single-cell, snRNA-seq, scRNA-seq, single-nucleus]
        min_year:   2018

branding:
  primary_color: "#0F766E"
  logo: assets/logo.svg

deploy:
  target_dir: /var/www/html/my_atlas
  url: "https://example.edu/my_atlas/"

Top-level — `StellarConfig`¶

stellar.config.StellarConfig ¶

Bases: _Strict

The full schema for stellar.yaml.

Minimal YAML

project:
  slug: my_atlas
  title: "My atlas"
input:
  matrices:
    - { name: primary, path: data/raw/my.h5ad, role: primary }
cohort:
  cell_type_column: cell_type
  condition_column: condition
  donor_column:     donor_id

`project`¶

stellar.config.Project ¶

Bases: _Strict

Top-level identity. slug is the only required field — used in URLs, dir names, and the wheel-level project key.

Minimal YAML

project:
  slug: my_atlas
  title: "My atlas"

Full YAML

project:
  slug: my_atlas
  title: "My atlas — snRNA-seq"
  description: "Integrated single-nucleus atlas of human cortex."
  base_url: "/my_atlas/"
  lab:
    name: "My Lab"
    url:  "https://example.edu/my-lab"

`project.lab`¶

stellar.config.Lab ¶

Bases: _Strict

`input`¶

stellar.config.Input ¶

Bases: _Strict

Top-level input: block — declares the source matrices.

Minimal YAML

input:
  matrices:
    - { name: primary, path: data/raw/my.h5ad, role: primary }

Full YAML (multiple matrices)

input:
  matrices:
    - name: primary
      path: data/raw/my_hvg.h5ad
      role: primary
      layer: null
    - name: wide
      path: data/raw/my_wide.h5ad
      role: wide
      layer: counts

`input.matrices[*]` — `MatrixInput`¶

stellar.config.MatrixInput ¶

Bases: _Strict

One expression matrix referenced from input.matrices.

Attributes:

Name	Type	Description
`name`	`str`	Slug used as the Lance table name and exposed in the API for per-matrix gene lookups (e.g. `"5k"`, `"25k"`, `"hvg"`).
`path`	`Path`	Path to the `.h5ad` file, relative to the project root.
`role`	`{'primary', 'wide'}`	`primary` matrices are used by default (smallest set with the broadest panel coverage); `wide` matrices serve as fallbacks when the user queries a gene that's not in the primary.
`layer`	`str \| None`	Optional AnnData layer to read. `None` uses `.X`.

`cohort`¶

stellar.config.Cohort ¶

Bases: _Strict

How to interpret adata.obs for this project.

Every field is a column name in the source h5ad's obs table. The project doesn't have to rename anything upstream — STELLAR just needs to know which column means what.

Attributes:

Name	Type	Description
`cell_type_column`	`str`	Major cell-type label (e.g. `cell_type` / `celltype` / `broad_label`).
`cell_subtype_column`	`str \| None`	Finer-grained label, if present. Powers the lasso-to-subtype drill-in. Set `None` to disable subtype coloring.
`condition_column`	`str`	Disease / treatment / state label (e.g. `condition`).
`condition_remap`	`dict[str, str]`	Optional canonicalisation — keys are raw values in the source column, values are the names to surface (e.g. `{"NCI": "Control", "Dementia": "AD"}`).
`condition_order`	`list[str] \| None`	Display order for the (post-remap) conditions. `None` falls back to alphabetical.
`exclude_conditions`	`list[str]`	Raw condition values to drop before any analysis runs (e.g. `["DSAD", "PD"]` for an AD-only atlas).
`donor_column`	`str`	Donor / sample-source identifier.
`sample_column`	`str \| None`	Optional finer sample-level identifier.
`umap`	`UMAPSpec`	How to find the UMAP coordinates.

Minimal YAML

cohort:
  cell_type_column: cell_type
  condition_column: condition
  donor_column:     donor_id

Full YAML

cohort:
  cell_type_column:    cell_type
  cell_subtype_column: cell_subtype
  condition_column:    condition
  condition_remap:
    "NCI":         Control
    "No Dementia": Control
  condition_order: [Control, Mild, Severe]
  exclude_conditions: [Other]
  donor_column: donor_id
  sample_column: sample_id
  umap:
    obsm_key: X_umap

`cohort.umap` — `UMAPSpec`¶

stellar.config.UMAPSpec ¶

Bases: _Strict

How to find UMAP coordinates inside the h5ad.

Use obsm_key for the conventional adata.obsm["X_umap"], or leave it None and set x_col / y_col to read coordinates that already live as columns in adata.obs.

From obsm (default)

cohort:
  umap:
    obsm_key: X_umap

From explicit obs columns

cohort:
  umap:
    obsm_key: null
    x_col: umap_1
    y_col: umap_2

`modules`¶

A mapping from module key (e.g. de, hdwgcna) to a ModuleConfig block. The core only reads enabled; everything else is forwarded to the module as-is — see the per-module pages under Modules for each one's keys.

`modules.<name>` — `ModuleConfig`¶

stellar.config.ModuleConfig ¶

Bases: BaseModel

Per-module config block. The core only reads enabled; everything else is forwarded to the module as-is so each module owns its own schema.

Minimal YAML (all modules off)

modules:
  de:         { enabled: false }
  hdwgcna:    { enabled: false }
  cellchat:   { enabled: false }
  milo:       { enabled: false }
  enrichment: { enabled: false }
  copilot:    { enabled: false }

Full YAML (DE + hdWGCNA enabled)

modules:
  de:
    enabled: true
    source_dir: data/external/de
  hdwgcna:
    enabled: true
    source_dir: data/external/hdwgcna

`branding`¶

stellar.config.Branding ¶

Bases: _Strict

Minimal YAML

branding:
  primary_color: "#0F766E"

Full YAML

branding:
  primary_color: "#0F766E"
  logo: assets/logo.svg

`deploy`¶

stellar.config.Deploy ¶

Bases: _Strict

Minimal YAML

deploy: {}

Full YAML

deploy:
  target_dir: /var/www/html/my_atlas
  url: "https://example.edu/my_atlas/"

Loading a config in code¶

from stellar.config import load_config

cfg = load_config("stellar.yaml")
print(cfg.project.title)
print(cfg.enabled_modules())   # -> ['de', 'hdwgcna']

stellar.config.load_config ¶

load_config(path: str | Path) -> StellarConfig

Parse path as YAML and validate against :class:StellarConfig.

Raises:

Type	Description
`FileNotFoundError`	If `path` doesn't exist.
`ValidationError`	On any schema violation. The error message points at the exact bad key + value (e.g. `cohort.umap.obsm_key: input should be a valid string`).

Configuration reference¶

Minimal example¶

Full example¶

Top-level — StellarConfig¶

stellar.config.StellarConfig ¶

project¶

stellar.config.Project ¶

project.lab¶

stellar.config.Lab ¶

input¶

stellar.config.Input ¶

input.matrices[*] — MatrixInput¶

stellar.config.MatrixInput ¶

cohort¶

stellar.config.Cohort ¶

cohort.umap — UMAPSpec¶

stellar.config.UMAPSpec ¶

modules¶

modules.<name> — ModuleConfig¶

stellar.config.ModuleConfig ¶

branding¶

stellar.config.Branding ¶

deploy¶

stellar.config.Deploy ¶

Loading a config in code¶

stellar.config.load_config ¶

Top-level — `StellarConfig`¶

`project`¶

`project.lab`¶

`input`¶

`input.matrices[*]` — `MatrixInput`¶

`cohort`¶

`cohort.umap` — `UMAPSpec`¶

`modules`¶

`modules.<name>` — `ModuleConfig`¶

`branding`¶

`deploy`¶