argument_groups:
  - name: Input files
    arguments:
      - type: file
        name: --input
        required: false
        description: |
          The FASTQ files to be analyzed. FASTQ files should conform to the naming conventions of bcl2fastq and mkfastq:
          `[Sample Name]_S[Sample Index]_L00[Lane Number]_[Read Type]_001.fastq.gz`
        example: [ mysample_S1_L001_R1_001.fastq.gz, mysample_S1_L001_R2_001.fastq.gz ]
        multiple: true

  - name: Feature type-specific input files
    description: |
      Helper functionality to allow feature type-specific input files, without the need to specify
      library_type or library_id. The library_id will be inferred from the input paths.
    arguments:
      - type: file
        name: --gex_input
        required: false
        description: |
          The FASTQ files to be analyzed for Gene Expression. FASTQ files should conform to the
          naming conventions of bcl2fastq and mkfastq:
          `[Sample Name]_S[Sample Index]_L00[Lane Number]_[Read Type]_001.fastq.gz`
        example:
          [mysample_S1_L001_R1_001.fastq.gz, mysample_S1_L001_R2_001.fastq.gz]
        multiple: true
        multiple_sep: ";"
      - type: file
        name: --abc_input
        required: false
        description: |
          The FASTQ files to be analyzed for Antibody Capture. FASTQ files should conform to 
          the naming conventions of bcl2fastq and mkfastq:
          `[Sample Name]_S[Sample Index]_L00[Lane Number]_[Read Type]_001.fastq.gz`
        example:
          [mysample_S1_L001_R1_001.fastq.gz, mysample_S1_L001_R2_001.fastq.gz]
        multiple: true
        multiple_sep: ";"
      - type: file
        name: --cgc_input
        required: false
        description: |
          The FASTQ files to be analyzed for CRISPR Guide Capture. FASTQ files should conform to
          the naming conventions of bcl2fastq and mkfastq:
          `[Sample Name]_S[Sample Index]_L00[Lane Number]_[Read Type]_001.fastq.gz`
        example:
          [mysample_S1_L001_R1_001.fastq.gz, mysample_S1_L001_R2_001.fastq.gz]
        multiple: true
        multiple_sep: ";"
      - type: file
        name: --mux_input
        required: false
        description: |
          The FASTQ files to be analyzed for Multiplexing Capture. FASTQ files should conform to
          the naming conventions of bcl2fastq and mkfastq:
          `[Sample Name]_S[Sample Index]_L00[Lane Number]_[Read Type]_001.fastq.gz`
        example:
          [mysample_S1_L001_R1_001.fastq.gz, mysample_S1_L001_R2_001.fastq.gz]
        multiple: true
        multiple_sep: ";"
      - type: file
        name: --vdj_input
        required: false
        description: |
          The FASTQ files to be analyzed for VDJ. FASTQ files should conform to the
          naming conventions of bcl2fastq and mkfastq:
          `[Sample Name]_S[Sample Index]_L00[Lane Number]_[Read Type]_001.fastq.gz`
        example:
          [mysample_S1_L001_R1_001.fastq.gz, mysample_S1_L001_R2_001.fastq.gz]
        multiple: true
        multiple_sep: ";"
      - type: file
        name: --vdj_t_input
        required: false
        description: |
          The FASTQ files to be analyzed for VDJ-T. FASTQ files should conform to the naming
          conventions of bcl2fastq and mkfastq:
          `[Sample Name]_S[Sample Index]_L00[Lane Number]_[Read Type]_001.fastq.gz`
        example:
          [mysample_S1_L001_R1_001.fastq.gz, mysample_S1_L001_R2_001.fastq.gz]
        multiple: true
        multiple_sep: ";"
      - type: file
        name: --vdj_t_gd_input
        required: false
        description: |
          The FASTQ files to be analyzed for VDJ-T-GD. FASTQ files should conform to
          the naming conventions of bcl2fastq and mkfastq:
          `[Sample Name]_S[Sample Index]_L00[Lane Number]_[Read Type]_001.fastq.gz`
        example:
          [mysample_S1_L001_R1_001.fastq.gz, mysample_S1_L001_R2_001.fastq.gz]
        multiple: true
        multiple_sep: ";"
      - type: file
        name: --vdj_b_input
        required: false
        description: |
          The FASTQ files to be analyzed for VDJ-B. FASTQ files should conform to
          the naming conventions of bcl2fastq and mkfastq:
          `[Sample Name]_S[Sample Index]_L00[Lane Number]_[Read Type]_001.fastq.gz`
        example:
          [mysample_S1_L001_R1_001.fastq.gz, mysample_S1_L001_R2_001.fastq.gz]
        multiple: true
        multiple_sep: ";"
      - type: file
        name: --agc_input
        required: false
        description: |
          The FASTQ files to be analyzed for Antigen Capture. FASTQ files should conform to
          the naming conventions of bcl2fastq and mkfastq:
          `[Sample Name]_S[Sample Index]_L00[Lane Number]_[Read Type]_001.fastq.gz`
        example:
          [mysample_S1_L001_R1_001.fastq.gz, mysample_S1_L001_R2_001.fastq.gz]
        multiple: true
        multiple_sep: ";"

  - name: Library arguments
    arguments:
      - type: string
        name: --library_id
        required: false
        description: |
          The Illumina sample name to analyze. This must exactly match the 'Sample Name'part
          of the FASTQ files specified in the `--input` argument.
        example: ["mysample1"]
        multiple: true
      - type: string
        name: --library_type
        required: false
        description: |
          The underlying feature type of the library.
        choices: ["Gene Expression", "VDJ", "VDJ-T", "VDJ-B", "VDJ-T-GD", "Antibody Capture",
                    "CRISPR Guide Capture", "Multiplexing Capture", "Antigen Capture", "Custom"]
        example: "Gene Expression"
        multiple: true
      - type: string
        name: --library_subsample
        required: false
        description: |
          The rate at which reads from the provided FASTQ files are sampled.
          Must be strictly greater than 0 and less than or equal to 1.
        example: "0.5"
        multiple: true
      - type: string
        name: --library_lanes
        required: false
        description: Lanes associated with this sample. Defaults to using all lanes.
        example: "1-4"
        multiple: true
      - type: string
        name: "--library_chemistry"
        description: |
          Only applicable to FRP. Library-specific assay configuration. By default,
          the assay configuration is detected automatically. Typically, users will
          not need to specify a chemistry.

  - name: Sample parameters
    # Corresponds to the [samples] section
    arguments:
      - type: string
        name: --sample_ids
        alternatives: "--cell_multiplex_sample_id"
        multiple: true
        description: |
          A name to identify a multiplexed sample. Must be alphanumeric with hyphens and/or underscores,
          and less than 64 characters. Required for Cell Multiplexing libraries.
      - type: string
        multiple: true
        name: --sample_description
        alternatives: [--cell_multiplex_description]
        description: A description for the sample.
      - type: integer
        multiple: true
        name: --sample_expect_cells
        example: 3000
        description: |
          Expected number of recovered cells, used as input to cell calling algorithm.
      - type: integer
        name: "--sample_force_cells"
        example: 3000
        multiple: true
        required: false
        description: |
          Force pipeline to use this number of cells, bypassing cell detection.

  - name: "Feature Barcode library specific arguments"
    # Corresponds to the [feature] section
    arguments:
      - name: "--feature_reference"
        type: file
        description: |
          Path to the Feature reference CSV file, declaring Feature Barcode constructs and associated barcodes.
          Required only for Antibody Capture or CRISPR Guide Capture libraries.
          See https://support.10xgenomics.com/single-cell-gene-expression/software/pipelines/latest/using/feature-bc-analysis#feature-ref for more information."
        example: "feature_reference.csv"
        required: false
      - name: "--feature_r1_length"
        type: integer
        required: false
        description: |
          Limit the length of the input Read 1 sequence of V(D)J libraries to the first N bases,
          where N is the user-supplied value. Note that the length includes the Barcode and UMI
          sequences so do not set this below 26.
      - name: "--feature_r2_length"
        type: integer
        required: false
        description: |
          Limit the length of the input Read 2 sequence of V(D)J libraries to the first N bases,
          where N is a user-supplied value. Trimming occurs before sequencing metrics are computed
          and therefore, limiting the length of Read 2 may affect Q30 scores.
      - name: "--min_crispr_umi"
        type: integer
        min: 1
        required: false
        description: |
          Set the minimum number of CRISPR guide RNA UMIs required for protospacer detection.
          If a lower or higher sensitivity is desired for detection, this value can be customized
          according to specific experimental needs. Applicable only to datasets that include a
          CRISPR Guide Capture library.
  - name: Gene expression arguments
    # Corresponds to the [gene-expression] section
    description: Arguments relevant to the analysis of gene expression data.
    arguments:
      - name: "--gex_reference"
        type: file
        description: "Genome refence index built by Cell Ranger mkref."
        example: "reference_genome.tar.gz"
        required: true
      - type: boolean
        name: "--gex_secondary_analysis"
        default: false
        description: Whether or not to run the secondary analysis e.g. clustering.
      - type: boolean
        name: "--gex_generate_bam"
        default: false
        description: Whether to generate a BAM file.
      - type: file
        name: "--tenx_cloud_token_path"
        description: The 10x Cloud Analysis user token used to enable cell annotation.
      - type: string
        name: "--cell_annotation_model"
        description: |
          "Cell annotation model to use. If auto, uses the default model for the species.
          If not given, does not run cell annotation."
        choices: ["auto", "human_pca_v1_beta", "mouse_pca_v1_beta"]
      - type: integer
        name: --gex_expect_cells
        example: 3000
        description: |
          Expected number of recovered cells, used as input to cell calling algorithm.
      - type: integer
        name: "--gex_force_cells"
        example: 3000
        description: |
          Force pipeline to use this number of cells, bypassing cell detection.
      - type: boolean
        name: "--gex_include_introns"
        default: true
        description: |
          Whether or not to include intronic reads in counts.
          This option does not apply to Fixed RNA Profiling analysis.
      - name: "--gex_r1_length"
        type: integer
        required: false
        description: |
          Limit the length of the input Read 1 sequence of V(D)J libraries to the first N bases,
          where N is the user-supplied value. Note that the length includes the Barcode and UMI
          sequences so do not set this below 26.
      - name: "--gex_r2_length"
        type: integer
        required: false
        description: |
          Limit the length of the input Read 2 sequence of V(D)J libraries to the first N bases,
          where N is a user-supplied value. Trimming occurs before sequencing metrics are computed
          and therefore, limiting the length of Read 2 may affect Q30 scores.
      - type: string
        name: --gex_chemistry
        default: auto
        description: |
          Assay configuration. Either specify a single value which will be applied to all libraries,
          or a number of values that is equal to the number of libararies. The latter is only applicable
          to only applicable to Fixed RNA Profiling.
            - auto: Chemistry autodetection (default)
            - threeprime: Single Cell 3'
            - SC3Pv1, SC3Pv2, SC3Pv3(-polyA), SC3Pv4(-polyA): Single Cell 3' v1, v2, v3, or v4
            - SC3Pv3HT(-polyA): Single Cell 3' v3.1 HT
            - SC-FB: Single Cell Antibody-only 3' v2 or 5'
            - fiveprime: Single Cell 5'
            - SC5P-PE: Paired-end Single Cell 5'
            - SC5P-PE-v3: Paired-end Single Cell 5' v3
            - SC5P-R2: R2-only Single Cell 5'
            - SC5P-R2-v3: R2-only Single Cell 5' v3
            - SCP5-PE-v3: Single Cell 5' paired-end v3 (GEM-X)
            - SC5PHT : Single Cell 5' v2 HT
            - SFRP: Fixed RNA Profiling (Singleplex)
            - MFRP: Fixed RNA Profiling (Multiplex, Probe Barcode on R2)
            - MFRP-R1: Fixed RNA Profiling (Multiplex, Probe Barcode on R1)
            - MFRP-RNA: Fixed RNA Profiling (Multiplex, RNA, Probe Barcode on R2)
            - MFRP-Ab: Fixed RNA Profiling (Multiplex, Antibody, Probe Barcode at R2:69)
            - MFRP-Ab-R2pos50: Fixed RNA Profiling (Multiplex, Antibody, Probe Barcode at R2:50)
            - MFRP-RNA-R1: Fixed RNA Profiling (Multiplex, RNA, Probe Barcode on R1)
            - MFRP-Ab-R1: Fixed RNA Profiling (Multiplex, Antibody, Probe Barcode on R1)
            - ARC-v1 for analyzing the Gene Expression portion of Multiome data. If Cell Ranger auto-detects ARC-v1 chemistry, an error is triggered.
          See https://kb.10xgenomics.com/hc/en-us/articles/115003764132-How-does-Cell-Ranger-auto-detect-chemistry- for more information.
        choices: [ auto, threeprime, fiveprime, SC3Pv1, SC3Pv2, SC3Pv3, SC3Pv3-polyA, SC3Pv4, SC3Pv4-polyA, SC3Pv3LT, SC3Pv3HT, SC3Pv3HT-polyA, 
                  SC5P-PE, SC5P-PE-v3, SC5P-R2, SC-FB, SC5P-R2-v3, SCP5-PE-v3, SC5PHT, MFRP, MFRP-R1, MFRP-RNA, MFRP-Ab,
                  SFRP, MFRP-Ab-R2pos50, MFRP-RNA-R1, MFRP-Ab-R1, ARC-v1]

  - name: "VDJ related parameters"
    # The [vdj] section
    arguments:
      - name: "--vdj_reference"
        type: file
        description: "VDJ refence index built by Cell Ranger mkref."
        example: "reference_vdj.tar.gz"
        required: false
      - name: "--vdj_inner_enrichment_primers"
        type: file
        description: |
          V(D)J Immune Profiling libraries: if inner enrichment primers other than those provided 
          in the 10x Genomics kits are used, they need to be specified here as a
          text file with one primer per line.
        example: "enrichment_primers.txt"
        required: false
      - name: "--vdj_r1_length"
        type: integer
        required: false
        description: |
          Limit the length of the input Read 1 sequence of V(D)J libraries to the first N bases, where N is the user-supplied value.
          Note that the length includes the Barcode and UMI sequences so do not set this below 26.
      - name: "--vdj_r2_length"
        type: integer
        required: false
        description: |
          Limit the length of the input Read 2 sequence of V(D)J libraries to the first N bases, where N is a user-supplied value. 
          Trimming occurs before sequencing metrics are computed and therefore, limiting the length of Read 2 may affect Q30 scores
      - name: "--vdj_denovo"
        type: boolean
        required: false
        description: |
          Run in reference-free mode (i.e., do not use annotations). This option is not supported for multiplexed experiments.
  - name: 3' Cell multiplexing parameters (CellPlex Multiplexing)
    # cell_multiplex_oligo_ids adds to [samples] section
    # min_assignment_confidence, cmo_set barcode_sample_assignment are added to [gene-expression]
    arguments:
      - type: string
        name: --cell_multiplex_oligo_ids
        alternatives: [--cmo_ids]
        multiple: true
        description: |
          The Cell Multiplexing oligo IDs used to multiplex this sample. If multiple CMOs were used for a sample,
          separate IDs with a pipe (e.g., CMO301|CMO302). Required for Cell Multiplexing libraries.
        
      - type: double
        name: --min_assignment_confidence
        description: | 
          The minimum estimated likelihood to call a sample as tagged with a Cell Multiplexing Oligo (CMO) instead of "Unassigned".
          Users may wish to tolerate a higher rate of mis-assignment in order to obtain more singlets to include in their analysis,
          or a lower rate of mis-assignment at the cost of obtaining fewer singlets.
      - type: file 
        direction: input
        required: false
        name: "--cmo_set"
        description: |
          Path to a custom CMO set CSV file, declaring CMO constructs and associated barcodes. If the default CMO reference IDs that are built into
          the Cell Ranger software are required, this option does not need to be used.
      - type: file
        direction: input
        required: false
        name: "--barcode_sample_assignment"
        description: |
          Path to a barcode-sample assignment CSV file that specifies the barcodes that belong to each sample.
  
  - name: Hashtag multiplexing parameters
    # Is added to [samples]
    arguments:
      - name: --hashtag_ids
        type: string
        multiple: true
        description: |
          The hashtag IDs used to multiplex this sample. If multiple antibody hashtags were used for the same sample,
          you can separate IDs with a pipe.

  - name: On-chip multiplexing parameters
    # Is added to [samples]
    arguments:
      - name: --ocm_barcode_ids
        type: string
        multiple: true
        # Note: choices is not an option here because multiple values can be added using pipe
        description: |
          The OCM barcode IDs used to multiplex this sample. Must be one of OB1, OB2, OB3, OB4.
          If multiple OCM Barcodes were used for the same sample, you can separate IDs
          with a pipe (e.g., OB1|OB2).

  - name: Flex multiplexing paramaters
    # probe_set, filter_probes and emptydrops_minimum_umis end up in [gene-expression]
    # probe_barcode_ids ends up in [samples]
    arguments:
      - type: file
        name: "--probe_set"
        description: |
          A probe set reference CSV file. It specifies the sequences used as a reference for probe alignment and the gene ID associated with each probe.
          It must include 4 columns (probe file format 1.0.0): gene_id,probe_seq,probe_id,included,region and an optional 5th column (probe file format 1.0.1).
          - gene_id: The Ensembl gene identifier targeted by the probe.
          - probe_seq: The nucleotide sequence of the probe, which is complementary to the transcript sequence.
          - probe_id: The probe identifier, whose format is described in Probe identifiers.
          - included: A TRUE or FALSE flag specifying whether the probe is included in the filtered counts matrix output or excluded by the probe filter. 
                      See filter-probes option of cellranger multi. All probes of a gene must be marked TRUE in the included column for that gene to be included.
          - region: Present only in v1.0.1 probe set reference CSV. The gene boundary targeted by the probe. Accepted values are spliced or unspliced.

          The file also contains a number of required metadata fields in the header in the format #key=value:
          - panel_name: The name of the probe set.
          - panel_type: Always predesigned for predesigned probe sets.
          - reference_genome: The reference genome build used for probe design.
          - reference_version: The version of the Cell Ranger reference transcriptome used for probe design.
          - probe_set_file_format: The version of the probe set file format specification that this file conforms to.
      - type: boolean  # Null is also a valid option because passing this argument to cellranger (true or false) requires --probe_set 
        name: "--filter_probes"
        description: |
          If 'false', include all non-deprecated probes listed in the probe set reference CSV file.
          If 'true' or not set, probes that are predicted to have off-target activity to homologous genes are excluded from analysis.
          Not filtering will result in UMI counts from all non-deprecated probes,
          including those with predicted off-target activity, to be used in the analysis.
          Probes whose ID is prefixed with DEPRECATED are always excluded from the analysis.

      - type: string
        name: "--probe_barcode_ids"
        multiple: true
        description: |
          The Fixed RNA Probe Barcode ID used for this sample, and for multiplex GEX + Antibody Capture libraries,
          the corresponding Antibody Multiplexing Barcode IDs. 10x recommends specifying both barcodes (e.g., BC001+AB001)
          when an Antibody Capture library is present. The barcode pair order is BC+AB and they
          are separated with a "+" (no spaces). Alternatively, you can specify the Probe Barcode ID alone and
          Cell Ranger's barcode pairing auto-detection algorithm will automatically match to the corresponding Antibody
          Multiplexing Barcode.
      - type: integer
        name: --emptydrops_minimum_umis
        min: 1
        description: |
          For singleplex Flex experiments, use this option to adjust the UMI cutoff during the second step of cell calling.
          Cell Ranger will still perform the full cell calling process but will only evaluate barcodes with UMIs above
          the threshold you specify.

  - name: Antigen Capture (BEAM) libary arguments
    # These end up in the [antigen-specificity] section
    description: |
      These arguments are recommended if an Antigen Capture (BEAM) library is present. 
      It is needed to calculate the antigen specificity score.
    arguments:
      - type: string
        name: --control_id
        multiple: true
        description: |
          A user-defined ID for any negative controls used in the T/BCR Antigen Capture assay. Must match id specified in the feature reference CSV.
          May only include ASCII characters and must not use whitespace, slash, quote, or comma characters. 
          Each ID must be unique and must not collide with a gene identifier from the transcriptome.
      - type: string
        multiple: true
        name: --mhc_allele
        description: |
          The MHC allele for TCR Antigen Capture libraries. Must match mhc_allele name specified in the Feature Reference CSV.
  - name: "General arguments"
    description: |
      These arguments are applicable to all library types.
    arguments:
      - name: "--check_library_compatibility"
        type: boolean
        default: true
        description: |
          Optional. This option allows users to disable the check that evaluates 10x Barcode overlap between
          ibraries when multiple libraries are specified (e.g., Gene Expression + Antibody Capture). Setting
          this option to false will disable the check across all library combinations. We recommend running
          this check (default), however if the pipeline errors out, users can bypass the check to generate
          outputs for troubleshooting.

