Merge branch 'master' of git.km3net.de:km3py/km3io

b12bc5e9 · Tamas Gal · a2168b95 · e7eb425b · b12bc5e9 · b12bc5e9
Commit b12bc5e9 authored 5 years ago by Tamas Gal
--- a/km3io/aanet.py
+++ b/km3io/aanet.py
@@ -2,16 +2,25 @@ import uproot


 class AanetReader:
+    """Reader for one Aanet ROOT file"""
    def __init__(self, file_path):
+        """ AanetReader class is a Aanet ROOT file wrapper
+
+        Parameters
+        ----------
+        file_path : path-like object
+            Path to the file of interest. It can be a str or any python
+            path-like object that points to the file of ineterst.
+        """
        self.file_path = file_path
        self.data = uproot.open(self.file_path)['E']
        self.lazy_data = self.data.lazyarrays()
-        self._valid_keys = None
+        self._events_keys = None
        self._hits_keys = None
        self._tracks_keys = None

-    def read_event(self, key: str):
-        """event_reader function reads data stored in a branch of interest in an event tree.
+    def __getitem__(self, key):
+        """reads data stored in the branch of interest in an event tree.

        Parameters
        ----------
@@ -21,111 +30,55 @@ class AanetReader:
        Returns
        -------
        lazyarray
-            Lazyarray of all data stored in a branch of interest (in an event tree). A lazyarray is an array-like
-            object that reads data on demand. Here, only the first and last chunks of data are
-            read in memory, and not all data in the array. The output of event_reader can be used
-            with all `Numpy's universal functions <https://docs.scipy.org/doc/numpy/reference/ufuncs.html>`.
+            Lazyarray of all data stored in the branch of interest. A lazyarray
+            is an array-like object that reads data on demand. Here, only the
+            first and last chunks of data are read in memory, and not all data
+            in the array. The output can be used with all `Numpy's universal
+            functions <https://docs.scipy.org/doc/numpy/reference/ufuncs.html>`
+            .

        Raises
        ------
-        NameError
-            Some branches in an Aanet file structure are "fake branches" and do not contain data. Therefore,
-            the keys corresponding to these fake branches are not read.
+        KeyEroor
+            Some branches in an Aanet file structure are "fake branches" and do
+            not contain data. Therefore, the keys corresponding to these fake
+            branches are not read.
        """
-        evt_tree = self.data['Evt']
-        evt_keys = self._event_keys(evt_tree)
-        if key in evt_keys:
-            evt_key_lazy = self.lazy_data[key]
-            return evt_key_lazy
-        else:
-            raise KeyError(
-                "{} could not be found or is a fake branch".format(key))
-
-    def read_hits(self, key: str):
-        """hits_reader function reads data stored in a branch of interest in hits tree from an Aanet
-        event file.
-
-        Parameters
-        ----------
-        hits_key : str
-            name of the branch of interest in hits tree.
+        if key not in self.keys() and not isinstance(key, int):
+            raise KeyError(f"'{key}' is not a valid key or is a fake branch.")
+        return self.lazy_data[key]

-        Returns
-        -------
-        lazyarray
-            Lazyarray of all data stored in a branch of interest (in hits tree). A lazyarray is an array-like
-            object that reads data on demand. Here, only the first and last chunks of data are
-            read in memory, and not all data in the array. The output of event_reader can be used
-            with all `Numpy's universal functions <https://docs.scipy.org/doc/numpy/reference/ufuncs.html>`.
-
-        Raises
-        ------
-        NameError
-            the hits.key stored in an Aanet file must be used to access the branch of interest
-            from hits tree data.
-        """
-        hits_tree = self.data['Evt']['hits']
-        keys = [key.decode('utf8') for key in hits_tree.keys()]
-        if key in keys:
-            hits_key_lazy = self.lazy_data[key]
-            return hits_key_lazy
-        else:
-            raise KeyError("{} is not a valid hits key".format(key))
+    def __len__(self):
+        return len(self.lazy_data)

-    def read_tracks(self, key: str):
-        """tracks_reader function reads data stored in a branch of interest in tracks tree
-        from an Aanet event file.
+    def __repr__(self):
+        return '\n'.join([
+            f"Number of events: {self.__len__()}",
+            "Events keys are:\n\t" + '\n\t'.join(self.events_keys),
+            "Hits keys are:\n\t" + '\n\t'.join(self.hits_keys),
+            "Tracks keys are:\n\t" + '\n\t'.join(self.tracks_keys)
+        ])

-        Parameters
-        ----------
-        tracks_key : str
-            name of the branch of interest in tracks tree.
+    def keys(self):
+        """constructs a list of all valid keys to be read from an Aanet event file.

        Returns
        -------
-        lazyarray
-            Lazyarray of all data stored in a branch of interest (in tracks tree). A lazyarray is an array-like
-            object that reads data on demand. Here, only the first and last chunks of data are
-            read in memory, and not all data in the array. The output of event_reader can be used
-            with all `Numpy's universal functions <https://docs.scipy.org/doc/numpy/reference/ufuncs.html>`.
-
-        Raises
-        ------
-        NameError
-            the trks.key stored in an Aanet file must be used to access the branch of interest
-            from tracks tree data.
+        list
+            list of all valid keys.
        """
-        tracks_tree = self.data['Evt']['trks']
-        keys = [key.decode('utf8') for key in tracks_tree.keys()]
-        if key in keys:
-            tracks_key_lazy = self.lazy_data[key]
-            return tracks_key_lazy
-        else:
-            raise KeyError("{} is not a valid tracks key".format(key))
+        return self.events_keys + self.hits_keys + self.tracks_keys

    @property
-    def valid_keys(self, evt_tree):
-        """_event_keys function returns a list of all the keys of interest
-            for data analysis, and removes the keys of empty "fake branches"
-            found in Aanet event files.
-
-        Parameters
-        ----------
-        evt_tree : aanet event (Evt) tree.
-
-        Returns
-        -------
-        list of str
-            list of all the event keys.
-        """
-        if self._valid_keys is None:
+    def events_keys(self):
+        if self._events_keys is None:
            fake_branches = ['Evt', 'AAObject', 'TObject', 't']
            t_baskets = ['t.fSec', 't.fNanoSec']
-            self._valid_keys = [
-                key.decode('utf-8') for key in evt_tree.keys()
+            self._events_keys = [
+                key.decode('utf-8') for key in self.data['Evt'].keys()
                if key.decode('utf-8') not in fake_branches
            ] + t_baskets
-        return self._valid_keys
+        return self._events_keys

    @property
    def hits_keys(self):

--- a/notebooks/AanetReader_tutorial.ipynb
+++ b/notebooks/AanetReader_tutorial.ipynb
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "['/home/zineb/km3net/km3net/km3io/notebooks', '/home/zineb/miniconda3/envs/km3pipe/lib/python37.zip', '/home/zineb/miniconda3/envs/km3pipe/lib/python3.7', '/home/zineb/miniconda3/envs/km3pipe/lib/python3.7/lib-dynload', '', '/home/zineb/miniconda3/envs/km3pipe/lib/python3.7/site-packages', '/home/zineb/miniconda3/envs/km3pipe/lib/python3.7/site-packages/IPython/extensions', '/home/zineb/.ipython', '/home/zineb/km3net/km3net/km3io']\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Add file to current python path\n",
+    "from pathlib import Path\n",
+    "import sys\n",
+    "sys.path.append(str(Path.cwd().parent))\n",
+    "Path.cwd()\n",
+    "print(sys.path)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from km3io import AanetReader"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# test samples directory - aanet test file\n",
+    "files_path = Path.cwd().parent / 'tests/samples' \n",
+    "aanet_file = files_path / 'aanet_v2.0.0.root'"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "Number of events: 10\n",
+       "Events keys are:\n",
+       "\tid\n",
+       "\tdet_id\n",
+       "\tmc_id\n",
+       "\trun_id\n",
+       "\tmc_run_id\n",
+       "\tframe_index\n",
+       "\ttrigger_mask\n",
+       "\ttrigger_counter\n",
+       "\toverlays\n",
+       "\thits\n",
+       "\ttrks\n",
+       "\tw\n",
+       "\tw2list\n",
+       "\tw3list\n",
+       "\tmc_t\n",
+       "\tmc_hits\n",
+       "\tmc_trks\n",
+       "\tcomment\n",
+       "\tindex\n",
+       "\tflags\n",
+       "\tt.fSec\n",
+       "\tt.fNanoSec\n",
+       "Hits keys are:\n",
+       "\thits.id\n",
+       "\thits.dom_id\n",
+       "\thits.channel_id\n",
+       "\thits.tdc\n",
+       "\thits.tot\n",
+       "\thits.trig\n",
+       "\thits.pmt_id\n",
+       "\thits.t\n",
+       "\thits.a\n",
+       "\thits.pos.x\n",
+       "\thits.pos.y\n",
+       "\thits.pos.z\n",
+       "\thits.dir.x\n",
+       "\thits.dir.y\n",
+       "\thits.dir.z\n",
+       "\thits.pure_t\n",
+       "\thits.pure_a\n",
+       "\thits.type\n",
+       "\thits.origin\n",
+       "\thits.pattern_flags\n",
+       "Tracks keys are:\n",
+       "\ttrks.fUniqueID\n",
+       "\ttrks.fBits\n",
+       "\ttrks.usr_data\n",
+       "\ttrks.usr_names\n",
+       "\ttrks.id\n",
+       "\ttrks.pos.x\n",
+       "\ttrks.pos.y\n",
+       "\ttrks.pos.z\n",
+       "\ttrks.dir.x\n",
+       "\ttrks.dir.y\n",
+       "\ttrks.dir.z\n",
+       "\ttrks.t\n",
+       "\ttrks.E\n",
+       "\ttrks.len\n",
+       "\ttrks.lik\n",
+       "\ttrks.type\n",
+       "\ttrks.rec_type\n",
+       "\ttrks.rec_stages\n",
+       "\ttrks.status\n",
+       "\ttrks.mother_id\n",
+       "\ttrks.fitinf\n",
+       "\ttrks.hit_ids\n",
+       "\ttrks.error_matrix\n",
+       "\ttrks.comment"
+      ]
+     },
+     "execution_count": 4,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "reader = AanetReader(aanet_file)\n",
+    "reader"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "<Table [<Row 0> <Row 1> <Row 2> ... <Row 7> <Row 8> <Row 9>] at 0x7f9011f02b50>"
+      ]
+     },
+     "execution_count": 5,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# big lazyarray with ALL file data!\n",
+    "lazy_data = reader.lazy_data\n",
+    "lazy_data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "5971"
+      ]
+     },
+     "execution_count": 6,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# getting the run_id for a specific event (event 5 for example)\n",
+    "reader[5]['run_id']"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "60"
+      ]
+     },
+     "execution_count": 7,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# one can check how many hits are in event 5\n",
+    "reader[5]['hits']"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "56"
+      ]
+     },
+     "execution_count": 8,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# one can also check how many tracks are in event 5\n",
+    "reader[5]['trks']"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "\"'whatever' is not a valid key or is a fake branch.\"\n"
+     ]
+    }
+   ],
+   "source": [
+    "# the user is reminded to always specify the \"correct\" event/hits/tracks \n",
+    "# key in the Aanet event file\n",
+    "try:\n",
+    "    reader['whatever']\n",
+    "except KeyError as e:\n",
+    "    print(e)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Now let's explore in more details the hits:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "<ChunkedArray [[806451572 806451572 806451572 ... 809544061 809544061 809544061] [806451572 806451572 806451572 ... 809524432 809526097 809544061] [806451572 806451572 806451572 ... 809544061 809544061 809544061] ... [806451572 806455814 806465101 ... 809526097 809544058 809544061] [806455814 806455814 806455814 ... 809544061 809544061 809544061] [806455814 806455814 806455814 ... 809544058 809544058 809544061]] at 0x7f9011eb3b10>"
+      ]
+     },
+     "execution_count": 10,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# reading all data from a specific branch in hits data: for example \n",
+    "# 'hits.dom_id'\n",
+    "reader['hits.dom_id']"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 11,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "array([806455814, 806487219, 806487219, 806487219, 806487226, 808432835,\n",
+       "       808432835, 808432835, 808432835, 808432835, 808432835, 808432835,\n",
+       "       808451904, 808451904, 808451907, 808451907, 808469129, 808469129,\n",
+       "       808469129, 808493910, 808949744, 808949744, 808951460, 808951460,\n",
+       "       808956908, 808961655, 808964908, 808969848, 808969857, 808972593,\n",
+       "       808972593, 808972598, 808972598, 808972698, 808972698, 808974758,\n",
+       "       808974811, 808976377, 808981510, 808981523, 808981812, 808982005,\n",
+       "       808982005, 808982018, 808982077, 808982077, 808982547, 809007627,\n",
+       "       809521500, 809521500, 809521500, 809524432, 809526097, 809526097,\n",
+       "       809526097, 809526097, 809526097, 809526097, 809526097, 809544058],\n",
+       "      dtype=int32)"
+      ]
+     },
+     "execution_count": 11,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# the user can access hits.dom_id data for a specific event (for example \n",
+    "# event 5)\n",
+    "reader['hits.dom_id'][5]"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 12,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "60"
+      ]
+     },
+     "execution_count": 12,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# We previsouly checked (using reader[5]['hits']) that event\n",
+    "# 5 has 60 hits, now we can see that reader['hits.dom_id'][5]\n",
+    "# has exaclty 60 dom ids as well! \n",
+    "len(reader['hits.dom_id'][5])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 13,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "806455814"
+      ]
+     },
+     "execution_count": 13,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# one can access a dom id of the first hit \n",
+    "reader['hits.dom_id'][5][0]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Now let's explore in more details the tracks:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 14,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "<ChunkedArray [[-0.872885221293917 -0.872885221293917 -0.872885221293917 ... -0.6631226836266504 -0.5680647731737454 -0.5680647731737454] [-0.8351996698137462 -0.8351996698137462 -0.8351996698137462 ... -0.7485107718446855 -0.8229838871876581 -0.239315690284641] [-0.989148723802379 -0.989148723802379 -0.989148723802379 ... -0.9350162572437829 -0.88545604390297 -0.88545604390297] ... [-0.5704611045902105 -0.5704611045902105 -0.5704611045902105 ... -0.9350162572437829 -0.4647231989130516 -0.4647231989130516] [-0.9779941383490359 -0.9779941383490359 -0.9779941383490359 ... -0.88545604390297 -0.88545604390297 -0.8229838871876581] [-0.7396916780974963 -0.7396916780974963 -0.7396916780974963 ... -0.6631226836266504 -0.7485107718446855 -0.7485107718446855]] at 0x7f9011ebdf10>"
+      ]
+     },
+     "execution_count": 14,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# reading all data from a specific branch in tracks data:\n",
+    "reader['trks.dir.z']"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 15,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "array([-0.60246049, -0.60246049, -0.60246049, -0.51420541, -0.5475772 ,\n",
+       "       -0.5772408 , -0.56068238, -0.64907684, -0.67781799, -0.66565114,\n",
+       "       -0.63014839, -0.64566464, -0.62691012, -0.58465493, -0.59287533,\n",
+       "       -0.63655091, -0.63771247, -0.73446841, -0.7456636 , -0.70941246,\n",
+       "       -0.66312268, -0.66312268, -0.56806477, -0.56806477, -0.66312268,\n",
+       "       -0.66312268, -0.74851077, -0.74851077, -0.66312268, -0.74851077,\n",
+       "       -0.56806477, -0.74851077, -0.66312268, -0.74851077, -0.56806477,\n",
+       "       -0.66312268, -0.56806477, -0.66312268, -0.56806477, -0.56806477,\n",
+       "       -0.66312268, -0.74851077, -0.66312268, -0.93501626, -0.56806477,\n",
+       "       -0.74851077, -0.66312268, -0.56806477, -0.82298389, -0.74851077,\n",
+       "       -0.66312268, -0.56806477, -0.82298389, -0.56806477, -0.66312268,\n",
+       "       -0.97094183])"
+      ]
+     },
+     "execution_count": 15,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# the user can access trks.dir.z data for a specific event (for example \n",
+    "# event 5)\n",
+    "reader['trks.dir.z'][5]"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 16,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "56"
+      ]
+     },
+     "execution_count": 16,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# We previsouly checked (using reader[5]['trks']) that event\n",
+    "# 5 has 56 tracks, now we can see that reader['trks.dir.z'][5]\n",
+    "# has exaclty 56 values of trks.dir.z as well! \n",
+    "len(reader['trks.dir.z'][5])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 17,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "-0.6024604933159441"
+      ]
+     },
+     "execution_count": 17,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# one can access the first trks.dir.z from event 5 using \n",
+    "reader['trks.dir.z'][5][0]"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.7.4"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
+%% Cell type:code id: tags:
+
+``` python
+# Add file to current python path
+from pathlib import Path
+import sys
+sys.path.append(str(Path.cwd().parent))
+Path.cwd()
+print(sys.path)
+```
+
+%% Output
+
+    ['/home/zineb/km3net/km3net/km3io/notebooks', '/home/zineb/miniconda3/envs/km3pipe/lib/python37.zip', '/home/zineb/miniconda3/envs/km3pipe/lib/python3.7', '/home/zineb/miniconda3/envs/km3pipe/lib/python3.7/lib-dynload', '', '/home/zineb/miniconda3/envs/km3pipe/lib/python3.7/site-packages', '/home/zineb/miniconda3/envs/km3pipe/lib/python3.7/site-packages/IPython/extensions', '/home/zineb/.ipython', '/home/zineb/km3net/km3net/km3io']
+
+%% Cell type:code id: tags:
+
+``` python
+from km3io import AanetReader
+```
+
+%% Cell type:code id: tags:
+
+``` python
+# test samples directory - aanet test file
+files_path = Path.cwd().parent / 'tests/samples'
+aanet_file = files_path / 'aanet_v2.0.0.root'
+```
+
+%% Cell type:code id: tags:
+
+``` python
+reader = AanetReader(aanet_file)
+reader
+```
+
+%% Output
+
+    Number of events: 10
+    Events keys are:
+    	id
+    	det_id
+    	mc_id
+    	run_id
+    	mc_run_id
+    	frame_index
+    	trigger_mask
+    	trigger_counter
+    	overlays
+    	hits
+    	trks
+    	w
+    	w2list
+    	w3list
+    	mc_t
+    	mc_hits
+    	mc_trks
+    	comment
+    	index
+    	flags
+    	t.fSec
+    	t.fNanoSec
+    Hits keys are:
+    	hits.id
+    	hits.dom_id
+    	hits.channel_id
+    	hits.tdc
+    	hits.tot
+    	hits.trig
+    	hits.pmt_id
+    	hits.t
+    	hits.a
+    	hits.pos.x
+    	hits.pos.y
+    	hits.pos.z
+    	hits.dir.x
+    	hits.dir.y
+    	hits.dir.z
+    	hits.pure_t
+    	hits.pure_a
+    	hits.type
+    	hits.origin
+    	hits.pattern_flags
+    Tracks keys are:
+    	trks.fUniqueID
+    	trks.fBits
+    	trks.usr_data
+    	trks.usr_names
+    	trks.id
+    	trks.pos.x
+    	trks.pos.y
+    	trks.pos.z
+    	trks.dir.x
+    	trks.dir.y
+    	trks.dir.z
+    	trks.t
+    	trks.E
+    	trks.len
+    	trks.lik
+    	trks.type
+    	trks.rec_type
+    	trks.rec_stages
+    	trks.status
+    	trks.mother_id
+    	trks.fitinf
+    	trks.hit_ids
+    	trks.error_matrix
+    	trks.comment
+
+%% Cell type:code id: tags:
+
+``` python
+# big lazyarray with ALL file data!
+lazy_data = reader.lazy_data
+lazy_data
+```
+
+%% Output
+
+    <Table [<Row 0> <Row 1> <Row 2> ... <Row 7> <Row 8> <Row 9>] at 0x7f9011f02b50>
+
+%% Cell type:code id: tags:
+
+``` python
+# getting the run_id for a specific event (event 5 for example)
+reader[5]['run_id']
+```
+
+%% Output
+
+    5971
+
+%% Cell type:code id: tags:
+
+``` python
+# one can check how many hits are in event 5
+reader[5]['hits']
+```
+
+%% Output
+
+    60
+
+%% Cell type:code id: tags:
+
+``` python
+# one can also check how many tracks are in event 5
+reader[5]['trks']
+```
+
+%% Output
+
+    56
+
+%% Cell type:code id: tags:
+
+``` python
+# the user is reminded to always specify the "correct" event/hits/tracks
+# key in the Aanet event file
+try:
+    reader['whatever']
+except KeyError as e:
+    print(e)
+```
+
+%% Output
+
+    "'whatever' is not a valid key or is a fake branch."
+
+%% Cell type:markdown id: tags:
+
+# Now let's explore in more details the hits:
+
+%% Cell type:code id: tags:
+
+``` python
+# reading all data from a specific branch in hits data: for example
+# 'hits.dom_id'
+reader['hits.dom_id']
+```
+
+%% Output
+
+    <ChunkedArray [[806451572 806451572 806451572 ... 809544061 809544061 809544061] [806451572 806451572 806451572 ... 809524432 809526097 809544061] [806451572 806451572 806451572 ... 809544061 809544061 809544061] ... [806451572 806455814 806465101 ... 809526097 809544058 809544061] [806455814 806455814 806455814 ... 809544061 809544061 809544061] [806455814 806455814 806455814 ... 809544058 809544058 809544061]] at 0x7f9011eb3b10>
+
+%% Cell type:code id: tags:
+
+``` python
+# the user can access hits.dom_id data for a specific event (for example
+# event 5)
+reader['hits.dom_id'][5]
+```
+
+%% Output
+
+    array([806455814, 806487219, 806487219, 806487219, 806487226, 808432835,
+           808432835, 808432835, 808432835, 808432835, 808432835, 808432835,
+           808451904, 808451904, 808451907, 808451907, 808469129, 808469129,
+           808469129, 808493910, 808949744, 808949744, 808951460, 808951460,
+           808956908, 808961655, 808964908, 808969848, 808969857, 808972593,
+           808972593, 808972598, 808972598, 808972698, 808972698, 808974758,
+           808974811, 808976377, 808981510, 808981523, 808981812, 808982005,
+           808982005, 808982018, 808982077, 808982077, 808982547, 809007627,
+           809521500, 809521500, 809521500, 809524432, 809526097, 809526097,
+           809526097, 809526097, 809526097, 809526097, 809526097, 809544058],
+          dtype=int32)
+
+%% Cell type:code id: tags:
+
+``` python
+# We previsouly checked (using reader[5]['hits']) that event
+# 5 has 60 hits, now we can see that reader['hits.dom_id'][5]
+# has exaclty 60 dom ids as well!
+len(reader['hits.dom_id'][5])
+```
+
+%% Output
+
+    60
+
+%% Cell type:code id: tags:
+
+``` python
+# one can access a dom id of the first hit
+reader['hits.dom_id'][5][0]
+```
+
+%% Output
+
+    806455814
+
+%% Cell type:markdown id: tags:
+
+# Now let's explore in more details the tracks:
+
+%% Cell type:code id: tags:
+
+``` python
+# reading all data from a specific branch in tracks data:
+reader['trks.dir.z']
+```
+
+%% Output
+
+    <ChunkedArray [[-0.872885221293917 -0.872885221293917 -0.872885221293917 ... -0.6631226836266504 -0.5680647731737454 -0.5680647731737454] [-0.8351996698137462 -0.8351996698137462 -0.8351996698137462 ... -0.7485107718446855 -0.8229838871876581 -0.239315690284641] [-0.989148723802379 -0.989148723802379 -0.989148723802379 ... -0.9350162572437829 -0.88545604390297 -0.88545604390297] ... [-0.5704611045902105 -0.5704611045902105 -0.5704611045902105 ... -0.9350162572437829 -0.4647231989130516 -0.4647231989130516] [-0.9779941383490359 -0.9779941383490359 -0.9779941383490359 ... -0.88545604390297 -0.88545604390297 -0.8229838871876581] [-0.7396916780974963 -0.7396916780974963 -0.7396916780974963 ... -0.6631226836266504 -0.7485107718446855 -0.7485107718446855]] at 0x7f9011ebdf10>
+
+%% Cell type:code id: tags:
+
+``` python
+# the user can access trks.dir.z data for a specific event (for example
+# event 5)
+reader['trks.dir.z'][5]
+```
+
+%% Output
+
+    array([-0.60246049, -0.60246049, -0.60246049, -0.51420541, -0.5475772 ,
+           -0.5772408 , -0.56068238, -0.64907684, -0.67781799, -0.66565114,
+           -0.63014839, -0.64566464, -0.62691012, -0.58465493, -0.59287533,
+           -0.63655091, -0.63771247, -0.73446841, -0.7456636 , -0.70941246,
+           -0.66312268, -0.66312268, -0.56806477, -0.56806477, -0.66312268,
+           -0.66312268, -0.74851077, -0.74851077, -0.66312268, -0.74851077,
+           -0.56806477, -0.74851077, -0.66312268, -0.74851077, -0.56806477,
+           -0.66312268, -0.56806477, -0.66312268, -0.56806477, -0.56806477,
+           -0.66312268, -0.74851077, -0.66312268, -0.93501626, -0.56806477,
+           -0.74851077, -0.66312268, -0.56806477, -0.82298389, -0.74851077,
+           -0.66312268, -0.56806477, -0.82298389, -0.56806477, -0.66312268,
+           -0.97094183])
+
+%% Cell type:code id: tags:
+
+``` python
+# We previsouly checked (using reader[5]['trks']) that event
+# 5 has 56 tracks, now we can see that reader['trks.dir.z'][5]
+# has exaclty 56 values of trks.dir.z as well!
+len(reader['trks.dir.z'][5])
+```
+
+%% Output
+
+    56
+
+%% Cell type:code id: tags:
+
+``` python
+# one can access the first trks.dir.z from event 5 using
+reader['trks.dir.z'][5][0]
+```
+
+%% Output
+
+    -0.6024604933159441
--- a/notebooks/DataReader_tutorial.ipynb
+++ b/notebooks/DataReader_tutorial.ipynb