morisita_horn_index

morisita_horn_index(domain, label_name, population=None, include_boundaries=None, exclude_boundaries=None, boundary_exclude_distance=0, regions_collection_name=None, regions_label_name=None, region_method='quadrats', region_kwargs={}, keep_regions_as_objects=False, visualise_output=False, visualise_correlation_matrix_kwargs={'center': 0.5, 'cmap': 'viridis', 'colorbar_label': 'Morisita-Horn index', 'colorbar_limit': [0, 1]})

Calculate the Morisita-Horn index for a given domain and label. The Morisita-Horn index is a measures the similarity of observations of a label within regions of a domain. Index values range from 0 to 1, where 0 indicates no overlap and 1 indicates complete overlap of the label observations. Regions are generated using either quadrats or hexagonal grids, or using pre-defined labels in the domain using regions_label_name or a collection of shape objects using regions_collection_name. The Morisita-Horn index is calculated for each pair of label categories and returned as a matrix.

Parameters:

domainobject

A muspan domain.

label_namestr

The name of the label to use to calculate the Morisita-Horn index on.

populationquery-like, optional

Query-like specifying the population of objects to include in the Morisita-Horn index. 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 Morisita-Horn index. 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 Morisita-Horn index. 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.

regions_collection_namestr, optional

The name of the regions collection, by default None.

regions_label_namestr, optional

The name of the label used to assign objects to regions, by default None.

region_methodstr, optional

The method to generate regions if no region colleciton or region label name provided, by default ‘quadrats’. Options are ‘hexgrid’ or ‘quadrats’.

region_kwargsdict, optional

Additional keyword arguments for region generation, by default {}.

keep_regions_as_objectsbool, optional

Whether to keep regions as objects if regions are constructed with this function, by default False.

visualise_outputbool, optional

Whether to visualise the index matrix. Default is False.

visualise_correlation_matrix_kwargsdict, optional

Additional keyword arguments for visualising the correlation matrix.

Returns:

morisita_horn_index_pairwise_matrixnumpy.ndarray

The Morisita-Horn index matrix for all pairwise combinations of label categories.

label_categorieslist

The list of label categories.

Raises:

RuntimeError

If the label name is not in the list of generated labels, if the label is not categorical, or if the region method is not recognised.

Notes

For more information on the Morisita-Horn index, see https://www.jstor.org/stable/2459242.