Skip to content

Making changes ​

Edit the dataset YAML to change samples, annotations or display settings, and site.yaml to change the gallery. Rerun spatialscape build <yaml> after a dataset edit. Changes to display names and palettes update metadata; changes to annotation mappings or input data rebuild the affected samples.

In the table below, metadata only means that the sample arrays are reused. The build still writes the dataset-level files, renders thumbnails and validates the bundle.

I want toEditThen run
Rename the dataset, change its descriptionname: / description:build (metadata only)
Choose the gene shown on opendefault_gene: SNAP25build (metadata only)
Open on an annotation insteaddefault_color: { field: domain }build (metadata only)
Name an annotation properly ("Layer", not "layer_guess_reordered_short")name: on its entry under fields:build (metadata only)
Compare conditions side by side in the viewermeta: { condition: stress } on each sample (or { column: condition }), optionally meta: at the top for names and orderbuild (metadata only for typed values; rebuilds affected samples for a column)
Show fewer / other annotationsthe fields: mapping on the sample entry: delete or uncomment linesbuild (rebuilds those samples)
Use my paper's colorspalette: colors.json plus palette_key: on the fieldbuild (metadata only)
Fix the order of categoriescategories: [L1, L2, …] on the fieldbuild (rebuilds the samples that carry it)
Merge spellings (AI and IA)aliases: { AI: IA } on the fieldbuild (rebuilds the samples that carry it)
Put QC metrics in one unit across platforms{ column: expr_chrM_ratio, scale: 100 } in the mappingbuild
Change which section is the thumbnailthumbnail_sample: vis_151673build (metadata only)
Space the sections outlayout: { gutter_fraction: 0.3 }build (metadata only)
Re-export one samplefix the file, keep the yamlbuild (rebuilds that sample)
Add a sampleadd it to samples:, or let the glob find itbuild (builds the new one)
Remove a sampledelete its entrybuild (deletes its folder)
Use another assay from an R objectassay: counts on the entrybuild (converts again, rebuilds)
Add a dataset to the gallerya config: line in site.yamlspatialscape site build site.yaml
Add a paper link, tags or a "coming soon" cardpaper:, tags:, or an id: + name: card in site.yamlsite build
Add a navigation bar above the viewernav: in site.yamlsite build

Run spatialscape build <yaml> --dry-run to list which samples would be built, reused or removed and why.

The same yaml, before and after ​

The following configuration was generated by spatialscape init for the DLPFC example. Some comments have been omitted:

yaml
id: visium-human-dlpfc
name: "Human DLPFC, Visium (Maynard et al. 2021)"
default_color: { field: domain }
layout: { mode: grid }
fields:
  - { id: domain, name: Spatial domain, type: categorical }
  - { id: total_counts, name: Total counts, type: continuous }
  - { id: detected_genes, name: Detected genes, type: continuous }
  - { id: mito_percent, name: Mito %, type: continuous }
samples:
  - path: raw/spe_dlpfc.rds                      # SpatialExperiment, 12 samples: 151507, 151508, ... (one sample per sample_id)
    platform: visium
    assay: logcounts
    id: "vis_{name}"
    name: "{name} (Visium)"
    group: "{name}"
    fields:
      domain: layer_guess_reordered_short        # 7 levels: L1, L3, WM, L6, ...; 352 NA
      total_counts: sum_umi
      detected_genes: sum_gene
      mito_percent: { column: expr_chrM_ratio, scale: 100 }
      # domain: Cluster                          # alternative; 9 levels: 1, 2, 3, 4, ...
    # meta: { subject: { column: subject }, position: { column: position }, replicate: { column: replicate } }

This version adds a description, initial view, layer order and donor metadata:

yaml
id: visium-human-dlpfc
name: Human DLPFC, Visium (Maynard et al. 2021)
description: "Twelve Visium sections of human dorsolateral prefrontal cortex from three donors, with the manual cortical layer annotation and the H&E of each section."
default_gene: SNAP25
default_color: { field: domain }
thumbnail_sample: vis_151673
layout: { mode: grid, columns: 4 }               # four sections per donor, so one row per donor
fields:
  - { id: domain, name: Layer (manual annotation), type: categorical, categories: [L1, L2, L3, L4, L5, L6, WM] }
  - { id: total_counts, name: Total counts, type: continuous }
  - { id: detected_genes, name: Detected genes, type: continuous }
  - { id: mito_percent, name: Mito %, type: continuous }
meta:
  - { id: subject, name: Donor }
  - { id: position, name: Position (µm) }
  - { id: replicate, name: Replicate }
samples:
  - path: raw/spe_dlpfc.rds
    platform: visium
    assay: logcounts
    id: "vis_{name}"
    name: "Section {name}"
    group: "{name}"
    fields:
      domain: layer_guess_reordered_short
      total_counts: sum_umi
      detected_genes: sum_gene
      mito_percent: { column: expr_chrM_ratio, scale: 100 }
    meta: { subject: { column: subject }, position: { column: position }, replicate: { column: replicate } }

This edit rebuilds the twelve samples because categories changes the stored category codes and meta reads a column from each sample. Later changes to names or colors reuse those arrays.

Colors ​

A palette file is JSON: top-level keys are palette names, each mapping a category label to a hex color. A field uses it through palette_key; several keys can be listed, first match wins. Labels missing from the palette get an automatic color. Categories are matched by label, so renaming a label in aliases also changes which color it gets.

json
{ "domain": { "L1": "#F0027F", "L2": "#377EB8", "WM": "#1A1A1A" } }

Two datasets, one vocabulary ​

When two datasets, or two platforms within one, label the same cell types, give them the same field id and the same palette_key. A Cell type field shared by a Xenium section and an snRNA-seq UMAP then uses one legend and one set of colors, and the viewer greys out samples that do not carry it.

Starting over ​

build --force rebuilds every sample from the yaml and the source files; deleting the bundle folder does the same. Neither is needed for ordinary edits.

MIT licensed.