[josemal98]

During my visit to Devika Narain's lab I needed to place new points in an embedding fitted once, without refitting it.

This PR depends on #12 (random_state). Its branch sits on top of that one, and its tests use random_state. Until #12 is merged, the diff here also shows its commits; the changes of this PR are the last six commits.

fit and transform raised NotImplementedError. This PR implements both:

• fit(X) fits the model and returns self. The embedding is stored in embedding_, which fit_transform now sets too.
• transform(X, return_residual=False) embeds new points with the local views of the fitted model, without changing the embedding.

How transform places a point

A RATS embedding is an atlas. Each view m is a local (kernel) PCA φ_m, and the alignment gives it a rotation T_m and a translation v_m. The embedding of a training point is the mean of what its views give it, y_i = mean over the views m of i of (φ_m(x_i) T_m + v_m): the least-squares solution of the last alignment step. transform applies the same formula to a new point. Three rules decide which views it uses:

1. Its views: the views of the training points that would have the new point among their n_neighbors nearest neighbors (closer than their own n_neighbors-th neighbor). This is the rule by which the fit assigns its points to views; applied to the training points, it gives back their views.
2. The tear: with tearing, only the views that contain the nearest training point are kept. A point near the tear then lands on that neighbor's side, not between the two sides.
3. Far points: a point that no training point would count as a neighbor is embedded with the views of its nearest training point, and a warning says how many there were. A point equal to a training point gets that point's views.

return_residual=True also returns each point's mean distance to the affine subspaces of its views. Large values flag points off the fitted manifold (linear PCA only).

A fix that torn fits need

The final embedding comes from the incidence used in the last alignment step, but Utildeg is recomputed afterwards from the final embedding. With tearing, the two differ near the tear: rebuilding the embedding of a torn small_spherewithhole fit from Utildeg misses 27 of its 1 986 points, by up to 2.3 typical neighbor distances in the embedding. The fit now keeps the incidence of the last step as Utilde_t, which rebuilds all of them (to 2e-14). compute_final_embedding returns it only with return_incidence=True, so its existing callers, such as examples/cut_and_paste_app.py, are unaffected.

Tests and verification

• tests/test_transform.py: 10 tests, about 16 s on one core, with small data generated in the files. They check that:

  • fit returns self and stores the embedding of fit_transform;
  • transform reproduces the embedding of the training points, with and without tearing (to 1e-10);
  • held-out points land among their neighbors;
  • near a tear, none falls between the two sides (the test also checks that averaging the neighbors would put some there);
  • held-out points land where a refit that includes them puts them;
  • points far from the data warn, and the residual flags points pushed off the manifold;
  • the input checks work, and kernel PCA is supported.

  A CI step runs them.

• The fit does not change. I compared this branch with the branch of Add a random_state parameter to RATS (default 42: results unchanged) #12, bit for bit (np.array_equal), on the 56 configurations of the full regression suite (tests/scripts/generate_snapshots.py), on three fits with the default constructor on 5 000 points with several cores, and on nine small configurations that reach every random draw (kernel PCA, the spectral initialization, n_forced_clusters=2, n_repel > 0 with one and with two clusters, min_cluster_size=1, tearing). In all 68 comparisons, y, the tear colors, Utilde, C, n_Utilde_Utilde, Utildeg and c were identical, and two repeated runs of the base branch were identical to each other. Both branches ran in the same environment as in Add a random_state parameter to RATS (default 42: results unchanged) #12.

• transform reproduces the embedding of every one of those fits. Applied to the training data of each fit, transform returned the embedding of fit_transform, with a largest error of 2.5e-12 in the 59 large fits (on barbell) and of 1.3e-14 in the nine small ones, including kernel PCA, tearing and forced clusters.

Example: points near a tear

I fitted the Klein bottle of the README (2 000 points, with tearing) without 10% of its points, and then placed those 193 points two ways:

• transform placed all of them next to their neighbors: at most 2.8 typical neighbor distances from the nearest one.
• Averaging the embeddings of their 28 nearest training points left 58 of them between the two sides of the tear, up to 126 typical distances away.

The README has a short section with the usage.

Not in this PR

inverse_transform (with linear PCA it could use the same views in reverse) and a residual for kernel PCA.

Prepared with the help of Claude Code; reviewed and tested by me.