add dynamic doc files

examples/plot_offline_events.py

+"""
+Reading Offline events
+======================
+
+The following example shows how to access events data in an offline ROOT file, which is
+written by aanet software.
+
+Note: the offline file used here has MC offline data and was intentionaly reduced
+to 10 events.
+"""
+import km3io as ki
+
+#####################################################
+# First, pass a filename to the `OfflineReader` class to open the file.
+# Note that only some meta information is read into memory.
+
+r = ki.OfflineReader("samples/numucc.root")
+
+
+#####################################################
+# Accessing the file header
+# -------------------------
+# Note that not all file headers are supported, so don't be surprised if 
+# nothing is returned when the file header is called (this can happen if your file
+# was produced with old versions of aanet).
+
+h = r.header
+print(h)
+
+
+#####################################################
+# Accessing the events data
+# -------------------------
+# Note that not all data is loaded in memory (again), so printing
+# events will only return how many events were found in the file.
+
+print(r.events)
+
+
+#####################################################
+# to explore the events keys:
+
+keys = r.events.keys()
+print(keys)
+
+#####################################################
+# to access the number of hits associated with each event:
+
+n_hits = r.events.n_hits
+print(n_hits)
+
+#####################################################
+# to access the number of tracks associated with each event:
+
+n_tracks = r.events.n_tracks
+print(n_tracks)
+
+#####################################################
+# to access the number of mc hits associated with each event:
+
+n_mc_hits = r.events.n_mc_hits
+print(n_mc_hits)
+
+#####################################################
+# to access the number of mc tracks associated with each event:
+
+n_mc_tracks = r.events.n_mc_tracks
+print(n_mc_tracks)
+
+#####################################################
+# to access the overlays:
+
+overlays = r.events.overlays
+print(overlays)
+
+#####################################################
+# That's it! you can access any key of your interest in the events
+# keys in the exact same way.
+
+
+#####################################################
+# item selection in events data
+# -----------------------------
+# events can be selected as you would select an item from a numpy array.
+# for example, to select the mc_hits in event 0:
+
+print(r.events[0].mc_hits)
+
+#####################################################
+# or:
+
+print(r.events.mc_hits[0])
+
+
+#####################################################
+# slicing of events
+# -----------------
+# you can select a slice of events data. For example, to select the number
+# of mc hits in the first 5 events:
+
+print(r.events.n_mc_hits[0:5])
+
+#####################################################
+# or:
+
+print(r.events[0:5].n_mc_hits)
+
+
+#####################################################
+# you can apply masks to events data as you would do with numpy arrays.
+# For example, to select the number of hits higher than 50:
+
+mask = r.events.n_mc_hits > 50
+
+print(r.events.n_mc_hits[mask])
+
+#####################################################
+# or:
+
+print(r.events.n_mc_tracks[mask])
+
+

examples/plot_offline_hits.py

+"""
+Reading Offline hits
+====================
+
+The following example shows how to access hits data in an offline ROOT file, which is
+written by aanet software.
+
+Note: the offline file used here has MC offline data and was intentionaly reduced
+to 10 events.
+"""
+import km3io as ki
+
+#####################################################
+# To access offline hits/mc_hits data:
+
+mc_hits = ki.OfflineReader("samples/numucc.root").events.mc_hits
+hits = ki.OfflineReader("samples/aanet_v2.0.0.root").events.hits
+
+
+#####################################################
+# Note that not all data is loaded in memory, so printing
+# hits will only return how many elements (events) were found in
+# the hits branch of the file.
+
+print(hits)
+
+#####################################################
+# same for mc hits
+
+print(mc_hits)
+
+#####################################################
+# Accessing the hits/mc_hits keys
+# -------------------------------
+# to explore the hits keys:
+
+keys = hits.keys()
+print(keys)
+
+#####################################################
+# to explore the mc_hits keys:
+
+mc_keys = mc_hits.keys()
+print(mc_keys)
+
+#####################################################
+# Accessing hits data
+# -------------------------
+# to access data in dom_id:
+
+dom_ids = hits.dom_id
+print(dom_ids)
+
+#####################################################
+# to access the channel ids:
+
+channel_ids = hits.channel_id
+print(channel_ids)
+
+#####################################################
+# That's it! you can access any key of your interest in the hits
+# keys in the exact same way.
+
+#####################################################
+# Accessing the mc_hits data
+# --------------------------
+# similarly, you can access mc_hits data in any key of interest by 
+# following the same procedure as for hits:
+
+mc_pmt_ids = mc_hits.pmt_id
+print(mc_pmt_ids)
+
+
+#####################################################
+# to access the mc_hits time:
+mc_t = mc_hits.t
+print(mc_t)
+
+#####################################################
+# item selection in hits data
+# ---------------------------
+# hits data can be selected as you would select an item from a numpy array.
+# for example, to select DOM ids in the hits corresponding to the first event:
+
+print(hits[0].dom_id)
+
+#####################################################
+# or:
+
+print(hits.dom_id[0])
+
+#####################################################
+# slicing of hits
+# ---------------
+# to select a slice of hits data:
+
+print(hits[0:3].channel_id)
+
+#####################################################
+# or:
+
+print(hits.channel_id[0:3])
+
+#####################################################
+# you can apply masks to hits data as you would do with numpy arrays:
+
+mask = hits.channel_id > 10
+
+print(hits.channel_id[mask])
+
+#####################################################
+# or:
+
+print(hits.dom_id[mask])
\ No newline at end of file

examples/plot_offline_tracks.py

+"""
+Reading Offline tracks
+======================
+
+The following example shows how to access tracks data in an offline ROOT file, which is
+written by aanet software.
+
+Note: the offline files used here were intentionaly reduced to 10 events.
+"""
+import km3io as ki
+
+#####################################################
+# To access offline tracks/mc_tracks data:
+
+mc_tracks = ki.OfflineReader("samples/numucc.root").events.mc_tracks
+tracks = ki.OfflineReader("samples/aanet_v2.0.0.root").events.tracks
+
+
+#####################################################
+# Note that not all data is loaded in memory, so printing
+# tracks will only return how many elements (events) were found in
+# the tracks branch of the file.
+
+print(tracks)
+
+#####################################################
+# same for mc hits
+
+print(mc_tracks)
+
+#####################################################
+# Accessing the tracks/mc_tracks keys
+# -----------------------------------
+# to explore the tracks keys:
+
+keys = tracks.keys()
+print(keys)
+
+#####################################################
+# to explore the mc_tracks keys:
+
+mc_keys = mc_tracks.keys()
+print(mc_keys)
+
+#####################################################
+# Accessing tracks data
+# ---------------------
+# to access data in `E` (tracks energy):
+
+E = tracks.E
+print(E)
+
+#####################################################
+# to access the likelihood:
+
+likelihood = tracks.lik
+print(likelihood)
+
+#####################################################
+# That's it! you can access any key of your interest in the tracks
+# keys in the exact same way.
+
+#####################################################
+# Accessing the mc_tracks data
+# ----------------------------
+# similarly, you can access mc_tracks data in any key of interest by 
+# following the same procedure as for tracks:
+
+cos_zenith = mc_tracks.dir_z
+print(cos_zenith)
+
+
+#####################################################
+# or:
+
+dir_y = mc_tracks.dir_y
+print(dir_y)
+
+
+#####################################################
+# item selection in tracks data
+# -----------------------------
+# tracks data can be selected as you would select an item from a numpy array.
+# for example, to select E (energy) in the tracks corresponding to the first event:
+
+print(tracks[0].E)
+
+#####################################################
+# or:
+
+print(tracks.E[0])
+
+
+#####################################################
+# slicing of tracks
+# -----------------
+# to select a slice of tracks data:
+
+print(tracks[0:3].E)
+
+#####################################################
+# or:
+
+print(tracks.E[0:3])
+
+#####################################################
+# you can apply masks to tracks data as you would do with numpy arrays:
+
+mask = tracks.lik > 100
+
+print(tracks.lik[mask])
+
+#####################################################
+# or:
+
+print(tracks.dir_z[mask])
\ No newline at end of file

examples/plot_offline_usr.py

+"""
+Reading usr data of events
+==========================
+
+To access the ``usr`` data of events, use the ``.usr`` property which behaves
+like a dictionary and returns ``lazyarray``, compatible to the ``numpy.array``
+interface. The available keys can be accessed either as attributes or via a
+dictionary lookup:
+"""
+import km3io as ki
+
+#####################################################
+# First, pass a filename to the `OfflineReader` class to open the file.
+# Note that only some meta information is read into memory.
+
+r = ki.OfflineReader("samples/usr-sample.root")
+
+
+#####################################################
+# Accessing the usr data:
+
+usr = r.events.usr
+print(usr)
+
+
+#####################################################
+# to access data of a specific key, you can either do:
+
+print(usr.DeltaPosZ)
+
+
+#####################################################
+# or
+
+print(usr['RecoQuality'])

examples/plot_online_example.py

+"""
+Reading Online Data
+===================
+
+The following example shows how to access hits in a ROOT file which is coming
+from the detector and written by the `JDataWriter` application.
+
+Such a file is usually called "KM3NET_00000001_00000002.root", where the first
+number is the detector ID and the second the run number.
+"""
+import km3io as ki
+
+#####################################################
+# Accessing the event tree
+# ------------------------
+# Just pass a filename to the reader class and get access to the event tree
+# with:
+
+
+f = ki.OnlineReader("samples/daq_v1.0.0.root")
+
+#####################################################
+# Note that only some meta information is read into memory.
+#
+# Printing it will simply tell you how many events it has found. Again, nothing
+# else is read yet:
+
+print(f.events)
+
+#####################################################
+# Now let's look at the hits data:
+
+print(f.events[0].snapshot_hits.tot)
+
+#####################################################
+# the resulting arrays are numpy arrays.
+
+#####################################################
+# Reading SummarySlices
+# ---------------------
+# The following example shows how to access summary slices, in particular the DOM
+# IDs of the slice with the index 0:
+
+dom_ids = f.summaryslices.slices[0].dom_id
+
+print(dom_ids)
+
+#####################################################
+# The .dtype attribute (or in general, <TAB> completion) is useful to find out
+# more about the field structure:
+
+print(f.summaryslices.headers.dtype)
+
+#####################################################
+# To read the frame index:
+
+print(f.summaryslices.headers.frame_index)
+
+#####################################################
+# The resulting array is a ChunkedArray which is an extended version of a
+# numpy array and behaves like one.
+
+#####################################################
+# Reading TimeSlices
+# ------------------
+# To be continued.
+#
\ No newline at end of file