name: normalize_total
namespace: "transform"
scope: "public"
description: |
  Normalize counts per cell.

  Normalize each cell by total counts over all genes, so that every cell has the same total count after normalization. If choosing target_sum=1e6, this is CPM normalization.

  If exclude_highly_expressed=True, very highly expressed genes are excluded from the computation of the normalization factor (size factor) for each cell. This is meaningful as these can strongly influence the resulting normalized values for all other genes [Weinreb17].
authors:
  - __merge__: /src/authors/dries_de_maeyer.yaml
    roles: [ maintainer ]
  - __merge__: /src/authors/robrecht_cannoodt.yaml
    roles: [ contributor ]
arguments:
  # input
  - name: "--input"
    alternatives: ["-i"]
    type: file
    description: Input h5mu file
    direction: input
    required: true
    example: input.h5mu

  - name: "--modality"
    description: |
      Which modality from the input MuData file to process.
    type: string
    default: "rna"
    required: false

  - name: "--input_layer"
    type: string
    required: false
    description: "Input layer to use. By default, X is normalized"
  # output
  - name: "--output"
    alternatives: ["-o"]
    type: file
    description: Output h5mu file.
    direction: output
    required: true
    default: output.h5mu

  - name: "--output_layer"
    type: string
    description: Output layer to use. By default, use X.
    required: false

  # arguments
  - name: "--target_sum"
    type: integer
    description: If None, after normalization, each observation (cell) has a total count equal to the median of total counts for observations (cells) before normalization.

  - name: "--exclude_highly_expressed"
    type: boolean_true
    description: Exclude (very) highly expressed genes for the computation of the normalization factor (size factor) for each cell. A gene is considered highly expressed, if it has more than max_fraction of the total counts in at least one cell. The not-excluded genes will sum up to target_sum.
__merge__: [., /src/base/h5_compression_argument.yaml]
resources:
  - type: python_script
    path: script.py
  - path: /src/utils/setup_logger.py
  - path: /src/utils/compress_h5mu.py
test_resources:
  - type: python_script
    path: test.py
  - path: /resources_test/pbmc_1k_protein_v3

engines:
- type: docker
  image: python:3.12-slim
  setup:
    - type: apt
      packages: 
        - procps
    - type: python
      __merge__: [/src/base/requirements/anndata_mudata.yaml, /src/base/requirements/scanpy.yaml, .]
  __merge__: [ /src/base/requirements/python_test_setup.yaml, .]

runners:
- type: executable
- type: nextflow
  directives:
    label: [midmem, lowcpu, highdisk]
