argument_groups:
  - name: Inputs
    arguments:
      - name: "--input"
        alternatives: [-i]
        description: Path to the sample.
        required: true
        example: input.h5mu
        type: file
      - name: "--rna_layer"
        type: string
        description: "Input layer for the gene expression modality. If not specified, .X is used."
        required: false
      - name: "--prot_layer"
        type: string
        description: "Input layer for the antibody capture modality. If not specified, .X is used."
        required: false
      - name: "--gdo_layer"
        type: string
        description: "Input layer for the guide-derived oligonucleotide (GDO) data. If not specified, .X is used."
        required: false

  - name: "Outputs"
    arguments:
      - name: "--output"
        type: file
        required: true
        direction: output
        description: Destination path to the output.
        example: output.h5mu

  - name: "Sample ID options"
    description: |
      Options for adding the id to .obs on the MuData object. Having a sample 
      id present in a requirement of several components for this pipeline.
    arguments:
      - name: "--add_id_to_obs"
        description: "Add the value passed with --id to .obs."
        type: boolean
        default: true
      - name: --add_id_obs_output
        description: |
          .Obs column to add the sample IDs to. Required and only used when 
          --add_id_to_obs is set to 'true'
        type: string
        default: "sample_id"
      - name: "--add_id_make_observation_keys_unique"
        type: boolean
        description: |
          Join the id to the .obs index (.obs_names). 
          Only used when --add_id_to_obs is set to 'true'.
        default: true
  
  - name: "RNA filtering options"
    arguments:
      - name: "--rna_min_counts"
        example: 200
        type: integer
        description: Minimum number of counts captured per cell.
      - name: "--rna_max_counts"
        example: 5000000
        type: integer
        description: Maximum number of counts captured per cell.

      - name: "--rna_min_percentile_counts"
        example: 0.05
        type: double
        description: |
          Minimum percentile of total RNA counts captured per cell. Quantile-based filtering is always
          performed on the log-transformed total counts.
      - name: "--rna_max_percentile_counts"
        example: 0.95
        type: double
        description: |
          Maximum percentile of total RNA counts captured per cell. Quantile-based filtering is always
          performed on the log-transformed total counts.

      - name: "--rna_min_genes_per_cell"
        type: integer
        example: 200
        description: Minimum of non-zero values per cell.
      - name: "--rna_max_genes_per_cell"
        example: 1500000
        type: integer
        description: Maximum of non-zero values per cell.

      - name: "--rna_min_cells_per_gene"
        example: 3
        type: integer
        description: Minimum of non-zero values per gene.

      - name: "--rna_min_fraction_mito"
        example: 0
        type: double
        description: Minimum fraction of UMIs that are mitochondrial.
      - name: "--rna_max_fraction_mito"
        type: double
        example: 0.2
        description: Maximum fraction of UMIs that are mitochondrial.

      - name: "--rna_min_fraction_ribo"
        example: 0
        type: double
        description: Minimum fraction of UMIs that are mitochondrial.
      - name: "--rna_max_fraction_ribo"
        type: double
        example: 0.2
        description: Maximum fraction of UMIs that are mitochondrial.

      - name: "--skip_scrublet_doublet_detection"
        type: boolean_true
        description: Skip the scrublet doublet detection step.

      - name: "--scrublet_do_subset"
        type: boolean_true
        description: |
          Remove cells classified as doublets by scrublet from the output. By default
          doublets are only annotated (in .obs "filter_with_scrublet" and
          "scrublet_doublet_score") and kept in the output.

      - name: "--scrublet_score_threshold"
        type: double
        required: false
        min: 0
        max: 1
        description: |
          Manual doublet score threshold passed to filter_with_scrublet. Cells with a
          doublet score above this value are classified as doublets. If not provided,
          the threshold is determined automatically by Scrublet.
      - name: "--scrublet_expected_doublet_rate"
        type: double
        required: false
        min: 0
        max: 1
        description: |
          The estimated fraction of doublets as from the experimental setup.
      - name: "--scrublet_stdev_doublet_rate"
        type: double
        required: false
        min: 0
        description: Uncertainty in the expected doublet rate.
      - name: "--scrublet_n_neighbors"
        type: integer
        required: false
        min: 0
        description: |
          Number of neighbors used to construct the KNN classifier of observed transcriptomes
          and simulated doublets.
      - name: "--scrublet_sim_doublet_ratio"
        type: double
        required: false
        min: 0
        description: |
          Number of doublets to simulate relative to the number of observed transcriptomes.
      - name: "--scrublet_min_counts"
        type: integer
        required: false
        description: |
          The number of minimal UMI counts per cell that have to be present for initial cell
          detection during scrublet doublet detection.
      - name: "--scrublet_min_cells"
        type: integer
        required: false
        description: |
          The number of cells in which UMIs for a gene were detected during scrublet
          doublet detection.
      - name: "--scrublet_min_gene_variability_percent"
        type: double
        required: false
        description: |
          Keep the most highly variable genes (in the top percentile) as measured by the
          v-statistic, used for gene filtering prior to PCA during scrublet doublet detection.
      - name: "--scrublet_num_pca_components"
        type: integer
        required: false
        description: |
          Number of principal components used during PCA dimensionality reduction in scrublet
          doublet detection.
      - name: "--scrublet_distance_metric"
        type: string
        required: false
        description: The distance metric used for computing similarities during scrublet doublet detection.
      - name: "--scrublet_allow_automatic_threshold_detection_fail"
        type: boolean_true
        description: |
          When scrublet fails to automatically determine the doublet score threshold, allow the
          pipeline to continue and set the output columns to NA.

  - name: "CITE-seq filtering options"
    arguments:
      - name: "--prot_min_counts"
        description: Minimum number of counts per cell.
        type: integer
        example: 3
      - name: "--prot_max_counts"
        description: Minimum number of counts per cell.
        type: integer
        example: 5000000

      - name: "--prot_min_percentile_counts"
        example: 0.05
        type: double
        description: |
          Minimum percentile of total protein counts captured per cell. Quantile-based filtering is always
          performed on the log-transformed total counts.
      - name: "--prot_max_percentile_counts"
        example: 0.95
        type: double
        description: |
          Maximum percentile of total protein counts captured per cell. Quantile-based filtering is always
          performed on the log-transformed total counts.

      - name: "--prot_min_proteins_per_cell"
        type: integer
        example: 200
        description: Minimum of non-zero values per cell.
      - name: "--prot_max_proteins_per_cell"
        description: Maximum of non-zero values per cell.
        type: integer
        example: 100000000

      - name: "--prot_min_cells_per_protein"
        example: 3
        type: integer
        description: Minimum of non-zero values per protein.

  - name: "GDO filtering options"
    arguments:
      - name: "--gdo_min_counts"
        description: Minimum number of counts per cell.
        type: integer
        example: 3
      - name: "--gdo_max_counts"
        description: Minimum number of counts per cell.
        type: integer
        example: 5000000
      - name: "--gdo_min_guides_per_cell"
        type: integer
        example: 200
        description: Minimum of non-zero values per cell.
      - name: "--gdo_max_guides_per_cell"
        description: Maximum of non-zero values per cell.
        type: integer
        example: 100000000
      - name: "--gdo_min_cells_per_guide"
        example: 3
        type: integer
        description: Minimum of non-zero values per guide.

  - name: "Mitochondrial & Ribosomal Gene Detection"
    arguments:
      - name: "--var_gene_names"
        required: false
        example: "gene_symbol"
        type: string
        description: |
          .var column name to be used to detect mitochondrial/ribosomal genes instead of .var_names (default if not set).
          Gene names matching with the regex value from --mitochondrial_gene_regex or --ribosomal_gene_regex will be 
          identified as mitochondrial or ribosomal genes, respectively. 
      - name: "--var_name_mitochondrial_genes"
        type: string
        required: false
        description: |
          In which .var slot to store a boolean array corresponding the mitochondrial genes.
      - name: "--obs_name_mitochondrial_fraction"
        type: string
        required: false
        description: |
          When specified, write the fraction of counts originating from mitochondrial genes 
          (based on --mitochondrial_gene_regex) to an .obs column with the specified name.
          Requires --var_name_mitochondrial_genes.
      - name: --mitochondrial_gene_regex
        type: string
        description: |
          Regex string that identifies mitochondrial genes from --var_gene_names.
          By default will detect human and mouse mitochondrial genes from a gene symbol.
        required: false
        default: "^[mM][tT]-"
      - name: "--var_name_ribosomal_genes"
        type: string
        required: false
        description: |
          In which .var slot to store a boolean array corresponding the ribosomal genes.
      - name: "--obs_name_ribosomal_fraction"
        type: string
        required: false
        description: |
          When specified, write the fraction of counts originating from ribosomal genes 
          (based on --ribosomal_gene_regex) to an .obs column with the specified name.
          Requires --var_name_ribosomal_genes.
      - name: --ribosomal_gene_regex
        type: string
        description: |
          Regex string that identifies ribosomal genes from --var_gene_names.
          By default will detect human and mouse ribosomal genes from a gene symbol.
        required: false
        default: "^[Mm]?[Rr][Pp][LlSs]"
