Umappp - UMAP for Ruby

🗺️ Umappp - Uniform Manifold Approximation and Projection - for Ruby

Uniform Manifold Approximation and Projection (UMAP) is a dimension reduction technique that can be used for visualisation similarly to t-SNE, but also for general non-linear dimension reduction. (original UMAP documentation)

• Ruby Umappp is a wrapper library for C++ Umappp library created by Aaron Lun
• Compatible with yaumap
• Support Numo::NArray

Installation

gem install umappp

• OpenMP is required for multithreading.

Usage

This Gem provides the module Umappp and its singular method Umappp.run(). The first argument of Umappp.run() is a two-dimensional Ruby array or a two-dimensional Numo array. Numo is a library for performing N-dimensional array computing like NumPy. The argument is converted to Numo::SFloat. SFloat is a single precision floating point number type of Numo::NArray.

# Original high-dimensional data as two-dimensional Ruby array or Numo array
data = Numo::SFloat.new(10, 784).rand # e.g. 10 images with 784 features

# Returns low-dimensional embedding as Numo::SFloat
embedding = Umappp.run(data)

# Run with parameters
embedding = Umappp.run(data, num_threads: 8, a: 1.8956, b: 0.8006)

Available parameters and their default values

(The defaults are obtained from the underlying C++ Umappp library via Umappp.default_parameters and may change when the bundled Umappp version is updated.)

parameters	default value
method	:annoy (another option is :vptree)
ndim	2
local_connectivity	1.0
bandwidth	1
mix_ratio	1
spread	1
min_dist	0.01
a	0
b	0
repulsion_strength	1
initialize	Umappp::InitMethod::SPECTRAL
num_epochs	500
learning_rate	1
negative_sample_rate	5
num_neighbors	15
seed	1234567890
num_threads	1 (OpenMP required)

For the initialize parameter, this gem currently accepts the symbols :spectral, :spectral_only, :random and :none, which are mapped to Umappp::InitMethod values internally.

Development

git clone https://github.com/kojix2/ruby-umappp
cd ruby-umappp
bundle exec rake compile
bundle exec rake test

Update LTLA/umappp

Requires cmake to run

cd script
./vendor.sh

Ruby dependencies

• rice - Ruby Interface for C++ Extensions
• numo.hpp - C++ header for Numo and Rice

Umappp dependencies

This Gem is a wrapper for Umappp. We store and distribute Umappp and other dependent C++ code in the Vendor directory. Umappp is compiled when the Gem is installed. Umappp's C++ modules have complex dependencies as shown in the figure below. It is not a good idea to manage them manually. Use script/vendor.sh to update them automatically. This actually runs cmake and moves the required directories to the vendor directory.

graph TD;
    id1(eigen)-->CppIrlba;
    aarand-->CppIrlba;
    Annoy-->knncolle;
    hnswlib-->knncolle;
    CppKmeans-->knncolle;
    aarand-->CppKmeans;
    powerit-->CppKmeans;
    aarand-->powerit;
    knncolle-->umappp;
    aarand-->umappp;
    CppIrlba-->umappp;
    style id1 fill:#f9f,stroke:#333

All modules except eigen are the work of Aaron Lun.

Contributing

Welcome!

Do you need commit rights to my repository?
Do you want to get admin rights and take over the project?
If so, please feel free to contact us @kojix2.

License

• As for the code I wrote, it is BSD 2-Clause (or MIT).
• The license of Umappp for C++ by Aaron Lun is BSD 2-Clause.
• For other codes, please check on your own. (There are many dependencies)