name: "celltypist"
namespace: "workflows/annotation"
scope: "public"
description: "Cell type annotation workflow by performing lognormalization of the raw counts layer followed by cell type annotation with CellTypist."
info:
  name: "CellTypist annotation"
  test_dependencies:
    - name: celltypist_test
      namespace: test_workflows/annotation
authors:
  - __merge__: /src/authors/dorien_roosen.yaml
    roles: [ author, maintainer ]
  - __merge__: /src/authors/weiwei_schultz.yaml
    roles: [ contributor ]

argument_groups:
  - name: Inputs
    description: Input dataset (query) arguments
    arguments:
      - name: "--input"
        alternatives: [-i]
        type: file
        description: The input (query) data to be labeled. Should be a .h5mu file.
        direction: input
        required: true
        example: input.h5mu
      - name: "--modality"
        description: Which modality to process.
        type: string
        default: "rna"
        required: false
      - name: "--input_layer"
        type: string
        description: The layer in the input data containing raw counts, if .X is not to be used. 
      - name: "--input_var_gene_names"
        type: string
        required: false
        description: |
          The name of the adata var column in the input data containing gene names; when no gene_name_layer is provided, the var index will be used.
      - name: "--input_reference_gene_overlap"
        type: integer
        default: 100
        min: 1
        description: | 
          The minimum number of genes present in both the reference and query datasets.
      - name: "--sanitize_ensembl_ids"
        type: boolean
        description: Whether to sanitize ensembl ids by removing version numbers.
        default: true
  
  - name: Reference
    description: Arguments related to the reference dataset.
    arguments:
      - name: "--reference"
        type: file
        description: "The reference data to train the CellTypist classifiers on. Only required if a pre-trained --model is not provided."
        example: reference.h5mu
        direction: input
        required: false
      - name: "--reference_layer"
        type: string
        description: The layer in the reference data containing raw counts, if .X is not to be used.
        required: false
      - name: "--reference_obs_target"
        type: string
        description: The name of the adata obs column in the reference data containing cell type annotations.
        default: "cell_ontology_class"
      - name: "--reference_var_gene_names"
        type: string
        required: false
        description: |
          The name of the adata var column in the reference data containing gene names; when no gene_name_layer is provided, the var index will be used.
      - name: "--reference_var_input"
        type: string
        required: false
        description: |
          .var column containing highly variable genes. By default, do not subset genes.

  - name: Model arguments
    description: Model arguments.
    arguments:
      - name: "--model"
        type: file
        description: "Pretrained model in pkl format. If not provided, the model will be trained on the reference data and --reference should be provided."
        required: false
        example: pretrained_model.pkl
      - name: "--feature_selection"
        type: boolean
        description: "Whether to perform feature selection."
        default: false
      - name: "--majority_voting"
        type: boolean
        description: "Whether to refine the predicted labels by running the majority voting classifier after over-clustering."
        default: false
      - name: "--C"
        type: double
        description: "Inverse of regularization strength in logistic regression."
        default: 1.0
      - name: "--max_iter"
        type: integer
        description: "Maximum number of iterations before reaching the minimum of the cost function."
        default: 1000
      - name: "--use_SGD"
        type: boolean_true
        description: "Whether to use the stochastic gradient descent algorithm."
      - name: "--min_prop"
        type: double
        description: |
          "For the dominant cell type within a subcluster, the minimum proportion of cells required to 
          support naming of the subcluster by this cell type. Ignored if majority_voting is set to False. 
          Subcluster that fails to pass this proportion threshold will be assigned 'Heterogeneous'."
        default: 0

  - name: Outputs
    description: Output arguments.
    arguments:
      - name: "--output"
        type: file
        description: Output h5mu file.
        direction: output
        example: output.h5mu
      - name: "--output_obs_predictions"
        type: string
        default: celltypist_pred
        required: false
        description: |
          In which `.obs` slots to store the predicted information.
      - name: "--output_obs_probability"
        type: string
        default: celltypist_probability
        required: false
        description: |
          In which `.obs` slots to store the probability of the predictions.
    __merge__: [., /src/base/h5_compression_argument.yaml]

dependencies:
  - name: workflows/rna/log_normalize
  - name: annotate/celltypist
    alias: celltypist_component

resources:
  - type: nextflow_script
    path: main.nf
    entrypoint: run_wf

test_resources:
  - type: nextflow_script
    path: test.nf
    entrypoint: test_wf
  - path: /resources_test/pbmc_1k_protein_v3/pbmc_1k_protein_v3_mms.h5mu
  - path: /resources_test/annotation_test_data/TS_Blood_filtered.h5mu
  - path: /resources_test/annotation_test_data/celltypist_model_Immune_All_Low.pkl
  - path: /resources_test/annotation_test_data/demo_2000_cells.h5mu

runners:
  - type: nextflow
