Package: nimble-raccoon
# nimble raccoonA slim and fast reimplementation of [RACCOON](https://github.com/shlienlab/raccoon)
(Resolution-Adaptive Coarse-to-fine Clusters OptimizatiON), iterative clustering library for python 3.<!–
<img src=”docs/figs/sps_logo.png” width=400, padding=100>
[![DOI](https://zenodo.org/badge/91130860.svg)](https://zenodo.org/badge/latestdoi/91130860)
[![PyPI version](https://badge.fury.io/py/simpsom.svg)](https://badge.fury.io/py/simpsom)
[![Documentation Status](https://readthedocs.org/projects/simpsom/badge/?version=latest)](https://simpsom.readthedocs.io/en/latest/?badge=latest)
![example workflow](https://github.com/fcomitani/simpsom/actions/workflows/pytest.yml/badge.svg)
[![codecov](https://codecov.io/gh/fcomitani/simpsom/branch/main/graph/badge.svg?token=2OHOCO0O4I)](https://codecov.io/gh/fcomitani/simpsom)
–>It relies on [faiss](https://github.com/facebookresearch/faiss) for quick nearest neighbors searches and better memory management,
but offers fewer functionalities, only allowingcosineandeuclideandistances, Louvain as its clustering algorithm, and grid search.## Installationnimble-raccooncan be installed withpipwith the following commandpip install nimble-raccoon<!– For the GPU-enable version, clone this repo and install add the-gpuflag –>## UsageTo identify clusters and build the hierarchy initialize aRaccoonobject
with set parameters and then call it on theinput_dataobject, a pandas dataframe.import numpy as np
from functools import partialfrom nimbloon import RaccoonYou can define custom functions to dynamically adapt the search range
to the size of the dataset.def half_sqrt_range(x, num_elements=5):sq = np.sqrt(x)
return np.linspace(sq/2, sq, num_elements, dtype=int)rc_args = {‘metric’: ‘cosine’,‘scale’: False,
‘cumulative_variance’: [.75, .8, .9, .95, .99],
‘clustering_parameter’: np.logspace(-2, 1.5, 10),
‘n_neighbors’: partial(half_sqrt_range, num_elements=3),
‘target_dimensions’: 12,
‘min_cluster_size’: 25,
‘max_neighbors’: 100,
‘silhouette_threshold’: 0.,
‘max_depth’: 5}Once everything is set up you can instantiate the Raccoon object.rc = Raccoon(outh_path=’./rc_output’, **rc_args)And then call it on the input dataset to build the clusters hierarchy.rc_labels, rc_tree = rc(input_table)Available parameters are:metric: the distance metric, currently onlycosineandeuclideancan be set as metrics.scale:  scale features at every iteration.cumulative_variance: the limit of cumulative variance for low-informationfeatures removal with tSVD. Can be a singlefloator alistoffloatclustering_parameter: the range of resolutions for the Louvain clusteringalgorithm. Can be a singlefloator alistoffloatn_neighbors: the number of nearest neighbors to use across the search.Can be a singleintor alistofint. Can also be a function, in which case this will be applied to the input set size,
adapting this parameter at each iteration.target_dimensions: the dimensionality of the target space afterapplying UMAP.min_cluster_size: minimum size of clusters, if a cluster is identifiedwith size below this threshold, it will not be further split.max_neighbors: maximum number of neighbors, useful whenn_neighborsisdynamic and population dependent avoiding excessively costly operations for large datasets.silhouette_threshold: minimum silhouette score value to reach for apartition to be accepted.max_depth: maximum depth of the clusters hierarchy.The output will be a one-hot-encoded dataframe with samples as rows and cluster labels as columns, and an anytree object with information on the
hierarchical relationship among clusters.
This information will also be automatically saved to disk in theout_pathfolder.Both tSVD and UMAP steps can be skipped, by settingcumulative_varianceto1and/ortarget_dimensionstoNonerespectively.## CitationIf you are using this library for your work, please cite the original RACCOON publication.> Comitani, F., Nash, J.O., Cohen-Gogo, S. et al. Diagnostic classification of childhood cancer using multiscale transcriptomics. Nat Med 29, 656–666 (2023).https://doi.org/10.1038/s41591-023-02221-x## ContributionsContributions are always welcome. If you would like to help us improve this library please fork the main branch and make sure pytest pass after your changes.