SourceGrouper#

class photutils.psf.SourceGrouper(min_separation)[source]#

Bases: object

Class to group sources into clusters based on a minimum separation distance.

The groups are the connected components of the graph linking pairs of sources separated by less than or equal to min_separation. This is identical to single-linkage hierarchical agglomerative clustering with a distance criterion, but is computed using a KD-tree so that it scales to large numbers of sources.

Parameters:
min_separationfloat

The minimum distance (in pixels) such that any two sources separated by less than or equal to this distance will be placed in the same group.

See also

SourceGroups

Examples

Create a SourceGrouper with a minimum separation of 10 pixels:

>>> from photutils.psf import SourceGrouper
>>> import numpy as np
>>> grouper = SourceGrouper(min_separation=10)

Group sources and get group IDs as an array (default behavior):

>>> x = np.array([10, 15, 50, 55, 100])
>>> y = np.array([20, 25, 60, 65, 90])
>>> group_ids = grouper(x, y)
>>> print(group_ids)
[1 1 2 2 3]

Optionally, get a SourceGroups object with additional analysis methods:

>>> groups = grouper(x, y, return_groups_object=True)
>>> print(groups)
<SourceGroups(n_sources=5, n_groups=3)>

Access properties of the SourceGroups object:

>>> print(f'Number of groups: {groups.n_groups}')
Number of groups: 3
>>> groups.size_map
{1: 2, 2: 2, 3: 1}

Retrieve the (x, y) positions of sources from a specific group:

>>> x_group1, y_group1 = groups.get_group_sources(1)
>>> print(x_group1, y_group1)
[10 15] [20 25]

Methods Summary

__call__(x, y[, return_groups_object])

Group sources into clusters based on a minimum distance criterion.

Methods Documentation

__call__(x, y, return_groups_object=False)[source]#

Group sources into clusters based on a minimum distance criterion.

Parameters:
x, y1D float ndarray

The 1D arrays of the x and y coordinates of the sources.

return_groups_objectbool, optional

If False (default), return a 1D array of group IDs. If True, return a SourceGroups object containing the grouping results along with analysis methods.

Returns:
resultndarray or SourceGroups

If return_groups_object=False (default), returns a 1D integer array of group IDs for each source, in the same order as the input coordinates.

If return_groups_object=True, returns a SourceGroups object containing the grouping results. The object provides:

  • groups : array of group IDs for each source

  • n_sources : total number of sources

  • n_groups : total number of groups

  • sizes : group size for each source

  • group_centers : centroid coordinates for each group

  • get_group_sources(group_id) : retrieve sources in a specific group

  • plot() : visualize the grouping with color-coded apertures

Examples

Get group IDs as an array (default behavior):

>>> from photutils.psf import SourceGrouper
>>> import numpy as np
>>> x = np.array([10, 15, 50])
>>> y = np.array([20, 25, 60])
>>> grouper = SourceGrouper(min_separation=10)
>>> group_ids = grouper(x, y)
>>> print(group_ids)
[1 1 2]

Get a SourceGroups object with additional analysis methods:

>>> groups = grouper(x, y, return_groups_object=True)
>>> print(groups.n_groups)
2
>>> print(groups.groups)
[1 1 2]