simplex_projection

Functions:

Name	Description
`knn`	Find the k-nearest neighbors of `Q` in `X` using either `usearch` or `scipy.spatial.KDTree` depending on the size and dimensionality of the data.
`loo`	Leave-one-out simplex projection: predict each point in `X` from its neighbors, excluding temporally close points.
`simplex_projection`	Perform simplex projection from `X` to `Y` using the nearest neighbors of the points specified by `Q`.

`knn`

knn(X: np.ndarray, Q: np.ndarray, k: int) -> tuple[np.ndarray, np.ndarray]

Find the k-nearest neighbors of Q in X using either usearch or scipy.spatial.KDTree depending on the size and dimensionality of the data.

Parameters:

Name	Type	Description	Default
`X`	`ndarray`	The input data (N, E)	required
`Q`	`ndarray`	The query points (M, E)	required
`k`	`int`	The number of nearest neighbors to find (typically E+1 for simplex projection).	required

Returns:

Name	Type	Description
`distances`	`ndarray`	The distances from each query point in `Q` to its k nearest neighbors in `X` (M, k)
`indices`	`ndarray`	The indices of the k nearest neighbors in `X` for each query point in `Q` (M, k)

`loo`

loo(X: np.ndarray, Y: np.ndarray, *, theiler_window: int) -> np.ndarray

Leave-one-out simplex projection: predict each point in X from its neighbors, excluding temporally close points.

Equivalent to simplex_projection(X, Y, X) with Theiler window exclusion, but with the correct temporal index handling.

Parameters:

Name	Type	Description	Default
`X`	`ndarray`	The input data of shape (N,) or (N, E) or (B, N, E).	required
`Y`	`ndarray`	The target data of shape (N,) or (N, E’) or (B, N, E’).	required
`theiler_window`	`int`	Theiler window half-width. Library points `j` where “	i - j

Returns:

Name	Type	Description
`predictions`	`ndarray`	The predicted values of shape (N,) or (N, E’) or (B, N, E’).

Raises:

Type	Description
`ValueError`	- If the input arrays `X` and `Y` do not have the same number of points. - If there are not enough library points outside the Theiler window.

`simplex_projection`

simplex_projection(X: np.ndarray, Y: np.ndarray, Q: np.ndarray, *, mask: np.ndarray | None = None, use_tensor: bool = False) -> np.ndarray

Perform simplex projection from X to Y using the nearest neighbors of the points specified by Q.

Parameters:

Name	Type	Description	Default
`X`	`ndarray`	The input data of shape (N,) or (N, E) or (B, N, E)	required
`Y`	`ndarray`	The target data of shape (N,) or (N, E’) or (B, N, E’)	required
`Q`	`ndarray`	The query points of shape (M,) or (M, E) or (B, M, E) for which to find the nearest neighbors in `X`.	required
`mask`	`ndarray or None`	Boolean mask of shape (N,) or (B, N) indicating which library points to include when finding nearest neighbors for the queries in `Q`.	`None`
`use_tensor`	`bool`	Whether to use `tinygrad.Tensor` for computation. This may be slower than the NumPy implementation in most cases for now.	`False`

Returns:

Name	Type	Description
`predictions`	`ndarray`	The predicted values based on the weighted mean of the nearest neighbors in `Y`.

Raises:

Type	Description
`ValueError`	- If the input arrays `X` and `Y` do not have the same number of points.

Examples:

import numpy as np

from edmkit.embedding import lagged_embed
from edmkit.simplex_projection import simplex_projection

# Generate a simple time series (logistic map)
N = 300
x = np.zeros(N)
x[0] = 0.4
for i in range(1, N):
    x[i] = 3.9 * x[i - 1] * (1 - x[i - 1])

tau = 2
E = 3

embedding = lagged_embed(x, tau=tau, e=E)
shift = tau * (E - 1)

lib_size = 200
Tp = 1
X = embedding[:lib_size - shift]
Y = x[shift + Tp : lib_size + Tp]
Q = embedding[lib_size - shift : -Tp]
actual = x[lib_size + Tp :]

predictions = simplex_projection(X, Y, Q)

correlation = np.corrcoef(predictions, actual)[0, 1]
print(f"Correlation: {correlation:.3f}")