name: "spaceranger_mapping"
namespace: "workflows/ingestion"
scope: "public"
description: "A pipeline for running SpaceRanger mapping."
info:
  name: SpaceRanger mapping
  test_dependencies:
    - name: spaceranger_mapping_test
      namespace: test_workflows/ingestion
authors:
  - __merge__: /src/authors/dorien_roosen.yaml
    roles: [ maintainer ]
  - __merge__: /src/authors/weiwei_schultz.yaml
    roles: [ contributor ]

argument_groups:
  - name: Inputs
    arguments:
      - name: "--id"
        required: true
        type: string
        description: ID of the sample.
        example: foo
      - name: --input
        type: file
        required: true
        multiple: true
        description: | 
          The fastq.gz files to align. 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

          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)

        example: [ "sample_S1_L001_R1_001.fastq.gz", "sample_S1_L001_R2_001.fastq.gz" ]
      - name: --gex_reference
        type: file
        required: true
        description: Path of folder containing 10x-compatible reference
        example: "/path/to/refdata-gex-GRCh38-2020-A"
      - name: --probe_set
        type: file
        required: true
        description: CSV file specifying the probe set used
        example: "Visium_Human_Transcriptome_Probe_Set_v2.0_GRCh38-2020-A.csv"
      - name: --cytaimage
        type: file
        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"
      - name: --image
        type: file
        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:
      - name: "--output_raw"
        type: file
        direction: output
        description: "Location where the output folder from Cell Ranger will be stored."
        required: true
        example: output_dir/
      - name: "--output_h5mu"
        type: file
        direction: output
        description: "The output from Cell Ranger, converted to h5mu."
        required: true
        example: output.h5mu
      - name: "--output_type"
        type: string
        description: "Which Cell Ranger output to use for converting to h5mu."
        choices: [ raw, filtered ]
        default: raw
      - name: "--uns_metrics"
        type: string
        description: Name of the .uns slot under which to QC metrics (if any).
        default: "metrics_summary"
      - name: "--uns_probe_set"
        type: string
        description: Name of the .uns slot under which to store probe set information (if any).
        default: "probe_set"
      - name: "--obsm_coordinates"
        type: string
        description: Name of the .obsm slot under which to store the cell centroid coordinates.
        default: "spatial"
      - name: "--output_compression"
        type: string
        description: Compression to use when writing the h5mu file.
        choices: [ gzip, lzf ]

  - name: Image Options
    arguments:
      - name: --darkimage
        type: file   
        description: Multi-channel, dark-background fluorescence image
        required: false
        example: "fluorescence.tif"
      - name: --colorizedimage
        type: file
        description: Color image representing pre-colored dark-background fluorescence images
        required: false
        example: "colored_fluorescence.tif"
      - name: --dapi_index
        type: integer
        description: Index of DAPI channel (1-indexed) of fluorescence image
        required: false
        example: 1
        min: 1
      - name: --image_scale
        type: double
        description: Microns per microscope image pixel
        required: false
        example: 0.65
        min: 0.01
        max: 10
      - name: --reorient_images
        type: boolean
        default: true
        description: Whether to rotate and mirror image to align fiducial pattern
  
  - name: Slide Information
    arguments:
      - name: --slide
        type: string
        description: Visium slide serial number (e.g., 'V10J25-015')
        required: false
        example: "V10J25-015"
      - name: --area
        type: string
        description: Visium capture area identifier (e.g., 'A1')
        required: false
        example: "A1"
      - name: --unknown_slide
        type: string
        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]
      - name: --slidefile
        type: file
        description: Slide design file for offline use
        required: false
        example: "slide_design.gpr"
      - name: --override_id
        type: boolean_true
        description: Overrides the slide serial number and capture area provided in the Cytassist image metadata
  
  - name: SpaceRanger arguments
    arguments:
      - name: --create_bam
        type: boolean
        required: true
        description: Enable or disable BAM file generation
        default: true
      - name: --nosecondary
        type: boolean_true
        description: Disable secondary analysis (e.g., clustering)
      - name: --r1_length
        type: integer
        required: false
        description: Hard trim the input Read 1 to this length before analysis
        min: 1
      - name: --r2_length
        type: integer
        required: false
        description: Hard trim the input Read 2 to this length before analysis
        min: 1
      - name: --filter_probes
        type: boolean
        default: true
        description: Whether to filter the probe set using the "included" column
      - name: --custom_bin_size
        type: integer
        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

dependencies:
  - name: mapping/spaceranger_count
  - name: convert/from_spaceranger_to_h5mu

resources:
  - type: nextflow_script
    path: main.nf
    entrypoint: run_wf
  - type: file
    path: /src/workflows/utils/
test_resources:
  - type: nextflow_script
    path: test.nf
    entrypoint: test_wf
  - path: /resources_test/visium
  - path: /resources_test/GRCh38
runners:
  - type: nextflow