Skip to content

Xenium Pipeline Add-on Modules

Overview

CartLoader provides add-on modules to support the Xenium pipeline orchestrator:

  • load_xenium_ranger scans a 10x Xenium Ranger output directory and writes a JSON manifest of detected assets.

Add-on Modules

Introduction

load_xenium_ranger scans a 10x Xenium Ranger output directory and writes a JSON manifest of detected assets. The manifest consolidates paths for Spatial Gene Expression (SGE), cell analysis outputs (cells, boundaries, clusters, DE, embeddings), and morphology images (OME‑TIFFs).

Typical next steps use this manifest as input for downstream commands such as run_xenium, sge_convert, import_cell, and import_image.

Requirements

  • Xenium Ranger output directory (unpacked) containing standard files and subfolders.
  • Optional: a writable directory for temporary archive extraction when using --unzip-dir.

Example Usage

1
2
3
4
cartloader load_xenium_ranger \
  --in-dir /path/to/xenium/ranger/output \
  --out-json /path/to/out/xenium_ranger_assets.json \
  --unzip-dir /path/to/out/tmp

Actions

Detect standard Xenium Ranger assets under --in-dir and build a structured JSON manifest (SGE, CELLS, IMAGES). Paths are resolved from files and supported archives (via --unzip-dir); only present items are included:

  • SGE:
    • Required: TRANSCRIPT — transcripts.csv.gz or transcripts.parquet
  • CELLS:
    • Required: CELL — cells.csv.gz or cells.parquet
    • Required: BOUNDARY — cell_boundaries.csv.gz
    • Optional: CELL_FEATURE_MEX — cell_feature_matrix/ (also cell_feature_matrix.tar.gz)
    • Required: CLUSTER — analysis/clustering/gene_expression_graphclust/clusters.csv (also within analysis.tar.gz)
    • Required: DE — analysis/diffexp/gene_expression_graphclust/differential_expression.csv (also within analysis.tar.gz)
    • Optional: PCA_PROJ — analysis/pca/gene_expression_*/projection.csv (also within analysis.tar.gz)
    • Optional: PCA_VAR — analysis/pca/gene_expression_*/variance.csv (also within analysis.tar.gz)
    • Optional: UMAP_PROJ — analysis/umap/gene_expression_*/projection.csv (also within analysis.tar.gz)
  • IMAGES (OME‑TIFF, all optional):
    • DAPI_OME — morphology_focus.ome.tif or morphology_focus/morphology_focus_0000.ome.tif
    • BOUNDARY_OME — morphology_focus/morphology_focus_0001.ome.tif
    • INTERIOR_RNA_OME — morphology_focus/morphology_focus_0002.ome.tif
    • INTERIOR_PROTEIN_OME — morphology_focus/morphology_focus_0003.ome.tif
    • DAPI_MIP_OME — morphology_mip.ome.tif

Note: Exact availability varies by dataset and pipeline options. Missing entries are omitted; zip archives listed above are unpacked or scanned when --unzip-dir is provided.

Parameters

  • --in-dir (str, required): Xenium Ranger output directory to scan.
  • --out-json (str, required): Path to write the generated assets JSON.
  • --unzip-dir (str, optional): Directory to extract archives found under --in-dir (defaults to --in-dir).
  • --overwrite (flag): Overwrite --out-json if it already exists.

Output

Writes a JSON manifest at --out-json.

Example: includes/xenium_ranger_assets.human_lung_cancer.json

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
    "SGE": {
        "TRANSCRIPT": "/example_dir/Xenium_V1_humanLung_Cancer_FFPE_outs/transcripts.csv.gz"
    },
    "CELLS": {
        "CELL": "/example_dir/Xenium_V1_humanLung_Cancer_FFPE_outs/cells.csv.gz",
        "BOUNDARY": "/example_dir/Xenium_V1_humanLung_Cancer_FFPE_outs/cell_boundaries.csv.gz",
        "CELL_FEATURE_MEX": "/example_dir/Xenium_V1_humanLung_Cancer_FFPE_outs/cell_feature_matrix",
        "CLUSTER": "/example_dir/Xenium_V1_humanLung_Cancer_FFPE_outs/analysis/clustering/gene_expression_graphclust/clusters.csv",
        "DE": "/example_dir/Xenium_V1_humanLung_Cancer_FFPE_outs/analysis/diffexp/gene_expression_graphclust/differential_expression.csv",
        "PCA_PROJ": "/example_dir/Xenium_V1_humanLung_Cancer_FFPE_outs/analysis/pca/gene_expression_10_components/projection.csv",
        "PCA_VAR": "/example_dir/Xenium_V1_humanLung_Cancer_FFPE_outs/analysis/pca/gene_expression_10_components/variance.csv",
        "UMAP_PROJ": "/example_dir/Xenium_V1_humanLung_Cancer_FFPE_outs/analysis/umap/gene_expression_2_components/projection.csv"
    },
    "IMAGES": {
        "DAPI_OME": "/example_dir/Xenium_V1_humanLung_Cancer_FFPE_outs/morphology_focus/morphology_focus_0000.ome.tif",
        "BOUNDARY_OME": "/example_dir/Xenium_V1_humanLung_Cancer_FFPE_outs/morphology_focus/morphology_focus_0001.ome.tif",
        "INTERIOR_RNA_OME": "/example_dir/Xenium_V1_humanLung_Cancer_FFPE_outs/morphology_focus/morphology_focus_0002.ome.tif",
        "INTERIOR_PROTEIN_OME": "/example_dir/Xenium_V1_humanLung_Cancer_FFPE_outs/morphology_focus/morphology_focus_0003.ome.tif",
        "DAPI_3D_OME": "/example_dir/Xenium_V1_humanLung_Cancer_FFPE_outs/morphology.ome.tif"
    }
}