name: find_neighbors
namespace: "neighbors"
scope: "public"
description: |
  Compute a neighborhood graph of observations [McInnes18].

  The neighbor search efficiency of this heavily relies on UMAP [McInnes18], which also provides a method for estimating connectivities of data points - the connectivity of the manifold (method=='umap'). If method=='gauss', connectivities are computed according to [Coifman05], in the adaption of [Haghverdi16].
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: "--obsm_input"
    type: string
    default: "X_pca"
    required: false
    description: "Which .obsm slot to use as a starting PCA embedding."

  # output
  - name: "--output"
    alternatives: ["-o"]
    type: file
    description: Output h5mu file containing the found neighbors.
    direction: output
    example: output.h5mu
  
  - name: "--uns_output"
    type: string
    default: neighbors
    description: Mandatory .uns slot to store various neighbor output objects.
      
  - name: "--obsp_distances"
    type: string
    default: "distances"
    description: "In which .obsp slot to store the distance matrix between the resulting neighbors."
      
  - name: "--obsp_connectivities"
    type: string
    default: "connectivities"
    description: "In which .obsp slot to store the connectivities matrix between the resulting neighbors."

  # arguments
  - name: "--metric"
    type: string
    default: "euclidean"
    description: The distance metric to be used in the generation of the nearest neighborhood network.
    choices: [ 'cityblock', 'cosine', 'euclidean', 'l1', 'l2', 'manhattan', 'braycurtis', 'canberra', 'chebyshev', 'correlation', 'dice', 'hamming', 'jaccard', 'kulsinski', 'mahalanobis', 'minkowski', 'rogerstanimoto', 'russellrao', 'seuclidean', 'sokalmichener', 'sokalsneath', 'sqeuclidean', 'yule' ]

  - name: "--num_neighbors"
    type: integer
    default: 15
    description: The size of local neighborhood (in terms of number of neighboring data points) used for manifold approximation. Larger values result in more global views of the manifold, while smaller values result in more local data being preserved. In general values should be in the range 2 to 100. If knn is True, number of nearest neighbors to be searched. If knn is False, a Gaussian kernel width is set to the distance of the n_neighbors neighbor.
    
  - name: "--seed"
    type: integer
    default: 0
    description: A random seed.
__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: [lowcpu, midmem, middisk]
