kernel_density_estimation#
- kernel_density_estimation(domain, population=None, include_boundaries=None, exclude_boundaries=None, mesh_step=10, bw_method=None, add_contribution_as_labels=False, contribution_label_name='KDE', visualise_output=False, visualise_heatmap_kwargs={})#
Perform kernel density estimation (KDE) on a given domain. The KDE is evaluated on a mesh grid, with values outside the boundary masked as NaN and density values rescaled to be a valid probability density function.
- Parameters:
- domainDomain
The domain object containing the data. Must have a dimension attribute and objects dictionary.
- populationquery-like, optional
Query-like specifying the population of objects to include in the KDE. Can be a list or array of object indices, a muspan query, or None to include all objects. Default is None.
- include_boundarieslist, np.ndarray, or query-like, optional
The query specifying the external boundaries within which to perform the KDE. Can be a list or array of object indices, a muspan query, or None to use the entire domain. Default is None.
- exclude_boundarieslist, np.ndarray, or query-like, optional
The query specifying the internal boundaries (i.e., excluded regions within the shapes defined by include_boundaries) within which to perform the KDE. Can be a list or array of object indices, a muspan query, or None. Default is None.
- mesh_stepint or list of two ints, optional
The resolution of the mesh grid for KDE evaluation. Can be a single integer for both dimensions or a list of two integers for x and y resolutions. Default is 100.
- bw_methodstr, scalar, or callable, optional
The method used to calculate the bandwidth for the KDE. Passed directly to gaussian_kde. Default is None.
- boundary_exclude_distancefloat, optional
Buffer to exclude objects located within boundary_exclude_distance from the boundaries. Defaults to 0.
- add_contribution_as_labelsbool, optional
Whether to add contributions as labels to the domain objects, by default False.
- contribution_label_namestr, optional
Name of the contribution label, by default ‘Distribution values’.
- visualise_outputbool, optional
Whether to visualize the output heatmap, by default False.
- visualise_heatmap_kwargsdict, optional
Additional keyword arguments for the visualization function.
- Returns:
- masked_kernel_density_matrixnp.ndarray
The KDE evaluated on the mesh grid, with values outside the boundary masked as NaN.
- Raises:
- NotImplementedError
If the domain dimension is not 1 or 2.
- ValueError
If the query or within_boundary_query is not of the correct type. If mesh_resolution is not an integer or a list of two integers.
Notes
The KDE is evaluated using a Gaussian kernel density estimator from the
scipy.statslibrary.