tsne_projection

Exact t-distributed Stochastic Neighbor Embedding for continuous datasets. The library implements the dimension_reducer_protocol and uses portable full-batch optimization. Its time and memory requirements are quadratic in the number of training examples.

API documentation

Open the ../../apis/library_index.html#tsne-projection link in a web browser.

Loading

To load this library, load the loader.lgt file:

| ?- logtalk_load(tsne_projection(loader)).

Testing

To test this library predicates, load the tester.lgt file:

| ?- logtalk_load(tsne_projection(tester)).

Features

  • Accepts datasets containing only continuous attributes.

  • Computes exact perplexity-matched Gaussian affinities.

  • Uses exact Student-t affinities and full-batch gradient optimization.

  • Supports early exaggeration, momentum, and adaptive coordinate gains.

  • Provides reproducible Gaussian initialization without changing caller RNG state.

  • Supports missing continuous values represented by variables using mean imputation.

  • Exports learned embeddings as ordinary predicate clauses.

  • Transforms new instances by optimizing one coordinate against the fixed training embedding.

Limitations

  • The implementation computes all pairwise affinities exactly and therefore requires quadratic time and memory in the number of training examples. It is intended for small and medium datasets.

  • Barnes-Hut, FFT-based interpolation, approximate nearest-neighbor search, sparse affinities, and backend-specific numerical acceleration are not currently implemented.

  • Training is a non-convex optimization. Different random seeds can produce different valid embeddings, and convergence does not guarantee a global optimum. Using the same seed and options produces a reproducible embedding.

  • Coordinate values, axis order, orientation, and scale have no standalone meaning. Interpret local neighborhoods instead of comparing coordinate signs or expecting global distances and densities to be preserved.

  • t-SNE does not learn a parametric projection function. transform/3 independently optimizes each new point against the fixed training embedding and is only an approximation; it does not update existing coordinates or model interactions among multiple new points.

  • No inverse transformation from embedding coordinates to original attributes is provided.

  • Categorical attributes are not supported.

  • Missing continuous values must be represented by variables in present Attribute-Value bindings. Omitted, duplicate, or undeclared bindings are rejected, as are attributes with no observed training values.

Options

  • n_components/1: Embedding dimensions. The default is 2.

  • feature_scaling/1: Standardize continuous attributes when true. The default is true.

  • perplexity/1: Positive float strictly smaller than the sample count. The default is 5.0.

  • learning_rate/1: Positive optimization learning rate. The default is 200.0.

  • early_exaggeration/1: Positive affinity multiplier used during the initial optimization phase. The default is 12.0.

  • early_exaggeration_iterations/1: Non-negative number of initial exaggerated iterations. The default is 250.

  • maximum_iterations/1: Positive optimization iteration limit. The default is 1000.

  • tolerance/1: Positive stopping tolerance for the maximum coordinate update. The default is 1.0e-7.

  • random_seed/1: Positive seed for reproducible initialization. The default is 1357911.

Usage

| ?- logtalk_load(dimension_reduction_protocols('test_datasets/correlated_plane')).

| ?- tsne_projection::learn(correlated_plane, DimensionReducer, [perplexity(2.0)]).

| ?- tsne_projection::transform(DimensionReducer, [x-2.0, y-4.0, z-6.0], ReducedInstance).

Missing continuous values are written as variables. Encoder means and scales are computed from observed numeric training values only. A missing value is then encoded as normalized zero, which is equivalent to imputing the observed training mean:

| ?- tsne_projection::transform(DimensionReducer, [x-_, y-4.0, z-6.0], ReducedInstance).

The out-of-sample transformation is an approximate independent extension. Transforming several new instances separately is not equivalent to jointly refitting t-SNE with those instances included in the training dataset.

Dimension reducer representation

Learned reducers use the following representation:

tsne_reducer(Encoders, ExampleIds, TrainingRows, EmbeddingRows, Diagnostics)

The reducer stores encoded training rows because t-SNE does not learn a linear projection matrix. Diagnostics include convergence information and the initial and final unexaggerated Kullback-Leibler divergences. The preprocessing diagnostics include missing_values(mean_imputation).

References

  1. van der Maaten, L. and Hinton, G. (2008) - “Visualizing Data using t-SNE”.