Merge branch 'add-header' into 'master'

Add header readout for offline files. Closes #13

Closes #13

See merge request !10

README.rst

@@ -140,12 +140,59 @@ First, let's read our file:
 .. code-block:: python3
 
   >>> import km3io as ki
-  >>> file = 'datav6.0test.jchain.aanet.00005971.root'
+  >>> file = 'my_file.root'
   >>> r = ki.OfflineReader(file)
-  <km3io.aanet.OfflineReader at 0x7f24cc2bd550>
+  <km3io.offline.OfflineReader at 0x7f24cc2bd550>
 
 and that's it! Note that `file` can be either an str of your file path, or a path-like object. 
 
+To read the file header:
+
+.. code-block:: python3
+
+    >>> r.header
+    DAQ             394
+    PDF             4      58
+    XSecFile        
+    can             0 1027 888.4
+    can_user        0.00 1027.00  888.40
+    coord_origin    0 0 0
+    cut_in          0 0 0 0
+    cut_nu          100 1e+08 -1 1
+    cut_primary     0 0 0 0
+    cut_seamuon     0 0 0 0
+    decay           doesnt happen
+    detector        NOT
+    drawing         Volume
+    end_event       
+    genhencut       2000 0
+    genvol          0 1027 888.4 2.649e+09 100000
+    kcut            2
+    livetime        0 0
+    model           1       2       0       1      12
+    muon_desc_file  
+    ngen            0.1000E+06
+    norma           0 0
+    nuflux          0       3       0 0.500E+00 0.000E+00 0.100E+01 0.300E+01
+    physics         GENHEN 7.2-220514 181116 1138
+    seed            GENHEN 3  305765867         0         0
+    simul           JSirene 11012 11/17/18 07
+    sourcemode      diffuse
+    spectrum        -1.4
+    start_run       1
+    target          isoscalar
+    usedetfile      false
+    xlat_user       0.63297
+    xparam          OFF
+    zed_user        0.00 3450.00
+
+**Note:** not all file header types are supported, so don't be surprised when you get the following warning
+
+.. code-block:: python3
+
+    /home/zineb/km3net/km3net/km3io/km3io/offline.py:341: UserWarning: Your file header has an unsupported format
+    warnings.warn("Your file header has an unsupported format")
+
 To explore all the available branches in our offline file: 
 
 .. code-block:: python3

km3io/offline.py

 import uproot
+import warnings
 
 # 110 MB based on the size of the largest basket found so far in km3net
 BASKET_CACHE_SIZE = 110 * 1024**2
@@ -319,6 +320,7 @@ class OfflineReader:
         self._mc_hits = None
         self._mc_tracks = None
         self._keys = None
+        self._header = None
 
     def __getitem__(self, item):
         return OfflineReader(file_path=self._file_path, data=self._data[item])
@@ -326,6 +328,20 @@ class OfflineReader:
     def __len__(self):
         return len(self._data)
 
+    @property
+    def header(self):
+        if self._header is None:
+            fobj = uproot.open(self._file_path)
+            if b'Head;1' in fobj.keys():
+                self._header = {}
+                for n, x in fobj['Head']._map_3c_string_2c_string_3e_.items():
+                    print("{:15s} {}".format(n.decode("utf-8"), x.decode("utf-8")))
+                    self._header[n.decode("utf-8")] = x.decode("utf-8")
+            if b'Header;1' in fobj.keys():
+                warnings.warn("Your file header has an unsupported format")
+        return self._header
+
+
     @property
     def keys(self):
         """wrapper for all keys in an offline file.

requirements.txt

 docopt
 numba
-uproot>=3.10.12
+uproot>=3.11.1
 setuptools_scm

tests/test_offline.py

@@ -132,6 +132,17 @@ class TestOfflineReader(unittest.TestCase):
         # check that there are 10 events
         self.assertEqual(Nevents, self.Nevents)
 
+    def test_reading_header(self):
+        # head is the supported format
+        head = OfflineReader(OFFLINE_NUMUCC).header
+
+        self.assertEqual(float(head['DAQ']), 394)
+        self.assertEqual(float(head['kcut']), 2)
+
+        # test the warning for unsupported fheader format
+        self.assertWarns(UserWarning, self.r.header,
+                         "Your file header has an unsupported format")
+
 
 class TestOfflineEvents(unittest.TestCase):
     def setUp(self):