generate_network#

generate_network(domain, network_name='default_network', objects_as_nodes=None, include_boundaries=None, exclude_boundaries=None, boundary_exclude_distance=0, network_type='Delaunay', inverse_distance_function=None, min_edge_distance=0, max_edge_distance=inf, number_of_nearest_neighbours=10, store_network=True, n_jobs=1)#

Generate a spatial network using domain objects. The network can stored within the domain under a given name for future use. Nodes are indexed using Object ID for consistent querying

Parameters:
domainobject

The domain containing the objects to be used for network generation.

network_namestr, optional

The name of the network, by default ‘default_network’.

objects_as_nodesarray-like, query-like, or None, optional

The objects_as_nodes to select specific objects, by default None.

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

Boundaries to include in the analysis. Defaults to None.

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

Boundaries to exclude from the analysis. Defaults to None.

boundary_exclude_distancefloat, optional

Buffer to exclude objects located within boundary_exclude_distance from the boundaries. Defaults to 0.

network_typestr, optional

The type of network to generate. Options are ‘Delaunay’ (Delaunay triangulation), ‘KNN’ (K-nearest neighbour), ‘Proximity’ and ‘RNG’ (relative neighbourhood graph).

inverse_distance_functioncallable, optional

Function to compute inverse distance, by default None.

min_edge_distancefloat, optional

Minimum edge distance, by default 0.

max_edge_distancefloat, optional

Maximum edge distance, by default np.inf.

number_of_nearest_neighboursint, optional

Number of nearest neighbours for KNN. Only used for KNN networks, by default 10.

store_networkbool, optional

Whether to store the network in the domain, by default True.

n_jobsint, string, optional

Number of cores to use for parallelisation of object-object distance computations in proximity networks with shapes. n_jobs=1 computes without parallisation, n_jobs=-1 computes will all available cores. n_jobs=’auto’ set the n_jobs using the number of computations. Defaults to 1.

Returns:
networkx.Graph

The generated network. KNN networks will return a directed network (networkx.DiGraph).

Raises:
ValueError

If the network type is not implemented or if the objects_as_nodes is of incorrect type.

Notes

  • Delaunay networks estimates a natural geometric triangulation for pointclouds. In spatial applications, a Delaunay network approximates contact-based connectivity using only centroid data. See Delaunay networks for more information.

  • K-Nearest Neighbours (KNN) networks estimates the local connectivity of points in space by connecting any object to it’s k closest objects. See KNN networks for more information.

  • Proximity networks define connectivity purely by distance thresholds. See Proximity networks for more information.

  • Relative Neighbourhood Graph (RNG) esimtates the natural connectivity of points in space. MuSpAn implements the Urquhart approximation to the RNG for computational efficiency. See RNGs for more information.

If parallisation is producing a ValueError: cannot pickle ‘_thread._local’ object, this is likely due to the domain object not being serializable. In this case, add if __name__ == “__main__”: to the top of your script or you can set n_jobs=1 to disable parallisation.

Examples

Example of generating a Delaunay network from all objects in the domain:

import muspan as ms

# load example domain
example_domain = ms.datasets.load_example_domain('Synthetic-Points-Architecture')

# generate a Delaunay network with maximum edge distance of 50 units
dt_network = ms.networks.generate_network(example_domain,
                                        network_name='DT-network',
                                        network_type='delaunay',
                                        max_edge_distance=50,
                                        min_edge_distance=0)

# visualise the generated network
ms.visualise.visualise_network(example_domain,
                            network_name='DT-network',
                            visualise_kwargs=dict(color_by='Celltype'))

Example of generating a proximity network from a specific collection of shape objects in the domain:

import muspan as ms

# load example domain
example_domain = ms.datasets.load_example_domain('Xenium-Healthy-Colon')

# generate and visualise a proximity network based on cell boundaries 
prox_network = ms.networks.generate_network(example_domain,
                                        network_name='contact-network',
                                        network_type='proximity',
                                        objects_as_nodes=('collection','Cell boundaries'),
                                        max_edge_distance=2,
                                        min_edge_distance=0)

ms.visualise.visualise_network(example_domain,
                            network_name='contact-network',
                            visualise_kwargs=dict(color_by='Cluster ID'))

Example of generating a KNN network with specific value of k:

import muspan as ms

# load example domain
example_domain = ms.datasets.load_example_domain('Synthetic-Points-Architecture')

# generate a k-nearest neighbours network for k = 10
knn_network = ms.networks.generate_network(example_domain,
                                        network_name='knn-network',
                                        network_type='KNN',
                                        number_of_nearest_neighbours=10)

# visualise the k-nearest neighbours network
ms.visualise.visualise_network(example_domain,
                            network_name='knn-network',
                            visualise_kwargs=dict(color_by='Celltype'))
On this page