workflows/ingestion/spaceranger_hd_mapping

Description

Take raw Visium HD FASTQ files and produce a SpatialData object with the
segmented cells. Runs Space Ranger 4.1.0 to align reads and perform
nucleus/cell segmentation, then converts the segmented output to SpatialData.

Segmentation runs by default when an H&E microscope image (--image) is
provided. Provide --probe_set for probe-based Visium HD assays.

Inputs

Name	Type & Properties	Description
--id	string required	ID of the sample.
--input	file required multiple	The fastq.gz files to align with Space Ranger. Can also be a single directory containing fastq.gz files. Individual FASTQ files should follow the naming convention of 10x Genomics: [Sample Name]_S[Sample Number]_L[Lane Number]_[Read Type]_001.fastq.gz
--gex_reference	file required	Path of folder containing 10x-compatible reference.
--probe_set	file	CSV file specifying the probe set used. Omit for Visium HD 3' data (sequencing-based); provide it only for probe-based Visium HD.
--cytaimage	file required	Brightfield image generated by the CytAssist instrument. Required for Visium HD.
--image	file	H&E microscope image (TIFF or JPG). Required to run nucleus/cell segmentation.

Name

Type & Properties

--id

string

required

--input

file

required

multiple

--gex_reference

file

required

--probe_set

file

--cytaimage

file

required

--image

file

Outputs

Name	Type & Properties	Description
--output_raw	file required output	Location where the raw Space Ranger output folder will be stored.
--output_spatialdata	file required output	The Space Ranger output, converted to SpatialData (Zarr).
--mode	string	Which Space Ranger HD output to convert to SpatialData: `segmented_cells` (per-cell counts and cell boundary polygons) or `bins` (binned counts at `--bin_size`). Segmentation is generally preferred, but binned output is available for compatibility.
--bin_size	integer	Bin size in microns to convert when `--mode bins`.
--output_type	string	Which count matrix to convert (`filtered` or `raw`). Applies to both modes.
--output_layer	string	If provided, store the counts as a named layer in addition to `.X`.
--dataset_id	string	Identifier used to name the spatial elements. Defaults to the sample id.

Name

Type & Properties

--output_raw

file

required

output

--output_spatialdata

file

required

output

--mode

string

--bin_size

integer

--output_type

string

--output_layer

string

--dataset_id

string

Slide Information

Name	Type & Properties	Description
--slide	string	Visium slide serial number. Optional if present in the CytAssist image metadata.
--area	string	Visium capture area identifier. Optional if present in the CytAssist image metadata.
--unknown_slide	string	Use if the slide serial number and area are unknown.
--slidefile	file	Slide design file for offline use
--override_id	boolean_true	Overrides the slide serial number and capture area provided in the Cytassist image metadata

Name

Type & Properties

--slide

string

--area

string

--unknown_slide

string

--slidefile

file

--override_id

boolean_true

Image Options

Name	Type & Properties	Description
--darkimage	file	Multi-channel, dark-background fluorescence image
--colorizedimage	file	Color image representing pre-colored dark-background fluorescence images
--dapi_index	integer	Index of DAPI channel (1-indexed) of fluorescence image
--image_scale	double	Microns per microscope image pixel
--reorient_images	boolean	Whether to rotate and mirror image to align fiducial pattern
--loupe_alignment	file	Alignment file produced by the Loupe Browser manual alignment step. Overrides automatic fiducial and tissue detection. The image used to generate this file must match --image or --cytaimage.

Name

Type & Properties

--darkimage

file

--colorizedimage

file

--dapi_index

integer

--image_scale

double

--reorient_images

boolean

--loupe_alignment

file

SpaceRanger arguments

Name	Type & Properties	Description
--create_bam	boolean	Enable or disable BAM file generation.
--nosecondary	boolean_true	Disable secondary analysis (e.g. clustering).
--r1_length	integer	Hard trim the input Read 1 to this length before analysis
--r2_length	integer	Hard trim the input Read 2 to this length before analysis
--filter_probes	boolean	Whether to filter the probe set using the "included" column
--custom_bin_size	integer	Bin Visium HD data to an additional custom size in microns (4-100, even).
--include_introns	boolean	Include intronic reads in the count. When unset, Space Ranger applies its own default (true for Visium HD 3' and Visium v1, false otherwise).
--nucleus_segmentation	boolean	Enable or disable nucleus/cell segmentation (on by default when an H&E image is given).
--cell_annotation_model	string	Cloud-based cell type annotation model to use, which requires `--tenx_cloud_token_path`. When left out, Space Ranger still annotates human samples with the bundled Pan-Human Azimuth model, which runs locally and needs no token.
--tenx_cloud_token_path	file	Path to a 10x Cloud token JSON, required for cloud-based annotation models.
--disable_cell_annotation	boolean_true	Disable cell type annotation.

Name

Type & Properties

--create_bam

boolean

--nosecondary

boolean_true

--r1_length

integer

--r2_length

integer

--filter_probes

boolean

--custom_bin_size

integer

--include_introns

boolean

--nucleus_segmentation

boolean

--cell_annotation_model

string

--tenx_cloud_token_path

file

--disable_cell_annotation

boolean_true

Segmentation Options

Name	Type & Properties	Description
--custom_segmentation_file	file	Custom nucleus segmentation mask to use instead of the built-in algorithm. Requires --nucleus_expansion_distance_micron.
--nucleus_expansion_distance_micron	double	Distance in microns to expand each nucleus to approximate the cell boundary.
--max_nucleus_diameter_px	integer	Maximum nucleus diameter in pixels, for samples with exceptionally large cells.
--umi_registration	boolean	Enable or disable UMI-based registration that aligns the microscope image to the UMI count data for Visium HD. When unset, Space Ranger applies its default.
--umi_to_image_offset	string	Supply a custom offset (as accepted by Space Ranger) to override UMI-to-image registration when automatic convergence is incorrect.

Name

Type & Properties

--custom_segmentation_file

file

--nucleus_expansion_distance_micron

double

--max_nucleus_diameter_px

integer

--umi_registration

boolean

--umi_to_image_offset

string

Run this component

Run the following command to execute this component with Nextflow:

cat > params.yaml <<'EOM'  
id: "run"  
output_raw: "$id.$key.output_raw.output_dir"  
output_spatialdata: "$id.$key.output_spatialdata.zarr"  
mode: [ "segmented_cells" ]  
bin_size: [ 8 ]  
output_type: [ "filtered" ]  
reorient_images: [ true ]  
create_bam: [ false ]  
filter_probes: [ true ]  
publish_dir: "output/"  
EOM

nextflow run https://packages.viash-hub.com/vsh/openpipeline_spatial.git \  
  -revision v0.6.0 \  
  -main-script target/nextflow/workflows/ingestion/spaceranger_hd_mapping/main.nf \  
  -params-file params.yaml

workflows/ingestion/spaceranger_hd_mapping

Inputs

Outputs

Slide Information

Image Options

SpaceRanger arguments

Segmentation Options

Run this component

Relationships

Used by

Uses