ophist 0.1.0__tar.gz

ophist-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+.snakemake/
+containers/build/
+data/
+output/
+logs/

ophist-0.1.0/LICENSE

@@ -0,0 +1,30 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Patrick Crock and the OphiST authors
+(St Vincent's Institute of Medical Research)
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

ophist-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.5
+Name: ophist
+Version: 0.1.0
+Summary: End-to-end, segmentation-free analysis for image-based spatial transcriptomics (Xenium, Atera, CosMx, MERSCOPE): a Snakemake pipeline with a command line.
+Project-URL: Repository, https://gitlab.svi.edu.au/biocellgen-public/ophist
+Author-email: Patrick Crock <pat.crock@svi.edu.au>, Yan Pan <anne.pan@svi.edu.au>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: CosMx,MERSCOPE,Snakemake,Xenium,domains,imaging spatial transcriptomics,niches,spatial domains,spatial transcriptomics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.11
+Requires-Dist: pandas
+Requires-Dist: pyyaml
+Requires-Dist: snakemake<10,>=9
+Provides-Extra: slurm
+Requires-Dist: snakemake-executor-plugin-slurm; extra == 'slurm'
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Overview
+
+OphiST is a Snakemake pipeline for the analysis of image-based spatial transcriptomics (iST) data in a segmentation-free manner. 
+
+The accurate assignment of transcripts to cells presents a major bottleneck in conventional analysis of iST data. Issues such as transcript bleed from adjacent cells, cells overlapping in the z-plane, and segmentation failures on irregularly-shaped cells can all lead to complications in downstream analyses. OphiST applies several tools from the Bioinformatics and Cellular Genomics Lab at SVI designed to operate directly on the raw, individual transcript data output by iST platforms, with no cell segmentation required. Namely, [SpatialRNA](https://pypi.org/project/spatialrna/) applies graph neural network (GNN) to embed each individual transcript in a latent space reflecting its local molecular context, and [DuetiST](https://pypi.org/project/duetist/) then derives both fine-grained molecular niches and broader spatial domains from the transcript-embedding data. These tools both operate downstream of sensible preprocessing steps such as demultiplexing, QC filtering (if possible), and tissue-detection. Further along the pipeline, basic downstream analyses such as domain-wise (and condition-wise, if contrasts are supplied) differential gene expression and gene-set enrichment analysis are performed. Everything is summarised in a self-contained HTML report output by the final step of the pipeline.
+
+## Documentation
+
+See the following sub-pages for further details about the pipeline: 
+
+- [Configuration](docs/config.md) explains every parameter in the `config` should you wish to tweak the defaults. 
+- [Outputs](docs/outputs.md) details the outputs of the pipeline. 
+- [Containers](docs/containers.md) contains information about the Apptainer containers and Conda environments used for running the pipeline, including instructions on building them yourself. 
+- [Command line](docs/cli.md) describes the `ophist` command: `run`, `init`, `examples` and `profile`.
+
+## Installation
+
+OphiST needs Python 3.11 or later. Install it with pip, including the SLURM plugin if you run
+on a SLURM cluster:
+
+```bash
+pip install "ophist[slurm]"
+```
+
+This installs the `ophist` command, the workflow and [Snakemake](https://snakemake.readthedocs.io).
+The latest development version installs straight from the repository:
+`pip install "ophist[slurm] @ git+https://gitlab.svi.edu.au/biocellgen-public/ophist.git"`.
+On a cluster, install into an environment on a shared filesystem, because the compute nodes run
+the workflow's scripts from there.
+
+To work on the workflow itself, clone the repository. An editable install then makes `ophist`
+run the clone:
+
+```bash
+git clone https://gitlab.svi.edu.au/biocellgen-public/ophist.git
+pip install -e "./ophist[slurm]"
+```
+
+A clone also runs without pip, through Snakemake directly; see
+[docs/cli.md](docs/cli.md#without-the-command).
+
+## Requirements
+
+- [Apptainer](https://apptainer.org). Each step runs in a prebuilt image, pulled on first use.
+  Conda works too; see [docs/containers.md](docs/containers.md).
+- An NVIDIA GPU for step 3 (spatialRNA training and embedding).
+- To run on a SLURM cluster, the
+  [SLURM executor plugin](https://snakemake.github.io/snakemake-plugin-catalog/plugins/executor/slurm.html),
+  installed by the `slurm` extra above.
+
+## Quick start
+
+1. Start a run directory from the example closest to your data (`ophist examples` lists
+   them):
+
+   ```bash
+   ophist init my_run --example xenium_tma
+   ```
+
+2. List your samples in `my_run/config/samples.tsv`. Adjust `my_run/config/config.yml` as
+   needed. A config only needs the settings it changes; see [docs/config.md](docs/config.md).
+
+3. Once, write a Snakemake profile, and fill in your account, partition and the data paths to
+   bind into the images:
+
+   ```bash
+   ophist profile slurm        # writes profiles/slurm/config.yaml
+   ```
+
+   On a single GPU machine, use `ophist profile local` instead, or no profile at all.
+
+4. Run. Output goes to `my_run/`; add `-n` first for a dry run.
+
+   ```bash
+   ophist run my_run/config/config.yml --profile profiles/slurm
+   ```
+
+   A long run is best launched from a batch job of its own. That head job needs about 1 CPU
+   and 8 GB.
+
+## Examples
+
+[`examples/`](examples/) holds configs for three data types:
+
+| Example | Data |
+|---|---|
+| [`xenium_tma`](examples/xenium_tma/) | Xenium slides cut into TMA cores, with a condition contrast |
+| [`atera_kidney`](examples/atera_kidney/) | one Atera whole-transcriptome slide |
+| [`ophist_logo`](examples/ophist_logo/) | the OphiST simulated dataset, a small test that runs end to end in under an hour |
+
+## Overview of the pipeline
+
+| Step | Rule file | Main output | Description |
+|---|---|---|---|
+| 1. Preprocessing | `rules/01_preprocessing.smk` | `data/{sample}/qc_transcripts.zarr` | Raw transcripts are QC-filtered if possible. (Optional: demultiplexing of slides) |
+| 2. Tissue detection | `rules/02_tissue_detection.smk` | `data/{sample}/tissue_mask.npz`, `data/cohort.zarr` | Tissue outline detected from transcript density; transcripts are filtered to this outline. |
+| 3. spatialRNA embeddings | `rules/03_spatialrna.smk` | `data/spatialrna/cohort_embeddings.zarr` | SpatialRNA applies a GNN to give each transcript an embedding vector describing its spatial context. |
+| 4. Lumen detection | `rules/04_lumen_detection.smk` | `data/{sample}/masks.geojson` | (Optional: Lumen within the tissue are detected from transcript density; this mask is used downstream in smoothing.) |
+| 6. Smoothing | `rules/06_smoothing.smk` | `data/{sample}/smoothed.npz` | The transcript-embeddings are smoothed onto a grid for tractability. |
+| 7. Niches and domains | `rules/07_hmrf_potts.smk` | `data/{sample}/{niches,domains}.npz`, `data/hmrf/` | DuetiST derives niches and domains shared across the samples from the GNN embeddings. | 
+| 8. Domain analysis | `rules/08_domain_analysis.smk` | `output/domain_dge/` | Transcripts are pseudobulked by domain. Domains are tested for marker genes and cell-type signatures. |
+| 9. Condition DGE | `rules/09_dge.smk` | `output/condition_dge/` | (Optional: Further pseudobulk analysis of transcripts within domains, across contrasts specified in inputs.) |
+| 10. Report | `rules/10_report.smk` | `output/report.html` | Summaries of all above steps, including QC figures, training and model reports, PCA analysis, spatial maps, DGE and GSEA tables. |
+
+Each rule file's scripts are in `scripts/<rule file name>/`. Helpers shared between steps are
+in `scripts/utils/`.
+
+## Credits
+
+- Patrick Crock: Lead engineer of the pipeline.
+- Anne Pan: Current maintainer of the [spatialrna](https://pypi.org/project/spatialrna/) package. Designed rules 03 and 10. 
+- Ruqian Lyu: Original author of the [spatialrna](https://pypi.org/project/spatialrna/) package.
+- Smoothing and the Potts model both use [duetist](https://gitlab.svi.edu.au/biocellgen-public/duetist).
+
+## Citation
+
+A manuscript is in preparation.
+
+## License
+
+BSD 3-Clause; see [LICENSE](LICENSE).

ophist-0.1.0/README.md

@@ -0,0 +1,121 @@
+# Overview
+
+OphiST is a Snakemake pipeline for the analysis of image-based spatial transcriptomics (iST) data in a segmentation-free manner. 
+
+The accurate assignment of transcripts to cells presents a major bottleneck in conventional analysis of iST data. Issues such as transcript bleed from adjacent cells, cells overlapping in the z-plane, and segmentation failures on irregularly-shaped cells can all lead to complications in downstream analyses. OphiST applies several tools from the Bioinformatics and Cellular Genomics Lab at SVI designed to operate directly on the raw, individual transcript data output by iST platforms, with no cell segmentation required. Namely, [SpatialRNA](https://pypi.org/project/spatialrna/) applies graph neural network (GNN) to embed each individual transcript in a latent space reflecting its local molecular context, and [DuetiST](https://pypi.org/project/duetist/) then derives both fine-grained molecular niches and broader spatial domains from the transcript-embedding data. These tools both operate downstream of sensible preprocessing steps such as demultiplexing, QC filtering (if possible), and tissue-detection. Further along the pipeline, basic downstream analyses such as domain-wise (and condition-wise, if contrasts are supplied) differential gene expression and gene-set enrichment analysis are performed. Everything is summarised in a self-contained HTML report output by the final step of the pipeline.
+
+## Documentation
+
+See the following sub-pages for further details about the pipeline: 
+
+- [Configuration](docs/config.md) explains every parameter in the `config` should you wish to tweak the defaults. 
+- [Outputs](docs/outputs.md) details the outputs of the pipeline. 
+- [Containers](docs/containers.md) contains information about the Apptainer containers and Conda environments used for running the pipeline, including instructions on building them yourself. 
+- [Command line](docs/cli.md) describes the `ophist` command: `run`, `init`, `examples` and `profile`.
+
+## Installation
+
+OphiST needs Python 3.11 or later. Install it with pip, including the SLURM plugin if you run
+on a SLURM cluster:
+
+```bash
+pip install "ophist[slurm]"
+```
+
+This installs the `ophist` command, the workflow and [Snakemake](https://snakemake.readthedocs.io).
+The latest development version installs straight from the repository:
+`pip install "ophist[slurm] @ git+https://gitlab.svi.edu.au/biocellgen-public/ophist.git"`.
+On a cluster, install into an environment on a shared filesystem, because the compute nodes run
+the workflow's scripts from there.
+
+To work on the workflow itself, clone the repository. An editable install then makes `ophist`
+run the clone:
+
+```bash
+git clone https://gitlab.svi.edu.au/biocellgen-public/ophist.git
+pip install -e "./ophist[slurm]"
+```
+
+A clone also runs without pip, through Snakemake directly; see
+[docs/cli.md](docs/cli.md#without-the-command).
+
+## Requirements
+
+- [Apptainer](https://apptainer.org). Each step runs in a prebuilt image, pulled on first use.
+  Conda works too; see [docs/containers.md](docs/containers.md).
+- An NVIDIA GPU for step 3 (spatialRNA training and embedding).
+- To run on a SLURM cluster, the
+  [SLURM executor plugin](https://snakemake.github.io/snakemake-plugin-catalog/plugins/executor/slurm.html),
+  installed by the `slurm` extra above.
+
+## Quick start
+
+1. Start a run directory from the example closest to your data (`ophist examples` lists
+   them):
+
+   ```bash
+   ophist init my_run --example xenium_tma
+   ```
+
+2. List your samples in `my_run/config/samples.tsv`. Adjust `my_run/config/config.yml` as
+   needed. A config only needs the settings it changes; see [docs/config.md](docs/config.md).
+
+3. Once, write a Snakemake profile, and fill in your account, partition and the data paths to
+   bind into the images:
+
+   ```bash
+   ophist profile slurm        # writes profiles/slurm/config.yaml
+   ```
+
+   On a single GPU machine, use `ophist profile local` instead, or no profile at all.
+
+4. Run. Output goes to `my_run/`; add `-n` first for a dry run.
+
+   ```bash
+   ophist run my_run/config/config.yml --profile profiles/slurm
+   ```
+
+   A long run is best launched from a batch job of its own. That head job needs about 1 CPU
+   and 8 GB.
+
+## Examples
+
+[`examples/`](examples/) holds configs for three data types:
+
+| Example | Data |
+|---|---|
+| [`xenium_tma`](examples/xenium_tma/) | Xenium slides cut into TMA cores, with a condition contrast |
+| [`atera_kidney`](examples/atera_kidney/) | one Atera whole-transcriptome slide |
+| [`ophist_logo`](examples/ophist_logo/) | the OphiST simulated dataset, a small test that runs end to end in under an hour |
+
+## Overview of the pipeline
+
+| Step | Rule file | Main output | Description |
+|---|---|---|---|
+| 1. Preprocessing | `rules/01_preprocessing.smk` | `data/{sample}/qc_transcripts.zarr` | Raw transcripts are QC-filtered if possible. (Optional: demultiplexing of slides) |
+| 2. Tissue detection | `rules/02_tissue_detection.smk` | `data/{sample}/tissue_mask.npz`, `data/cohort.zarr` | Tissue outline detected from transcript density; transcripts are filtered to this outline. |
+| 3. spatialRNA embeddings | `rules/03_spatialrna.smk` | `data/spatialrna/cohort_embeddings.zarr` | SpatialRNA applies a GNN to give each transcript an embedding vector describing its spatial context. |
+| 4. Lumen detection | `rules/04_lumen_detection.smk` | `data/{sample}/masks.geojson` | (Optional: Lumen within the tissue are detected from transcript density; this mask is used downstream in smoothing.) |
+| 6. Smoothing | `rules/06_smoothing.smk` | `data/{sample}/smoothed.npz` | The transcript-embeddings are smoothed onto a grid for tractability. |
+| 7. Niches and domains | `rules/07_hmrf_potts.smk` | `data/{sample}/{niches,domains}.npz`, `data/hmrf/` | DuetiST derives niches and domains shared across the samples from the GNN embeddings. | 
+| 8. Domain analysis | `rules/08_domain_analysis.smk` | `output/domain_dge/` | Transcripts are pseudobulked by domain. Domains are tested for marker genes and cell-type signatures. |
+| 9. Condition DGE | `rules/09_dge.smk` | `output/condition_dge/` | (Optional: Further pseudobulk analysis of transcripts within domains, across contrasts specified in inputs.) |
+| 10. Report | `rules/10_report.smk` | `output/report.html` | Summaries of all above steps, including QC figures, training and model reports, PCA analysis, spatial maps, DGE and GSEA tables. |
+
+Each rule file's scripts are in `scripts/<rule file name>/`. Helpers shared between steps are
+in `scripts/utils/`.
+
+## Credits
+
+- Patrick Crock: Lead engineer of the pipeline.
+- Anne Pan: Current maintainer of the [spatialrna](https://pypi.org/project/spatialrna/) package. Designed rules 03 and 10. 
+- Ruqian Lyu: Original author of the [spatialrna](https://pypi.org/project/spatialrna/) package.
+- Smoothing and the Potts model both use [duetist](https://gitlab.svi.edu.au/biocellgen-public/duetist).
+
+## Citation
+
+A manuscript is in preparation.
+
+## License
+
+BSD 3-Clause; see [LICENSE](LICENSE).

ophist-0.1.0/Snakefile

@@ -0,0 +1,110 @@
+import os
+import re
+
+import pandas as pd
+
+
+# Settings: the pipeline's defaults, then the run's config/config.yml when there is one, then
+# any --configfile / --config given to Snakemake (`ophist run CONFIG` passes CONFIG this way).
+# A run's config only needs the settings it changes.
+
+configfile: f"{workflow.basedir}/config/config.yml"
+if os.path.exists("config/config.yml"):
+    configfile: "config/config.yml"
+
+
+# Setup sample list (or single sample name)
+
+samples_cfg = config["samples"]
+
+if isinstance(samples_cfg, str) and not samples_cfg.endswith(".tsv"):
+    SAMPLES = [samples_cfg]
+    SAMPLE_SHEET = None
+else:
+    # sample_name, path (Xenium outs/ directory), optional x/y_min/max crop and contrast_N columns
+    SAMPLE_SHEET = pd.read_csv(samples_cfg, sep="\t", dtype={"sample_name": str, "path": str}).set_index("sample_name")
+    SAMPLES = SAMPLE_SHEET.index.tolist()
+
+wildcard_constraints:
+    sample="|".join(re.escape(s) for s in SAMPLES)
+
+
+# spatialRNA's output store: written by rule 03, or already there for prerun data.
+# Everything downstream of spatialRNA reads its transcripts from here.
+
+PRERUN = config["preprocessing"]["type"] == "prerun"
+EMBEDDINGS = config["spatialrna"]["embeddings"]
+EMBEDDING_ROWS = f"{EMBEDDINGS}/{{sample}}/x"   # a sample's row count, for mem_by_rows()
+
+# Apptainer images (--sdm apptainer), one per envs/*.yml; each rule's container: sits
+# next to its conda: env, which --sdm conda uses instead.
+CONTAINERS = config["containers"]
+
+# Smoothing and the Potts model (rules 06, 07) come from the duetist package installed in
+# the spatial env, or from a duetist checkout when duetist.src is set (docs/config.md).
+DUETIST_SRC = str(config.get("duetist", {}).get("src") or "")
+
+# The report's heading and file: report.title, and output/<title>.html with anything unsafe
+# in a file name replaced. No title gives the default heading in output/report.html.
+REPORT_TITLE = str(config.get("report", {}).get("title") or "").removesuffix(".html")
+REPORT_FILE = re.sub(r"[^\w.-]+", "_", REPORT_TITLE).strip("_") or "report"
+REPORT_HTML = f"output/{REPORT_FILE}.html"
+
+
+# Condition DGE targets: only with several samples and a contrast_N column in samples.tsv
+
+def has_condition_contrasts():
+    header = pd.read_csv(samples_cfg, sep="\t", nrows=0).columns
+    return any(re.match(r"^contrast_\d+$", c) for c in header)
+
+def get_conditional_targets():
+    if len(SAMPLES) > 1 and has_condition_contrasts():
+        return ["output/condition_dge/condition_de.csv", "output/condition_dge/condition_gsea.csv",
+                "output/condition_dge/condition_de_full.csv", "output/condition_dge/condition_gsea_full.csv"]
+    return []
+
+
+# Define all targets
+
+rule all:
+    input:
+        expand("output/{sample}/lumen_plot.png", sample=SAMPLES),
+        expand("output/{sample}/tx_lumen_plot.png", sample=SAMPLES),
+        "output/plots/lumen_detection.png",
+        expand("output/{sample}/smoothed_embeddings.png", sample=SAMPLES),
+        expand("output/{sample}/hmrf_labels.png", sample=SAMPLES),
+        [f"output/plots/hmrf_{p}.png" for p in ("domains", "niches", "domain_profiles", "history", "composition")],
+        "output/domain_dge/domain_de.csv",
+        "output/domain_dge/domain_gsea.csv",
+        REPORT_HTML,
+        get_conditional_targets()
+
+localrules: all
+
+
+# Resource allocation for job submission
+
+include: "rules/resources.smk"
+
+
+# Rules proper
+
+# 1. Preprocessing - including splitting of multiplexed samples, and filtering of low-quality/negative control spots
+include: "rules/01_preprocessing.smk"
+# 2. Tissue detection - Masking of the tissue area to exclude background spots
+include: "rules/02_tissue_detection.smk"
+# 3. SpatialRNA - production of per-transcript embeddings reflecting their local spatial context
+if not PRERUN:
+    include: "rules/03_spatialrna.smk"
+# 4. Lumen detection - detection of lumen in the tissue
+include: "rules/04_lumen_detection.smk"
+# 6. Smoothing - smoothing of the spatial embeddings onto a grid
+include: "rules/06_smoothing.smk"
+# 7. Niches and domains - a hierarchical Potts model of niches and domains across the cohort
+include: "rules/07_hmrf_potts.smk"
+# 8. Domain analysis - pseudobulk counts per domain, domain marker genes and GSEA
+include: "rules/08_domain_analysis.smk"
+# 9. DGE - differential gene expression analysis between conditions, if multiple samples and contrasts are provided
+include: "rules/09_dge.smk"
+# 10. Report - generation of a report summarizing the results
+include: "rules/10_report.smk"

ophist-0.1.0/config/config.yml

@@ -0,0 +1,128 @@
+# OphiST configuration. Every setting is explained in docs/config.md;
+# examples/ has configs tuned for Xenium, Atera and the OphiST simulated data.
+
+# ---- Inputs ----
+samples: "config/samples.tsv"
+
+# ---- Software images (--sdm apptainer) ----
+containers:
+  spatial:    "oras://ghcr.io/patrickcrock/ophist-spatial:0.2.0"
+  spatialrna: "oras://ghcr.io/patrickcrock/ophist-spatialrna:0.1.1"
+  dge:        "oras://ghcr.io/patrickcrock/ophist-dge:0.1.0"
+
+# ---- General ----
+global:
+  seed: 23
+  species: "human"
+
+# ---- 1. Preprocessing ----
+preprocessing:
+  type: "xenium"
+  xenium:
+    qv_threshold: 20
+  atera:
+    qv_threshold: 20
+  cosmx:
+    um_per_px: 0.12028
+    control_prefixes: ["NegPrb", "Negative", "SystemControl", "FalseCode"]
+  merscope:
+    control_prefixes: ["Blank-"]
+  custom:
+    file: ""
+    gene_col: "gene"
+    x_col: "x"
+    y_col: "y"
+    z_col: ""
+    qv_col: ""
+    count_col: ""
+    qv_threshold: 20
+    um_per_unit: 1.0
+    control_prefixes: []
+
+# ---- 2 & 4. Tissue and lumen masks ----
+masks:
+  downscaling: 0
+  resolution: 4
+  blur_sigma: 8
+  threshold: 0.05
+  min_feature_size: 250
+  closing_radius: 5
+
+# ---- 3. spatialRNA embeddings ----
+spatialrna:
+  embeddings: "data/spatialrna/cohort_embeddings.zarr"
+  work_dir: "data/spatialrna"
+  conda_env: ""
+  graph:
+    radius: 3.0
+    max_num_neighbors: 500
+    radius_method: "knn"
+    radius_3d: False
+    pad_hops: 2
+    tx_per_tile: 500000
+    num_tiles: 0
+    n_procs: 4
+    mem_per_proc_mb: 16000
+    threads: 8
+  model:
+    name: "gat_l2"
+    kwargs:
+      hidden_channels: 64
+      out_channels: 50
+      num_layers: 2
+      dropout: 0.0
+  training:
+    epochs: 5
+    lr: 0.001
+    batch_size: 2048
+    num_neighbors: [15, 10]
+    num_train_edges: 25000
+    val_fraction: 0.05
+    tiles_per_epoch: 0
+    mem_mb: 64000
+    runtime_min: 1440
+  embed:
+    method: "sampled"
+    num_neighbors: [15, 10]
+    batch_size: 2048
+
+# ---- 6. Smoothing ----
+smoothing:
+  grid_size: 8
+  sigma: 8
+
+# ---- 7. Niches and domains (hierarchical Potts model) ----
+hmrf_potts:
+  init: "dp"
+  K1: 50
+  K2: 25
+  hdbscan_niche_min_frac: 0.0005
+  hdbscan_domain_min_frac: 0.0005
+  init_n_max: 500000
+  burn_in: 12
+  n_iter: 36
+  radius_um: 20
+  n0: 0.0625
+  floor_um2: 800
+  domain_stride_um: 16
+  merge_h_max: 0.3
+  niche_h_max: 0.95
+  icm_max_sweeps: 50
+
+# ---- 10. Report ----
+report:
+  title: ""
+  target_mb: 200
+  map_px_max: 1600
+  embedding_points: 2000000
+  umap_points: 100000
+  max_table_rows: 1000
+  embedding_panels_max_samples: 32
+
+# ---- Cluster resources ----
+resources:
+  max_mem_mb: 1400000
+  gpu_max_mem_mb: 490000
+  gpu_partition: "gpu"
+  gpu_gres: "gpu:1"
+  gpu_slurm_extra: ""

ophist-0.1.0/config/samples.tsv

@@ -0,0 +1,3 @@
+sample_name	path
+sample1	/path/to/sample1/outs
+sample2	/path/to/sample2/outs

ophist-0.1.0/containers/conda_env.def

@@ -0,0 +1,28 @@
+# One image per conda env: envs/{{ ENV }}.yml installed into /opt/env, on PATH, so
+# Snakemake's `python` / `Rscript` resolve to it. Build from the repo root (the %files
+# path is relative to it), e.g.
+#     apptainer build --fakeroot --build-arg ENV=spatial ophist-spatial.sif containers/conda_env.def
+# See docs/containers.md.
+Bootstrap: docker
+From: mambaorg/micromamba:2.8.1-debian12-slim
+
+%arguments
+    ENV=spatial
+
+%files
+    envs/{{ ENV }}.yml /opt/env.yml
+
+%post
+    export MAMBA_ROOT_PREFIX=/opt/conda
+    # envs/spatialrna.yml's CUDA pytorch only solves where conda sees a GPU driver; the
+    # build runs on drivers for CUDA >= 12.4. Harmless for the other envs.
+    export CONDA_OVERRIDE_CUDA=12.4
+    micromamba create -y -p /opt/env -f /opt/env.yml
+    micromamba clean -afy
+
+%environment
+    export PATH=/opt/env/bin:$PATH
+
+%labels
+    org.opencontainers.image.source https://gitlab.svi.edu.au/biocellgen-public/ophist
+    env {{ ENV }}

ophist-0.1.0/docs/cli.md

@@ -0,0 +1,83 @@
+# Command line
+
+`pip install ophist` installs the `ophist` command together with the workflow. The command
+calls Snakemake for you; everything Snakemake can do is still available through it.
+
+On a cluster, install OphiST into an environment on a shared filesystem. The jobs run the
+workflow's scripts from where the package is installed, so the compute nodes must be able to
+read it.
+
+## `ophist run`
+
+```bash
+ophist run CONFIG [-d DIR] [--profile PROFILE] [SNAKEMAKE OPTIONS ...]
+```
+
+Runs the pipeline with the settings in `CONFIG`.
+
+- **Settings.** A config only needs the settings it changes. Every other setting keeps its
+  default (see [config.md](config.md#partial-configs)).
+- **Run directory.** This is where `data/`, `output/` and `logs/` are written, and where
+  relative paths in the config (such as `samples: "config/samples.tsv"`) are looked up. It is
+  the config's folder, or its parent when that folder is called `config`, so
+  `ophist run my_run/config/config.yml` runs in `my_run/`. `-d DIR` chooses another one.
+- **Profile.** `--profile PROFILE` is a Snakemake profile: a folder holding a `config.yaml`, or
+  the name of one in `~/.config/snakemake/`. Use it to run on a cluster; see `ophist profile`
+  below.
+  - Without a profile, and without any of Snakemake's own execution options (`--sdm`,
+    `--executor`, `--cores`, `--jobs`), the pipeline runs on the local machine in the published
+    Apptainer images (`--sdm apptainer --cores all`).
+- **Snakemake options.** Any other option goes straight to Snakemake. For example:
+  - `-n` for a dry run;
+  - `--jobs 50`;
+  - `--rerun-incomplete`;
+  - `--config smoothing='{"grid_size": 4}'`.
+- **Binds.** The jobs' containers are given the installed workflow and every sample's raw-data
+  folder, through `APPTAINER_BIND`. Other folders the run needs (for example a `prerun`
+  embedding store elsewhere) still need a `--bind` in the profile's `apptainer-args`.
+
+The command prints the Snakemake command it runs, and returns Snakemake's exit status.
+
+## `ophist init`
+
+```bash
+ophist init DIR [--example NAME] [--force]
+```
+
+Starts a run directory: it writes `DIR/config/config.yml` and `DIR/config/samples.tsv`.
+- With `--example`, they are copied from one of the examples, together with the example's
+  `README.md`.
+- Without it, they are the full default config and a template sample sheet.
+
+Existing files are kept unless you pass `--force`.
+
+## `ophist examples`
+
+Lists the example configs and what each is for. Their settings are explained in
+[examples/README.md](../examples/README.md).
+
+## `ophist profile`
+
+```bash
+ophist profile {slurm,local} [DEST] [--force]
+```
+
+Copies a Snakemake profile template to `DEST` (default `profiles/<name>/`), to edit and then
+pass to `ophist run --profile DEST`.
+- `slurm` submits each job to SLURM. Set your account and partition, and the paths to bind,
+  in it. It needs `pip install ophist[slurm]`.
+- `local` runs everything on one machine.
+
+## Without the command
+
+The `ophist` command is a convenience. A clone of the repository runs with Snakemake alone, in
+an environment that has Snakemake 9 and pandas:
+
+```bash
+mamba create -n snakemake -c conda-forge -c bioconda snakemake pandas snakemake-executor-plugin-slurm
+snakemake --snakefile /path/to/ophist/Snakefile -d my_run --profile ...
+```
+
+Here `my_run/config/config.yml` is read automatically, over the defaults. The profile's
+`apptainer-args` must then bind the clone and the data folders, since nothing sets
+`APPTAINER_BIND` for you.