.. index::
   single: catalog
   pair: table access protocol; TAP
   pair: simple cone search; SCS

.. sectionauthor:: Robert Nikutta <robert.nikutta@noirlab.edu>, Mike Fitzpatrick <mike.fitzpatrick@noirlab.edu>

.. _sec_CatalogDataAccessTAPSCS:

*****************************
Catalog Data Access (TAP/SCS)
*****************************
.. contents::
   :local:

IVOA service definitions
========================

+---------+-----------------------+------------------------------------------------------+
| Acronym | Service               | Latest definition                                    |
+=========+=======================+======================================================+
| TAP     | Table Access Protocol | http://www.ivoa.net/documents/TAP/                   |
+---------+-----------------------+------------------------------------------------------+
| SCS     | Simple Cone Search    | http://www.ivoa.net/documents/latest/ConeSearch.html |
+---------+-----------------------+------------------------------------------------------+

Table Access Protocol (TAP)
===========================

The Table Access Protocol (TAP) is an IVOA standard developed to
enable services to access tabular data (even remote ones), including
e.g. astronomical catalogs. The definition of the protocol can be
found at http://www.ivoa.net/documents/TAP/

Data Lab exposes a TAP service endpoint, i.e. you can point any
TAP-aware software to that endpoint and gain immediate access to the
catalog holdings at Data Lab.

The Data Lab TAP service URL is: https://datalab.noirlab.edu/tap

Example: TAP usage with TOPCAT
==============================

TOPCAT (Taylor 2005, [1]_) is a desktop application popular among
astronomers to access remote databases using the TAP protocol. Here we
demonstrate the few steps necessary to tell your TOPCAT how to access
the Data Lab TAP service.

Install and launch TOPCAT
-------------------------

Get TOPCAT from http://www.star.bris.ac.uk/~mbt/topcat/ and follow the
installation instructions there. When installed, you can launch TOPCAT
from the installation directory via

.. code-block:: bash

   cd topcatdir/
   ./topcat

This will launch the TOPCAT root window:

.. figure:: topcat_root.png
   :scale: 100 %
   :alt: Topcat root window

Tell TOPCAT where to find Data Lab's TAP service
------------------------------------------------

You can set the TAP service URL in TOPCAT's `VO-->TAP` menu

.. figure:: topcat_vo.png
   :scale: 100 %
   :alt: Topcat VO menu

A new window will open. At the very bottom of that window, in the
`Selected TAP Service` field, type or paste the Data Lab TAP service
endpoint ``https://datalab.noirlab.edu/tap``, and click the `Use Service`
button.

.. figure:: topcat_selecttap_2023.png
   :scale: 100 %
   :alt: Topcat select TAP service

The view will change to the `Use Service` tab, and the left menu bar
will display all catalogs currently held at Data Lab:

.. figure:: topcat_usetap_2023.png
   :scale: 100 %
   :alt: Topcat use TAP service

Browse the data holdings in Data Lab
------------------------------------

Double-click on any of the database schema listed in the left-hand
panel to expand a tree of all tables in that schema. A simple click on
any of the tables in a schema brings up information about that table
in the right-hand panel. In the example below, the `Columns` tab shows
the names, data types, descriptions, etc., of all columns in the
``object`` table in the ``smash_dr2`` database schema.

.. figure:: topcat_smashobjectcolumns_2023.png
   :scale: 100 %
   :alt: SMASH column view


Simple Cone Search (SCS) protocol
=================================

From the protocol definition document: http://www.ivoa.net/documents/latest/ConeSearch.html

"This specification defines a simple query protocol for retrieving
records from a catalog of astronomical sources. The query describes
sky position and an angular distance, defining a cone on the sky. The
response returns a list of astronomical sources from the catalog whose
positions lie within the cone, formatted as a VOTable."

Example: SCS usage with TOPCAT
==============================

A cone search can be performed with TOPCAT, using the `VO-->Cone
Search` menu:

.. figure:: topcat_conemenu.png
   :scale: 100 %
   :alt: Topcat cone search menu

A new window dialog will open. In the `Cone Parameters` panel, enter
the defined cone search service endpoint in the `Cone URL` field (the
example below uses ``https://datalab.noirlab.edu/scs/ls_dr8/tractor`` to
query the `Legacy Surveys <http://www.legacysurvey.org/>`_ Data
Release 8 catalog).

.. figure:: topcat_conesearch_2023.png
   :scale: 100 %
   :alt: Topcat cone search

In the `RA` and `Dec` fields enter the center point of the search
cone, and in the `Radius` field the search radius around the (RA,Dec)
center position.

.. todo:: Describe how to obtain a list of all defined cone searches once the bugs are ironed out.

References
==========

.. [1] Taylor, M.B. (2005, ASPC 347, 29) "TOPCAT & STIL: Starlink Table/VOTable Processing Software": http://adsabs.harvard.edu/abs/2005ASPC..347...29T