name: leiden
namespace: "cluster"
scope: "public"
description: |
  Cluster cells using the [Leiden algorithm] [Traag18] implemented in the [Scanpy framework] [Wolf18]. 
  Leiden is an improved version of the [Louvain algorithm] [Blondel08]. 
  It has been proposed for single-cell analysis by [Levine15] [Levine15]. 
  This requires having ran `neighbors/find_neighbors` or `neighbors/bbknn` first.

  [Blondel08]: Blondel et al. (2008), Fast unfolding of communities in large networks, J. Stat. Mech.  
  [Levine15]: Levine et al. (2015), Data-Driven Phenotypic Dissection of AML Reveals Progenitor-like Cells that Correlate with Prognosis, Cell.  
  [Traag18]: Traag et al. (2018), From Louvain to Leiden: guaranteeing well-connected communities arXiv.  
  [Wolf18]: Wolf et al. (2018), Scanpy: large-scale single-cell gene expression data analysis, Genome Biology.  
authors:
  - __merge__: /src/authors/dries_de_maeyer.yaml
    roles: [ maintainer ]
arguments:
  # input
  - name: "--input"
    alternatives: [-i]
    type: file
    description: Input 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: "--obsp_connectivities"
    type: string
    description: In which .obsp slot the neighbor connectivities can be found.
    default: "connectivities"

  # output
  - name: "--output"
    alternatives: ["-o"]
    type: file
    description: Output file.
    direction: output
    required: true
    example: output.h5mu
  - name: "--obsm_name"
    type: string
    description: |
      Name of the .obsm key under which to add the cluster labels.
      The name of the columns in the matrix will correspond to the resolutions.
    default: "leiden"

  - name: --flavor
    type: string
    description: |
          Which package's implementation to use.
    choices: ["leidenalg", "igraph"]
    default: "leidenalg"
  - name: "--n_iterations"
    required: false
    type: integer
    min: 1
    description: |
      How many iterations of the Leiden clustering algorithm to perform.
      When defined, positive values above 2 define the total number of iterations to perform.
      When not set, the algorithm will run until it reaches its optimal clustering.
  - name: "--seed"
    required: false
    type: integer
    description: |
      Fix the initialization of the optimization. Can be used to increase reproducibility.
    min: 0

  # arguments
  - name: "--resolution"
    type: double
    description: |
      A parameter value controlling the coarseness of the clustering. Higher values lead to more clusters.
      Multiple values will result in clustering being performed multiple times.
    default: [1]
    required: true
    multiple: true
__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.13-slim
    setup:
      - type: apt
        packages: 
          - procps
      - type: python
        __merge__: [/src/base/requirements/anndata_mudata.yaml, /src/base/requirements/scanpy.yaml, .]
        packages:
          - leidenalg~=0.11.0
    __merge__: [ /src/base/requirements/python_test_setup.yaml ]
runners:
  - type: executable
  - type: nextflow
    directives:
      label: [highcpu, midmem, middisk]
