Package: bbknn
Batch balanced KNNBBKNN is a fast and intuitive batch effect removal tool that can be directly used in thescanpyworkflow. It serves as an alternative toscanpy.pp.neighbors(), with both functions creating a neighbour graph for subsequent use in clustering, pseudotime and UMAP visualisation. The standard approach begins by identifying the k nearest neighbours for each individual cell across the entire data structure, with the candidates being subsequently transformed to exponentially related connectivities before serving as the basis for further analyses. If technical artifacts (be they because of differing data acquisition technologies, protocol alterations or even particularly severe operator effects) are present in the data, they will make it challenging to link corresponding cell types across different batches.As such, BBKNN actively combats this effect by taking each cell and identifying a (smaller) k nearest neighbours in each batch separately, rather than the dataset as a whole. These nearest neighbours for each batch are then merged into a final neighbour list for the cell. This helps create connections between analogous cells in different batches without altering the counts or PCA space.CitationIf you use BBKNN in your work, please cite thepaper:@article{polanski2019bbknn,
  title={BBKNN: Fast Batch Alignment of Single Cell Transcriptomes},
  author={Pola{\'n}ski, Krzysztof and Young, Matthew D and Miao, Zhichao and Meyer, Kerstin B and Teichmann, Sarah A and Park, Jong-Eun},
  doi={10.1093/bioinformatics/btz625},
  journal={Bioinformatics},
  year={2019}
}InstallationBBKNN depends on Cython, numpy, scipy, annoy, pynndescent, umap-learn and scikit-learn. The package is available on pip and conda, and can be easily installed as follows:pip3installbbknnorcondainstall-cbiocondabbknnBBKNN can also make use of faiss. Consult theofficial installation instructions, the easiest way to get it is via conda.Usage and DocumentationBBKNN has the option to immediately slot into the spot occupied byscanpy.neighbors()in theSeurat-inspired scanpy workflow. It computes a batch aligned variant of the neighbourhood graph, with its uses within scanpy including clustering, diffusion map pseudotime inference and UMAP visualisation. The basic syntax to run BBKNN on scanpy's AnnData object (with PCA computed viascanpy.tl.pca()) is as follows:importbbknnbbknn.bbknn(adata)You can provide whichadata.obscolumn to use for batch discrimination via thebatch_keyparameter. This defaults to'batch', which is created by scanpy when you merge multiple AnnData objects (e.g. if you were to import multiple samples separately and then concatenate them).Integration can be improved by using ridge regression on both a technical effect and a biological grouping prior to BBKNN, following a workflow fromParket al., 2020. In the event of not having a biological grouping at hand, a coarse clustering obtained from a BBKNN-corrected graph can be used in its place. This creates the following basic workflow syntax:importbbknnimportscanpybbknn.bbknn(adata)scanpy.tl.leiden(adata)bbknn.ridge_regression(adata,batch_key=['batch'],confounder_key=['leiden'])scanpy.tl.pca(adata)bbknn.bbknn(adata)Alternately, you can just provide a PCA matrix with cells as rows and a matching vector of batch assignments for each of the cells and call BBKNN as follows (withconnectivitiesbeing the primary graph output of interest):importbbknn.matrixdistances,connectivities,parameters=bbknn.matrix.bbknn(pca_matrix,batch_list)An HTML render of the BBKNN function docstring, detailing all the parameters, can be accessed atReadTheDocs. BBKNN use, along with using ridge regression to improve the integration, is shown in ademonstration notebook.BBKNN in RAt this point, there is no plan to create a BBKNN R package. However, it can be ran quite easily via reticulate. Using the base functions is the same as in python. If you're in possession of a PCA matrix and a batch assignment vector and want to get UMAP coordinates out of it, you can use the following code snippet to do so. The weird PCA computation part and replacing it with your original values is unfortunately necessary due to how AnnData innards operate from a reticulate level. Provide your python path inuse_python()library(reticulate)use_python("/usr/bin/python3")anndata=import("anndata",convert=FALSE)bbknn=import("bbknn",convert=FALSE)sc=import("scanpy",convert=FALSE)adata=anndata$AnnData(X=pca,obs=batch)sc$tl$pca(adata)adata$obsm$X_pca=pcabbknn$bbknn(adata,batch_key=0)sc$tl$umap(adata)umap=py_to_r(adata$obsm[["X_umap"]])If you wish to change any integer arguments (such asneighbors_within_batch), you'll have toas.integer()the value so python understands it as an integer.When testing locally, faiss refused to work when BBKNN was reticulated. As such, provideuse_faiss=FALSEto the BBKNN call if you run into this problem.Example Notebooksdemo.ipynbis the main demonstration, applying BBKNN to some pancreas data with a batch effect. The notebook also uses ridge regression to improve the integration.TheBBKNN papermakes use of the following analyses:simulation.ipynbapplies BBKNN to simulated data with a known ground truth, and demonstrates the utility of graph trimming by introducing an unrelated cell population. This simulated data is then used to benchmark BBKNN against mnnCorrect, CCA, Scanorama and Harmony inbenchmark.ipynb, and then finish off with a benchmarking of a BBKNN variant reluctant to work within R/reticulate and visualise the findings inbenchmark2.ipynb.benchmark3-new-R-methods.ipynbadds some newer R approaches to the benchmark.mouse.ipynbruns a collection of murine atlases through BBKNN.mouse-harmony.ipynbapplies Harmony to the same data.TheBBKNN preprintperformed some additional analyses that got left out of the final manuscript. Archival notebooks are stored in aseparate repository.