name: spaceranger_count
namespace: mapping
description: Count gene expression and protein expression reads from a single capture area.
keywords: [spaceranger]
links:
  documentation: https://www.10xgenomics.com/support/software/space-ranger/latest/analysis/running-pipelines/space-ranger-count
authors:
  - __merge__: /src/authors/jakub_majercik.yaml
    roles: [ author ]
argument_groups:
  - name: Inputs
    arguments:
      - type: file
        name: --gex_reference
        required: true
        description: Path of folder containing 10x-compatible reference
        example: "/path/to/refdata-gex-GRCh38-2020-A"

      - type: file
        name: --input
        required: true
        description: | 
          Path to a directory containing input FASTQ data. Individual FASTQ files should follow the naming convention of 10x Genomics:
          [Sample Name]_S[Sample Number]_L[Lane Number]_[Read Type]_001.fastq.gz

          Where:
          [Sample Name] is the name assigned during sample preparation/sequencing
          S[Sample Number] is the sample index (usually S1, S2, etc.)
          L[Lane Number] identifies the sequencing lane (L001, L002, etc.)

          [Read Type] will be one of:
          R1 - Read 1 (contains the spatial barcode and UMI)
          R2 - Read 2 (contains the actual cDNA sequence)
          I1 - Index Read 1 (if applicable)
          I2 - Index Read 2 (if applicable)
        example: "/path/to/fastq_folder"

      - type: file
        name: --probe_set
        required: true
        description: CSV file specifying the probe set used
        example: "Visium_Human_Transcriptome_Probe_Set_v2.0_GRCh38-2020-A.csv"

      - type: file
        name: --cytaimage
        required: false
        description: | 
          Brightfield image generated by the CytAssist instrument. 
          When using CytAssist workflow, either this or --image must be provided.
        example: "cyta_image.tif"

      - type: file
        name: --image
        required: false
        description: | 
          H&E or fluorescence microscope image in TIFF or JPG format. 
          Required for standard Visium workflow, optional when using --cytaimage for CytAssist workflow.
        example: "brightfield.tif"

  - name: Outputs
    arguments:
      - type: file
        name: --output
        required: true
        direction: output
        description: The folder to store the alignment results
        example: "/path/to/output"

  - name: Slide Information
    arguments:
      - type: string
        name: --slide
        description: Visium slide serial number (e.g., 'V10J25-015')
        required: false
        example: "V10J25-015"

      - type: string
        name: --area
        description: Visium capture area identifier (e.g., 'A1')
        required: false
        example: "A1"

      - type: string
        name: --unknown_slide
        description: | 
          Use this option if the slide serial number and area were entered incorrectly on the CytAssist 
          instrument and the correct values are unknown. Not compatible with --slide, --area, or 
          --slide-file options
        required: false
        choices: [visium-1, visium-2, visium-2-large, visium-hd]

      - type: file
        name: --slidefile
        description: Slide design file for offline use
        required: false
        example: "slide_design.gpr"

      - type: boolean_true
        name: --override_id
        description: Overrides the slide serial number and capture area provided in the Cytassist image metadata

  - name: Image Options
    arguments:
      - type: file
        name: --darkimage
        description: Multi-channel, dark-background fluorescence image
        required: false
        example: "fluorescence.tif"

      - type: file
        name: --colorizedimage
        description: Color image representing pre-colored dark-background fluorescence images
        required: false
        example: "colored_fluorescence.tif"

      - type: integer
        name: --dapi_index
        description: Index of DAPI channel (1-indexed) of fluorescence image
        required: false
        example: 1
        min: 1

      - type: double
        name: --image_scale
        description: Microns per microscope image pixel
        required: false
        example: 0.65
        min: 0.01
        max: 10

      - type: boolean
        name: --reorient_images
        default: true
        description: Whether to rotate and mirror image to align fiducial pattern

  - name: Processing Options
    arguments:
      - type: boolean
        name: --create_bam
        required: true
        description: Enable or disable BAM file generation
        default: true

      - type: boolean_true
        name: --nosecondary
        description: Disable secondary analysis (e.g., clustering)

      - type: integer
        name: --r1_length
        required: false
        description: Hard trim the input Read 1 to this length before analysis
        min: 1

      - type: integer
        name: --r2_length
        required: false
        description: Hard trim the input Read 2 to this length before analysis
        min: 1

      - type: boolean
        name: --filter_probes
        default: true
        description: Whether to filter the probe set using the "included" column

      - type: integer
        name: --custom_bin_size
        description: Bin Visium HD data to specified size in microns (4-100, even values only) in addition to the standard binning size (2 µm, 8 µm, 16 µm)
        min: 4
        max: 100

  - name: Input Selection
    arguments:
      - type: string
        name: --project
        required: false
        description: Project folder name within mkfastq output
        
      - type: string
        name: --sample
        required: false
        description: Prefix of FASTQ filenames to select

      - type: integer
        name: --lanes
        multiple: true
        required: false
        description: Only use FASTQs from selected lanes
        example: [1,2,3]

resources:
  - type: bash_script
    path: script.sh
test_resources:
  - type: bash_script
    path: test.sh
  - path: /resources_test/visium
  - path: /resources_test/GRCh38
engines:
  - type: docker
    image: ghcr.io/data-intuitive/spaceranger:3.1
    setup:
      - type: docker
        run: |
          DEBIAN_FRONTEND=noninteractive apt update && \
          apt upgrade -y && apt install -y procps && rm -rf /var/lib/apt/lists/*
runners:
  - type: executable
  - type: nextflow