spateo.tools.cluster.spagcn_utils ================================= .. py:module:: spateo.tools.cluster.spagcn_utils Classes ------- .. autoapisummary:: spateo.tools.cluster.spagcn_utils.GraphConvolution spateo.tools.cluster.spagcn_utils.simple_GC_DEC spateo.tools.cluster.spagcn_utils.SpaGCN Functions --------- .. autoapisummary:: spateo.tools.cluster.spagcn_utils.calculate_adj_matrix spateo.tools.cluster.spagcn_utils.calculate_p spateo.tools.cluster.spagcn_utils.search_l spateo.tools.cluster.spagcn_utils.get_cluster_num spateo.tools.cluster.spagcn_utils.search_res spateo.tools.cluster.spagcn_utils.refine Module Contents --------------- .. py:function:: calculate_adj_matrix(x, y, x_pixel=None, y_pixel=None, image=None, beta=49, alpha=1, histology=True) (Part of spagcn algorithm) Function to calculate adjacent matrix according to spatial coordinate and image pixels. :param x: a list which contains corresponding x-coordinates for the spots, spatialy. :type x: list :param y: a list which contains corresponding y-coordinates for the spots, spatialy. :type y: list :param x_pixel: a list which contains corresponding x-pixels for the spots, in histology image. Defaults to None. :type x_pixel: list, optional :param y_pixel: a list which contains corresponding y-pixels for the spots, in histology image. Defaults to None. :type y_pixel: list, optional :param image (class: `numpy.ndarray`, optional): the image(typically histology image) in `numpy.ndarray` format(can be obtained by cv2.imread). Defaults to None. :param beta: to control the range of neighbourhood when calculate grey value for one spot. Defaults to 49. :type beta: int, optional :param alpha: to control the color scale. Defaults to 1. :type alpha: int, optional :param histology: if the image is histological. Defaults to True. :type histology: bool, optional :returns: `numpy.ndarray`: the calculated adjacent matrix. :rtype: class .. py:function:: calculate_p(adj, l) .. py:function:: search_l(p, adj, start=0.01, end=1000, tol=0.01, max_run=100) Function to search proper `l` value for spagcn algorithm. :param p: parameter `p` in spagcn algorithm. See `SpaGCN` for details. :type p: float, optional :param adj (class: `numpy.ndarray`): the calculated adjacent matrix in spagcn algorithm. :param start: lower boundary of search. Defaults to 0.01. :type start: float, optional :param end: upper boundary of search. Defaults to 1000. :type end: int, optional :param tol: step length for search. Defaults to 0.01. :type tol: float, optional :param max_run: maximum number of searching iteration. Defaults to 100. :type max_run: int, optional :returns: the `l` value :rtype: float .. py:function:: get_cluster_num(adata, adj, res, tol, lr, max_epochs, l, r_seed=100, t_seed=100, n_seed=100) get the initial number of clusters corresponding to given louvain resolution. :param adata: further passed to SpaGCN.train(), see `SpaGCN.train`. :param adj: further passed to SpaGCN.train(), see `SpaGCN.train`. :param res: further passed to SpaGCN.train(), see `SpaGCN.train`. :param tol: further passed to SpaGCN.train(), see `SpaGCN.train`. :param lr: further passed to SpaGCN.train(), see `SpaGCN.train`. :param max_epochs: further passed to SpaGCN.train(), see `SpaGCN.train`. :param l: parameter `l` in spagcn algorithm, see `SpaGCN` for details. :type l: float :param r_seed: Global seed for `random`, `torch`, `numpy`. Defaults to 100. :type r_seed: int, optional :param t_seed: Global seed for `random`, `torch`, `numpy`. Defaults to 100. :type t_seed: int, optional :param n_seed: Global seed for `random`, `torch`, `numpy`. Defaults to 100. :type n_seed: int, optional :returns: number of clusters :rtype: int .. py:function:: search_res(adata, adj, l, target_num, start=0.4, step=0.1, tol=0.005, lr=0.05, max_epochs=10, r_seed=100, t_seed=100, n_seed=100, max_run=10) Function to search a proper initial louvain resolution to get desired number of clusters in spagcn algorithm. :param adata (class: `~anndata.AnnData`): an Annadata object. :param adj (class: `numpy.ndarray`): the calculated adjacent matrix in spagcn algorithm. :param l: parameter `l` in spagcn algorithm, see `SpaGCN` for details. :type l: float :param target_num: desired number of clusters. :type target_num: int :param start: the lower boundary of search for resolution. Defaults to 0.4. :type start: float, optional :param step: search step length. Defaults to 0.1. :type step: float, optional :param tol: further passed to SpaGCN.train(), see `SpaGCN.train`. :param lr: further passed to SpaGCN.train(), see `SpaGCN.train`. :param max_epochs: further passed to SpaGCN.train(), see `SpaGCN.train`. :param r_seed: Global seed for `random`, `torch`, `numpy`. Defaults to 100. :type r_seed: int, optional :param t_seed: Global seed for `random`, `torch`, `numpy`. Defaults to 100. :type t_seed: int, optional :param n_seed: Global seed for `random`, `torch`, `numpy`. Defaults to 100. :type n_seed: int, optional :param max_run: max number of iteration. Defaults to 10. :type max_run: int, optional :returns: calculated initial louvain resolution. :rtype: float .. py:function:: refine(sample_id, pred, dis, shape='square') To refine(smooth) the boundary of spatial domains(clusters). :param sample_id: list of sample(cell, spot or bin) names. :type sample_id: list :param pred: list of spatial domains corresponding to the sample_id list. :type pred: list :param dis (class: `numpy.ndarray`): the calculated adjacent matrix in spagcn algorithm. :param shape: Smooth the spatial domains with given spatial topology, "hexagon" for Visium data, "square" for ST data. Defaults to "square". :type shape: str, optional :returns: list of refined spatial domains corresponding to the sample_id list. :rtype: [list] .. py:class:: GraphConvolution(in_features, out_features, bias=True) Bases: :py:obj:`torch.nn.Module` Simple GCN layer, similar to https://arxiv.org/abs/1609.02907 .. py:attribute:: in_features .. py:attribute:: out_features .. py:attribute:: weight .. py:method:: reset_parameters() .. py:method:: forward(input, adj) .. py:method:: __repr__() .. py:class:: simple_GC_DEC(nfeat, nhid, alpha=0.2) Bases: :py:obj:`torch.nn.Module` Simple NN model constructed with a GraphConvolution layer followed by a DeepEmbeddingClustering layer. For DEC, see https://arxiv.org/abs/1511.06335v2 .. py:attribute:: gc .. py:attribute:: nhid .. py:attribute:: alpha :value: 0.2 .. py:method:: forward(x, adj) .. py:method:: loss_function(p, q) .. py:method:: target_distribution(q) .. py:method:: fit(X, adj, lr=0.001, max_epochs=5000, update_interval=3, trajectory_interval=50, weight_decay=0.0005, opt='sgd', init='louvain', n_neighbors=10, res=0.4, n_clusters=10, init_spa=True, tol=0.001) .. py:method:: predict(X, adj) .. py:class:: SpaGCN Bases: :py:obj:`object` Implementation for spagcn algorithm, see https://doi.org/10.1038/s41592-021-01255-8 .. py:attribute:: l :value: None .. py:method:: set_l(l) .. py:method:: train(adata, adj, num_pcs=50, lr=0.005, max_epochs=2000, weight_decay=0, opt='adam', init_spa=True, init='louvain', n_neighbors=10, n_clusters=None, res=0.4, tol=0.001) train model for spagcn :param adata (class: `~anndata.AnnData`): an Annadata object. :param adj (class: `numpy.ndarray`): the calculated adjacent matrix in spagcn algorithm. :param num_pcs: number of pcs(out dimension of PCA) to use. Defaults to 50. :type num_pcs: int, optional :param lr: learning rate in neural network. Defaults to 0.005. :type lr: float, optional :param max_epochs: max epochs to train in neural network. Defaults to 2000. :type max_epochs: int, optional :param weight_decay: make learning rate decay while training. Defaults to 0. :type weight_decay: int, optional :param opt: the optimizer to use. Defaults to "adam". :type opt: str, optional :param init_spa: make initial clusters with louvain or kmeans. Defaults to True. :type init_spa: bool, optional :param init: algorithm to use in inital clustering. Supports "louvain", "kmeans". Defaults to "louvain". :type init: str, optional .. py:method:: predict()