balltree.AngularTree

class balltree.AngularTree(radec: ArrayLike, weight: ArrayLike | None = None, leafsize: int = 20)

A wrapper around balltree.BallTree for using angular coordinates.

The the method and attributes of this tree class work in angular units as they are commonly used in astronomy, i.e. right ascension and declination in radian for the first and second coordinates. Distances and radii are expressed as great circle distance in radians. Internally, data is still represented in Euclidean (x, y, z) coordinates.

The data point(s) radec can be a numpy array of shape (2,) or (N, 2), or an equivalent python object. The optional weights can be a float or a 1-dim sequence of matching length, the optional leafsize determines when the tree query algorithms switch from traversal to brute force.

classmethod from_random(ra_min: float, ra_max: float, dec_min: float, dec_max: float, size: int, leafsize: int = 20) → AngularTree

Build a new AngularTree instance from randomly generated points.

The (ra, dec) coordinates are generated uniformly in the interval [ra_min, ra_max) and [dec_min, dec_max), respectively. size controlls the number of points generated. The optional leafsize determines when the tree query algorithms switch from traversal to brute force.

classmethod from_file(cls, path: str) → BallTree

–

Load back a class instance from a file created by the to_file() method.

property data: NDArray

Get a view of the data points stored in the tree.

Note that the points are reordered when the tree is constructed.

property num_points: int

Get the number of data points stored in the tree.

property leafsize: int

Get the leaf size of the tree.

property sum_weight: float

Get the sum over the data point weights stored in the tree.

property center: tuple(float, float)

Get the coordinates of the root node of the tree.

property radius: float

Get the radius of the root node of the tree.

to_file(path: str) → None

Store a representation of the tree instance in a binary file.

count_nodes() → int

Get a count of all nodes of the tree, including the root node.

get_node_data() → NDArray

Collect the meta data of all tree nodes in a numpy array.

The array fields record depth (starting from the root node), num_points, sum_weight, x, y, z (node center) and node radius.

Note

The node coordinates and radius are currently not converted to anlges.

nearest_neighbours(radec, k, max_ang=-1.0) → NDArray

Query a fixed number of nearest neighbours.

The query point(s) radec can be a numpy array of shape (2,) or (N, 2), or an equivalent python object. The number of neighbours k must be a positive integer and the optional max_ang parameter puts an upper bound on the angular separation (in radian) to the neighbours.

Returns an array with fields index, holding the index to the neighbour in the array from which the tree was constructed, and angle, the angular separation in radian. The result is sorted by separation, missing neighbours (e.g. if angle > max_ang) are indicated by an index of -1 and infinite separation.

brute_radius(radec: ArrayLike, angle: float, weight: ArrayLike | None = None) → float

Count neighbours within a given angle in radian using brute force.

The query point(s) radec can be a numpy array of shape (2,) or (N, 2), or an equivalent python object. The optional weights can be a float or a 1-dim sequence of matching length.

count_radius(radec: ArrayLike, angle: float, weight: ArrayLike | None = None) → float

Count neighbours within a given angle in radian using tree traversal.

The query point(s) radec can be a numpy array of shape (2,) or (N, 2), or an equivalent python object. The optional weights can be a float or a 1-dim sequence of matching length.

dualcount_radius(other: AngularTree, angle: float) → float

Count all pairs within a given angle in radian from points in another tree.

The pairs between the two trees are computed with the efficient dualtree algorithm.

brute_range(radec: ArrayLike, angles: ArrayLike, weight: ArrayLike | None = None) → NDArray

Count neighbours within a sequence of angles in radian using brute force.

The query point(s) radec can be a numpy array of shape (2,) or (N, 2), or an equivalent python object. The angles must either be a float or monotonic sequence. The optional weights can be a float or a 1-dim sequence of matching length.

Returns an array of counts. The first element contains the count of all neighbours 0 <= r <= r_1, the following values contain the incremental counts r_i-1 <= r <= r_i.

count_range(radec: ArrayLike, angles: ArrayLike, weight: ArrayLike | None = None) → NDArray

Count neighbours within a sequence of angles in radian using tree traversal.

The query point(s) radec can be a numpy array of shape (2,) or (N, 2), or an equivalent python object. The angles must either be a float or monotonic sequence. The optional weights can be a float or a 1-dim sequence of matching length.

Returns an array of counts. The first element contains the count of all neighbours 0 <= r <= r_1, the following values contain the incremental counts r_i-1 <= r <= r_i.

dualcount_range(other: AngularTree, angles: ArrayLike) → NDArray

Count all pairs within a sequence of angles in radian from points in another tree.

The pairs between the two trees are computed with the efficient dualtree algorithm. The radii must either be a float or monotonic sequence. The optional weights can be a float or a 1-dim.

Returns an array of counts. The first element contains the count of all neighbours 0 <= r <= r_1, the following values contain the incremental counts r_i-1 <= r <= r_i.