simplex_projection

Functions:

Name	Description
`linear_operator`	Build the linear operator `S` of simplex projection, such that `S @ Y` equals `simplex_projection(X, Y, Q)` for any target `Y`.
`simplex_projection`	Perform simplex projection from `X` to `Y` using the nearest neighbors of the points specified by `Q`.
`soft_linear_operator`	Build the linear operator `S` of soft simplex projection, such that `S @ Y` equals `soft_simplex_projection(X, Y, Q)` for any target `Y`.
`soft_simplex_projection`	Perform simplex projection from `X` to `Y` using the nearest neighbors of the points specified by `Q`, with a soft boundary between neighbors and non-neighbors.

`linear_operator`

linear_operator(X, Q, *, k = None, mask = None)

Build the linear operator S of simplex projection, such that S @ Y equals simplex_projection(X, Y, Q) for any target Y.

Parameters:

Name	Type	Description	Default
`X`	`ndarray or Tensor`	The input data of shape (N,) or (N, E) or (B, N, E)	required
`Q`	`ndarray or Tensor`	The query points of shape (M,) or (M, E) or (B, M, E) for which to find the nearest neighbors in `X`.	required
`k`	`int or None`	The number of nearest neighbors to use. If None, uses E + 1, where E is the dimension of `X`.	`None`
`mask`	`Mask or None`	`mask(i, j)`, or `mask(b, i, j)`, indicating for each query in `Q` which library points to include when finding nearest neighbors.	`None`

Returns:

Name	Type	Description
`S`	`ndarray or Tensor`	The operator of shape (M, N) or (B, M, N).

Raises:

Type	Description
`ValueError`	- If `k` is not positive. - If the batch size or dimension of `X` and `Q` do not match. - If fewer than `k` library points are unmasked for some query.

Examples:

import numpy as np

from edmkit.simplex_projection import linear_operator, simplex_projection

rng = np.random.default_rng(0)
X = rng.normal(size=(200, 3))
Q = rng.normal(size=(50, 3))
Y = rng.normal(size=(200, 4))

assert np.allclose(linear_operator(X, Q) @ Y, simplex_projection(X, Y, Q))

`simplex_projection`

simplex_projection(X, Y, Q, *, k = None, mask = None)

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

Parameters:

Name	Type	Description	Default
`X`	`ndarray or Tensor`	The input data of shape (N,) or (N, E) or (B, N, E)	required
`Y`	`ndarray or Tensor`	The target data of shape (N,) or (N, E’) or (B, N, E’)	required
`Q`	`ndarray or Tensor`	The query points of shape (M,) or (M, E) or (B, M, E) for which to find the nearest neighbors in `X`.	required
`k`	`int or None`	The number of nearest neighbors to use. If None, uses E + 1, where E is the dimension of `X`.	`None`
`mask`	`Mask or None`	`mask(i, j)`, or `mask(b, i, j)`, indicating for each query in `Q` which library points to include when finding nearest neighbors.	`None`

Returns:

Name	Type	Description
`predictions`	`ndarray or Tensor`	The predicted values based on the weighted mean of the nearest neighbors in `Y`. Shape (M,) if `Y` is 1D, (M, E’) if `Y` is 2D, or (B, M, E’) if `Y` is 3D.

Raises:

Type	Description
`ValueError`	- If `k` is not positive. - If the input arrays `X` and `Y` do not have the same number of points. - If the batch size or dimension of `X` and `Q` do not match. - If fewer than `k` library points are unmasked for some query.

Examples:

import numpy as np

from edmkit.embedding import 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

coordinates = np.array([[0, tau * j] for j in range(E)])
embedding, _ = embed(coordinates, x)
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}")

`soft_linear_operator`

soft_linear_operator(X, Q, *, k = None, mask = None, softness = 0.02)

Build the linear operator S of soft simplex projection, such that S @ Y equals soft_simplex_projection(X, Y, Q) for any target Y.

Parameters:

Name	Type	Description	Default
`X`	`ndarray or Tensor`	The input data of shape (N,) or (N, E) or (B, N, E)	required
`Q`	`ndarray or Tensor`	The query points of shape (M,) or (M, E) or (B, M, E) for which to find the nearest neighbors in `X`.	required
`k`	`int or None`	The number of nearest neighbors to use. If None, uses E + 1, where E is the dimension of `X`.	`None`
`mask`	`Mask or None`	`mask(i, j)`, or `mask(b, i, j)`, indicating for each query in `Q` which library points to include when finding nearest neighbors.	`None`
`softness`	`float`	Width of the boundary between neighbors and non-neighbors, as a fraction of the neighborhood radius.	`0.02`

Returns:

Name	Type	Description
`S`	`ndarray or Tensor`	The operator of shape (M, N) or (B, M, N).

Raises:

Type	Description
`ValueError`	- If `k` is not positive. - If `softness` is not positive. - If the batch size or dimension of `X` and `Q` do not match. - If fewer than `k + 1` library points are unmasked for some query.

Examples:

import numpy as np

from edmkit.simplex_projection import soft_linear_operator, soft_simplex_projection

rng = np.random.default_rng(0)
X = rng.normal(size=(200, 3))
Q = rng.normal(size=(50, 3))
Y = rng.normal(size=(200, 4))

assert np.allclose(soft_linear_operator(X, Q) @ Y, soft_simplex_projection(X, Y, Q))

`soft_simplex_projection`

soft_simplex_projection(X, Y, Q, *, k = None, mask = None, softness = 0.02)

Perform simplex projection from X to Y using the nearest neighbors of the points specified by Q, with a soft boundary between neighbors and non-neighbors.

Parameters:

Name	Type	Description	Default
`X`	`ndarray or Tensor`	The input data of shape (N,) or (N, E) or (B, N, E)	required
`Y`	`ndarray or Tensor`	The target data of shape (N,) or (N, E’) or (B, N, E’)	required
`Q`	`ndarray or Tensor`	The query points of shape (M,) or (M, E) or (B, M, E) for which to find the nearest neighbors in `X`.	required
`k`	`int or None`	The number of nearest neighbors to use. If None, uses E + 1, where E is the dimension of `X`.	`None`
`mask`	`Mask or None`	`mask(i, j)`, or `mask(b, i, j)`, indicating for each query in `Q` which library points to include when finding nearest neighbors.	`None`
`softness`	`float`	Width of the boundary between neighbors and non-neighbors, as a fraction of the neighborhood radius. For distinct boundary distances: `soft_simplex_projection(X, Y, Q, softness) -> simplex_projection(X, Y, Q) as softness -> 0`	`0.02`

Returns:

Name	Type	Description
`predictions`	`ndarray or Tensor`	The predicted values based on the weighted mean of the nearest neighbors in `Y`. Shape (M,) if `Y` is 1D, (M, E’) if `Y` is 2D, or (B, M, E’) if `Y` is 3D.

Raises:

Type	Description
`ValueError`	- If `k` is not positive. - If `softness` is not positive. - If the input arrays `X` and `Y` do not have the same number of points. - If the batch size or dimension of `X` and `Q` do not match. - If fewer than `k + 1` library points are unmasked for some query.

Examples:

import numpy as np
from tinygrad import Tensor

from edmkit.embedding import embed
from edmkit.simplex_projection import soft_simplex_projection

# Generate a simple time series (logistic map)
N = 300
x = np.zeros(N, dtype=np.float32)
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

coordinates = np.array([[0, tau * j] for j in range(E)])
embedding, _ = embed(coordinates, x)
shift = tau * (E - 1)

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

predictions = soft_simplex_projection(X, Y, Q).numpy()

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