name: "bd_rhapsody"
namespace: "workflows/ingestion"
scope: "public"
info:
  name: "BD Rhapsody"
  test_dependencies:
    - name: bd_rhapsody_test
      namespace: test_workflows/ingestion
description: |
    BD Rhapsody Sequence Analysis CWL pipeline v2.2.1

    This pipeline performs analysis of single-cell multiomic sequence read (FASTQ) data. The supported
    sequencing libraries are those generated by the BD Rhapsody assay kits, including: Whole Transcriptome
    mRNA, Targeted mRNA, AbSeq Antibody-Oligonucleotides, Single-Cell Multiplexing, TCR/BCR, and
    ATAC-Seq

    The CWL pipeline file is obtained by cloning 'https://bitbucket.org/CRSwDev/cwl' and removing all objects with class 'DockerRequirement' from the YAML.
  
authors:
  - __merge__: /src/authors/robrecht_cannoodt.yaml
    roles: [ maintainer ]
  - __merge__: /src/authors/dorien_roosen.yaml
    roles: [ author ]

argument_groups:
- name: Inputs
  arguments:
    - name: "--reads"
      type: file
      description: |
        Reads (optional) - Path to your FASTQ.GZ formatted read files from libraries that may include:
          
        - WTA mRNA
        - Targeted mRNA
        - AbSeq
        - Sample Multiplexing
        - VDJ
          
        You may specify as many R1/R2 read pairs as you want.
      required: false
      multiple: true
      example:
        - WTALibrary_S1_L001_R1_001.fastq.gz
        - WTALibrary_S1_L001_R2_001.fastq.gz
      info:
        config_key: Reads
    - name: "--reads_atac"
      type: file
      description: |
        Path to your FASTQ.GZ formatted read files from ATAC-Seq libraries.
        You may specify as many R1/R2/I2 files as you want.
      required: false
      multiple: true
      example:
        - ATACLibrary_S2_L001_R1_001.fastq.gz
        - ATACLibrary_S2_L001_R2_001.fastq.gz
        - ATACLibrary_S2_L001_I2_001.fastq.gz
      info:
        config_key: Reads_ATAC
- name: References
  description: |
    Assay type will be inferred from the provided reference(s).
    Do not provide both reference_archive and targeted_reference at the same time.
      
    Valid reference input combinations:
      - reference_archive: WTA only
      - reference_archive & abseq_reference: WTA + AbSeq
      - reference_archive & supplemental_reference: WTA + extra transgenes
      - reference_archive & abseq_reference & supplemental_reference: WTA + AbSeq + extra transgenes
      - reference_archive: WTA + ATAC or ATAC only
      - reference_archive & supplemental_reference: WTA + ATAC + extra transgenes
      - targeted_reference: Targeted only
      - targeted_reference & abseq_reference: Targeted + AbSeq
      - abseq_reference: AbSeq only

    The reference_archive can be generated with the `reference/build_bdrhap_reference` component.
    Alternatively, BD also provides standard references which can be downloaded from these locations:

      - Human: https://bd-rhapsody-public.s3.amazonaws.com/Rhapsody-WTA/Pipeline-version2.x_WTA_references/RhapRef_Human_WTA_2023-02.tar.gz
      - Mouse: https://bd-rhapsody-public.s3.amazonaws.com/Rhapsody-WTA/Pipeline-version2.x_WTA_references/RhapRef_Mouse_WTA_2023-02.tar.gz

  arguments:
    - name: "--reference_archive"
      type: file
      description: |
        Path to Rhapsody WTA Reference in the tar.gz format.

        Structure of the reference archive:
          
        - `BD_Rhapsody_Reference_Files/`: top level folder
          - `star_index/`: sub-folder containing STAR index, that is files created with `STAR --runMode genomeGenerate`
          - GTF for gene-transcript-annotation e.g. "gencode.v43.primary_assembly.annotation.gtf"
      example: "RhapRef_Human_WTA_2023-02.tar.gz"
      required: false
      info:
        config_key: Reference_Archive
    - name: "--targeted_reference"
      type: file
      description: |
        Path to the targeted reference file in FASTA format.
      example: "BD_Rhapsody_Immune_Response_Panel_Hs.fasta"
      multiple: true
      info:
        config_key: Targeted_Reference
    - name: "--abseq_reference"
      type: file
      description: Path to the AbSeq reference file in FASTA format.  Only needed if BD AbSeq Ab-Oligos are used.
      example: "AbSeq_reference.fasta"
      multiple: true
      info:
        config_key: AbSeq_Reference
    - name: "--supplemental_reference"
      type: file
      alternatives: [-s]
      description: Path to the supplemental reference file in FASTA format.  Only needed if there are additional transgene sequences to be aligned against in a WTA assay experiment.
      example: "supplemental_reference.fasta"
      multiple: true
      info:
        config_key: Supplemental_Reference
- name: Outputs
  description: Outputs
  arguments:
    - name: "--output"
      type: file
      direction: output
      description: "The processed output file in h5mu format."
      example: output.h5mu
      required: true
    - name: "--output_raw"
      type: file
      direction: output
      alternatives: [-o]
      description: "The unprocessed output directory containing all the outputs from the pipeline."
      required: true
      example: output_dir/
- name: Putative Cell Calling Settings
  arguments:
    - name: "--cell_calling_data"
      type: string
      description: |
        Specify the dataset to be used for putative cell calling: mRNA, AbSeq, ATAC, mRNA_and_ATAC
          
        For putative cell calling using an AbSeq dataset, please provide an AbSeq_Reference fasta file above.
          
        For putative cell calling using an ATAC dataset, please provide a WTA+ATAC-Seq Reference_Archive file above.
          
        The default data for putative cell calling, will be determined the following way:
          
        - If mRNA Reads and ATAC Reads exist: mRNA_and_ATAC
        - If only ATAC Reads exist: ATAC
        - Otherwise: mRNA
      choices: [mRNA, AbSeq, ATAC, mRNA_and_ATAC]
      example: mRNA
      info:
        config_key: Cell_Calling_Data
    - name: "--cell_calling_bioproduct_algorithm"
      type: string
      description: |
        Specify the bioproduct algorithm to be used for putative cell calling: Basic or Refined
          
        By default, the Basic algorithm will be used for putative cell calling.
      choices: [Basic, Refined]
      example: Basic
      info:
        config_key: Cell_Calling_Bioproduct_Algorithm
    - name: "--cell_calling_atac_algorithm"
      type: string
      description: |
        Specify the ATAC-seq algorithm to be used for putative cell calling: Basic or Refined
          
        By default, the Basic algorithm will be used for putative cell calling.
      choices: [Basic, Refined]
      example: Basic
      info:
        config_key: Cell_Calling_ATAC_Algorithm
    - name: "--exact_cell_count"
      type: integer
      description: |
        Set a specific number of cells as putative, based on those with the highest error-corrected read count
      example: 10000
      min: 1
      info:
        config_key: Exact_Cell_Count
    - name: "--expected_cell_count"
      type: integer
      description: |
        Guide the basic putative cell calling algorithm by providing an estimate of the number of cells expected.  Usually this can be the number of cells loaded into the Rhapsody cartridge.  If there are multiple inflection points on the second derivative cumulative curve, this will ensure the one selected is near the expected. 
      example: 20000
      min: 1
      info:
        config_key: Expected_Cell_Count
- name: Intronic Reads Settings
  arguments:
    - name: --exclude_intronic_reads
      type: boolean
      description: |
        By default, the flag is false, and reads aligned to exons and introns are considered and represented in molecule counts. When the flag is set to true, intronic reads will be excluded.
        The value can be true or false.
      example: false
      info:
        config_key: Exclude_Intronic_Reads
- name: Multiplex Settings
  arguments:
    - name: "--sample_tags_version"
      type: string
      description: |
        Specify the version of the Sample Tags used in the run:

        * If Sample Tag Multiplexing was done, specify the appropriate version: human, mouse, flex, nuclei_includes_mrna, nuclei_atac_only
        * If this is an SMK + Nuclei mRNA run or an SMK + Multiomic ATAC-Seq (WTA+ATAC-Seq) run (and not an SMK + ATAC-Seq only run), choose the "nuclei_includes_mrna" option.
        * If this is an SMK + ATAC-Seq only run (and not SMK + Multiomic ATAC-Seq (WTA+ATAC-Seq)), choose the "nuclei_atac_only" option.
      choices: [human, mouse, flex, nuclei_includes_mrna, nuclei_atac_only]
      example: human
      info:
        config_key: Sample_Tags_Version
    - name: "--tag_names"
      type: string
      description: |
        Specify the tag number followed by '-' and the desired sample name to appear in Sample_Tag_Metrics.csv
        Do not use the special characters.
      multiple: true
      example: [4-mySample, 9-myOtherSample, 6-alsoThisSample]
      info:
        config_key: Tag_Names
- name: VDJ arguments
  arguments:
    - name: "--vdj_version"
      type: string
      description: |
        If VDJ was done, specify the appropriate option: human, mouse, humanBCR, humanTCR, mouseBCR, mouseTCR
      choices: [human, mouse, humanBCR, humanTCR, mouseBCR, mouseTCR]
      example: human
      info:
        config_key: VDJ_Version
- name: ATAC options
  arguments:
    - name: "--predefined_atac_peaks"
      type: file
      description: An optional BED file containing pre-established chromatin accessibility peak regions for generating the ATAC cell-by-peak matrix.
      example: predefined_peaks.bed
      info:
        config_key: Predefined_ATAC_Peaks
- name: Additional options
  arguments:
    - name: "--run_name"
      type: string
      description: |
        Specify a run name to use as the output file base name. Use only letters, numbers, or hyphens. Do not use special characters or spaces.
      default: sample
      info:
        config_key: Run_Name
    - name: "--generate_bam"
      type: boolean
      description: |
        Specify whether to create the BAM file output
      default: false
      info:
        config_key: Generate_Bam
    - name: "--long_reads"
      type: boolean
      description: |
        Use STARlong (default: undefined - i.e. autodetects based on read lengths) - Specify if the STARlong aligner should be used instead of STAR. Set to true if the reads are longer than 650bp.
      info:
        config_key: Long_Reads
- name: Advanced options
  description: |
    NOTE: Only change these if you are really sure about what you are doing
  arguments:
    - name: "--custom_star_params"
      type: string
      description: |
        Modify STAR alignment parameters - Set this parameter to fully override default STAR mapping parameters used in the pipeline.
        For reference this is the default that is used:

          Short Reads: `--outFilterScoreMinOverLread 0 --outFilterMatchNminOverLread 0 --outFilterMultimapScoreRange 0 --clip3pAdapterSeq AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA --seedSearchStartLmax 50 --outFilterMatchNmin 25 --limitOutSJcollapsed 2000000`
          Long Reads: Same as Short Reads + `--seedPerReadNmax 10000`

        This applies to fastqs provided in the Reads user input 
        Do NOT set any non-mapping related params like `--genomeDir`, `--outSAMtype`, `--outSAMunmapped`, `--readFilesIn`, `--runThreadN`, etc.
        We use STAR version 2.7.10b
      example: "--alignIntronMax 6000 --outFilterScoreMinOverLread 0.1 --limitOutSJcollapsed 2000000"
      info:
        config_key: Custom_STAR_Params
    - name: "--custom_bwa_mem2_params"
      type: string
      description: |
        Modify bwa-mem2 alignment parameters - Set this parameter to fully override bwa-mem2 mapping parameters used in the pipeline
        The pipeline does not specify any custom mapping params to bwa-mem2 so program default values are used
        This applies to fastqs provided in the Reads_ATAC user input 
        Do NOT set any non-mapping related params like `-C`, `-t`, etc.
        We use bwa-mem2 version 2.2.1
      example: "-k 16 -w 200 -r"
      info:
        config_key: Custom_bwa_mem2_Params
- name: CWL-runner arguments
  arguments:
    - name: "--parallel"
      type: boolean
      description: "Run jobs in parallel."
      default: true
    - name: "--timestamps"
      type: boolean_true
      description: "Add timestamps to the errors, warnings, and notifications."
- name: Undocumented arguments
  arguments:
    - name: --abseq_umi
      type: integer
      multiple: false
      info:
        config_key: AbSeq_UMI
    - name: --target_analysis
      type: boolean
      multiple: false
      info:
        config_key: Target_analysis
    - name: --vdj_jgene_evalue
      type: double
      description: |
        e-value threshold for J gene. The e-value threshold for J gene call by IgBlast/PyIR, default is set as 0.001
      multiple: false
      info:
        config_key: VDJ_JGene_Evalue
    - name: --vdj_vgene_evalue
      type: double
      description: |
        e-value threshold for V gene. The e-value threshold for V gene call by IgBlast/PyIR, default is set as 0.001
      multiple: false
      info:
        config_key: VDJ_VGene_Evalue
    - name: --write_filtered_reads
      type: boolean
      multiple: false
      info:
        config_key: Write_Filtered_Reads
dependencies:
  - name: mapping/bd_rhapsody
    alias: bd_rhapsody_component
  - name: convert/from_bdrhap_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/bdrhap_5kjrt
  - path: /resources_test/reference_gencodev41_chr1/
runners:
  - type: nextflow