Update xenium ranger modules and subworkflows

modules/nf-core/xeniumranger/Dockerfile

@@ -10,20 +10,20 @@ RUN apt-get update --allow-releaseinfo-change \
 
 # copy over xeniumranger
 # the latest version of the xeniumranger tool has been downloaded from https://www.10xgenomics.com/support/software/xenium-ranger/downloads
-COPY xeniumranger-3.0.1.tar.gz /xeniumranger-3.0.1.tar.gz
+COPY xeniumranger-4.0.0.tar.gz /xeniumranger-4.0.0.tar.gz
 
 # install xenium ranger
-RUN tar -xzvf /xeniumranger-3.0.1.tar.gz && \
-    rm /xeniumranger-3.0.1.tar.gz
+RUN tar -xzvf /xeniumranger-4.0.0.tar.gz && \
+    rm /xeniumranger-4.0.0.tar.gz
 
 # Set environment variables
-# ENV PATH="xeniumranger-xenium3.0/bin:$PATH"
+# ENV PATH="xeniumranger-xenium4.0/bin:$PATH"
 
 # multistage to reduce image size
 FROM ubuntu:20.04
 
 # Set environment variables
-ENV PATH="/xeniumranger-xenium3.0/bin:$PATH"
+ENV PATH="/xeniumranger-xenium4.0/bin:$PATH"
 
 # copy over xenium from builder
-COPY --from=builder /xeniumranger-xenium3.0 /xeniumranger-xenium3.0/
+COPY --from=builder /xeniumranger-xenium4.0 /xeniumranger-xenium4.0/

modules/nf-core/xeniumranger/README.md

@@ -5,7 +5,7 @@ Xenium Ranger is a commercial tool from 10X Genomics. The container provided for
 1. Navigate to the appropriate download page. - [Xenium Ranger](https://www.10xgenomics.com/support/software/xenium-ranger/downloads): download the tar ball of the desired Xenium Ranger version with `curl` or `wget`. Place this file in the same folder where the Dockerfile lies.
 
 2. Edit the Dockerfile. Update the Xenium Ranger versions in this line:
-   (current version for xenium ranger is fixated at [3.0.1](https://www.10xgenomics.com/support/software/xenium-ranger/downloads) in the dockerfile)
+   (current version for xenium ranger is fixated at [4.0.0](https://www.10xgenomics.com/support/software/xenium-ranger/downloads) in the dockerfile)
 
 3. Create and test the container:
 

modules/nf-core/xeniumranger/import-segmentation/main.nf

@@ -2,80 +2,67 @@ process XENIUMRANGER_IMPORT_SEGMENTATION {
     tag "$meta.id"
     label 'process_high'
 
-    container "nf-core/xeniumranger:3.0.1"
+    container "nf-core/xeniumranger:4.0"
 
     input:
-    tuple val(meta), path(xenium_bundle)
-    val(expansion_distance)
-    path(coordinate_transform)
-    path(nuclei)
-    path(cells)
-    path(transcript_assignment)
-    path(viz_polygons)
+    tuple val(meta), path(xenium_bundle, stageAs: "bundle/"), path(transcript_assignment), path(viz_polygons), path(nuclei), path(cells), path(coordinate_transform), val(units)
 
     output:
-    tuple val(meta), path("**/outs/**"), emit: outs
-    path "versions.yml", emit: versions
+    tuple val(meta), path("${prefix}"), emit: outs
+    tuple val("${task.process}"), val("xeniumranger"), eval("xeniumranger -V | sed -e 's/.*xenium-//'"), emit: versions_xeniumranger, topic: versions
 
     when:
     task.ext.when == null || task.ext.when
 
     script:
+
     // Exit if running this module with -profile conda / -profile mamba
     if (workflow.profile.tokenize(',').intersect(['conda', 'mamba']).size() >= 1) {
-        error "XENIUMRANGER_IMPORT-SEGMENTATION module does not support Conda. Please use Docker / Singularity / Podman instead."
+        error "XENIUMRANGER_IMPORT_SEGMENTATION module does not support Conda. Please use Docker / Singularity / Podman instead."
     }
-    def args = task.ext.args ?: ''
-    def prefix = task.ext.prefix ?: "${meta.id}"
 
-    // image based segmentation options
-    def expansion_distance = expansion_distance ? "--expansion-distance=\"${expansion_distance}\"": "" // expansion distance (default - 5, range - 0 - 100)
-    def coordinate_transform = coordinate_transform ? "--coordinate-transform=\"${coordinate_transform}\"": ""
+    prefix = task.ext.prefix ?: "${meta.id}"
 
-    def nuclei_detection = nuclei ? "--nuclei=\"${nuclei}\"": ""
-    def cells = cells ? "--cells=\"${cells}\"": ""
+    // nuclei and cells are for image segmentation results
+    // transcript_assignment and viz_polygons are for transcript assignment results
+    // they are mutually exclusive
+    if ((nuclei || cells) && (transcript_assignment || viz_polygons)) {
+        error "--nuclei and --cells are for image segmentation results, which are mutually exclusive with --transcript-assignment and --viz-polygons for transcript assignment results. Please use only one of them."
+    }
 
-    // transcript based segmentation
-    def transcript_assignment = transcript_assignment ? "--transcript-assignment=\"${transcript_assignment}\"": ""
-    def viz_polygons = viz_polygons ? "--viz-polygons=\"${viz_polygons}\"":""
+    def assembled_args = []
+    if (task.ext.args) { assembled_args << task.ext.args.trim() }
+    if (nuclei) { assembled_args << "--nuclei=\"${nuclei}\"" }
+    if (cells) { assembled_args << "--cells=\"${cells}\"" }
+    if (transcript_assignment) { assembled_args << "--transcript-assignment=\"${transcript_assignment}\"" }
+    if (viz_polygons) { assembled_args << "--viz-polygons=\"${viz_polygons}\"" }
+    if (coordinate_transform) {
+        assembled_args << "--coordinate-transform=\"${coordinate_transform}\""
+        // if coordinate_transform is provided, units must be microns
+        assembled_args << "--units=\"microns\""
+    } else if (units) {
+        assembled_args << "--units=\"${units}\""
+    }
 
-    // shared argument
-    def units = coordinate_transform ? "--units=microns": "--units=pixels"
+    def args = assembled_args ? assembled_args.join(" \\\n        ") : ""
 
     """
     xeniumranger import-segmentation \\
-        --id="${prefix}" \\
+        --id="XENIUMRANGER_IMPORT_SEGMENTATION" \\
         --xenium-bundle="${xenium_bundle}" \\
         --localcores=${task.cpus} \\
         --localmem=${task.memory.toGiga()} \\
-        ${coordinate_transform} \\
-        ${nuclei_detection} \\
-        ${cells} \\
-        ${expansion_distance} \\
-        ${transcript_assignment} \\
-        ${viz_polygons} \\
-        ${units} \\
         ${args}
 
-    cat <<-END_VERSIONS > versions.yml
-    "${task.process}":
-        xeniumranger: \$(xeniumranger -V | sed -e "s/xeniumranger-/- /g")
-    END_VERSIONS
+    rm -rf "${prefix}"
+    mv XENIUMRANGER_IMPORT_SEGMENTATION/outs "${prefix}"
     """
 
     stub:
-    // Exit if running this module with -profile conda / -profile mamba
-    if (workflow.profile.tokenize(',').intersect(['conda', 'mamba']).size() >= 1) {
-        error "XENIUMRANGER_IMPORT-SEGMENTATION module does not support Conda. Please use Docker / Singularity / Podman instead."
-    }
-    def prefix = task.ext.prefix ?: "${meta.id}"
+    prefix = task.ext.prefix ?: "${meta.id}"
     """
-    mkdir -p "${prefix}/outs/"
-    touch "${prefix}/outs/fake_file.txt"
-
-    cat <<-END_VERSIONS > versions.yml
-    "${task.process}":
-        xeniumranger: \$(xeniumranger -V | sed -e "s/xeniumranger-/- /g")
-    END_VERSIONS
+    mkdir -p "${prefix}"
+    touch "${prefix}/experiment.xenium"
     """
+
 }

modules/nf-core/xeniumranger/import-segmentation/meta.yml

@@ -1,9 +1,14 @@
 name: xeniumranger_import_segmentation
-description: The xeniumranger import-segmentation module allows you to specify 2D
-  nuclei and/or cell segmentation results for assigning transcripts to cells and recalculate
-  all Xenium Onboard Analysis (XOA) outputs that depend on segmentation. Segmentation
-  results can be generated by community-developed tools or prior Xenium segmentation
-  result.
+description: |
+  The xeniumranger import-segmentation module runs `xeniumranger import-segmentation`
+  to recompute Xenium Onboard Analysis outputs using external segmentation results.
+  It supports two execution modes mirroring the Xenium Ranger CLI: an image-based
+  mode that accepts nuclei and/or cell masks (TIFF/NPY) or GeoJSON polygons together
+  with optional coordinate transforms and unit definitions, and a transcript-based
+  mode that ingests Baysor-style transcript assignment CSV files plus visualization
+  polygons. Use the image-based inputs when providing label masks or polygons, or
+  switch to the transcript-based inputs when supplying transcript-level assignments
+  so the appropriate command-line arguments are passed to Xenium Ranger.
 keywords:
   - spatial
   - segmentation
@@ -28,66 +33,109 @@ input:
         type: map
         description: |
           Groovy Map containing run information
-          e.g. [id:'xenium_bundle_path']
+          e.g. [ id:'xenium_sample' ]
     - xenium_bundle:
         type: directory
-        description: Path to the xenium output bundle generated by the Xenium Onboard
-          Analysis pipeline
-  - expansion_distance:
-      type: integer
-      description: Nuclei boundary expansion distance in µm. Only for use when nucleus
-        segmentation provided as input. Default-5 (accepted range 0 - 100)
-  - coordinate_transform:
-      type: file
-      description: Image alignment file containing similarity transform matrix e.g.,
-        the _imagealignment.csv file exported from Xenium Explorer
-      ontologies: []
-  - nuclei:
-      type: file
-      description: |
-        Label mask (TIFF or NPY), polygons of nucleus segmentations (GeoJSON FeatureCollection), or Xenium Onboard Analysis cells.zarr.zip (the nucleus masks as input).
-        --nuclei will use nucleusGeometry polygon if it exists in the GeoJSON (i.e., for QuPath-like GeoJSON files),
-        or geometry if it does not. Error if --transcript-assignment argument is used.
-      ontologies: []
-  - cells:
-      type: file
-      description: |
-        Label mask (TIFF or NPY), polygons of cell segmentations (GeoJSON FeatureCollection), or Xenium Onboard Analysis cells.zarr.zip (the cell masks as input).
-        Features with a non-cell objectType will be ignored. Error if --transcript-assignment argument is used.
-        In Xenium Ranger v2.0, --nuclei no longer needs to be used with --cells.
-      ontologies: []
-  - transcript_assignment:
-      type: file
-      description: |
-        Transcript CSV with cell assignment from Baysor v0.6. Error if --cells or --nuclei arguments are used.
-      ontologies: []
-  - viz_polygons:
-      type: file
-      description: |
-        Cell boundary polygons (GeoJSON) for visualization from Baysor v0.6. Required if --transcript-assignment argument used. Error if --cells or --nuclei arguments used.
-      ontologies: []
+        description: Path to the Xenium output bundle generated by the Xenium
+          Onboard Analysis pipeline
+    - transcript_assignment:
+        type: file
+        optional: true
+        description: |
+          Transcript assignment CSV with cell assignment, such as from Baysor v0.6, (transcript-based mode).
+          Mutually exclusive with image-based inputs (`nuclei`, `cells`). Required when using
+          transcript-based mode. Passed to `--transcript-assignment`.
+        pattern: "*.csv"
+        ontologies:
+          - edam: http://edamontology.org/format_3752 # CSV
+    - viz_polygons:
+        type: file
+        optional: true
+        description: |
+          Cell boundary polygons (GeoJSON) for visualization, such as from Baysor v0.6 (transcript-based mode).
+          Mutually exclusive with image-based inputs (`nuclei`, `cells`). Required when using
+          `transcript_assignment`. Passed to `--viz-polygons`.
+        pattern: "*.{json,geojson}"
+        ontologies:
+          - edam: http://edamontology.org/format_3464 # JSON
+    - nuclei:
+        type: file
+        optional: true
+        description: |
+          Nucleus segmentation input as label mask (TIFF/NPY), polygons (GeoJSON), or Xenium Onboard
+          Analysis cells.zarr.zip (image-based mode).
+          Mutually exclusive with transcript-based inputs
+          (`transcript_assignment`, `viz_polygons`). Passed to `--nuclei`.
+        pattern: "*.{tif,tiff,npy,json,geojson,zarr.zip}"
+        ontologies:
+          - edam: http://edamontology.org/format_4003 # NumPy format
+          - edam: http://edamontology.org/format_3464 # JSON
+    - cells:
+        type: file
+        optional: true
+        description: |
+          Cell segmentation input as label mask (TIFF/NPY), polygons (GeoJSON), or Xenium Onboard
+          Analysis cells.zarr.zip (image-based mode).
+          Mutually exclusive with transcript-based inputs
+          (`transcript_assignment`, `viz_polygons`). Passed to `--cells`.
+        pattern: "*.{tif,tiff,npy,json,geojson,zarr.zip}"
+        ontologies:
+          - edam: http://edamontology.org/format_4003 # NumPy format
+          - edam: http://edamontology.org/format_3464 # JSON
+    - coordinate_transform:
+        type: file
+        optional: true
+        description: |
+          Image alignment file containing similarity transform matrix (e.g., `_imagealignment.csv` from
+          Xenium Explorer). Only used with image-based mode inputs (`nuclei`, `cells`). `units` will be automatically set to "microns". Passed to `--coordinate-transform`.
+        pattern: "*.csv"
+        ontologies:
+          - edam: http://edamontology.org/format_3752 # CSV
+    - units:
+        type: string
+        optional: true
+        description: |
+          Units for segmentation results. Must be one of two options: "microns" (physical space) or
+          "pixels" (pixel space). Can be used with both image-based and transcript-based modes.
+          Default: "pixels". Must be "microns" if `coordinate_transform` is used. For Baysor v0.6
+          inputs, must be "microns". Passed to `--units`.
+        enum:
+          - "microns"
+          - "pixels"
 output:
   outs:
     - - meta:
-          type: file
-          description: Files containing the outputs of Cell Ranger, see official 10X
-            Genomics documentation for a complete list
-          pattern: "${meta.id}/outs/*"
-          ontologies: []
-      - "**/outs/**":
-          type: file
-          description: Files containing the outputs of xenium ranger, see official 10X
-            Genomics documentation for a complete list of outputs
-          pattern: "${meta.id}/outs/*"
-          ontologies: []
+          type: map
+          description: Groovy Map containing sample information e.g. [ id:'test' ]
+      - ${prefix}:
+          type: directory
+          description: Directory containing the output xenium bundle of Xenium
+            Ranger
+          pattern: "${prefix}"
+  versions_xeniumranger:
+    - - ${task.process}:
+          type: string
+          description: The process the versions were collected from
+      - xeniumranger:
+          type: string
+          description: The tool name
+      - xeniumranger -V | sed -e 's/.*xenium-//':
+          type: string
+          description: The command used to generate the version of the tool
+topics:
   versions:
-    - versions.yml:
-        type: file
-        description: File containing software versions
-        pattern: "versions.yml"
-        ontologies:
-          - edam: http://edamontology.org/format_3750 # YAML
+    - - ${task.process}:
+          type: string
+          description: The process the versions were collected from
+      - xeniumranger:
+          type: string
+          description: The tool name
+      - xeniumranger -V | sed -e 's/.*xenium-//':
+          type: string
+          description: The command used to generate the version of the tool
 authors:
   - "@khersameesh24"
+  - "@dongzehe"
 maintainers:
   - "@khersameesh24"
+  - "@dongzehe"