name: score_genes_cell_cycle_scanpy
namespace: feature_annotation
scope: "public"
authors:
  - __merge__: /src/authors/robrecht_cannoodt.yaml
    roles: [ author ]
  - __merge__: /src/authors/dorien_roosen.yaml
    roles: [ author ]
  - __merge__: /src/authors/weiwei_schultz.yaml
    roles: [ contributor ]

description: |
  Calculates the score associated to S phase and G2M phase and annotates the cell cycle phase for each cell, as implemented by scanpy. 
  The score is the average expression of a set of genes subtracted with the average expression of a reference set of genes.
argument_groups:
  - name: Inputs
    arguments:
      - name: --input
        type: file
        description: Input h5mu file
        required: true
        example: input_file.h5mu
      - name: "--modality"
        description: |
          Which modality from the input MuData file to process.
        type: string
        default: "rna"
        required: false
      - name: "--input_layer"
        type: string
        example: log_normalized
        required: false
        description: |
          The layer of the adata object containing normalized expression values.
          If not provided, the X attribute of the adata object will be used.
      - name: "--var_gene_names"
        type: string
        description: |
          The name of the column in the var attribute of the adata object that contains the gene names (symbols).
          If not provided, the index of the var attribute will be used.
        required: false
        example: "gene_names"
  - name: Gene list inputs
    description: |
      The gene list inputs can be provided as a list of gene symbols or as a file containing a list of gene symbols. The gene list file should be formatted as a single column with gene symbols.

      Make sure that the gene list inputs are consistent with the gene names in the adata object as provided by the --var_gene_names argument.
    arguments:
      - name: --s_genes
        type: string
        description: |
          List of gene symbols for scoring s phase genes.
        required: false
        multiple: true
        example: [gene1, gene2, gene3]
      - name: --s_genes_file
        type: file
        description: |
          Path to a .txt file containing the gene list of s phase genes to be scored. 
          The gene list file should be formatted as a single column with gene symbols.
        required: false
        example: s_gene_list.txt
      - name: --g2m_genes
        type: string
        description: |
          List of gene symbols for scoring g2m phase genes.
        required: false
        multiple: true
        example: [gene1, gene2, gene3]
      - name: --g2m_genes_file
        type: file
        description: |
          Path to a .txt file containing the gene list of g2m phase genes to be scored. 
          The gene list file should be formatted as a single column with gene symbols.
        required: false
        example: g2m_gene_list.txt
      - name: --gene_pool
        type: string
        description: |
          List of gene symbols for sampling the reference set. Default is all genes.
        required: false
        multiple: true
        example: [gene1, gene2, gene3]
      - name: --gene_pool_file
        type: file
        description: |
          File with genes for sampling the reference set. Default is all genes. 
          The gene pool file should be formatted as a single column with gene symbols.
        required: false
        example: gene_pool.txt

  - name: Outputs
    arguments:
      - name: --output
        type: file
        direction: output
        description: |
          Output h5mu file
        required: true
        example: output_file.h5mu
      - name: "--obs_phase"
        type: string
        description: |
          The name of the column in the obs attribute of the adata object that will store the cell cycle phase annotation.
        required: false
        default: "phase"
      - name: "--obs_s_score"
        type: string
        description: |
          The name of the column in the obs attribute of the adata object that will store the s phase score.
        required: false
        default: "S_score"
      - name: "--obs_g2m_score"
        type: string
        description: |
          The name of the column in the obs attribute of the adata object that will store the g2m phase score.
        required: false
        default: "G2M_score"
    __merge__: [., /src/base/h5_compression_argument.yaml]

  - name: Arguments
    arguments:
      - name: --n_bins
        type: integer
        min: 0
        default: 25
        required: false
        description: |
          Number of expression level bins for sampling.
      - name: --random_state
        type: integer
        description: |
          The random seed for sampling.
        default: 0
        required: false
      - name: --allow_missing_genes
        type: boolean
        description: |
          If true, missing genes in the gene list will be ignored.
        default: false
        required: false

resources:
  - path: script.py
    type: python_script
  - path: ../score_genes_scanpy/helper.py
test_resources:
  - type: python_script
    path: test.py
  - path: /resources_test/pbmc_1k_protein_v3/
  
engines:
  - type: docker
    image: python:3.11
    setup:
      - type: python
        __merge__: [ /src/base/requirements/scanpy.yaml, /src/base/requirements/anndata_mudata.yaml ]
    test_setup:
      - type: python
        __merge__: [ /src/base/requirements/viashpy.yaml, .]

runners:
  - type: nextflow
  - type: executable