- Include first online docs

doc/conf.py → docs/conf.py

@@ -44,8 +44,11 @@ extensions = [
     'sphinx.ext.todo',
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
+    'sphinx.ext.autosummary',
 ]
 
+autosummary_generate = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

doc/index.rst → docs/index.rst

@@ -9,6 +9,7 @@ Welcome to OrcaSong's documentation!
    :maxdepth: 2
    :caption: Contents:
 
+   api
 
 
 Indices and tables

orcasong/h5_data_to_h5_input.py → orcasong/data_to_images.py

 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
-"""This main code takes raw simulated .hdf5 files as input in order to generate 2D/3D histograms ('images') that can be used for CNNs."""
+"""Main OrcaSong code which takes raw simulated .h5 files as input in order to generate 2D/3D/4D histograms ('images') that can be used for CNNs."""
 
 import os
 import sys
@@ -26,9 +26,12 @@ __status__ = 'Prototype'
 def parse_input(do2d, do2d_pdf):
     """
     Handles input exceptions, warnings and helps.
+
     :param bool do2d: Boolean flag for creation of 2D histograms.
-    :param (bool, int) do2d_pdf: Boolean flag for creation of 2D pdf images.
-    :return: str fname: Parsed filename.
+    :param do2d_pdf: Boolean flag for creation of 2D pdf images.
+    :type do2d_pdf: tuple(bool, int)
+    :rtype: str
+    :return: fname: Parsed filename.
     """
     if len(sys.argv) < 2 or str(sys.argv[1]) == "-h":
         print("Usage: python " + str(sys.argv[0]) + " file.h5")
@@ -79,6 +82,7 @@ def calculate_bin_edges(n_bins, det_geo, fname_geo_limits, do4d):
     Calculates the bin edges for the corresponding detector geometry (1 DOM/bin) based on the number of specified bins.
     Used later on for making the event "images" with the in the np.histogramdd funcs in hits_to_histograms.py.
     The bin edges are necessary in order to get the same bin size for each event regardless of the fact if all bins have a hit or not.
+
     :param tuple n_bins: contains the desired number of bins for each dimension. [n_bins_x, n_bins_y, n_bins_z]
     :param str det_geo: declares what detector geometry should be used for the binning.
     :param str fname_geo_limits: filepath of the .txt ORCA geometry file.
@@ -124,7 +128,8 @@ def calculate_bin_edges(n_bins, det_geo, fname_geo_limits, do4d):
 def main(n_bins, det_geo, do2d=False, do2d_pdf=(False, 10), do3d=False, do4d=(True, 'time'), prod_ident=None,
          timecut=('trigger_cluster', 'tight_1'), do_mc_hits=False, use_calibrated_file=False, data_cuts=None):
     """
-    Main code. Reads raw .hdf5 files and creates 2D/3D histogram projections that can be used for a CNN
+    Main code. Reads raw .hdf5 files and creates 2D/3D histogram projections that can be used for a CNN.
+
     :param tuple(int) n_bins: Declares the number of bins that should be used for each dimension (x,y,z,t).
     :param str det_geo: declares what detector geometry should be used for the binning. E.g. 'Orca_115l_23m_h_9m_v'.
     :param bool do2d: Declares if 2D histograms should be created.

orcasong/file_to_hits.py

 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
-"""This utility code contains functions that read the raw MC .h5 files"""
+"""Code that reads the h5 simulation files and extracts the necessary information for making event images."""
 
 import numpy as np
 #from memory_profiler import profile
@@ -11,6 +11,7 @@ def get_primary_track_index(event_blob):
     """
     Gets the index of the primary (neutrino) track.
     Uses bjorkeny in order to get the primary track, since bjorkeny!=0 for the initial interacting neutrino.
+
     :param kp.io.HDF5Pump.blob event_blob: HDF5Pump event blob.
     :return: int primary index: Index of the primary track (=neutrino) in the 'McTracks' branch.
     """
@@ -21,10 +22,12 @@ def get_primary_track_index(event_blob):
 
 def get_time_residual_nu_interaction_mean_triggered_hits(time_interaction, hits_time, triggered):
     """
+    Gets the time_residual of the event with respect to mean time of the triggered hits.
+    This is required for vertex_time reconstruction, as the absolute time scale needs to be relative to the triggered hits.
 
-    :param time_interaction:
-    :param hits_time:
-    :param triggered:
+    :param float time_interaction: time of the neutrino interaction measured in JTE time.
+    :param ndarray(ndim=1) hits_time: time of the event_hits measured in JTE time.
+    :param ndarray(ndim=1) triggered: array with trigger flags that specifies if the hit is triggered or not.
     :return:
     """
     hits_time_triggered = hits_time[triggered == 1]
@@ -38,6 +41,7 @@ def get_event_data(event_blob, geo, do_mc_hits, use_calibrated_file, data_cuts,
     """
     Reads a km3pipe blob which contains the information for one event.
     Returns a hit array and a track array that contains all relevant information of the event.
+
     :param kp.io.HDF5Pump.blob event_blob: Event blob of the HDF5Pump which contains all information for one event.
     :param kp.Geometry geo: km3pipe Geometry instance that contains the geometry information of the detector.
                             Only used if the event_blob is from a non-calibrated file!

orcasong/histograms_to_files.py

 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
-"""This utility code contains functions that save the histograms (generated by hits_to_histograms) to .h5 files"""
+"""Code that saves the histograms (generated by hits_to_histograms) and the mc event_info to a h5 file"""
 
 import h5py
 
 def store_histograms_as_hdf5(hists, mc_infos, filepath_output, compression=(None, None)):
     """
-    Takes numpy histograms ('images') for a certain projection as well as the mc_info ('tracks') and saves them to a h5 file. 
+    Takes numpy histograms ('images') for a certain projection as well as the mc_info ('tracks') and saves them to a h5 file.
+
     :param ndarray(ndim=2) hists: array that contains all histograms for a certain projection.
     :param ndarray(ndim=2) mc_infos: 2D array containing important MC information for each event_id. [event_id, particle_type, energy, isCC, categorical event types]
     :param str filepath_output: complete filepath of the created h5 file.

orcasong/hits_to_histograms.py

 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
-"""This utility code contains functions that computes 2D/3D histograms based on the file_to_hits.py output"""
+"""Code for computeing 2D/3D/4D histograms ("images") based on the event_hits hit pattern of the file_to_hits.py output"""
 
 import matplotlib as mpl
 mpl.use('Agg')
@@ -15,6 +15,7 @@ def get_time_parameters(event_hits, mode=('trigger_cluster', 'all'), t_start_mar
     """
     Gets the fundamental time parameters in one place for cutting a time residual.
     Later on these parameters cut out a certain time span of events specified by t_start and t_end.
+
     :param ndarray(ndim=2) event_hits: 2D array that contains the hits (_xyzt) data for a certain eventID. [positions_xyz, time, triggered]
     :param tuple(str, str) mode: type of time cut that is used. Currently available: timeslice_relative and first_triggered.
     :param float t_start_margin: Used in timeslice_relative mode. Defines the start time of the selected timespan with t_mean - t_start * t_diff.
@@ -62,6 +63,7 @@ def get_time_parameters(event_hits, mode=('trigger_cluster', 'all'), t_start_mar
 def compute_4d_to_2d_histograms(event_hits, x_bin_edges, y_bin_edges, z_bin_edges, n_bins, all_4d_to_2d_hists, timecut, event_track, do2d_pdf, pdf_2d_plots):
     """
     Computes 2D numpy histogram 'images' from the 4D data.
+
     :param ndarray(ndim=2) event_hits: 2D array that contains the hits (_xyzt) data for a certain eventID. [positions_xyz, time, triggered]
     :param ndarray(ndim=1) x_bin_edges: bin edges for the X-direction.
     :param ndarray(ndim=1) y_bin_edges: bin edges for the Y-direction.
@@ -107,6 +109,7 @@ def compute_4d_to_2d_histograms(event_hits, x_bin_edges, y_bin_edges, z_bin_edge
 def convert_2d_numpy_hists_to_pdf_image(hists, t_start, t_end, pdf_2d_plots, event_track=None):
     """
     Creates matplotlib 2D histos based on the numpy histogram2D objects and saves them to a pdf file.
+
     :param list(ndarray(ndim=2)) hists: Contains np.histogram2d objects of all projections [xy, xz, yz, xt, yt, zt].
     :param float t_start: absolute start time of the timespan cut.
     :param float t_end: absolute end time of the timespan cut.
@@ -170,6 +173,7 @@ def compute_4d_to_3d_histograms(event_hits, x_bin_edges, y_bin_edges, z_bin_edge
     Careful: Currently, appending to all_4d_to_3d_hists takes quite a lot of memory (about 200MB for 3500 events).
     In the future, the list should be changed to a numpy ndarray.
     (Which unfortunately would make the code less readable, since an array is needed for each projection...)
+
     :param ndarray(ndim=2) event_hits: 2D array that contains the hits (_xyzt) data for a certain eventID. [positions_xyz, time, triggered]
     :param ndarray(ndim=1) x_bin_edges: bin edges for the X-direction. 
     :param ndarray(ndim=1) y_bin_edges: bin edges for the Y-direction.
@@ -207,6 +211,7 @@ def compute_4d_to_3d_histograms(event_hits, x_bin_edges, y_bin_edges, z_bin_edge
 def compute_4d_to_4d_histograms(event_hits, x_bin_edges, y_bin_edges, z_bin_edges, n_bins, all_4d_to_4d_hists, timecut, do4d):
     """
     Computes 4D numpy histogram 'images' from the 4D data.
+
     :param ndarray(ndim=2) event_hits: 2D array that contains the hits (_xyzt) data for a certain eventID. [positions_xyz, time, triggered, (channel_id)]
     :param ndarray(ndim=1) x_bin_edges: bin edges for the X-direction.
     :param ndarray(ndim=1) y_bin_edges: bin edges for the Y-direction.