.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_examples/plot_calibrating_hits.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_auto_examples_plot_calibrating_hits.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_auto_examples_plot_calibrating_hits.py:


==================
Calibrating Hits
==================

Hits stored in ROOT and HDF5 files are usually not calibrated, which
means that they have invalid positions, directions and uncorrected hit times.
This example shows how to assign the PMT position and direction to each hit
and applying a time correction to them.

The KM3NeT offline format (derived from aanet) uses a single class for every
hit type (regular hits, MC hits and their correspeonding calibrated and
uncalibrated counter parts). In ROOT files, the actual struct/class definition
is stored along the data, which means that all the attributes are accessible
even when they are invalid or not instantiated. Positions and directions are
also part of these attributes and they are initialised to `(0, 0, 0)`.

The `km3pipe.calib.Calibration()` class can be used to load a calibration and
the `.apply()` method to update the position, direction and correct the arrival
time of hit.

.. GENERATED FROM PYTHON SOURCE LINES 26-34

.. code-block:: Python


    # Author: Tamas Gal <tgal@km3net.de>
    # License: BSD-3

    import km3pipe as kp
    import km3io
    from km3net_testdata import data_path








.. GENERATED FROM PYTHON SOURCE LINES 35-36

The `offline/km3net_offline.root` contains 10 events with hit information:

.. GENERATED FROM PYTHON SOURCE LINES 36-39

.. code-block:: Python


    f = km3io.OfflineReader(data_path("offline/km3net_offline.root"))








.. GENERATED FROM PYTHON SOURCE LINES 40-41

The corresponding calibration file is stored in `detx/km3net_offline.detx`:

.. GENERATED FROM PYTHON SOURCE LINES 41-44

.. code-block:: Python


    calib = kp.calib.Calibration(filename=data_path("detx/km3net_offline.detx"))





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Detector: Parsing the DETX header
    Detector: Reading PMT information...
    Detector: Done.




.. GENERATED FROM PYTHON SOURCE LINES 45-46

Let's grab the hits of the event with index `5`:

.. GENERATED FROM PYTHON SOURCE LINES 46-49

.. code-block:: Python


    hits = f.events[5].hits








.. GENERATED FROM PYTHON SOURCE LINES 50-54

The positions (pos_x, pos_y, pos_z) and directions (dir_x, dir_y, dir_z) are
not available for uncalibrated hits, in contrast to aanet where each field
is present and initialised to some magic value (e.g. 0). km3io hides all
those fields and do not occupy additional memory for those.

.. GENERATED FROM PYTHON SOURCE LINES 56-57

Here are the uncalibrated times:

.. GENERATED FROM PYTHON SOURCE LINES 57-63

.. code-block:: Python


    n = 7  # just an arbitrary number to limit the output
    uncalibrated_times = hits.t
    print(uncalibrated_times[:n])






.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    [8.19e+07, 8.19e+07, 8.19e+07, 8.19e+07, 8.19e+07, 8.19e+07, 8.19e+07]




.. GENERATED FROM PYTHON SOURCE LINES 64-67

To calibrate the hits, use the `calib.apply()` method which will create a
`km3pipe.Table`, retrieve the positions and directions of the corresponding
PMTs, apply the time calibration and also do the PMT time slew correction.

.. GENERATED FROM PYTHON SOURCE LINES 67-70

.. code-block:: Python


    calibrated_hits = calib.apply(hits)








.. GENERATED FROM PYTHON SOURCE LINES 71-73

The calibrated hits are stored in a `kp.Table` which is a thin wrapper
around a `numpy.record` array (a simple numpy array with named attributes):

.. GENERATED FROM PYTHON SOURCE LINES 73-77

.. code-block:: Python


    print(calibrated_hits.dtype)






.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    (numpy.record, [('channel_id', '<u4'), ('dir_x', '<f8'), ('dir_y', '<f8'), ('dir_z', '<f8'), ('dom_id', '<i4'), ('du', 'u1'), ('floor', 'u1'), ('pmt_id', '<i4'), ('pos_x', '<f8'), ('pos_y', '<f8'), ('pos_z', '<f8'), ('t0', '<f8'), ('time', '<f8'), ('tot', '<u4'), ('triggered', '<i4')])




.. GENERATED FROM PYTHON SOURCE LINES 78-80

The positions and directions are now showing the correct values and the time
is the calibrated one:

.. GENERATED FROM PYTHON SOURCE LINES 80-86

.. code-block:: Python


    for attr in [f"{k}_{q}" for k in ("pos", "dir") for q in "xzy"]:
        print(attr, getattr(calibrated_hits, attr)[:n])

    print(calibrated_hits.time[:n])





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    pos_x [  9.486  -2.2    -2.366  -2.368  -2.037 -13.339 -13.503]
    pos_z [116.027 182.901 183.212 183.16  106.456 192.881 192.881]
    pos_y [ 5.779 -9.6   -9.604 -9.509 -9.5    6.754  6.73 ]
    dir_x [-0.57   0.    -0.832 -0.838  0.816  0.304 -0.518]
    dir_z [-0.555 -1.     0.555  0.295  0.295  0.555  0.555]
    dir_y [-0.606 -0.    -0.02   0.458  0.497  0.774  0.651]
    [82069045.722      82067743.25       82068723.247      82069201.96800001
     82068064.22299999 82068657.47600001 82068658.204     ]




.. GENERATED FROM PYTHON SOURCE LINES 87-89

The `t0` field holds the time calibration correction which was automatically
added to hit time (`hit.time`):

.. GENERATED FROM PYTHON SOURCE LINES 89-93

.. code-block:: Python


    print(calibrated_hits.t0[:n])






.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    [207808.962 208135.32  208137.147 208140.038 207706.953 208031.076
     208033.454]




.. GENERATED FROM PYTHON SOURCE LINES 94-99

As mentioned above, the PMT time slewing correction is also applied, which
is a tiny correction of the arrival time with respect to the hit's ToT value.
We can reveal their values by subtracting the t0 from the calibrated time and
compare to the uncalibrated ones. Notice that hits represented as `kp.Table`
in km3pipe use `.time` instead of `.t` for mainly historical reasons:

.. GENERATED FROM PYTHON SOURCE LINES 99-103

.. code-block:: Python


    slews = uncalibrated_times - (calibrated_hits.time - calibrated_hits.t0)
    print(slews[:n])





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    [0.24, 0.07, -0.1, 0.07, -0.27, 0.6, 3.25]




.. GENERATED FROM PYTHON SOURCE LINES 104-106

Let's compare the slews with the ones calculated with `kp.calib.slew()`. The
values match very well, with tiny variations due to floating point arithmetic:

.. GENERATED FROM PYTHON SOURCE LINES 106-110

.. code-block:: Python


    slew_diff = slews - kp.calib.slew(hits.tot)
    print(slew_diff[:n])





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    [-5.36e-09, -7.15e-09, 5.96e-09, -7.15e-09, 4.17e-09, -5.96e-09, 0]




.. GENERATED FROM PYTHON SOURCE LINES 111-113

To omit the PMT slew calibration, you can pass the `correct_slewing=False`
option the `.apply()`:

.. GENERATED FROM PYTHON SOURCE LINES 113-116

.. code-block:: Python


    calibrated_hits_no_slew_correction = calib.apply(hits, correct_slewing=False)








.. GENERATED FROM PYTHON SOURCE LINES 117-119

The difference between the calibration with and without slewing is obviously
the slewing correction itself:

.. GENERATED FROM PYTHON SOURCE LINES 119-121

.. code-block:: Python


    print((calibrated_hits_no_slew_correction.time - calibrated_hits.time)[:n])




.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    [ 0.23999999  0.06999999 -0.09999999  0.06999999 -0.27        0.59999999
      3.25      ]





.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 2.387 seconds)


.. _sphx_glr_download_auto_examples_plot_calibrating_hits.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: plot_calibrating_hits.ipynb <plot_calibrating_hits.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: plot_calibrating_hits.py <plot_calibrating_hits.py>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_