.. sectionauthor:: Robert Nikutta <robert.nikutta@noirlab.edu>

*Version: 20220215*

.. index::
   single: convex hull
   pair: helpers; clustering
   pair: helpers; crossmatch
   pair: crossmatch; xmatch
   pair: helpers; plot
   pair: helpers; utils
 

.. _sec_Helpers:

*******
Helpers
*******

Data Lab provides several convenient helper modules for use e.g. in
:ref:`sec_JupyterNotebooks`. They can simplify some of the more
tedious or repetitive tasks that one would perform with Data Lab.

This collection is ever-evolving, and we welcome user suggestions for
other helper functionalities.

Available helpers
=================

The table below lists the currently available helper modules and
briefly describes their function. All functions therein, and their
call signatures, are described in the `API documentation
<https://datalab.noirlab.edu/docs/api/helpers.html>`_.

.. table:: Available helper modules
   :widths: auto

   +-------------------+------------------------------------------------------------------------------------------------+
   | Helper module     | Description                                                                                    |
   +===================+================================================================================================+
   | ``cluster.py``    | find clusters in 2d (e.g. RA/Dec positions), compute convex hulls around clusters              |
   +-------------------+------------------------------------------------------------------------------------------------+
   | ``crossmatch.py`` | local (in-RAM) cross-matching of two datasets (RA/Dec positions)                               |
   +-------------------+------------------------------------------------------------------------------------------------+
   | ``plot.py``       | plot helpers, e.g. all-sky projected scatter plots                                             |
   +-------------------+------------------------------------------------------------------------------------------------+
   | ``utils.py``      | utility functions, e.g. conversion of query results to various formats (pandas, ndarray, etc.) |
   +-------------------+------------------------------------------------------------------------------------------------+
   | ``legacy.py``     | deprecated helpers; may still be used by some older notebooks                                  |
   +-------------------+------------------------------------------------------------------------------------------------+
   | ``all.py``        | alias that loads all of the above                                                              |
   +-------------------+------------------------------------------------------------------------------------------------+

Importing
=========

There are various ways to import either a single helper module, a
function from a helper, or all helpers at once:

Import a single helper module:

.. code-block:: python
    :linenos:
       
    from dl.helpers import cluster
    result = cluster.findClusters(...)  # use a function from the helper

Import one function from a helper module:

.. code-block:: python
    :linenos:
       
    from dl.helpers.cluster import findClusters
    result = findClusters(...)

Import all functions from all helper modules at once:

.. code-block:: python
    :linenos:

    from dl.helpers import all  # `all` is a convenience module; loads all others
    result = findClusters(...)  # use a function