summarise_distribution

summarise_distribution(domain, population=None, include_boundaries=None, exclude_boundaries=None, boundary_exclude_distance=0, weight_by_label=None, max_std=1, add_outputs_as_objects=True, summary_collection_name='spatial summaries', summary_label_name='summary descriptors')

Summarises the spatial distribution of objects within a given domain providing the mean centre, standard distance, and standard deviational ellipses.

Parameters:

domainobject

A muspan domain object.

populationquery-like, optional

Query-like specifying the population of objects to include in the spatial summary. Can be a list or array of object indices, a muspan query, or None to include all objects. Default is None.

include_boundariesquery-like, optional

Query specifying the external boundaries within which to perform the spatial summary. Can be a list or array of object indices, a muspan query, or None to use the entire domain. Default is None.

exclude_boundariesquery-like, optional

Query specifying the internal boundaries (i.e., excluded regions within the shapes defined by include_boundaries) within which to perform the spatial summary. Can be a list or array of object indices, a muspan query, or None. Default is None.

boundary_exclude_distancefloat, optional

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

weight_by_labelstr, optional

Label to weight the spatial distribution of objects. Must be a continuous label. Defaults to None.

max_stdint, optional

Maximum number of standard deviations for the standard deviational ellipse. Must be between 1 and 3. Default is 1.

add_outputs_as_objectsbool, optional

If True, adds the output shapes and points as objects in the domain. Default is True.

summary_collection_namestr, optional

Name of the collection to store the summary shapes and points. Default is ‘spatial summaries’.

summary_label_namestr, optional

Name of the label to assign to the summary shapes and points. Default is ‘summary descriptors’.

Returns:

mean_centrenumpy.ndarray

The mean centre of the objects.

std_distancefloat

The standard distance of the objects from the mean centre.

list_of_std_ellipseslist

A list of standard deviational ellipses.

Raises:

ValueError

If max_std is not an integer or is not between 1 and 3. If weight_by_label is not in the domain labels or is not continuous. If all objects do not have the specified weight_by_label.