Cell Analysis Import

Usually run for you

run_together calls these importers when a platform's cell-analysis outputs are present (e.g., import_visiumhd_cell for Space Ranger segmentation, import_xenium_cell for per-sample Xenium Ranger clusters in joint runs). This page is for importing cell analyses directly, step by step.

Overview

Import platform‑specific cell analysis outputs (cells, boundaries, clusters/DE, UMAP), convert them to web‑ready PMTiles layers, write an asset JSON for run_cartload2 --cell-assets, and optionally register them in an existing catalog.yaml. Two commands are available:

• import_xenium_cell for 10x Xenium Ranger outputs;
• import_visiumhd_cell for 10x Visium HD Space Ranger segmented outputs.

---

Requirements

• Cell analysis outputs from the platform (see per‑platform inputs below).
• Tools (defaults point to the bundled submodules): tippecanoe, spatula, and punkst (--ficture2, for the factor report of regenerated DE); python3; Rscript on PATH for UMAP plots; parquet-tools for a Xenium cells Parquet.
• An expression source for the pseudobulk/DE that is regenerated by default (see Pseudobulk and DE).
• For --update-catalog: an existing catalog.yaml from Asset Packaging.

---

Actions

Action Specifications

No action runs by default. Activate at least one using the action parameters.

Cell Conversion Step (--cells)

Converts cell centroids into <outprefix>-cells.pmtiles with cell_id, count, and topK (cluster index, ranked by cluster size) attributes. Visium HD centroids are derived from the cell polygons.

Cell Boundary Conversion Step (--boundaries)

Converts cell polygons into <outprefix>-boundaries.geojson (attributes cell_id, topK) and <outprefix>-boundaries.pmtiles.

UMAP Conversion Step (--umap)

Converts the UMAP projection into <outprefix>-umap.pmtiles and draws UMAP plots. Xenium skips this step with a warning when the projection file is missing; Visium HD stops with an error.

Catalog Update (--update-catalog)

Adds (or replaces, by ID) the cell factor in assets.factors of an existing catalog. Not included in --all.

--all enables --cells, --boundaries, and --umap. Every run also writes <outprefix>_assets.json.

Pseudobulk and DE

By default both commands regenerate a cluster pseudobulk matrix and a cluster DE table from expression data, rather than using the platform's DE CSV:

• Xenium: needs either --pixel (a transcript TSV with cell ID, gene, and count columns) or a cell-feature MEX (--mex-dir, or CELL_FEATURE_MEX in the JSON). Use --skip-redo-diffexp to read the DE CSV instead, and add --skip-redo-pseudobulk to skip the pseudobulk (then no expression source is needed).
• Visium HD: uses the cell-feature MEX (--mtx-cells / CELL_FEATURE_MEX) and runs with --cells. Either --skip-mex-pseudobulk or --skip-mex-diffexp switches to the DE CSV. Run --boundaries together with --cells (or with a skip flag) so a DE table is written.

---

Example Usage

Two Input Modes

Each command accepts one of two mutually exclusive input modes:

• JSON mode: pass --in-json (e.g., a manifest from load_xenium_ranger / load_space_ranger; keys are read from its CELLS section when present).
• Manual mode: pass --in-dir; file locations are relative to it (absolute paths are also accepted for Xenium).

Xenium ExampleVisium HD Example

# JSON input mode (keys: CELL, BOUNDARY, CLUSTER, DE; optional UMAP_PROJ, CELL_FEATURE_MEX)
cartloader import_xenium_cell \
  --all \
  --outprefix /path/to/out/xeniumranger \
  --in-json /path/to/xenium_ranger_assets.json

# Manual input mode (pseudobulk/DE regenerated from the cell-feature MEX)
cartloader import_xenium_cell \
  --all \
  --outprefix /path/to/out/xeniumranger \
  --in-dir /path/to/xenium_ranger_output \
  --csv-cells cells.csv.gz \
  --csv-boundaries cell_boundaries.csv.gz \
  --csv-clust analysis/clustering/gene_expression_graphclust/clusters.csv \
  --csv-diffexp analysis/diffexp/gene_expression_graphclust/differential_expression.csv \
  --mex-dir cell_feature_matrix

# JSON input mode (keys: CELL_FEATURE_MEX, CELL_GEOJSON, CLUSTER, DE; optional UMAP_PROJ; scale from SGE.SCALE)
cartloader import_visiumhd_cell \
  --cells --boundaries \
  --outprefix /path/to/out/spaceranger \
  --in-json /path/to/space_ranger_assets.json

# Manual input mode (defaults match the Space Ranger layout)
cartloader import_visiumhd_cell \
  --cells --boundaries \
  --outprefix /path/to/out/spaceranger \
  --in-dir /path/to/spaceranger_output \
  --mtx-cells segmented_outputs/filtered_feature_cell_matrix \
  --geojson-cells segmented_outputs/cell_segmentations.geojson \
  --csv-clust segmented_outputs/analysis/clustering/gene_expression_graphclust/clusters.csv \
  --csv-diffexp segmented_outputs/analysis/diffexp/gene_expression_graphclust/differential_expression.csv

---

Parameters

Action Parameters

• --cells (flag): Import segmented cells and generate PMTiles.
• --boundaries (flag): Import cell boundaries and generate GeoJSON/PMTiles.
• --umap (flag): Import the UMAP projection and generate PMTiles.
• --update-catalog (flag): Update an existing catalog.yaml.
• --all (flag): Enable --cells, --boundaries, and --umap.

Input/Output Parameters

• --outprefix (str, required): Output prefix (e.g., /path/to/out/sample).
• --id (str): Identifier for the cell factor (default: basename of --outprefix).
• --name (str): Display name for the cell factor (default: basename of --outprefix).

Xenium InputVisium HD Input

JSON Mode:

• --in-json (str): JSON/YAML with keys CELL, BOUNDARY, CLUSTER, DE, and optionally UMAP_PROJ, CELL_FEATURE_MEX, PIXEL.

Manual Mode (relative to --in-dir, or absolute):

• --in-dir (str): Base input directory.
• --csv-cells (str): Cell table, CSV or Parquet (default: cells.csv.gz).
• --csv-boundaries (str): Cell boundary CSV whose first three columns are cell ID, X, and Y (default: cell_boundaries.csv.gz).
• --csv-clust (str): Cluster CSV (default: analysis/clustering/gene_expression_graphclust/clusters.csv).
• --csv-diffexp (str): DE CSV (default: analysis/diffexp/gene_expression_graphclust/differential_expression.csv).
• --csv-umap (str): UMAP projection CSV (default: analysis/umap/gene_expression_2_components/projection.csv).
• --mex-dir (str): Cell-feature MEX directory for pseudobulk/DE (e.g., cell_feature_matrix; default: none).
• --mex-bcd / --mex-ftr / --mex-mtx (str): MEX file names (default: barcodes.tsv.gz / features.tsv.gz / matrix.mtx.gz).

Expression source and DE:

• --pixel (str): Transcript TSV with cell IDs, used as given (not under --in-dir); takes precedence over --mex-dir. In JSON mode the path is read from the PIXEL key and --pixel only selects this route.
• --pixel-colname-cell-id / --pixel-colname-gene / --pixel-colname-count (str): Columns in --pixel (default: cell_id / gene / count).
• --skip-redo-diffexp (flag): Use the DE CSV instead of regenerating DE.
• --skip-redo-pseudobulk (flag): Do not regenerate the pseudobulk (requires --skip-redo-diffexp).

JSON Mode:

• --in-json (str): JSON/YAML with keys CELL_FEATURE_MEX, CELL_GEOJSON, CLUSTER, DE, and optionally UMAP_PROJ (under CELLS); SGE.SCALE supplies the scale JSON.

Manual Mode (relative to --in-dir):

• --in-dir (str): Space Ranger output directory.
• --mtx-cells (str): Cell-feature MEX directory (default: segmented_outputs/filtered_feature_cell_matrix).
• --geojson-cells (str): Cell segmentation GeoJSON (default: segmented_outputs/cell_segmentations.geojson).
• --csv-clust (str): Cluster CSV (default: segmented_outputs/analysis/clustering/gene_expression_graphclust/clusters.csv).
• --csv-diffexp (str): DE CSV (default: segmented_outputs/analysis/diffexp/gene_expression_graphclust/differential_expression.csv).
• --csv-umap (str): UMAP projection CSV (default: segmented_outputs/analysis/umap/gene_expression_2_components/projection.csv).
• --mex-bcd / --mex-ftr / --mex-mtx (str): MEX file names (default: barcodes.tsv.gz / features.tsv.gz / matrix.mtx.gz).
• --scale-json (str): Scale factors JSON (default: binned_outputs/square_002um/spatial/scalefactors_json.json). It must exist and sets --units-per-um from microns_per_pixel; pass --scale-json "" to use --units-per-um instead.
• --units-per-um (float): Coordinate units per µm, used only without a scale JSON (default: 1).

DE:

• --skip-mex-pseudobulk / --skip-mex-diffexp (flag): Use the DE CSV instead of regenerating pseudobulk/DE from the MEX.

Auxiliary Parameters

PMTiles Conversion:

• --min-zoom / --max-zoom (int): Zoom range for cells and boundaries (default: 10 / 18).
• --umap-min-zoom / --umap-max-zoom (int): Zoom range for UMAP (default: 0 / 18).
• --max-tile-bytes (int): Max bytes per tile (default: 5000000).
• --max-feature-counts (int): Max features per tile (default: 500000).
• --preserve-point-density-thres (int): Point density threshold (default: 1024).

Coloring and DE:

• --tsv-cmap (str): Cluster color table TSV (default: <cartloader_dir>/assets/default_color_map.tsv).
• --de-max-pval (float): Max p-value (default: 0.01).
• --de-min-fc (float): Min fold change (default: 1.2).

Catalog:

• --catalog-yaml (str): Catalog to update (default: catalog.yaml in the directory of --outprefix).
• --out-catalog-yaml (str): Write the updated catalog here instead of overwriting --catalog-yaml.

Column Names:

Xenium only:

• --cells-colname-cell-id / --cells-colname-x / --cells-colname-y / --cells-colname-count (default: cell_id / x_centroid / y_centroid / transcript_counts)
• --boundaries-colname-cell-id / --boundaries-colname-x / --boundaries-colname-y (default: cell_id / vertex_x / vertex_y)

Both:

• --clust-colname-barcode / --clust-colname-cluster (default: Barcode / Cluster; common aliases such as cell_id or cluster are also recognized)
• --umap-colname-barcode / --umap-colname-x / --umap-colname-y (default: Barcode / UMAP-1 / UMAP-2)

Run and Environment:

• --threads (int): Threads for tippecanoe (default: 4).
• --tmp-dir (str): Temporary directory (default: tmp/ in the directory of --outprefix).
• --keep-intermediate-files (flag): Keep intermediate files.
• --log (flag) / --log-suffix (str): Write a log next to the outputs (default suffix: .log).
• --tippecanoe (str): Default <cartloader_dir>/submodules/tippecanoe/tippecanoe.
• --spatula (str): Default <cartloader_dir>/submodules/spatula/bin/spatula.
• --ficture2 (str): punkst repository (default: <cartloader_dir>/submodules/punkst).
• --python, --gzip, --sort (str): Binaries on PATH (default: python3, gzip, sort).
• --R (str): Checked before UMAP plotting (default: Rscript for Xenium, R for Visium HD); the plots themselves call Rscript.
• --parquet-tools (str): Xenium only; for a Parquet --csv-cells (default: parquet-tools).

---

Output

Written next to --outprefix:

• <outprefix>-cells.pmtiles and <outprefix>-cells.csv: Cell centroids with cell_id, count, topK.
• <outprefix>-boundaries.pmtiles and <outprefix>-boundaries.geojson: Cell polygons with cell_id, topK.
• <outprefix>-rgb.tsv: Cluster color table.
• <outprefix>-cells-bulk-de.tsv: Cluster DE table.
• <outprefix>-pseudobulk.tsv.gz and <outprefix>-info.tsv: Cluster pseudobulk and factor info (when regenerated).
• <outprefix>-umap.tsv.gz, <outprefix>-umap.pmtiles, <outprefix>.umap.png, <outprefix>.umap.single.binary.png: UMAP outputs (with --umap).
• <outprefix>_assets.json: Cell asset entry for run_cartload2 --cell-assets (always written).
• With --update-catalog: the catalog rewritten with the cell factor in assets.factors.