.. _gallery_nb_gallery_example_voservices.ipynb:

Using VO services
=================

OpenKM3 uses the `pyvo interface <https://pyvo.readthedocs.io>`__ to
access data provided through the `VO server <http://vo.km3net.de>`__ of
KM3NeT. Currently implemented is a Simple Cone Search (SCS) service
accessible through the TAP protocol.

.. code:: ipython3

    from openkm3.store import KM3Store
    store = KM3Store()


.. parsed-literal::

    INFO:root:Loaded catalog from cache.


.. code:: ipython3

    service = store.get("ana20_01_vo")


.. parsed-literal::

    INFO:root:Loaded entry ana20_01_vo as <class 'openkm3.dataclasses.SCSServiceVO'>.


.. code:: ipython3

    service.show_paraminfo()


.. parsed-literal::

    Table: ant20_01.main
    Neutrino candidates from full-sky search from 2007-2017
    
    name                 description                 unit       ucd       utype arraysize datatype
    ---- ------------------------------------------- ---- --------------- ----- --------- --------
      _r                     Distance to cone center  deg    pos.distance  None         1     None
     MJD                         Modified Julian Day None      time.epoch  None         1     None
    Beta    angular error estimate on reconstruction None      stat.error  None         1     None
    Nhit number of light signals in photomultipliers None     phys.energy  None         1     None
      RA              FK5 equatorial right ascension None  POS_EQ_RA_MAIN  None         1     None
    Decl                  FK5 equatorial declination None POS_EQ_DEC_MAIN  None         1     None
      ID                            Event identifier None         ID_MAIN  None         *     None


Getting TAP service or SCS
--------------------------

You can get the services from the loaded KM3Object, which returns pyvo
objects. From here onwards, you can use pyvo functions.

.. code:: ipython3

    tap = service.get_tap()
    highEevents = tap.search("SELECT * FROM ant20_01.main WHERE nhit>150") # get most high-energetic events
    highEevents.to_table()




.. raw:: html

    <i>Table length=10</i>
    <table id="table139982155829936" class="table-striped table-bordered table-condensed">
    <thead><tr><th>mjd</th><th>beta</th><th>nhit</th><th>ra</th><th>decl</th><th>id</th></tr></thead>
    <thead><tr><th>float64</th><th>float64</th><th>int32</th><th>float64</th><th>float64</th><th>object</th></tr></thead>
    <tr><td>54789.2282</td><td>0.1</td><td>263</td><td>315.0</td><td>-16.7</td><td>ANT1157</td></tr>
    <tr><td>55970.095</td><td>0.3</td><td>160</td><td>18.6</td><td>-43.3</td><td>ANT4737</td></tr>
    <tr><td>56660.329</td><td>0.9</td><td>200</td><td>10.8</td><td>-1.5</td><td>ANT6138</td></tr>
    <tr><td>56221.4919</td><td>0.3</td><td>158</td><td>39.6</td><td>11.0</td><td>ANT5198</td></tr>
    <tr><td>56329.4015</td><td>0.2</td><td>157</td><td>156.7</td><td>3.6</td><td>ANT5571</td></tr>
    <tr><td>54725.8894</td><td>0.2</td><td>152</td><td>200.4</td><td>17.9</td><td>ANT0886</td></tr>
    <tr><td>56574.7303</td><td>0.3</td><td>153</td><td>105.2</td><td>-44.3</td><td>ANT5888</td></tr>
    <tr><td>54731.2417</td><td>0.1</td><td>155</td><td>281.1</td><td>-48.7</td><td>ANT0907</td></tr>
    <tr><td>56412.889</td><td>0.2</td><td>156</td><td>283.4</td><td>-57.1</td><td>ANT5655</td></tr>
    <tr><td>57998.9599</td><td>0.2</td><td>162</td><td>1.8</td><td>-64.0</td><td>ANT8518</td></tr>
    </table>



.. code:: ipython3

    scs = service.get_scs()
    coneevents = scs.search((20,30), 2) # get events for a 2 degree cone around given sky coordinates
    coneevents.to_table()




.. raw:: html

    <i>Table length=2</i>
    <table id="table139984557642224" class="table-striped table-bordered table-condensed">
    <thead><tr><th>_r</th><th>MJD</th><th>Beta</th><th>Nhit</th><th>RA</th><th>Decl</th><th>ID</th></tr></thead>
    <thead><tr><th>deg</th><th></th><th></th><th></th><th></th><th></th><th></th></tr></thead>
    <thead><tr><th>float64</th><th>float64</th><th>float64</th><th>int32</th><th>float64</th><th>float64</th><th>object</th></tr></thead>
    <tr><td>0.327663931770686</td><td>56195.5948</td><td>0.4</td><td>45</td><td>20.3</td><td>30.2</td><td>ANT5087</td></tr>
    <tr><td>1.56948430621669</td><td>55692.7303</td><td>0.3</td><td>62</td><td>18.7</td><td>31.1</td><td>ANT3659</td></tr>
    </table>



Access full table
-----------------

.. code:: ipython3

    fulltable = service.get_dataframe()

.. code:: ipython3

    plot = fulltable.beta.plot(kind = "hist")



.. image:: images/example_VOservices_0.png



.. only:: html

    .. container:: sphx-glr-download

        **Download python script:** :download:`example_VOservices.py`

        **Download Jupyter notebook:** :download:`example_VOservices.ipynb`