Skip to content

run.md

Latest commit

 

History

History
188 lines (135 loc) · 4 KB

run.md

File metadata and controls

188 lines (135 loc) · 4 KB
Raw

Running Baysor

The main CLI entrypoint in the C++ branch is:

./build/baysor [SUBCOMMAND] ...

For segmentation, use:

./build/baysor run [OPTIONS] coordinates [prior_segmentation]

Minimal Forms

With an explicit scale and no prior:

./build/baysor run --scale 8 molecules.csv

With a prior segmentation:

./build/baysor run molecules.csv segmentation_mask.tif

With a config file:

./build/baysor run -c configs/xenium.toml data/transcripts.parquet :cell_id

Positionals

coordinates

  • required
  • molecule table in CSV or Parquet form
  • may also be experiment.xenium for Xenium-aware runs

prior_segmentation

  • optional
  • one of:
    • image mask
    • boundary CSV / Parquet
    • :column_name for transcript-native prior labels in the molecule table

Common Options

Geometry / column mapping:

  • -x,--x-column
  • -y,--y-column
  • -z,--z-column
  • -g,--gene-column
  • --qv-column
  • --force-2d

Segmentation scale / convergence:

  • -s,--scale
  • --scale-std
  • --iters
  • --tol
  • --n-cells-init
  • --cluster-method
  • --n-clusters
  • --cluster-resolution
  • --cluster-graph-k
  • --cluster-n-dims
  • --cluster-basis-sample-size

Filtering:

  • --min-molecules-per-cell
  • --min-molecules-per-gene
  • --exclude-genes
  • --min-qv

Cropping:

  • --x-min, --x-max
  • --y-min, --y-max
  • --z-min, --z-max

Outputs:

  • -o,--output
  • --output-style legacy|parquet
  • --polygon-format
  • --count-matrix-format
  • -p,--plot
  • --skip-ncv-color

Prior inputs:

  • --prior-segmentation-confidence
  • --unassigned-prior-label

For the files written by each bundle, see Outputs and Output Files.

Clustering Methods

run supports four clustering modes:

  • mrf
    • the legacy Baysor molecule clustering path
    • default mode
    • --n-clusters is the exact number of molecule clusters to fit
    • default n_clusters: 4
  • louvain
    • graph clustering on NCV basis anchors, followed by label transfer to all molecules
    • --n-clusters is the target final coarse cluster count after anchor communities are merged
    • default n_clusters: 10
  • leiden
    • same anchor-based NCV workflow as louvain, with Leiden refinement
    • --n-clusters is again the target final coarse cluster count
    • default n_clusters: 10
  • none
    • disables the clustering prior entirely

Examples:

./build/baysor run --cluster-method mrf --n-clusters 4 ...
./build/baysor run --cluster-method louvain --n-clusters 10 ...
./build/baysor run --cluster-method leiden --n-clusters 10 ...

--cluster-resolution and --cluster-graph-k are advanced controls for the graph methods. In most datasets, the defaults are a reasonable starting point.

For very large runs, especially high-gene-panel Xenium runs such as 5K panels, prefer Louvain clustering with about 10 coarse clusters:

./build/baysor run --cluster-method louvain --n-clusters 10 ...

This keeps the clustering prior coarse enough for large-scale segmentation while using the anchor-based NCV graph path instead of the legacy MRF clustering model.

Threading

Baysor uses OpenMP for parallel sections. Set the thread count with the standard OpenMP environment variable:

OMP_NUM_THREADS=20 ./build/baysor run ...

Some phases are intentionally serial or only partially parallel, so CPU use may not stay at the requested thread count for the full run.

Config Files

Most common protocol setups are captured in:

The example config is:

CLI flags override the config file.

Other Subcommands

The current C++ CLI also provides:

Full Help

For the up-to-date option list, use:

./build/baysor run --help