Crate bhtsne 

bhtsne

bhtsne contains the implementations of both a parallel, exact, version of the t-SNE algorithm and a parallel, approximate, version leveraging the Barnes-Hut algorithm.

The implementation supports custom data types and custom defined metrics. See tSNE for more details.

This crate also includes load_csv, a commodity function to parse data, record by record, from a csv file.

Example

use bhtsne;

const N: usize = 150;         // Number of vectors to embed.
const D: usize = 4;           // The dimensionality of the
                              // original space.
const THETA: f32 = 0.5;       // Parameter used by the Barnes-Hut algorithm.
                              // Small values improve accuracy but increase complexity.
    
const PERPLEXITY: f32 = 10.0; // Perplexity of the conditional distribution.
const EPOCHS: usize = 2000;   // Number of fitting iterations.

// Loads the data from a csv file skipping the first row,
// treating it as headers and skipping the 5th column,
// treating it as a class label.
// Do note that you can also switch to f64s for higher precision.
let data: Vec<f32> = bhtsne::load_csv("iris.csv", true, Some(&[4]), |float| {
    float.parse().unwrap()
})?;
let samples: Vec<&[f32]> = data.chunks(D).collect();

// Executes the Barnes-Hut approximation of the algorithm and writes the embedding to the
// specified csv file.
bhtsne::tSNE::<f32, &[f32], 2>::new(&samples)
    .perplexity(PERPLEXITY)
    .epochs(EPOCHS)
    .barnes_hut(THETA, |sample_a, sample_b| {
        sample_a
            .iter()
            .zip(sample_b.iter())
            .map(|(a, b)| (a - b).powi(2))
            .sum::<f32>()
            .sqrt()
    })
    .write_csv("iris_embedding.csv")?;

Structs

Dim

Public re-exports. Carrier type the per-D Morton implementations attach to, since a trait needs a type to dispatch on while D stays a const generic on the arena.

Neighbor

A sample’s nearest neighbor for tSNE::barnes_hut_with_neighbors: its index and the distance (not a similarity) to it.

SparseAffinities

A precomputed sparse, symmetric affinity graph in the CSR-like layout barnes_hut uses internally. Obtain via tSNE::affinities and inject with tSNE::with_affinities.

SpectralParams

Public re-exports. Tunable parameters of the spectral embedding initialization, accepted by tSNE::spectral_init_with and tSNE::spectral_embedding_with. The defaults resolve the leading eigenvectors of a 70k point MNIST affinity graph to a fraction of a degree, so tuning is only warranted to trade accuracy for speed or to handle unusually structured graphs.

tSNE

t-distributed stochastic neighbor embedding. Provides a parallel implementation of both the exact version of the algorithm and the tree accelerated one leveraging space partitioning trees.

Traits

FftNum

Public re-exports. Generic floating point number, implemented for f32 and f64

Morton

Public re-exports. Per-dimension Z-order codec, implemented for Dim<2>, Dim<3>, Dim<4>, Dim<5>, Dim<6>, and Dim<7>.

SpectralBlock

Public re-exports. Fixed-width row storage of the spectral solver, in the spirit of the Morton associated types: each dimensionality names its concrete [T; D + 8] row type, giving the solver compile-time block widths on stable Rust. The fused kernel unrolls and vectorizes over these rows for about twice the throughput of a dynamic-width loop.

Functions

load_csv

Loads data from a csv file.

Type Aliases

EpochCallback

Boxed closure invoked at the end of each fitting epoch with the epoch index and a snapshot of the current embedding. See tSNE::epoch_callback.