Package: raccoon-cluster
<img src=”docs/figs/logo_rc.png” width=400, padding=100>## Resolution-Adaptive Coarse-to-fine Clusters OptimizatiON
### v 0.5.1[![GitHub tag (latest by date)](https://img.shields.io/github/v/tag/shlienlab/raccoon)](https://github.com/shlienlab/raccoon/releases/tag/v0.5.1)
[![PyPI](https://img.shields.io/pypi/v/raccoon-cluster)](https://pypi.org/project/raccoon-cluster/)
[![Licence](https://img.shields.io/github/license/shlienlab/raccoon)](https://github.com/shlienlab/raccoon/blob/main/LICENSE)
[![GitHub top language](https://img.shields.io/github/languages/top/shlienlab/raccoon)](https://github.com/shlienlab/raccoon/search?l=python)
[![Documentation Status](https://readthedocs.org/projects/raccoon-cluster/badge/?version=latest)](https://raccoon-cluster.readthedocs.io/en/latest/?badge=latest)RACCOON (raccoon) is a Python 3 package for top-down clustering automatization.
It searches for the optimal clusters in your data by running low information features removal, non-linear dimensionality reduction, and clusters identification. Tunable parameters at each of these steps are automatically set to maximize a clustering “goodness” score. This process is then repeated iteratively within each cluster identified.This library includesfeatures filtering by variance, MAD or t-SVDintegrated unsupervised/supervised UMAP non-linear dimensionality reductionclusters identification by DBSCAN, HDBSCAN, SNN or Louvainoptimization with grid search, differential evolution or TPEk-NN classificationGPU implementation with RAPIDSDetailed documentation, API references, FAQ and tutorials can be found at this [link](https://raccoon-cluster.readthedocs.io/en/latest/).### DependenciesBesides basic scientific and plotting libraries, the current version requires` -scikit-learn-scikit-network-umap-learn- optuna - seaborn `Optional dependencies include` - hdbscan -feather-format- rapids (see below) `### GPUraccoon can be run on GPU by leveraging RAPIDS libraries. Since these libraries are still in active development, the latest versions are required to avoid issues.` - cupy      v8.60 - cuml      v0.18 - cudf      v0.18 - cugraph   v0.18 `Currently, there are some limitations in this implementation (e.g. UMAP can only run with euclidean distance).
If these do not affect your analysis, we suggest activating the GPU option, especially for larger datasets that could lead to cumbersome runs. Alternatively, this option should be used for exploratory runs only.Important note: the GPU implementation is still a work in progress and may change considerably in the coming versions. Please report any bug or issue you experience.### ScriptsUseful scripts can be found in thescriptsfolder. These include files to read hdf5 storing the output pandas dataframe in R.
See the documentation for more details.### InstallationRaccoon releases can be easily installed through the python standard package managerpip install raccoon-cluster.To install the latest (unreleased) version you can download it from this repository by runninggit clonehttps://github.com/shlienlab/raccooncd raccoon
python setup.py install### Basic usageGiven aninputdataset in pandas-like format (samples X features), therunfunction will
automatically set up a clusters search with just some basic options.import raccoon as rccluster_membership, tree = rc.cluster(input, dim=2, pop_cut=25,optimizer=’auto’, dyn_mesh=True,
metric_clu=’cosine’, metric_map=’cosine’,
save_map=True, chk=True,
out_path=’./output’, gpu=False)### CitationWhen using this library, please cite> F. Comitani, J. O. Nash, S. Cohen-Gogo, A. Chang, T. T. Wen, A. Maheshwari, B. Goyal, E. S. L. Tio, K. Tabatabaei, R. Zhao, L. Brunga, J. E. G. Lawrence, P. Balogh, A. Flanagan, S. Teichmann, B. Ho, A. Huang, V. Ramaswamy, J. Hitzler, J. Wasserman, R. A. Gladdy, B. C. Dickson, U. Tabori, M. J. Cowley, S. Behjati, D. Malkin, A. Villani, M. S. Irwin and A. Shlien, “Multi-scale transcriptional clustering and heterogeneity analysis reveal diagnostic classes of childhood cancer” (under review).### ContributionsThis library is still a work in progress and we are striving to improve it, by adding more flexibility and increase the memory and time efficiency of the code. If you would like to be part of this effort, please fork the main branch and work from there. We plan on adding pytests and CI in the coming versions.Contributions are always welcome.