thisnotthat 0.4.2
Tools for interactive visualization and exploration of _data maps_
License: new BSD

.. -*- mode: rst -*-

.. image:: doc/tnt_logo.png
  :width: 600
  :alt: TNT Logo

===================
This Not That (TNT)
===================

This Not That is a suite of tools for working with, exploring, and interacting with "data maps". A data map is a two
(or three) dimensional representation of higher dimensional vector space data, usually produced by UMAP, t_SNE, or
another manifold learning technique. The goal of This Not That is to make it quick and easy to visualize, enrich and
interact with data maps. This not that also aims to make it easy to build and deploy simple web-apps on top of data
maps to let other users gain access to rich interactive data maps as a means to explore data sets.

---------------------------
This Not That for Labelling
---------------------------

This Not That makes it easy to quickly build an interactive data labeller directly in your notebook, allowing
you to quickly tag data for further analysis, extract interesting samples, or do an initial round of bulk
labelling.

-----------------------------
This Not That for Exploration
-----------------------------

This Not That makes it easy to get an interactive plot of a data map, but also allows you to quickly connect
other tools to it, including powerful search utilities, a rich data instance viewer, data tables tied to
in-plot selections, and tools for quickly adjusting plot attributes from lists of extra variables.

This Not That also provides a variety of automated solutions for adding textual annotation layers to data maps,
providing easier navigation and exploration.

-------------------------------
This Not That for Data Map Apps
-------------------------------

Because This Not That is built on top of the `Panel library`_ it is trivial to deploy TNT based solutions as
interactive web applications.

-------------
Documentation
-------------

Get the latest on `Read The Docs <https://thisnotthat.readthedocs.io/en/latest/>`_.

----------
Installing
----------
**JUPYTER HUB WARNING:** attempting to use a TNT notebook in conjunction with a jupyter hub instance can result in broken linkages between the selections for your 
various panel panes.  If you are running on jupyter hub server and can select points in one of your plots but it isn't updating any other plots then this
is the likely culprit.  Fixing this requires that the same versions of the `Panel library`_ and `bokeh <https://pypi.org/project/bokeh/>`_ are installed in the main kernel that starts the jupyter hub server and the local kernel.
If you are running on a groups jupyterhub server this may require you contacting the administrator and asking them to install your favorite versions of bokeh and panel before restarting
their server.  I'd recommend you then record the version information for your team so that they can easily match the versions in their local kernels.  

This Not That is built on top of Panel and Bokeh, so you will need these installed. In all you will need:

* panel
* bokeh
* numpy >= 1.22
* pandas
* scikit-learn
* matplotlib
* umap-learn
* hdbscan
* glasbey
* cmocean
* vectorizers

We also highly recommend installing:

* networkx
* apricot-select

Currently you can pip install from PyPI:

.. code:: bash

    pip install thisnotthat

Or directly from this repository:

.. code:: bash

    pip install git+https://github.com/TutteInstitute/thisnotthat

------------
Contributing
------------

Contributions are more than welcome! There are lots of opportunities
for potential projects, so please get in touch if you would like to
help out. Everything from code to notebooks to
examples and documentation are all *equally valuable* so please don't feel
you can't contribute. We are also keen to hear user stories and suggestions for new Pane's to add to
to our catalog. We also welcome contributions to get other plot libraries integrated and
working with TNT, including plotly, VTK/PyVista, and others, so if you have expertise with these please consider
contributing.

To contribute please `fork the project <https://github.com/TutteInstitute/thisnotthat/issues#fork-destination-box>`_ make your changes and
submit a pull request. We will do our best to work through any issues with
you and get your code merged into the main branch.

------------
Development
------------

To create a development environment clone the repo and install the package in editable mode

.. code:: bash

    pip install -e .[tests]

To run unit tests

.. code:: bash

    pytest thisnotthat/tests

UI tests are done using `Playwright <https://playwright.dev/>`_ and build on `Panel's UI tests <https://panel.holoviz.org/how_to/test/uitests.html>`_. 
They are not run by default and require the --ui flag. Note that this only runs the UI tests. You can install a browser for Playwright and use it to run tests:

.. code:: bash

    playwright install chromium
    pytest thisnotthat/tests/ --ui --browser chromium -n 1

or use an existing browser on your machine such as Chrome

.. code:: bash

    pytest thisnotthat/tests/ --ui --browser-channel chrome -n 1

-------
License
-------

The This Not That package is 3-clause BSD licensed.


.. _Panel library: https://panel.holoviz.org/