smap

Functions:

Name	Description
coefficients	Compute the S-Map coefficients C of the local linear regression from X to Y around each query in Q.
linear_operator	Build the linear operator S of S-Map, such that S @ Y equals smap(X, Y, Q) for any target Y.
smap	Perform S-Map (local linear regression) from X to Y.

coefficients

coefficients(X, Y, Q, *, theta, alpha = 1e-10, mask = None)

Compute the S-Map coefficients C of the local linear regression from X to Y around each query in Q.

C[m, 0] is the intercept and C[m, 1 + i, j] is the slope of target j with respect to coordinate i around Q[m], so smap(X, Y, Q)[m] equals C[m, 0] + Q[m] @ C[m, 1:]. The slopes estimate the local Jacobian of the map from X to Y, shrunk by the regularization.

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) around which to fit the regressions.	required
theta	float	Locality parameter. (0: global linear, >0: local linear)	required
alpha	float	Regularization parameter to stabilize the inversion.	1e-10
mask	Mask or None	mask(i, j), or mask(b, i, j), indicating for each query in Q which library points to include in the regression.	None

Returns:

Name	Type	Description
C	ndarray or Tensor	The coefficients of shape (M, E+1) if Y is 1D, (M, E+1, E’) if Y is 2D, or (B, M, E+1, E’) if Y is 3D.

Raises:

Type	Description
ValueError	- If theta is negative. - 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 E + 1 library points are unmasked for some query.

Examples:

import numpy as np

from edmkit.smap import coefficients, smap

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

C = coefficients(X, Y, Q, theta=4.0)  # (50, 4, 4)
jacobians = C[:, 1:].swapaxes(-1, -2)  # (50, 4, 3): d Y_j / d X_i around each query

assert np.allclose(C[:, 0] + np.einsum("mi,mij->mj", Q, C[:, 1:]), smap(X, Y, Q, theta=4.0))

linear_operator

linear_operator(X, Q, *, theta, alpha = 1e-10, mask = None)

Build the linear operator S of S-Map, such that S @ Y equals smap(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 make predictions.	required
theta	float	Locality parameter. (0: global linear, >0: local linear)	required
alpha	float	Regularization parameter to stabilize the inversion.	1e-10
mask	Mask or None	mask(i, j), or mask(b, i, j), indicating for each query in Q which library points to include in the regression.	None

Returns:

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

Raises:

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

Examples:

import numpy as np

from edmkit.smap import linear_operator, smap

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, theta=4.0) @ Y, smap(X, Y, Q, theta=4.0))

smap

smap(X, Y, Q, *, theta, alpha = 1e-10, mask = None)

Perform S-Map (local linear regression) from X to Y.

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 make predictions.	required
theta	float	Locality parameter. (0: global linear, >0: local linear)	required
alpha	float	Regularization parameter to stabilize the inversion.	1e-10
mask	Mask or None	mask(i, j), or mask(b, i, j), indicating for each query in Q which library points to include in the regression.	None

Returns:

Name	Type	Description
predictions	ndarray or Tensor	The predicted values based on the weighted linear regression. 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 theta is negative. - 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 E + 1 library points are unmasked for some query.

Examples:

import numpy as np

from edmkit.embedding import embed
from edmkit.smap import smap

# 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 :]

# Local linear with theta=4.0
predictions = smap(X, Y, Q, theta=4.0)
correlation = np.corrcoef(predictions, actual)[0, 1]
print(f"Correlation (theta=4.0): {correlation:.3f}")

# Global linear with theta=0.0
predictions_global = smap(X, Y, Q, theta=0.0)
correlation_global = np.corrcoef(predictions_global, actual)[0, 1]
print(f"Correlation (theta=0.0): {correlation_global:.3f}")