cluster_neighbourhoods

cluster_neighbourhoods(domains_to_analyse, label_name, populations_to_analyse=None, neighbourhood_source=None, include_boundaries=None, exclude_boundaries=None, boundary_exclude_distance=0, network_kwargs={'network_type': 'Delaunay'}, k_hops=3, force_labels_to_include=[], labels_to_ignore=[], transform_neighbourhood_composition=None, neighbourhood_label_name='Neighbourhood ID', cluster_method='kmeans', cluster_parameters={'n_clusters': 8}, neighbourhood_enrichment_as='zscore', return_observation_matrix=False)

The function generates a network of objects and finds the neighbourhoods, calculates the composition of labels within the neighbourhoods, and clusters the neighbourhoods based on the label composition. The size of the neighbourhoods is determined by type of network and the number of hops from the source object. Neighbourhood enrichment is calculated as the z-score or log-fold change of the neighbourhood composition compared to the global composition. Neighbourhood labels are added to the objects in the domain. This function allows for the analysis of multiple domains and the comparison of neighbourhoods across domains.

Parameters:

domains_to_analyselist or object

A list of muspan domains or a single muspan domain to be analyzed.

label_namestr

The name of the label to be used for clustering.

populations_to_analysearray-like, query-like, or None, optional

Populations to be analyzed within the domains. If None, defaults to the neighbourhood_source.

neighbourhood_sourcearray-like, query-like, or None, optional

Source of neighbourhoods within the domains. If None, defaults to populations_to_analyse.

include_boundariesarray-like, query-like, or None, optional

Boundaries to include in the analysis. If None, no boundaries are included.

exclude_boundariesarray-like, query-like, or None, optional

Boundaries to exclude from the analysis. If None, no boundaries are excluded.

boundary_exclude_distancefloat, optional

Distance to exclude from the boundaries. Default is 0.

network_kwargsdict, optional

Keyword arguments for the network generation passed through to generate_network. See generate_network for all options. Default is {‘network_type’:’Delaunay’}.

k_hopsint, optional

Number of hops for neighbourhood construction. k-hop neighbourhoods are all nodes reachable in k edges from a source node. Default is 3.

force_labels_to_includelist, optional

Labels to forcefully include in the analysis. Default is an empty list.

labels_to_ignorelist, optional

Labels to ignore in the analysis. Default is an empty list.

transform_neighbourhood_compositionstr, optional

Transformation method for the neighbourhood composition. Options are ‘log’ or ‘sqrt’. If ‘log’ is selected, the transformed Mt=log(1e4*M+1) is performed, for M original the orginal composition matrix. If ‘sqrt’ is selected, Mt=sqrt(M). Default is None.

neighbourhood_label_namestr, optional

Name for the neighbourhood label. Default is ‘Neighbourhood ID’.

cluster_methodstr, optional

Clustering method to use. Default is ‘kmeans’.

cluster_parametersdict, optional

Parameters for the clustering method. Default is dict(n_clusters=8).

neighbourhood_enrichment_asstr, optional

Method to calculate neighbourhood enrichment. Options are ‘zscore’ or ‘log-fold’. The ‘log-fold’ option computes the log2 fold change. Default is ‘zscore’.

return_observation_matrixbool, optional

Whether to return the observation matrix. Adds additional output in return tuple if True. Default is False.

Returns:

neighbourhood_enrichment_matrixnumpy.ndarray

Matrix representing the enrichment of neighbourhoods.

consistent_global_labelslist

List of consistent global labels across all domains.

unique_cluster_labelsnumpy.ndarray

Array of unique cluster labels.

If return_observation_matrix is True:

global_comp_matrixnumpy.ndarray

The global composition matrix.