muspan.domain#

The muspan.domain module provides tools for working with spatial domains in the MuSpAn package.

class domain(name, unit_of_length='units')#

The basic container for all MuSpAn analysis. A domain keeps track of which pointclouds / shapeclouds, labels, and metadata are within the domain. The default domain is a unit cube in n-dimensions, with default units of length being “units”.

Parameters:

namestr: The name of the domain.
unit_of_lengthstr, optional: The unit of length for the domain. Default is ‘units’.

Attributes:

unit_of_lengthstr: The unit of length for the domain.
dimensionint: The number of dimensions of the domain.
n_collectionsint: Number of collections in the domain.
n_objectsint: Number of objects in the domain.
n_verticesint: Number of vertices in the domain.
max_IDint: Maximum ID of objects in the domain.
collectionsdict: Dictionary to store collections.
int_to_collectiondict: Dictionary to map collection integers to collection names.
objectsdict: Dictionary to store objects.
nd_componentsdict: Dictionary to store n-dimensional components.
colorsdict: Dictionary to store colors for collections, objects, and labels.
verticesnp.ndarray: Array to store vertices.
boundaryShape: Boundary shape of the domain.
labelsdict: Dictionary to store labels associated with objects.
networksdict: Dictionary to store network information.
distancesdict: Dictionary to store distance matrices.

Methods

`domain.add_points`(points[, collection_name, ...])	Adds points to this domain.
`domain.add_lines`(lines[, collection_name, ...])	Adds lines to this domain.
`domain.add_shapes`(shapes[, collection_name, ...])	Adds shapes to this domain.
`domain.add_shapes_with_internal_holes`(...[, ...])	Adds shapes to this domain which contain one or more internal voids.
`domain.add_labels`(label_name, labels[, ...])	Add labels to objects in the domain.
`domain.add_objects_to_collection`([...])	Add objects to a specified collection.
`domain.estimate_boundary`([method, ...])	Estimate the boundary of the domain using the specified method.
`domain.simplify_shape_boundaries`(shape_indices)	Simplify the boundaries of a set of shapes by removing vertices, using the Visvalingam-Whyatt algorithm.
`domain.update_colors`(new_colors[, ...])	Update the colors for labels, objects, or collections.
`domain.convert_objects`([population, ...])	Convert objects in the population to a specified type using a specified method.
`domain.delete_distances`([distance_metric])	Delete distance matrix stored within the domain.
`domain.delete_network`([network_name])	Delete a network stored within the domain.
`domain.delete_labels`([label_name])	Delete labels stored within the domain.
`domain.delete_objects`(objects_to_delete)	Delete objects from the domain.
`domain.print_labels`([label_name])	Print a table of labels of objects in the domain.
`domain.print_collections`()	Print a table of collections in the domain.

add_labels(label_name, labels, add_labels_to=None, label_type=None, cmap=None, bypass_checks=False)#

Add labels to objects in the domain.

Parameters:

label_namestr: The name of the label to be added.
labelslist or np.ndarray: The labels to be added. Must be the same length as the number of objects specified.
add_labels_tostr, query-like, list, np.ndarray, or None, optional: Specifies which objects to add labels to. Can be: - A string representing the name of a collection. - A query-like object to filter objects. - A list or 1D numpy array of object indices. - None, to apply labels to all objects in the domain. Default is None.
label_typestr, optional: The type of the label. Can be ‘categorical’ or ‘continuous’. Default is ‘categorical’.
cmapstr, optional: The colormap to use for categorical labels. If None, a default colormap is used. Default is None.

Raises:

ValueError: If add_labels_to is not a valid collection name, query-like object, or list of object indices. If the length of labels does not match the number of objects specified. If label_type is not ‘categorical’ or ‘continuous’.

Notes

If label_name already exists, the function updates the existing labels with the new ones.
For categorical labels, the function assigns colors based on the specified or default colormap.
For continuous labels, the function uses the ‘plasma’ colormap by default.

add_lines(lines, collection_name=None, zorder=20, return_IDs=False)#

Adds lines to this domain.

Parameters:

lineslist of array-like: List of m (n x d) arrays of d-dimensional points.
collection_namestr, optional: Name of a collection to add these objects to.
zorderint, optional: Z-order for plotting, by default 20.
return_IDsbool, optional: If True, the IDs of newly created objects will be returned as an array.

add_objects_to_collection(add_collection_to=None, collection_name=None)#

Add objects to a specified collection.

Parameters:

objectIDsint, list, np.ndarray, or query-like: The IDs of the objects to be added to the collection. It can be a single integer ID, a list or numpy array of IDs, or a query that returns object IDs.
collection_namestr or None: The name of the collection to which the objects will be added. If None, a default collection name ‘default_collection’ will be used.

Raises:

ValueError: If any of the provided object IDs do not exist in self.objects, or if the type of objectIDs is unrecognized.

add_points(points, collection_name=None, zorder=30, return_IDs=False)#

Adds points to this domain.

Parameters:

pointsarray-like, shape (n, d): Array of d-dimensional points.
collection_namestr, optional: Name of a collection to add these objects to.
zorderint, optional: Z-order for plotting, by default 30.
return_IDsbool, optional: If True, the IDs of newly created objects will be returned as an array.

add_shapes(shapes, collection_name=None, zorder=10, return_IDs=False)#

Adds shapes to this domain.

Parameters:

shapeslist of array-like: List of m (n x d) arrays of d-dimensional points.
collection_namestr, optional: Name of a collection to add these objects to.
zorderint, optional: Z-order for plotting, by default 10.
return_IDsbool, optional: If True, the IDs of newly created objects will be returned as an array.

add_shapes_with_internal_holes(shapes_and_holes, collection_name=None, zorder=10, return_IDs=False)#

Adds shapes to this domain which contain one or more internal voids.

Parameters:

shapes_and_holeslist of tuples: List of shape-holes pairs, where the first entry is an (n x d) array of d-dimensional points and the second entry is a list of m_hole x (n_hole x d) arrays of d-dimensional points.
collection_namestr, optional: Name of a collection to add these objects to.
zorderint, optional: Z-order for plotting, by default 10.
return_IDsbool, optional: If True, the IDs of newly created objects will be returned as an array.

convert_objects(population=None, collection_name='converted objects', object_type='point', conversion_method='centroid', conversion_method_kwargs={}, remove_parent_objects=False, inherit_collections=False, return_IDs=False, zorder=10)#

Convert objects in the population to a specified type using a specified method.

Parameters:

populationquery-like, optional: Query-like specifying the population of objects to analysis. Can be a list or array of object indices, a muspan query, or None to include all objects. Default is None.
collection_namestr, optional: Name of the collection to which the converted objects will be added. Default is ‘converted objects’.
object_typestr, optional: Type of objects to convert to. Options are ‘point’ or ‘shape’. Default is ‘point’.
conversion_methodstr, optional: Method to use for conversion. For ‘point’, options are ‘centroid’, ‘centroids’, ‘vertices’. For ‘shape’, options are ‘alpha shape’, ‘convex hull’, ‘boundary’, ‘voronoi’. Default is ‘centroid’.
conversion_method_kwargsdict, optional: Additional keyword arguments for the conversion method. Default is an empty dictionary.
remove_parent_objectsbool, optional: If True, parent objects will be removed after conversion. Default is False.
inherit_collectionsbool, optional: If True, the converted objects will inherit collections from their parent objects. Default is False.
return_IDsbool, optional: If True, the function will return the IDs of the new objects. Default is False.
zorderint, optional: Z-order for the new objects. Default is 10.

Returns:

new_object_idslist, optional: List of IDs of the new objects, if return_IDs is True.

Raises:

ValueError: If an invalid object_type or conversion_method is provided.

Notes

If alpha shape is used, the conversion_method_kwargs dictionary should contain the following ‘alpha’ key. Otherwise alpha=50 will be assumed.

delete_distances(distance_metric=None)#

Delete distance matrix stored within the domain.

Parameters:

distance_metricstr, optional: The key for the distance matrix to be deleted. Default is None.

Raises:

Warning: If no distance matrix is stored with the specified key.

delete_labels(label_name=None)#

Delete labels stored within the domain.

Parameters:

label_namestr, optional: The name of the label to delete. Default is None.

Raises:

Warning: If no label is stored with the specified name.

delete_network(network_name=None)#

Delete a network stored within the domain.

Parameters:

network_namestr, optional: The name of the network to delete. Default is None.

Raises:

Warning: If no network is stored with the specified name.

delete_objects(objects_to_delete)#

Delete objects from the domain.

This function performs the relevant bookkeeping of removing any object associated with labels, distances, and networks stored within the domain.

Parameters:

objects_to_deletequery, list, tuple, array, or int: The objects to delete. This can be a query, a list/tuple of indices, or a single integer.

Raises:

ValueError: If objects_to_delete is not of the correct type. Potential types are query, list, tuple, array, or int.

estimate_boundary(method='rectangle', alpha_shape_kwargs={}, specify_boundary_coords=None)#

Estimate the boundary of the domain using the specified method.

Parameters:

methodstr, optional: The method to use for boundary estimation. Options are ‘convex hull’, ‘rectangle’, ‘alpha shape’, and ‘specify’. If ‘specify’, pass a set of coordinates that will define the boundary. Default is ‘rectangle’.
alpha_shape_kwargsdict, optional: Keyword arguments to pass to the alpha shape function. Default is an empty dictionary.
specify_boundary_coordsarray-like, optional: An array of coordinates to specify the boundary. specify_boundary_coords must be a (nx2) array. Required if method is ‘specify’.

Raises:

ValueError: If the specified method is not one of the available options.