mojolearn.RadiusNeighbors#

class mojolearn.RadiusNeighbors(radius=1.0, *, metric='euclidean', algorithm='auto', p=2)[source]#

Bases: NumericModeMixin

Find every fitted point within a radius of each query.

Returns scikit-learn’s radius_neighbors shape: a ragged (distances, indices) pair with one variable-length array per query. The search runs over a random ball cover index (neither brute force nor one of scikit-learn’s trees) and returns the exact set: its pruning is a triangle-inequality bound, not an approximation. Input is converted to float32.

Parameters:

radius (float, default 1.0) – Default search radius; must be positive and finite.
metric (str, default ‘euclidean’) – Any distance that satisfies the triangle inequality: ‘euclidean’/’l2’, ‘manhattan’/’l1’/’cityblock’/’taxicab’, ‘chebyshev’/’linf’ and ‘minkowski’/’lp’ with p >= 1. ‘cosine’, ‘sqeuclidean’, Minkowski with p < 1 and other names raise ValueError, because the index would silently miss neighbors under them. For squared Euclidean, use ‘euclidean’ and square the distances.
algorithm ({‘auto’, ‘rbc’}, default ‘auto’) – Both mean the random ball cover. ‘brute’, ‘kd_tree’ and ‘ball_tree’ raise ValueError, since they would name a different algorithm.
p (float, default 2) – Minkowski exponent, read only by metric='minkowski' (or ‘lp’); must be finite and at least 1. Under any other metric, a value other than 2 raises ValueError.
numeric_mode ({‘identical’, ‘deterministic’, ‘fast’}, optional) – Numeric mode for this estimator; None uses the process default (mojolearn.set_numeric_mode). ‘fast’ is available on Apple GPUs only.

Variables:

n_samples_fit_ (int) – Number of fitted samples.
n_features_in_ (int) – Number of features seen at fit.

Examples

>>> import numpy as np, mojolearn
>>> X = np.random.default_rng(0).random((1000, 8), dtype=np.float32)
>>> rn = mojolearn.RadiusNeighbors(radius=0.5).fit(X)
>>> distances, indices = rn.radius_neighbors(X[:10], sort_results=True)
>>> len(indices)
10

__init__(radius=1.0, *, metric='euclidean', algorithm='auto', p=2)[source]#

Methods

`fit`(X[, y])	Store the points to search.
`get_params`([deep])
`load`(path)	Load a model written by `save`.
`numeric_mode_used`()	The numeric mode this estimator runs in.
`radius_neighbors`([X, radius, ...])	Find the fitted points within `radius` of each query.
`save`(path)	Save the fitted model to an `.npz` file.
`set_params`(**params)	Set constructor parameters.
`vendor_used`()	The GPU backend this estimator runs on.

fit(X, y=None)[source]#

Store the points to search.

Parameter checks run here, so an unsupported metric, algorithm, p or radius raises ValueError before any search. The ball cover index is built at each radius_neighbors call, not here.

Parameters:

X (array-like of shape (n_samples, n_features)) – Points to search; converted to float32.
y (ignored) – Accepted for scikit-learn compatibility.

Returns:

self

save(path)[source]#

Save the fitted model to an .npz file.

The file holds the float32 points as fitted and the parameters (radius, metric, p, algorithm, numeric mode). mojolearn.host_model(path) can answer radius_neighbors from it on a CPU with no GPU.

Parameters:: path (str or path-like) – Destination file.
Raises:: RuntimeError – If the model is not fitted.

classmethod load(path)[source]#

Load a model written by save.

Arrays are read at their saved dtypes and never cast. Parameters fit would refuse raise ValueError here too.

Parameters:: path (str or path-like) – File written by save.
Returns:: RadiusNeighbors – A fitted model, ready for radius_neighbors.

radius_neighbors(X=None, radius=None, return_distance=True, sort_results=False)[source]#

Find the fitted points within radius of each query.

X=None queries the fitted points against themselves, as in scikit-learn. Unlike scikit-learn, each point is then included in its own neighbor list.

Parameters:

X (array-like of shape (n_queries, n_features), optional) – Query points; converted to float32. None uses the fitted points.
radius (float, optional) – Search radius for this call; defaults to the constructor’s radius. Must be positive and finite.
return_distance (bool, default True) – Return the distances as well as the indices.
sort_results (bool, default False) – Sort each row by increasing distance. Requires return_distance=True. Under the ‘identical’ mode, rows come in ascending index order, so sorted rows break distance ties by the lower index.

Returns:

distances (list of Array, float32) – One 1-D array per query. Returned only when return_distance is True.
indices (list of Array, int64) – One 1-D array per query of row indices into the fitted data. Rows have different lengths, so these are Python lists rather than a rectangular array: indexing with [i] and len() work, np.asarray on the list does not give a 2-D block.

Raises:

ValueError – If the model is not fitted, the radius is invalid, X has the wrong number of features, or sort_results=True with return_distance=False.