By incorporating neighborhood information for clustering, BANKSY is able to:
Improve cell-type assignment in noisy data
Distinguish subtly different cell-types stratified by microenvironment
Identify spatial zones sharing the same microenvironment
BANKSY is applicable to a wide variety of spatial technologies (e.g. 10x Visium, Slide-seq, MERFISH) and scales well to large datasets. For more details on use-cases and methods, see the preprint.
This Python version of BANKSY (compatible with Scanpy), we show how BANKSY can be used for task 1 (improving cell-type assignment) using Slide-seq and Slide-seq V2 mouse cerebellum datasets.
The R version of BANKSY is available here (https://github.com/prabhakarlab/Banksy).
Changes for v1.3.0:
Now pip-installable! Install with pip install pybanksy
AGF has been corrected to align with R version. Normalization is with mean neighbour expression rather than mean of the modulated expression ($e^{\phi}$)
Prerequisites
Requirements
Python: 3.8 - 3.12
RAM: At least 16 GB recommended
Dependencies: Automatically installed via pip (see pyproject.toml)
Optional Dependencies
For mclust clustering (alternative to Leiden):
pip install "pybanksy[mclust]"
Requires R and rpy2.
For Jupyter notebooks:
pip install "pybanksy[notebooks]"
For everything (mclust + Jupyter):
pip install "pybanksy[all]"
Note: BANKSY uses Leiden clustering by default (included). Advanced users can also use any clustering method on the BANKSY matrix, including scanpy.tl.louvain().
Note: To run the slideseq_v2 dataset, download the data from the original source and save it in the data/slide_seq/v2 folder.
General Steps of the BANKSY algorithm
To run BANKSY on a spatial single-cell expression dataset in anndata
format:
Preprocess the gene-cell matrix using Scanpy. This includes filtering out cells and genes by various criteria, and
(for sequencing-based technologies e.g. 10X Visium or Slide-seq) selecting the most highly variable genes.
intitalize_banksy to generate the spatial graph (stored
in banksy_dict object).
run_banksy_multiparam to perform dimensionality reduction and clustering.
Note that individual BANKSY matrices (for given hyperparameter settings)
can be accesed from the banksy_dict object.
For example, to access the BANKSY matrix generated using
scaled_gaussian decay and lambda = 0.2, use banksy_dict['scaled gaussian'][0.2]["adata"].
(optional) For advanced users who want to understand the entire BANKSY pipeline, you also can run individual steps below:
Preprocess gene-cell matrix (as above). z-score by gene using banksy.main.zscore or scanpy.pp.scale. Functions provided in the Scanpy package handle most of these steps. Parameters and filtering criterion may vary by spatial technology and dataset source.
Constructing the spatial graph which defines spatial neighbour relationships using banksy.main.generate_spatial_weights_fixed_nbrs. This outputs a sparse adjacency matrix defining the graph. Visualize these with banksy_utils.plotting.plot_graph_weights. Some parameters that affect this step are:
The spatial graph can be generated via the $k_{geom}$ parameter, which connects a cell to its $k_{geom}$ nearest neighbours. This spatial graph is the basis in which the neighbourhood matrix $M$ and the azimuthal gabor filter (AGF) matrix $G$ is constructed.
decay types: By default, we recommend scaled_gaussian, which weights a cell's neighbour expression as a gaussian envelope. Alternative methods include uniform which weights all neighbours equally, reciprocal weights neighbours by $1/r$ where $r$ is the distance from neighbouring cell to the index cell. ranked ranks neighbouring cells by distance with farther cells having higher rank, then sets Gaussian decay by rank. Sum of neighbour weights are always normalized to 1 for each cell.
generate_spatial_weights_fixed_radius (not used in paper) generates a spatial graph where each cell is connected to all cells within a given radius. This leads to variable numbers of neighbours per cell.
drawing
Generate neighbour expression matrix $N$ (ncells by ngenes) using spatial graph to average over spatial neighbours. The neighbourhood matrix can be computed by sparse matrix multiplication of the spatial graph's adjacency matrix with the gene-cell matrix. Similarly, the AGF matrix $G$ (ncells by ngenes) which represents the magnitude of expression gradient is also generated from the azimuthal transform.
Scale original expression matrix by $√(1 - λ)$ and neighbour expression matrix by √(λ) and concatenate matrices to obtain neighbour-augmented expression matrix (ncells by 2ngenes) using banksy.main.weighted_concatenate with neighbourhood_contribution = $λ$. These operations are performed on the numerical data adata.X; use banksy.main.bansky_matrix_to_adata to recover Anndata object with the appropriate annotations.
drawing
The following steps are identical to single cell RNA seq analysis:
Dimensionality reduction, particularly PCA to reduce expression matrix (either neighbour-augmented or original for comparison) to (ncells by nPCA_dims). As a default, we set $PCA_{dims}$ = 20.
Clustering cells by finding neighbours in expression space and cluster using graph-based clustering. Here we find expression-neighbours and perform Leiden clustering following the implemenation in Giotto.
Refinement (Optional) In the prescene of noisy clusters, we offer an optional refinement step via banksy_utils.refine_clusters to smooth labels in the clusters exclusively for domain segmentation tasks. However, we do not recommend the use of excessive refinement as it wears out fine-grained domains.
Other useful tools in package
banksy.main.LeidenPartition
Finds neighbours in expression space and performs Leiden clustering. Aims to replicate implementation from the Giotto package as of 2020 to align with R version of the code. Note that scanpy also has a Leiden clustering implemenation with a different procedure for defining expression neighbours that can be used as an alternative. BANKSY is compatible with any clustering algorithm that takes a feature-cell matrix as input.
labels.Label
Object for convenient computation with class labels. Converts labels to sparse one-hot vector for fast computation of connectivity across clusters with spatial graph. To obtain an array of integer labels in the usual format (e.g. [1, 1, 5, 2, ...]), use Label.dense.
Examples to get started
We recommend the following examples to get started with the BANKSY package
To reproduce the results from our manuscript, please use the branch BANKSY-manuscript.
Contributing
Bug reports, questions, request for enhancements or other contributions can be raised at the issue
page, or you may submit a pull request with your changes.
