bhtsne

https://docs.rs/bhtsne/0.5.4
Admin
bhtsne is a parallel Rust implementation of the t-SNE algorithm with support for the Barnes-Hut...
Tokens:24,523
Snippets:153
Trust Score:9.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Initialize tSNE with String Data

Source: https://docs.rs/bhtsne/0.5.4/bhtsne/struct.tSNE.html

Example of initializing a tSNE instance using a collection of string slices.

```rust
use bhtsne::tSNE;

const N: usize = 1000; // Supposedly 1000 strings.
let strings: Vec<&str> = vec!["Hello World!"; N];

let mut tsne: tSNE<f32, &str> = tSNE::new(&strings);
```

--------------------------------

### Parallel Barnes-Hut Approximation Setup in t-SNE

Source: https://docs.rs/bhtsne/0.5.4/src/bhtsne/lib.rs.html

Initializes parameters and buffers for the parallel Barnes-Hut t-SNE approximation. Validates the 'theta' parameter and checks perplexity.

```rust
        assert!(
            theta > T::zero(),
            "error: theta value must be greater than 0.0. 
            A value of 0.0 corresponds to using the exact version of the algorithm."
        );
```

```rust
        tsne::check_perplexity(&self.perplexity, &n_samples);
```

```rust
        tsne::prepare_buffers(
            &mut self.y,
            &mut self.dy,
            &mut self.uy,
            &mut self.gains,
            grad_entries,
        );
```

```rust
        self.p_values.resize(pairwise_entries, T::zero().into());
```

--------------------------------

### Initialize tSNE with Vector Data

Source: https://docs.rs/bhtsne/0.5.4/bhtsne/struct.tSNE.html

Example of initializing a tSNE instance using a collection of vector slices.

```rust
use bhtsne::tSNE;

const N: usize = 1000; // Supposedly 1000 25-dimensional points.
const D: usize = 25;

let data: Vec<f32> = vec![0.0_f32; N * D];
let vectors: Vec<&[f32]> = data.chunks(D).collect();

let mut tsne: tSNE<f32, &[f32]> = tSNE::new(&vectors); // Will compute using f32s.
let mut tsne: tSNE<f64, &[f32]> = tSNE::new(&vectors); // Will compute using f64s.
```

--------------------------------

### Random Initialization of Solution

Source: https://docs.rs/bhtsne/0.5.4/src/bhtsne/lib.rs.html

Initializes the solution vector 'y' randomly, which serves as the starting point for the t-SNE optimization process.

```rust
tsne::random_init(&mut self.y);
```

--------------------------------

### tSNE Initialization and Configuration

Source: https://docs.rs/bhtsne/0.5.4/bhtsne/struct.tSNE.html

Methods for creating a new tSNE instance and configuring its hyperparameters.

```APIDOC
## tSNE::new

### Description
Creates a new t-SNE instance with default configuration parameters.

### Parameters
- **data** (&[U]) - Required - The dataset to execute the t-SNE algorithm on.

## Configuration Methods

### Description
Methods to update the default configuration of the t-SNE instance.

- **learning_rate(T)** - Sets the learning rate (default: 200).
- **epochs(usize)** - Sets the maximum number of fitting iterations (default: 1000).
- **momentum(T)** - Sets the initial momentum (default: 0.5).
- **final_momentum(T)** - Sets the final momentum (default: 0.8).
- **momentum_switch_epoch(usize)** - Sets the epoch to switch to final momentum.
- **stop_lying_epoch(usize)** - Sets the epoch after which P distribution values become true (default: 250).
- **embedding_dim(u8)** - Sets the embedding space dimensionality (default: 2).
- **perplexity(T)** - Sets the perplexity value (default: 20.0).
```

--------------------------------

### Compute Pairwise Distance Matrix

Source: https://docs.rs/bhtsne/0.5.4/src/bhtsne/tsne/mod.rs.html

Computes a squared distance matrix. It computes only the upper triangular entries, excluding the diagonal, and then symmetrizes the matrix to get the full distance matrix.

```APIDOC
## compute_pairwise_distance_matrix

### Description
Computes a squared distance matrix. Computes only the upper triangular entries, excluding the
diagonal. The matrix is symmetrized after to get the full distance matrix.

### Arguments
* `distances` - distance matrix to fill.
* `f` - distance function.
* `g` - a closure that given an index returns the associated sample.
* `n_samples` - total number of samples.

### Signature
```rust
pub(super) fn compute_pairwise_distance_matrix<'a, T, U, F, G>(
    distances: &mut [CachePadded<T>],
    f: F,
    g: G,
    n_samples: usize,
)
where
    T: Float + Send + Sync,
    U: 'a + Send + Sync + ?Sized,
    F: Fn(&U, &U) -> T + Sync + Send,
    G: Fn(&usize) -> &'a U + Sync + Send,
```
```

--------------------------------

### VP-Tree Node Construction Logic

Source: https://docs.rs/bhtsne/0.5.4/src/bhtsne/tsne/vptree.rs.html

This code snippet illustrates the logic for constructing a VP-Tree node, including calculating the threshold based on distances to the median and pushing child nodes onto a stack for recursive building. It's part of the tree building process.

```rust
node.threshold = metric_f(self.items[lower].1, self.items[median].1);

stack.push(VPTreeBuilder::new(&mut node.left, lower + 1, median));
stack.push(VPTreeBuilder::new(&mut node.right, median, upper));
```

--------------------------------

### Initialize t-SNE with different data types

Source: https://docs.rs/bhtsne/0.5.4/src/bhtsne/lib.rs.html

Demonstrates how to instantiate the t-SNE struct using different numeric types or custom data types like strings.

```rust
let vectors: Vec<&[f32]> = data.chunks(D).collect();

let mut tsne: tSNE<f32, &[f32]> = tSNE::new(&vectors); // Will compute using f32s.
let mut tsne: tSNE<f64, &[f32]> = tSNE::new(&vectors); // Will compute using f64s.
```

```rust
use bhtsne::tSNE;

const N: usize = 1000; // Supposedly 1000 strings.
let strings: Vec<&str> = vec!["Hello World!"; N];

let mut tsne: tSNE<f32, &str> = tSNE::new(&strings);
```

--------------------------------

### Compute Sparse Input Similarities with VPTree

Source: https://docs.rs/bhtsne/0.5.4/src/bhtsne/lib.rs.html

Computes sparse input similarities using a vantage point tree. This involves searching for nearest neighbors for each sample and calculating pairwise probabilities.

```rust
let mut distances: Vec<CachePadded<T>> = vec![T::zero().into(); pairwise_entries];

            // Build ball tree on data set. The tree is freed at the end of the scope.
            let tree = tsne::vptree::VPTree::new(data, &metric_f);

            // For each sample in the dataset compute the perplexities using a vantage point tree
            // in parallel.
            {
                let perplexity = &self.perplexity; // Immutable borrow must be outside.
                self.p_values
                    .par_chunks_mut(n_neighbors)
                    .zip(distances.par_chunks_mut(n_neighbors))
                    .zip(p_columns.par_chunks_mut(n_neighbors))
                    .zip(data.par_iter())
                    .enumerate()
                    .for_each(
                        |(index, (((p_values_row, distances_row), p_columns_row), sample))| {
                            // Writes the indices and the distances of the nearest neighbors of sample.
                            tree.search(
                                sample,
                                index,
                                n_neighbors + 1, // The first NN is sample itself.
                                p_columns_row,
                                distances_row,
                                &metric_f,
                            );
                            debug_assert!(!p_columns_row.iter().any(|&i| *i == index));
                            tsne::search_beta(p_values_row, distances_row, perplexity);
                        },
                    );
            }
```

--------------------------------

### VPTree Constructor

Source: https://docs.rs/bhtsne/0.5.4/src/bhtsne/tsne/vptree.rs.html

Constructs a new VPTree from a slice of items and a metric function. It initializes the tree structure and prepares for building the tree from the provided data.

```rust
/// Vantage Point tree.
pub(crate) struct VPTree<'a, T: Float + Send + Sync, U> {
    items: Vec<(usize, &'a U)> ,
    pub(crate) root: Option<Box<Node<T>>> ,
}

impl<'a, T: Float + Send + Sync, U> VPTree<'a, T, U> {
    /// Constructor for the `VPTree` struct.
    ///
    /// # Arguments
    ///
    /// * `items` - **original** items to build the tree on.
    ///
    /// * `metric_f` - metric function.
    pub fn new<F>(items: &'a [U], metric_f: F) -> Self
    where
        F: Fn(&U, &U) -> T,
    {
        let mut tree = VPTree {
            // Need to swap some references around, don't want to move original data.
            // Also need to keep track of the original position, as it will differ.
            items: items.iter().enumerate().collect(),
            root: None,
        };
        let n_samples = tree.items.len(); // Immutable borrow must be kept outside.
        tree.build_from_points(0, n_samples, &metric_f);

        tree
    }
    /// Function that iteratively fills the tree.
    ///
    /// # Arguments
    ///
    /// * `lower' - lower bound.
    ///
    /// * `upper` - upper bound.
    ///
    /// * `metric_f` - metric function.
    fn build_from_points<F>(&mut self, lower: usize, upper: usize, metric_f: F)
    where
        F: Fn(&U, &U) -> T,
    {
        let mut stack = vec![VPTreeBuilder::new(&mut self.root, lower, upper)];
        let mut thread_rng = rand::rng();

        while let Some(builder) = stack.pop() {
            let VPTreeBuilder { root, lower, upper } = builder;

            // Lower index is center of current node.
            if upper != lower {
                *root = Some(Box::new(Node::default()));
                let node = root.as_deref_mut().unwrap();
                node.index = lower;

                if upper - lower > 1 {
                    // If we did not arrive at leaf yet choose an arbitrary point
                    // and move it to the start.
                    let i = thread_rng.random_range(lower..upper);
                    self.items.swap(lower, i);

                    let (_, to_cmp) = self.items[lower];
                    // Partition around the median distances.
                    let median: usize = (upper + lower) / 2;
                    self.items[lower + 1..upper].select_nth_unstable_by(
                        median - lower - 1,
                        &mut |(_, a): &(usize, &U), (_, b): &(usize, &U)| {
                            if metric_f(to_cmp, a) < metric_f(to_cmp, b) {
                                Ordering::Less
                            } else if metric_f(to_cmp, a) == metric_f(to_cmp, b) {
                                Ordering::Equal
                            } else {
                                Ordering::Greater
                            }
                        },
                    );
                }
            }
        }
    }
}
```

--------------------------------

### Structs

Source: https://docs.rs/bhtsne/0.5.4/bhtsne/all.html

Information about the structs available in the bhtsne crate.

```APIDOC
## Structs

### tSNE

This struct likely represents the t-SNE algorithm implementation.
```

--------------------------------

### Construct SPTree in Rust

Source: https://docs.rs/bhtsne/0.5.4/src/bhtsne/tsne/sptree.rs.html

Initializes and builds an SPTree from provided data. It calculates the mean, min, and max values for each dimension to define the tree's boundaries.

```rust
/// The constructor for SPTree, builds the tree too.
///
/// # Arguments
///
/// * `dimension` - dimensions of a point.
///
/// * `data` - data to build the tree from.
///
/// * `n_samples` - number of points in `inp_data`.
pub(crate) fn new(dimension: usize, data: &'a [CachePadded<T>], n_samples: usize) -> Self {
    // Mean for each dimension.
    let mut mean: Vec<T> = vec![T::zero(); dimension];
    // Min for each dimension.
    let mut min: Vec<T> = vec![T::max_value(); dimension];
    // Max for each dimension.
    let mut max: Vec<T> = vec![-T::max_value(); dimension];
    // Compute the boundaries of SPTree.
    data.chunks(dimension).for_each(|sample| {
        sample
            .iter()
            .zip(mean.iter_mut())
            .zip(min.iter_mut())
            .zip(max.iter_mut())
            .for_each(|(((s, mean_d), min_d), max_d)| {
                *mean_d += **s;
                *min_d = min_d.min(**s);
                *max_d = max_d.max(**s);
            })
    });

    let denominator = T::from(n_samples).unwrap();
    mean.iter_mut().for_each(|el| *el /= denominator);

    // Build SPTree.
    let mut width: Vec<T> = vec![T::zero(); dimension];
    width
        .iter_mut()
        .zip(mean.iter())
        .zip(min.iter())
        .zip(max.iter())
        .for_each(|(((w, mean_d), min_d), max_d)| {
            *w = (*max_d - *mean_d).max(*mean_d - *min_d) + T::min_positive_value();
        });

    let mut tree = SPTree::new_empty(dimension, data, mean, width);
    tree.fill(n_samples);

    tree
}
```

--------------------------------

### Buffer Preparation

Source: https://docs.rs/bhtsne/0.5.4/src/bhtsne/tsne/mod.rs.html

Prepares the buffers necessary for computation by allocating memory. This memory should be freed by `clear_buffers`.

```APIDOC
## prepare_buffers

### Description
Prepares the buffers necessary to the computation. Allocates memory freed by `clear_buffers`.

### Arguments
* `y` - embedding.
* `dy` - gradient.
* `uy` - momentum buffer.
* `gains` - gains.
* `grad_entries` - number of gradient entries.

### Signature
```rust
pub(super) fn prepare_buffers<T: Float + Send + Sync>(
    y: &mut Vec<CachePadded<T>>,
    dy: &mut Vec<CachePadded<T>>,
    uy: &mut Vec<CachePadded<T>>,
    gains: &mut Vec<CachePadded<T>>,
    grad_entries: usize,
)
```
```

--------------------------------

### Execute Barnes-Hut t-SNE with CSV input

Source: https://docs.rs/bhtsne/0.5.4/bhtsne/index.html

Demonstrates loading data from a CSV file and running the Barnes-Hut t-SNE algorithm to generate an embedding.

```rust
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.
const NO_DIMS: u8 = 2;        // Dimensionality of the embedded space.

// 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::new(&samples)
    .embedding_dim(NO_DIMS)
    .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")?;
```

--------------------------------

### Fill SPTree with dataset

Source: https://docs.rs/bhtsne/0.5.4/src/bhtsne/tsne/sptree.rs.html

Populates the tree by inserting a specified number of samples.

```rust
    /// Build SPTree on dataset.
    ///
    /// # Arguments
    ///
    /// `n_samples` - number of points.
    fn fill(&mut self, n_samples: usize) {
        (0..n_samples).for_each(|index| {
            self.insert(index);
        })
    }
```

--------------------------------

### VP-Tree k-Nearest Neighbors Search (look_up)

Source: https://docs.rs/bhtsne/0.5.4/src/bhtsne/tsne/vptree.rs.html

Implements the core recursive search logic for finding k-nearest neighbors in a VP-Tree. It uses a stack for iterative traversal and a binary heap to maintain the k closest points found so far. The `tau` parameter tracks the distance to the farthest point in the current results.

```rust
fn look_up<F>(
        &self,
        tau: &mut T, // Tracks the distances to the farthest point in the results.
        target: &U,
        k: usize,
        heap: &mut BinaryHeap<HeapItem<T>>,
        metric_f: F,
    ) where
        F: Fn(&U, &U) -> T,
    {
        let mut stack: Vec<&Option<Box<Node<T>>>> = vec![&self.root];

        while let Some(next_in_stack) = stack.pop() {
            if let Some(node) = next_in_stack {
                let (original_position, point) = &self.items[node.index];
                // Compute distances between target and current node.
                let distance: T = metric_f(point, target);
                if distance < *tau {
                    // If current node is within the radius tau
                    // remove furthest node from result list (if it already contains k results),
                    // add current node to result list and
                    // update value of tau (farthest point in result list).
                    if heap.len() == k {
                        heap.pop();
                    }
                    heap.push(HeapItem {
                        index: *original_position,
                        distance,
                    });
                    if heap.len() == k {
                        *tau = heap.peek().unwrap().distance;
                    }
                }

                match (node.left.as_ref(), node.right.as_ref()) {
                    // Return if we arrived at a leaf.
                    (None, None) => continue,
                    (_, _) => {
                        // If the target lies within the radius of ball.
                        if distance < node.threshold {
                            // if there can still be neighbors inside the ball, recursively search left child first.
                            if distance - *tau <= node.threshold {
                                stack.push(&node.left)
                            }
                            // if there can still be neighbors outside the ball, recursively search right child.
                            if distance + *tau >= node.threshold {
                                stack.push(&node.right)
                            }
                        } else {
                            // If the target lies outsize the radius of the ball.
                            // If there can still be neighbors outside the ball, recursively search right child.
                            if distance + *tau >= node.threshold {
                                stack.push(&node.right)
                            }
                            // if there can still be neighbors inside the ball, recursively search left child.
                            if distance - *tau <= node.threshold {
                                stack.push(&node.left)
                            }
                        }
                    }
                }
            }
        }
    }
```

--------------------------------

### tSNE Configuration Methods

Source: https://docs.rs/bhtsne/0.5.4/src/bhtsne/lib.rs.html

Methods to configure the t-SNE instance parameters before execution.

```APIDOC
## Configuration Methods

### Description
These methods allow for the modification of t-SNE hyperparameters.

### Parameters
- **learning_rate** (T) - Sets the learning rate.
- **epochs** (usize) - Sets the maximum number of fitting iterations.
- **momentum** (T) - Sets the momentum value.
- **final_momentum** (T) - Sets the final momentum value.
- **momentum_switch_epoch** (usize) - Sets the epoch to switch to final momentum.
- **stop_lying_epoch** (usize) - Sets the epoch to stop multiplying P distribution values.
- **embedding_dim** (u8) - Sets the dimensionality of the embedding space.
- **perplexity** (T) - Sets the perplexity value for Gaussian kernels.
```

--------------------------------

### SPTree Structure and Methods

Source: https://docs.rs/bhtsne/0.5.4/src/bhtsne/tsne/sptree.rs.html

Details the SPTree struct, a spatial partitioning tree, and its core methods for construction and data insertion.

```APIDOC
## SPTree<'a, T>

### Description
An implementation of a spatial partitioning tree (SPTree) used for organizing multi-dimensional data.

### Type Parameters
- **'a**: Lifetime parameter for the data slice.
- **T**: A type parameter that must implement `Float`, `NumCast`, and several arithmetic traits, ensuring it can be used for numerical computations.

### Fields
- **dimension** (usize) - The number of dimensions of the data points.
- **is_leaf** (bool) - Flag indicating if the current node is a leaf node.
- **cumulative_size** (i64) - The total number of points contained within this node and its children.
- **boundary** (SPTreeCell<T>) - The spatial boundary of this node.
- **data** (&'a [CachePadded<T>]) - A reference to the underlying data points.
- **center_of_mass** (Vec<T>) - The calculated center of mass for the points within this node.
- **index** (Option<usize>) - The index of the point if this node represents a single point (leaf node).
- **children** (Vec<SPTree<'a, T>>) - A vector holding the child nodes of this tree node.
- **n_children** (usize) - The number of potential children this node can have (2^dimension).

### Methods
#### `new(dimension: usize, data: &'a [CachePadded<T>], n_samples: usize) -> Self`

Constructs a new SPTree and builds the tree structure from the provided data.

* **Arguments**
  * `dimension` - The dimensionality of the data points.
  * `data` - A slice containing the data points to build the tree from.
  * `n_samples` - The total number of samples (points) in the `data`.

* **Returns**
  * `Self` - The newly constructed SPTree.

#### `new_empty(dimension: usize, data: &'a [CachePadded<T>], corner: Vec<T>, width: Vec<T>) -> Self`

Constructs an empty SPTree node with a specified boundary.

* **Arguments**
  * `dimension` - The dimensionality of the data points.
  * `data` - A reference to the underlying data points.
  * `corner` - The corner coordinates defining the boundary of this node.
  * `width` - The dimensions defining the boundary of this node.

* **Returns**
  * `Self` - An empty SPTree node.

#### `insert(&mut self, index: usize) -> bool`

Inserts a point, identified by its index in the `data` slice, into the SPTree.

* **Arguments**
  * `index` - The index of the point within the `data` slice to insert.

* **Returns**
  * `bool` - Indicates if the insertion was successful (implementation detail, likely always true if valid index).
```

--------------------------------

### Prepare Buffers for t-SNE Computation

Source: https://docs.rs/bhtsne/0.5.4/src/bhtsne/tsne/mod.rs.html

Allocates and initializes memory buffers required for t-SNE computation. These buffers are freed by `clear_buffers`.

```rust
pub(super) fn prepare_buffers<T: Float + Send + Sync>(
    y: &mut Vec<CachePadded<T>>,
    dy: &mut Vec<CachePadded<T>>,
    uy: &mut Vec<CachePadded<T>>,
    gains: &mut Vec<CachePadded<T>>,
    grad_entries: usize,
) {
    // Prepares the buffers.
    y.resize(grad_entries, T::zero().into()); // Embeddings.
    dy.resize(grad_entries, T::zero().into()); // Gradient.
    uy.resize(grad_entries, T::zero().into()); // Momentum buffer.
    gains.resize(grad_entries, T::one().into()); // Gains.
}
```

--------------------------------

### Exact t-SNE Fitting Method

Source: https://docs.rs/bhtsne/0.5.4/src/bhtsne/lib.rs.html

The primary method for performing exact t-SNE. It handles buffer initialization, distance matrix computation, perplexity search, and the iterative optimization loop.

```rust
pub fn exact<F: Fn(&U, &U) -> T + Send + Sync>(&mut self, distance_f: F) -> &mut Self {
        let data = self.data;
        let n_samples = self.data.len(); // Number of samples in data.

        // Checks that the supplied perplexity is suitable for the number of samples at hand.
        tsne::check_perplexity(&self.perplexity, &n_samples);

        let embedding_dim = self.embedding_dim as usize;
        // NUmber of entries in gradient and gains matrices.
        let grad_entries = n_samples * embedding_dim;
        // Number of entries in pairwise measures matrices.
        let pairwise_entries = n_samples * n_samples;

        // Prepares the buffers.
        tsne::prepare_buffers(
            &mut self.y,
            &mut self.dy,
            &mut self.uy,
            &mut self.gains,
            grad_entries,
        );
        // Prepare distributions matrices.
        self.p_values.resize(pairwise_entries, T::zero().into()); // P.
        self.q_values.resize(pairwise_entries, T::zero().into()); // Q.

        // Alignment prevents false sharing.
        let mut distances: Vec<CachePadded<T>> = vec![T::zero().into(); pairwise_entries];
        // Zeroes the diagonal entries. The distances vector is recycled but the elements
        // corresponding to the diagonal entries of the distance matrix are always kept to 0. and
        // never written on. This hold as an invariant through all the algorithm.
        for i in 0..n_samples {
            distances[i * n_samples + i] = T::zero().into();
        }

        // Compute pairwise distances in parallel with the user supplied function.
        // Only upper triangular entries, excluding the diagonal are computed: flat indexes are
        // unraveled to pick such entries.
        tsne::compute_pairwise_distance_matrix(
            &mut distances,
            distance_f,
            |index| &data[*index],
            n_samples,
        );

        // Compute gaussian perplexity in parallel. First, the conditional distribution is computed
        // for each element. Each row of the P matrix is independent from the others, thus, this
        // computation is accordingly parallelized.
        {
            let perplexity = &self.perplexity;
            self.p_values
                .par_chunks_mut(n_samples)
                .zip(distances.par_chunks(n_samples))
                .for_each(|(p_values_row, distances_row)| {
                    tsne::search_beta(p_values_row, distances_row, perplexity);
                });
        }

        // Symmetrize pairwise input similarities. Conditional probabilities must be summed to
        // obtain the joint P distribution.
        for i in 0..n_samples {
            for j in (i + 1)..n_samples {
                let symmetric = *self.p_values[j * n_samples + i];
                *self.p_values[i * n_samples + j] += symmetric;
                *self.p_values[j * n_samples + i] = *self.p_values[i * n_samples + j];
            }
        }

        // Normalize P values.
        tsne::normalize_p_values(&mut self.p_values);

        // Initialize solution randomly.
        tsne::random_init(&mut self.y);

        // Vector used to store the mean values for each embedding dimension. It's used
        // to make the solution zero mean.
        let mut means: Vec<T> = vec![T::zero(); embedding_dim];

        // Main fitting loop.
        for epoch in 0..self.epochs {
            // Compute pairwise squared euclidean distances between embeddings in parallel.
            tsne::compute_pairwise_distance_matrix(
                &mut distances,
                |ith: &[CachePadded<T>], jth: &[CachePadded<T>]| {
                    ith.iter()
                        .zip(jth.iter())
                        .map(|(&i, &j)| (*i - *j).powi(2))
                        .sum()
                },
                |index| &self.y[index * embedding_dim..index * embedding_dim + embedding_dim],
                n_samples,
            );

            // Computes Q.
            self.q_values
                .par_iter_mut()
                .zip(distances.par_iter())
                .for_each(|(q, d)| **q = T::one() / (T::one() + **d));

            // Computes the exact gradient in parallel.
            let q_values_sum: T = self.q_values.par_iter().map(|&q| *q).sum();

            // Immutable borrow to self must happen outside of the inner sequential
            // loop. The outer parallel loop already has a mutable borrow.
            let y = &self.y;
            self.dy
```

--------------------------------

### Configure t-SNE hyperparameters

Source: https://docs.rs/bhtsne/0.5.4/src/bhtsne/lib.rs.html

Methods for setting algorithm parameters using a builder pattern. Each method returns a mutable reference to the struct for chaining.

```rust
pub fn learning_rate(&mut self, learning_rate: T) -> &mut Self {
    self.learning_rate = learning_rate;

    self
}
```

```rust
pub fn epochs(&mut self, epochs: usize) -> &mut Self {
    self.epochs = epochs;

    self
}
```

```rust
pub fn momentum(&mut self, momentum: T) -> &mut Self {
    self.momentum = momentum;

    self
}
```

```rust
pub fn final_momentum(&mut self, final_momentum: T) -> &mut Self {
    self.final_momentum = final_momentum;

    self
}
```

```rust
pub fn momentum_switch_epoch(&mut self, momentum_switch_epoch: usize) -> &mut Self {
    self.momentum_switch_epoch = momentum_switch_epoch;

    self
}
```

```rust
pub fn stop_lying_epoch(&mut self, stop_lying_epoch: usize) -> &mut Self {
    self.stop_lying_epoch = stop_lying_epoch;

    self
}
```

```rust
pub fn embedding_dim(&mut self, embedding_dim: u8) -> &mut Self {
    self.embedding_dim = embedding_dim;

    self
}
```

```rust
pub fn perplexity(&mut self, perplexity: T) -> &mut Self {
    self.perplexity = perplexity;

    self
}
```

--------------------------------

### Random Initialization

Source: https://docs.rs/bhtsne/0.5.4/src/bhtsne/tsne/mod.rs.html

Randomly initializes the embedding by sampling from a normal distribution with mean 0 and sigma 1e-4.

```APIDOC
## random_init

### Description
Random initializes the embedding sampling from a normal distribution with mean 0 and sigma 1e-4.

### Arguments
* `y` - embedding.

### Signature
```rust
pub(super) fn random_init<T: Float + Send + Sync + Copy>(y: &mut [CachePadded<T>])
```
```

--------------------------------

### Functions

Source: https://docs.rs/bhtsne/0.5.4/bhtsne/all.html

Information about the functions available in the bhtsne crate.

```APIDOC
## Functions

### load_csv

This function is likely used to load data from a CSV file for use with the t-SNE algorithm.
```

--------------------------------

### Search k-Nearest Neighbors

Source: https://docs.rs/bhtsne/0.5.4/src/bhtsne/tsne/vptree.rs.html

This function searches the VPTree to find the k nearest neighbors of a given target point. It utilizes an auxiliary `look_up` function to traverse the tree and a `BinaryHeap` to maintain the nearest neighbors found so far.

```APIDOC
## POST /search/k-nearest-neighbors

### Description
Searches the VPTree for the k nearest neighbors of a target data point.

### Method
POST

### Endpoint
`/search/k-nearest-neighbors`

### Parameters
#### Query Parameters
- **target** (U) - Required - The target data point to search around.
- **target_index** (usize) - Required - The index of the target data point.
- **k** (usize) - Required - The number of nearest neighbors to find.
- **neighbors_indices** (&mut [CachePadded<usize>]) - Required - A mutable slice to store the indices of the nearest neighbors.
- **distances** (&mut [CachePadded<T>]) - Required - A mutable slice to store the distances to the nearest neighbors.
- **metric_f** (F) - Required - The metric function used for distance calculations. It takes two arguments of type U and returns a value of type T.

### Request Body
This endpoint does not have a request body. All parameters are passed via query parameters or function arguments.

### Response
#### Success Response (200)
This endpoint does not return a direct response body. The results (neighbor indices and distances) are populated in the `neighbors_indices` and `distances` mutable slices passed as arguments.

#### Response Example
(No direct response body, results are in output parameters)

```

--------------------------------

### VP-Tree Public Search Function

Source: https://docs.rs/bhtsne/0.5.4/src/bhtsne/tsne/vptree.rs.html

The public interface for searching the VP-Tree to find the k nearest neighbors of a target point. It initializes the search by calling the `look_up` function with an initial maximum distance and then gathers the results.

```rust
pub fn search<F>(
        &self,
        target: &U,
        target_index: usize,
        k: usize,
        neighbors_indices: &mut [CachePadded<usize>],
        distances: &mut [CachePadded<T>],
        metric_f: F,
    ) where
        F: Fn(&U, &U) -> T,
    {
        debug_assert_eq!(neighbors_indices.len(), distances.len());

        // Use a priority queue to store intermediate results on.
        let mut heap: BinaryHeap<HeapItem<T>> = BinaryHeap::with_capacity(k);
        // Perform the search.
        self.look_up(&mut T::max_value(), target, k, &mut heap, metric_f);
        // Gather final results.

```

--------------------------------

### Search Optimal Beta for Gaussian Kernel

Source: https://docs.rs/bhtsne/0.5.4/src/bhtsne/tsne/mod.rs.html

Performs a binary search to find the optimal bandwidth (beta) for the Gaussian kernel, relative to a given conditional distribution row and perplexity.

```rust
pub(super) fn search_beta<T>(
    p_values_row: &mut [CachePadded<T>],
    distances_row: &[CachePadded<T>],
    perplexity: &T,
) where

```

--------------------------------

### Implement HeapItem for VPTree Search

Source: https://docs.rs/bhtsne/0.5.4/src/bhtsne/tsne/vptree.rs.html

Implements the HeapItem struct and its comparison traits (PartialOrd, PartialEq, Eq, Ord) for use in the intermediate result heap during nearest neighbor searches in a VPTree. It orders items based on their distance.

```rust
/// An item on the intermediate result heap. It is used to store results from the nearest neighbors
/// search performed of the vantage point tree.
struct HeapItem<T: Float> {
    // Index of a sample.
    index: usize,
    // Distance of the sample from the target.
    distance: T,
}

impl<T: Float> PartialOrd for HeapItem<T> {
    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
        Some(self.cmp(other))
    }
}

impl<T: Float> PartialEq for HeapItem<T> {
    fn eq(&self, other: &Self) -> bool {
        self.distance == other.distance
    }
}

impl<T: Float> Eq for HeapItem<T> {}

impl<T: Float> Ord for HeapItem<T> {
    fn cmp(&self, other: &Self) -> Ordering {
        self.distance.partial_cmp(&other.distance).unwrap()
    }
}
```

--------------------------------

### Create Empty SPTree in Rust

Source: https://docs.rs/bhtsne/0.5.4/src/bhtsne/tsne/sptree.rs.html

Constructs an empty SPTree with initial parameters like dimension, data, and boundary cell. It sets up the basic structure before data is populated.

```rust
/// Constructs an empty tree.
///
/// # Arguments
///
/// * `dimension` - dimensions of a point.
///
/// * `data` - data to build the tree from.
///
/// * `corner` - a corner for a cell.
///
/// * `width` - cell's width.
fn new_empty(
    dimension: usize,
    data: &'a [CachePadded<T>],
    corner: Vec<T>,
    width: Vec<T>,
) -> Self {
    let n_children = 2usize.pow(dimension as u32);
    let boundary = SPTreeCell::new(corner, width);
    let children = Vec::new();
    let center_of_mass = vec![T::zero(); dimension];

    SPTree {
        children,
        center_of_mass,
        boundary,
        cumulative_size: 0,
        is_leaf: true,
        dimension,
        n_children,
        index: None,
        data,
    }
}
```

--------------------------------

### From trait implementation

Source: https://docs.rs/bhtsne/0.5.4/bhtsne/struct.tSNE.html

Returns the argument unchanged.

```rust
impl<T> From<T> for T
fn from(t: T) -> T
```

--------------------------------

### Load Data from CSV File

Source: https://docs.rs/bhtsne/0.5.4/src/bhtsne/lib.rs.html

Loads data from a CSV file with options to specify headers, skip columns, and provide a custom parsing function for each string field. Requires the 'csv' feature to be enabled.

```rust
/// Loads data from a csv file.
///
/// # Arguments
///
/// * `file_path` - path of the file to load the data from.
///
/// * `has_headers` - whether the file has headers or not. if set to `true` the function will
///   not parse the first line of the csv file.
///
/// * `skip` - an optional slice that specifies a subset of the file columns that must not be
///   parsed.
///
/// * `f` - function that converts [`String`] into a data sample. It takes as an argument a single
///   record field.
///
/// # Errors
///
/// Returns an error is something goes wrong during the I/O operations.
#[cfg(feature = "csv")]
pub fn load_csv<T, F>(
    path: &str,
    has_headers: bool,
    skip: Option<&[usize]>,
    f: F,
) -> Result<Vec<T>, Box<dyn Error>>
where
    F: Fn(String) -> T,
{
    let mut data: Vec<T> = Vec::new();

    let file = File::open(path)?;

    let mut reader = csv::ReaderBuilder::new()

```

--------------------------------

### Search Beta

Source: https://docs.rs/bhtsne/0.5.4/src/bhtsne/tsne/mod.rs.html

Performs a binary search over the real numbers to find the optimal bandwidth of the Gaussian kernel relative to the condition distribution `p_values_row`.

```APIDOC
## search_beta

### Description
Performs a binary search over the real numbers looking for the optimal bandwidth of the
Gaussian kernel relative to the condition distribution `p_values_row`.

### Arguments
* `p_values_rows` - conditional distribution relative to the sample.
* `distances_row` - row of the distance matrix relative to the sample.
* `perplexity` - given perplexity value.

### Signature
```rust
pub(super) fn search_beta<T>(
    p_values_row: &mut [CachePadded<T>],
    distances_row: &[CachePadded<T>],
    perplexity: &T,
)
where
```
```

--------------------------------

### t-SNE Arguments

Source: https://docs.rs/bhtsne/0.5.4/bhtsne/struct.tSNE.html

Describes the arguments used in the t-SNE algorithm.

```APIDOC
## t-SNE Arguments

### Description
Arguments for the t-SNE algorithm.

### Parameters
#### Query Parameters
- **theta** (float) - Required - Determines the accuracy of the approximation. Must be strictly greater than 0.0. Large values for θ increase the speed of the algorithm but decrease its accuracy. For small values of θ it is less probable that a cell in the space partitioning tree will be treated as a single point. For θ equal to 0.0 the method degenerates in the exact version.
- **metric_f** (function) - Required - Metric function. Must be a metric distance, i.e. it must satisfy the triangle inequality.
```

--------------------------------

### Compute Forces using Barnes-Hut Algorithm

Source: https://docs.rs/bhtsne/0.5.4/src/bhtsne/lib.rs.html

Computes forces using the Barnes-Hut algorithm in parallel. This method approximates interactions between points in the embedding space for efficiency.

```rust
positive_forces
                    .par_chunks_mut(embedding_dim)
                    .zip(negative_forces.par_chunks_mut(embedding_dim))
                    .zip(forces_buffer.par_chunks_mut(embedding_dim))
                    .zip(q_sums.par_iter_mut())
                    .zip(self.y.par_chunks(embedding_dim))
                    .enumerate()
                    .for_each(
                        |(index, (
                            (                                
                                ((positive_forces_row, negative_forces_row), forces_buffer_row),
                                q_sum,
                            ),
                            sample,
                        ))| {
                            tree.compute_edge_forces(
                                index,
                                embedding_dim,
                                &self.y,
                                &self.p_values,
                                n_samples,
                                &self.q_values,
                                positive_forces_row,
                                negative_forces_row,
                                forces_buffer_row,
                                q_sum,
                            );
                        },
                    );
```

--------------------------------

### Into trait implementation

Source: https://docs.rs/bhtsne/0.5.4/bhtsne/struct.tSNE.html

Performs a conversion into another type.

```rust
impl<T, U> Into<U> for T
where U: From<T>,
fn into(self) -> U
```

--------------------------------

### tSNE Execution

Source: https://docs.rs/bhtsne/0.5.4/src/bhtsne/lib.rs.html

Methods to initialize the t-SNE instance and retrieve the final embedding.

```APIDOC
## tSNE::new

### Description
Initializes a new t-SNE instance with the provided data.

### Parameters
- **data** (&'data [U]) - The input data to be embedded.

## tSNE::embedding

### Description
Returns the computed embedding as a vector.

### Response
- **Vec<T>** - The resulting embedding coordinates.
```

--------------------------------

### Randomly Initialize Embedding

Source: https://docs.rs/bhtsne/0.5.4/src/bhtsne/tsne/mod.rs.html

Initializes the embedding vector by sampling from a normal distribution with a mean of 0 and a standard deviation of 1e-4.

```rust
pub(super) fn random_init<T: Float + Send + Sync + Copy>(y: &mut [CachePadded<T>]) {
    let distr = Normal::new(0.0, 1e-4).unwrap();
    let mut rng = rand::rng();
    y.iter_mut()
        .for_each(|el| **el = T::from(distr.sample(&mut rng)).unwrap());
}
```

--------------------------------

### t-SNE Update and Optimization

Source: https://docs.rs/bhtsne/0.5.4/src/bhtsne/lib.rs.html

Details the internal update steps of the t-SNE algorithm, including gradient descent, momentum, and zero-mean normalization.

```APIDOC
## Internal Operations (t-SNE)

### Description
This section describes internal operations within the t-SNE algorithm, including gradient updates, momentum application, and data normalization.

### Method
Internal

### Endpoint
N/A (Internal Algorithm Steps)

### Parameters
N/A

### Request Example
N/A

### Response
N/A

### Internal Operations Details:
- **Gradient Descent Update**: Updates the embedding `y` using calculated gradients `dy`, previous updates `uy`, learning rate, and momentum.
- **Gradient Zeroing**: Resets the gradient buffer `dy` to zero after each update.
- **Zero Mean Normalization**: Centers the embedding `y` to have a mean of zero.
- **P-value Adjustment**: Potentially adjusts P-values at a specified epoch (`stop_lying_epoch`).
- **Momentum Switch**: Switches to a final momentum value at a specified epoch (`momentum_switch_epoch`).
- **Buffer Clearing**: Clears temporary buffers (`dy`, `uy`, `gains`) after fitting is complete.
```

--------------------------------

### Process Sparse Matrix Data in Rust

Source: https://docs.rs/bhtsne/0.5.4/src/bhtsne/tsne/mod.rs.html

Processes sparse matrix data to populate symmetric structures. This involves checking for element presence, handling additions, and updating offsets. Ensure correct indexing and value assignments for symmetric matrices.

```rust
if !p_columns[p_rows(*p_columns[i])..p_rows(*p_columns[i] + 1)]
                .iter()
                .any(|el| **el == n)
            {
                row_counts[*p_columns[i]] += 1;
            }
        }
    }

    let total: usize = row_counts.iter().sum();

    let mut sym_row_p: Vec<usize> = vec![0; n_samples + 1];
    let mut sym_col_p: Vec<usize> = vec![0; total];
    let mut sym_val_p: Vec<CachePadded<T>> = vec![T::zero().into(); total];

    sym_row_p[0] = 0;
    for _n in 0..n_samples {
        sym_row_p[_n + 1] = sym_row_p[_n] + row_counts[_n];
    }

    let mut offset: Vec<usize> = vec![0; n_samples];

    for _n in 0..n_samples {
        for i in p_rows(_n)..p_rows(_n + 1) {
            // Check whether element (col_P[i], n) is present.
            let mut present: bool = false;
            // Considering element(n, col_P[i]).
            for m in p_rows(*p_columns[i])..p_rows(*p_columns[i] + 1) {
                if *p_columns[m] == _n {
                    present = true;
                    // Make sure we do not add elements twice.
                    if _n <= *p_columns[i] {
                        sym_col_p[sym_row_p[_n] + offset[_n]] = *p_columns[i];
                        sym_col_p[sym_row_p[*p_columns[i]] + offset[*p_columns[i]]] = _n;
                        *sym_val_p[sym_row_p[_n] + offset[_n]] = *p_values[i] + *p_values[m];
                        *sym_val_p[sym_row_p[*p_columns[i]] + offset[*p_columns[i]]] =
                            *p_values[i] + *p_values[m];
                    }
                }
            }
            // If (col_P[i], n) is not present, there is no addition involved.
            if !present {
                sym_col_p[sym_row_p[_n] + offset[_n]] = *p_columns[i];
                sym_col_p[sym_row_p[*p_columns[i]] + offset[*p_columns[i]]] = _n;
                *sym_val_p[sym_row_p[_n] + offset[_n]] = *p_values[i];
                *sym_val_p[sym_row_p[*p_columns[i]] + offset[*p_columns[i]]] = *p_values[i];
            }
            // Update offsets.
            if !present || _n <= *p_columns[i] {
                offset[_n] += 1;
                if *p_columns[i] != _n {
                    offset[*p_columns[i]] += 1;
                }
            }
        }
    }

    // Divide result by two.
    let zero_point_five = T::from(0.5).unwrap();
    sym_val_p.iter_mut().for_each(|p| **p *= zero_point_five);

    *p_values = sym_val_p;
    *sym_p_rows = sym_row_p;
    *sym_p_columns = sym_col_p;
}
```

--------------------------------

### Any trait implementation

Source: https://docs.rs/bhtsne/0.5.4/bhtsne/struct.tSNE.html

Provides the TypeId for the object.

```rust
impl<T> Any for T
where T: 'static + ?Sized,
fn type_id(&self) -> TypeId
```
Tokens:
Raw