1openTSNE 2======== 3 4|Build Status| |ReadTheDocs Badge| |License Badge| 5 6openTSNE is a modular Python implementation of t-Distributed Stochasitc Neighbor Embedding (t-SNE) [1]_, a popular dimensionality-reduction algorithm for visualizing high-dimensional data sets. openTSNE incorporates the latest improvements to the t-SNE algorithm, including the ability to add new data points to existing embeddings [2]_, massive speed improvements [3]_ [4]_, enabling t-SNE to scale to millions of data points and various tricks to improve global alignment of the resulting visualizations [5]_. 7 8.. figure:: docs/source/images/macosko_2015.png 9 :alt: Macosko 2015 mouse retina t-SNE embedding 10 :align: center 11 12 A visualization of 44,808 single cell transcriptomes obtained from the mouse retina [6]_ embedded using the multiscale kernel trick to better preserve the global aligment of the clusters. 13 14- `Documentation <http://opentsne.readthedocs.io>`__ 15- `User Guide and Tutorial <https://opentsne.readthedocs.io/en/latest/tsne_algorithm.html>`__ 16- Examples: `basic <https://opentsne.readthedocs.io/en/latest/examples/01_simple_usage/01_simple_usage.html>`__, `advanced <https://opentsne.readthedocs.io/en/latest/examples/02_advanced_usage/02_advanced_usage.html>`__, `preserving global alignment <https://opentsne.readthedocs.io/en/latest/examples/03_preserving_global_structure/03_preserving_global_structure.html>`__, `embedding large data sets <https://opentsne.readthedocs.io/en/latest/examples/04_large_data_sets/04_large_data_sets.html>`__ 17- `Speed benchmarks <https://opentsne.readthedocs.io/en/latest/benchmarks.html>`__ 18 19Installation 20------------ 21 22openTSNE requires Python 3.7 or higher in order to run. 23 24Conda 25~~~~~ 26 27openTSNE can be easily installed from ``conda-forge`` with 28 29:: 30 31 conda install --channel conda-forge opentsne 32 33`Conda package <https://anaconda.org/conda-forge/opentsne>`__ 34 35PyPi 36~~~~ 37 38openTSNE is also available through ``pip`` and can be installed with 39 40:: 41 42 pip install opentsne 43 44`PyPi package <https://pypi.org/project/openTSNE>`__ 45 46Installing from source 47~~~~~~~~~~~~~~~~~~~~~~ 48 49If you wish to install openTSNE from source, please run 50 51:: 52 53 python setup.py install 54 55 56in the root directory to install the appropriate dependencies and compile the necessary binary files. 57 58Please note that openTSNE requires a C/C++ compiler to be available on the system. Additionally, 59``numpy`` must be pre-installed in the active environment. 60 61In order for openTSNE to utilize multiple threads, the C/C++ compiler 62must support ``OpenMP``. In practice, almost all compilers 63implement this with the exception of older version of ``clang`` on OSX 64systems. 65 66To squeeze the most out of openTSNE, you may also consider installing 67FFTW3 prior to installation. FFTW3 implements the Fast Fourier 68Transform, which is heavily used in openTSNE. If FFTW3 is not available, 69openTSNE will use numpy’s implementation of the FFT, which is slightly 70slower than FFTW. The difference is only noticeable with large data sets 71containing millions of data points. 72 73A hello world example 74--------------------- 75 76Getting started with openTSNE is very simple. First, we'll load up some data using scikit-learn 77 78.. code:: python 79 80 from sklearn import datasets 81 82 iris = datasets.load_iris() 83 x, y = iris["data"], iris["target"] 84 85then, we'll import and run 86 87.. code:: python 88 89 from openTSNE import TSNE 90 91 embedding = TSNE().fit(x) 92 93Citation 94-------- 95 96If you make use of openTSNE for your work we would appreciate it if you would cite the paper 97 98.. code:: 99 100 @article {Poli{\v c}ar731877, 101 author = {Poli{\v c}ar, Pavlin G. and Stra{\v z}ar, Martin and Zupan, Bla{\v z}}, 102 title = {openTSNE: a modular Python library for t-SNE dimensionality reduction and embedding}, 103 year = {2019}, 104 doi = {10.1101/731877}, 105 publisher = {Cold Spring Harbor Laboratory}, 106 URL = {https://www.biorxiv.org/content/early/2019/08/13/731877}, 107 eprint = {https://www.biorxiv.org/content/early/2019/08/13/731877.full.pdf}, 108 journal = {bioRxiv} 109 } 110 111openTSNE implements two efficient algorithms for t-SNE. Please consider citing the original authors of the algorithm that you use. If you use FIt-SNE (default), then the citation is [4]_ below, but if you use Barnes-Hut the citation is [3]_. 112 113 114References 115---------- 116 117.. [1] Van Der Maaten, Laurens, and Hinton, Geoffrey. `“Visualizing data using 118 t-SNE.” <http://www.jmlr.org/papers/volume9/vandermaaten08a/vandermaaten08a.pdf>`__ 119 Journal of Machine Learning Research 9.Nov (2008): 2579-2605. 120.. [2] Poličar, Pavlin G., Martin Stražar, and Blaž Zupan. `“Embedding to Reference t-SNE Space Addresses Batch Effects in Single-Cell Classification.” <https://link.springer.com/article/10.1007/s10994-021-06043-1>`__ Machine Learning (2021): 1-20. 121.. [3] Van Der Maaten, Laurens. `“Accelerating t-SNE using tree-based algorithms.” 122 <http://www.jmlr.org/papers/volume15/vandermaaten14a/vandermaaten14a.pdf>`__ 123 Journal of Machine Learning Research 15.1 (2014): 3221-3245. 124.. [4] Linderman, George C., et al. `"Fast interpolation-based t-SNE for improved 125 visualization of single-cell RNA-seq data." <https://www.nature.com/articles/s41592-018-0308-4>`__ Nature Methods 16.3 (2019): 243. 126.. [5] Kobak, Dmitry, and Berens, Philipp. `“The art of using t-SNE for single-cell transcriptomics.” <https://www.nature.com/articles/s41467-019-13056-x>`__ 127 Nature Communications 10, 5416 (2019). 128.. [6] Macosko, Evan Z., et al. \ `“Highly parallel genome-wide expression profiling of 129 individual cells using nanoliter droplets.” 130 <https://www.sciencedirect.com/science/article/pii/S0092867415005498>`__ 131 Cell 161.5 (2015): 1202-1214. 132 133.. |Build Status| image:: https://dev.azure.com/pavlingp/openTSNE/_apis/build/status/Test?branchName=master 134 :target: https://dev.azure.com/pavlingp/openTSNE/_build/latest?definitionId=1&branchName=master 135.. |ReadTheDocs Badge| image:: https://readthedocs.org/projects/opentsne/badge/?version=latest 136 :target: https://opentsne.readthedocs.io/en/latest/?badge=latest 137 :alt: Documentation Status 138.. |License Badge| image:: https://img.shields.io/badge/License-BSD%203--Clause-blue.svg 139 :target: https://opensource.org/licenses/BSD-3-Clause 140