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 formed using hierarchical agglomerative clustering with a distance criterion, calling the scipy.cluster.hierarchy.fclusterdata function.

Parameters:
min_separationfloat

The minimum distance (in pixels) such that any two sources separated by less than 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 criteria.

Methods Documentation

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

Group sources into clusters based on a minimum distance criteria.

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]