Dataclasses
===========

Data can be loaded from the data center through the KM3Store calling it by its identifier

.. code-block:: python

    from openkm3.store import KM3Store
    store = KM3Store()
    km3object = store.get(identifier)

This returns a `KM3Object` (or derivative thereof), if the identifier actually points to a resource.

Exploring the data object
-------------------------

For each KM3Object, you can call

.. code-block:: python

    data = km3object.data
    km3object.show_metadata()
    
This will desplay the available metadata from the resource, while the `data` attribute hold the actual data, which varies from datatype to datatype.

Using data by datatype
----------------------

Which data is returned depends on the 'ktype' attribute in the resource metadata. For each type, additional functions to handle the data are made available according to the specific scientific needs. For a full list, see the API reference.

Data from the Virtual Observatory server
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Astrophysics data of KM3NeT is provided through the `VO server <http://vo.km3net.de>`_. 

A `Simple Cone Search (SCS) <https://www.ivoa.net/documents/cover/ConeSearch-20080222.html>`_ service offered through the VO by KM3NeT usually holds a list of neutrino event candidates. They can be queried through the SCS protocol or using TAP.

.. code-block:: python

    service = store.get("ana20_01_vo")
    tap = service.get_tap()
    highEevents = tap.search("SELECT * FROM ant20_01.main WHERE nhit>150")
    
    scs = service.get_scs()
    coneevents = scs.search((20,30), 2)

The return objects can be handled using pyvo functions.

Supplementary functions and services
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Derivates from simulation or complex data processing like lookup tables or parameterized distributions are essential to interpreting the data. The return objects here are generally based on numpy and pandas. Information on the parameters of the objects can be retrieved by calling :code:`km3object.show_paraminfo()`.

They include a lookup table, e.g. for a given zenith angle and spectral index,

.. code-block:: python

    acceptance = store.get("ana20_01_acc") # lookup table, 
    acc_value = acceptance.lookup(xvalue = 80, yvalue = 2.0)

or a polynomial function, e.g. to estimate the number of background events for a given declination band.

.. code-block:: python

    bkgfunction = store.get("ana20_01_bkg")
    number_bkground = bkg.evaluate(20)
    
KM3NeT event files
~~~~~~~~~~~~~~~~~~

KM3NeT event tables are (apart from being offered through the VO services where relevant for astrophysics) provided as HDF5 or FITS tables.

Acoustic data 
~~~~~~~~~~~~~

Acoustic data is offered as mp3 or wave files, together with psd-files which contain statistical properties of the recorded audio channel. Direct access in python in possible using the wave module for wave files, and pandas Dataframes for the statistics summaries.

.. code-block:: python

    psd = store.get("acoustic20_01_psd_DOM_808974724_CH1_1601366233")
    df = psd.get_dataframe()

    wave = store.get("acoustic20_01_wav_DOM_808974724_CH1_1601366233")
    df = wave.get_dataframe(endframe = 13476645, startframe = 10000000)