Switched from restructured text docs to numpydocs style.

First prototype of docs included!

docs/conf.py

@@ -12,9 +12,10 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../..'))
+#sys.path.insert(0, os.path.abspath('.'))
 import orcasong
 
 
@@ -45,7 +46,7 @@ extensions = [
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
     'sphinx.ext.autosummary',
-    'sphinx.ext.napoleon',
+    'numpydoc',
 ]
 
 autosummary_generate = True

orcasong/data_to_images.py

@@ -27,12 +27,17 @@ def parse_input(do2d, do2d_pdf):
     """
     Handles input exceptions, warnings and helps.
 
-    Args:
-        do2d (bool): Boolean flag for creation of 2D histograms.
-        do2d_pdf (tuple(bool, int)): Tuple with boolean flag for creation of 2D pdf images.
-
-    Returns:
-        fname (str): Parsed filename.
+    Parameters
+    ----------
+    do2d : bool
+        Boolean flag for creation of 2D histograms.
+    do2d_pdf : tuple(bool, int)
+        Tuple with boolean flag for creation of 2D pdf images.
+
+    Returns
+    -------
+    fname : str
+        A string containing the parsed filename.
 
     """
     if len(sys.argv) < 2 or str(sys.argv[1]) == "-h":
@@ -56,6 +61,7 @@ def parse_input(do2d, do2d_pdf):
 def calculate_bin_edges_test(geo, y_bin_edge, z_bin_edge):
     """
     Tests, if the bins in one direction don't accidentally have more than 'one' OM.
+
     For the x-direction, an overlapping can not be avoided in an orthogonal space.
     For y and z though, it can!
     For y, every bin should contain the number of lines per y-direction * 18 for 18 doms per line.
@@ -82,14 +88,26 @@ def calculate_bin_edges_test(geo, y_bin_edge, z_bin_edge):
 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.
-    :param (bool, str) do4d: Tuple that declares if 4D histograms should be created [0] and if yes, what should be used as the 4th dim after xyz.
-    :return: ndarray(ndim=1) x_bin_edges, y_bin_edges, z_bin_edges: contains the resulting bin edges for each dimension.
+    Parameters
+    ----------
+    n_bins : tuple
+        Contains the desired number of bins for each dimension, [n_bins_x, n_bins_y, n_bins_z].
+    det_geo : str
+        Declares what detector geometry should be used for the binning.
+    fname_geo_limits : str
+        Filepath of the .txt ORCA geometry file.
+    do4d : tuple(boo, str)
+        Tuple that declares if 4D histograms should be created [0] and if yes, what should be used as the 4th dim after xyz.
+
+    Returns
+    -------
+    x_bin_edges, y_bin_edges, z_bin_edges : ndarray(ndim=1)
+        The bin edges for the x,y,z direction.
+
     """
     print("Reading detector geometry in order to calculate the detector dimensions from file " + fname_geo_limits)
     geo = np.loadtxt(fname_geo_limits)
@@ -132,28 +150,42 @@ def main(n_bins, det_geo, do2d=False, do2d_pdf=(False, 10), do3d=False, do4d=(Tr
     """
     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.
-    :param (bool, int) do2d_pdf: Declares if pdf visualizations of the 2D histograms should be created. Cannot be called if do2d=False.
-                                 The event loop will be stopped after the integer specified in the second argument.
-    :param bool do3d: Declares if 3D histograms should be created.
-    :param (bool, str) do4d: Tuple that declares if 4D histograms should be created [0] and if yes, what should be used as the 4th dim after xyz.
-                             Currently, only 'time' and 'channel_id' are available.
-    :param int prod_ident: optional int identifier for the used mc production.
-                           This is e.g. useful, if you use events from two different mc productions, e.g. the 1-5GeV & 3-100GeV Orca 2016 MC.
-                           In this case, the events are not fully distinguishable with only the run_id and the event_id!
-                           In order to keep a separation, an integer can be set in the event_track for all events, such that they stay distinguishable.
-    :param (str, str/None) timecut: Tuple that defines what timecut should be used in hits_to_histograms.py.
-                                    Currently available:
-                                    ('timeslice_relative', None): Cuts out the central 30% of the snapshot.
-                                    ('trigger_cluster', 'all' / 'tight-1' / 'tight-2'): Cuts based on the mean of the triggered hits.
-                                    all: [-350ns, 850ns] -> 20ns / bin (60 bins)
-                                    tight-1: [-250ns, 500ns] -> 12.5ns / bin , tight-2: [-150ns, 200ns] -> 5.8ns / bin
-    :param bool do_mc_hits: Declares if hits (False, mc_hits + BG) or mc_hits (True) should be processed
-    :param bool use_calibrated_file: Declares if the input file is already calibrated (pos_x/y/z, time) or not.
-    :param dict data_cuts: Dictionary that contains information about any possible cuts that should be applied.
-                           Supports the following cuts: 'triggered', 'energy_lower_limit'
+    Parameters
+    ----------
+    n_bins : tuple of int
+        Declares the number of bins that should be used for each dimension, e.g. (x,y,z,t).
+    det_geo : str
+        Declares what detector geometry should be used for the binning. E.g. 'Orca_115l_23m_h_9m_v'.
+    do2d : bool
+        Declares if 2D histograms, 'images', should be created.
+    do2d_pdf : tuple(bool, int)
+        Declares if pdf visualizations of the 2D histograms should be created, cannot be called if do2d=False.
+        The event loop will be stopped after the integer specified in the second argument.
+    do3d : bool
+        Declares if 3D histograms should be created.
+    do4d : tuple(bool, str)
+        Tuple that declares if 4D histograms should be created [0] and if yes, what should be used as the 4th dim after xyz.
+        Currently, only 'time' and 'channel_id' are available.
+    prod_ident : int
+        Optional int identifier for the used mc production.
+        This is e.g. useful, if you use events from two different mc productions, e.g. the 1-5GeV & 3-100GeV Orca 2016 MC.
+        In this case, the events are not fully distinguishable with only the run_id and the event_id!
+        In order to keep a separation, an integer can be set in the event_track for all events, such that they stay distinguishable.
+    timecut : tuple(str, str/None)
+        Tuple that defines what timecut should be used in hits_to_histograms.py.
+        Currently available:
+        ('timeslice_relative', None): Cuts out the central 30% of the snapshot.
+        ('trigger_cluster', 'all' / 'tight-1' / 'tight-2'): Cuts based on the mean of the triggered hits.
+        all: [-350ns, 850ns] -> 20ns / bin (60 bins)
+        tight-1: [-250ns, 500ns] -> 12.5ns / bin , tight-2: [-150ns, 200ns] -> 5.8ns / bin
+    do_mc_hits : bool
+        Declares if hits (False, mc_hits + BG) or mc_hits (True) should be processed
+    use_calibrated_file : bool
+        Declares if the input file is already calibrated (pos_x/y/z, time) or not.
+    data_cuts : dict
+        Dictionary that contains information about any possible cuts that should be applied.
+        Supports the following cuts: 'triggered', 'energy_lower_limit'
+
     """
     if data_cuts is None: data_cuts={'triggered': False, 'energy_lower_limit': 0}
     np.random.seed(42) # set random seed

orcasong/file_to_hits.py

@@ -10,10 +10,19 @@ import numpy as np
 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.
+    Parameters
+    ----------
+    event_blob : kp.io.HDF5Pump.blob
+        HDF5Pump event blob.
+
+    Returns
+    -------
+    primary_index : int
+        Index of the primary track (=neutrino) in the 'McTracks' branch.
+
     """
     bjorken_y_array = event_blob['McTracks'].bjorkeny
     primary_index = np.where(bjorken_y_array != 0.0)[0][0]
@@ -23,13 +32,20 @@ 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 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:
+    Parameters
+    ----------
+    time_interaction : float
+        Time of the neutrino interaction measured in JTE time.
+    hits_time : ndarray(ndim=1)
+        Time of the event_hits measured in JTE time.
+    triggered : ndarray(ndim=1)
+        Array with trigger flags that specifies if the hit is triggered or not.
+
     """
+
     hits_time_triggered = hits_time[triggered == 1]
     t_mean_triggered = np.mean(hits_time_triggered, dtype=np.float64)
     time_residual_vertex = t_mean_triggered - time_interaction
@@ -39,23 +55,41 @@ def get_time_residual_nu_interaction_mean_triggered_hits(time_interaction, hits_
 
 def get_event_data(event_blob, geo, do_mc_hits, use_calibrated_file, data_cuts, do4d, prod_ident):
     """
-    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!
-    :param bool do_mc_hits: tells the function of the hits (mc_hits + BG) or the mc_hits only should be parsed.
-                            In the case of mc_hits, the dom_id needs to be calculated thanks to the jpp output.
-    :param bool use_calibrated_file: specifies if a calibrated file is used as an input for the event_blob.
-                                     If False, the hits of the event_blob are calibrated based on the geo parameter.
-    :param dict data_cuts: specifies if cuts should be applied. Contains the keys 'triggered' and 'energy_lower_limit'.
-    :param (bool, str) do4d: Tuple that declares if 4D histograms should be created [0] and if yes, what should be used as the 4th dim after xyz.
-                             In the case of 'channel_id', this information needs to be included in the event_hits as well.
-    :param int prod_ident: optional int that identifies the used production, more documentation in the docs of the main function.
-    :return: ndarray(ndim=2) event_hits: 2D array containing the hit information of the event [pos_xyz time (channel_id)].
-    :return: ndarray(ndim=1) event_track: 1D array containing important MC information of the event.
-                                          [event_id, particle_type, energy, isCC, bjorkeny, dir_x/y/z, time]
+    Reads a km3pipe blob which contains the information for one event and returns a hit array and a track array
+    that contains all relevant information of the event.
+
+    Parameters
+    ----------
+    event_blob : kp.io.HDF5Pump.blob
+        Event blob of the HDF5Pump which contains all information for one event.
+    geo : kp.Geometry
+        km3pipe Geometry instance that contains the geometry information of the detector.
+        Only used if the event_blob is from a non-calibrated file!
+    do_mc_hits : bool
+        Tells the function of the hits (mc_hits + BG) or the mc_hits only should be parsed.
+        In the case of mc_hits, the dom_id needs to be calculated thanks to the jpp output.
+    use_calibrated_file : bool
+        Specifies if a calibrated file is used as an input for the event_blob.
+        If False, the hits of the event_blob are calibrated based on the geo parameter.
+    data_cuts : dict
+        Specifies if cuts should be applied.
+        Contains the keys 'triggered' and 'energy_lower/upper_limit' and 'throw_away_prob'.
+    do4d : tuple(bool, str)
+        Tuple that declares if 4D histograms should be created [0] and if yes, what should be used as the 4th dim after xyz.
+        In the case of 'channel_id', this information needs to be included in the event_hits as well.
+    prod_ident : int
+        Optional int that identifies the used production, more documentation in the docs of the main function.
+
+    Returns
+    -------
+    event_hits : ndarray(ndim=2)
+        2D array containing the hit information of the event [pos_xyz, time, triggered, (channel_id)].
+
+    event_track : ndarray(ndim=1)
+        1D array containing important MC information of the event,
+        [event_id, particle_type, energy, is_cc, bjorkeny, dir_x, dir_y, dir_z, time_track, run_id,
+        vertex_pos_x, vertex_pos_y, vertex_pos_z, time_residual_vertex, (prod_ident)].
+
     """
     p = get_primary_track_index(event_blob)
 

orcasong/histograms_to_files.py

@@ -8,10 +8,17 @@ def store_histograms_as_hdf5(hists, mc_infos, filepath_output, compression=(None
     """
     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.
-    :param (None/str, None/int) compression: Tuple that specifies if a compression filter should be used. Either ('gzip', 1-9) or ('lzf', None).
+    Parameters
+    ----------
+    hists : ndarray(ndim=2)
+        Array that contains all histograms for a certain projection.
+    mc_infos : ndarray(ndim=2)
+        2D array containing important MC information for each event_id, [event_id, particle_type, energy, isCC, categorical event types].
+    filepath_output : str
+        Complete filepath of the to be created h5 file.
+    compression : tuple(None/str, None/int)
+        Tuple that specifies if a compression filter should be used. Either ('gzip', 1-9) or ('lzf', None).
+
     """
     f = h5py.File(filepath_output, 'w')
 
@@ -19,9 +26,9 @@ def store_histograms_as_hdf5(hists, mc_infos, filepath_output, compression=(None
     chunks_mc_infos = (32,) + mc_infos.shape[1:] if compression[0] is not None else None
     fletcher32 = True if compression[0] is not None else False
 
-    dset_hists = f.create_dataset('x', data=hists, dtype='uint8', fletcher32=fletcher32, chunks=chunks_hists,
-                                    compression=compression[0], compression_opts=compression[1], shuffle=False)
-    dset_mc_infos = f.create_dataset('y', data=mc_infos, dtype='float32', fletcher32=fletcher32, chunks=chunks_mc_infos,
-                                       compression=compression[0], compression_opts=compression[1], shuffle=False)
+    f.create_dataset('x', data=hists, dtype='uint8', fletcher32=fletcher32, chunks=chunks_hists,
+                     compression=compression[0], compression_opts=compression[1], shuffle=False)
+    f.create_dataset('y', data=mc_infos, dtype='float32', fletcher32=fletcher32, chunks=chunks_mc_infos,
+                     compression=compression[0], compression_opts=compression[1], shuffle=False)
 
     f.close()
\ No newline at end of file

orcasong/hits_to_histograms.py

@@ -14,14 +14,24 @@ from mpl_toolkits.axes_grid1 import make_axes_locatable
 def get_time_parameters(event_hits, mode=('trigger_cluster', 'all'), t_start_margin=0.15, t_end_margin=0.15):
     """
     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.
-    :param float t_end_margin: Used in timeslice_relative mode. Defines the end time of the selected timespan with t_mean + t_start * t_diff.
-    :return: float t_start, t_end: absolute start and end time that will be used for the later timespan cut.
-                                   Events in this timespan are accepted, others are rejected.
+
+    Later on, these parameters cut out a certain time span during an event specified by t_start and t_end.
+
+    Parameters
+    ----------
+    event_hits : ndarray(ndim=2)
+        2D array that contains the hits data for a certain event_id.
+    mode : tuple(str, str)
+        Type of time cut that is used. Currently available: timeslice_relative and trigger_cluster.
+    t_start_margin, t_end_margin : float
+        Used in timeslice_relative mode. Defines the start/end time of the selected timespan with t_mean -/+ t_start * t_diff.
+
+    Returns
+    -------
+    t_start, t_end : float
+        Absolute start and end time that will be used for the later timespan cut.
+        Events in this timespan are accepted, others are rejected.
+
     """
     t = event_hits[:, 3:4]
 
@@ -62,19 +72,28 @@ 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.
-    :param ndarray(ndim=1) z_bin_edges: bin edges for the Z-direction.
-    :param tuple n_bins: Contains the number of bins that should be used for each dimension (x,y,z,t).
-    :param list all_4d_to_2d_hists: contains all 2D histogram projections.
-    :param (str, str/None) timecut: Tuple that defines what timecut should be used in hits_to_histograms.py.
-    :param ndarray(ndim=2) event_track: contains the relevant mc_track info for the event in order to get a nice title for the pdf histos.
-    :param bool do2d_pdf: if True, generate 2D matplotlib pdf histograms.
-    :param PdfPages/None pdf_2d_plots: either a mpl PdfPages instance or None.
-    :return: appends the 2D histograms to the all_4d_to_2d_hists list.
+    Computes 2D numpy histogram 'images' from the 4D data and appends the 2D histograms to the all_4d_to_2d_hists list,
+    [xy, xz, yz, xt, yt, zt].
+
+    Parameters
+    ----------
+    event_hits : ndarray(ndim=2)
+        2D array that contains the hits data for a certain event_id.
+    x_bin_edges, y_bin_edges, z_bin_edges: ndarray(ndim=1)
+        Bin edges for the X/Y/Z-direction.
+    n_bins : tuple of int
+        Contains the number of bins that should be used for each dimension.
+    all_4d_to_2d_hists : list
+        List that contains all 2D histogram projections.
+    timecut : tuple(str, str/None)
+        Tuple that defines what timecut should be used in hits_to_histograms.
+    event_track : ndarray(ndim=2)
+        Contains the relevant mc_track info for the event in order to get a nice title for the pdf histos.
+    do2d_pdf : bool
+        If True, generate 2D matplotlib pdf histograms.
+    pdf_2d_plots : mpl.backends.backend_pdf.PdfPages/None
+        Either a mpl PdfPages instance or None.
+
     """
     x, y, z, t = event_hits[:, 0], event_hits[:, 1], event_hits[:, 2], event_hits[:, 3]
 
@@ -110,13 +129,19 @@ def convert_2d_numpy_hists_to_pdf_image(hists, t_start, t_end, pdf_2d_plots, eve
     """
     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.
-    :param PdfPages/None pdf_2d_plots: either a mpl PdfPages instance or None.
-    :param ndarray(ndim=2) event_track: contains the relevant mc_track info for the event in order to get a nice title for the pdf histos.
-                                        [event_id, particle_type, energy, isCC, bjorkeny, dir_x/y/z]
+    Parameters
+    ----------
+    hists : list(ndarray(ndim=2))
+        Contains np.histogram2d objects of all projections [xy, xz, yz, xt, yt, zt].
+    t_start, t_end : float
+        Absolute start/end time of the timespan cut.
+    pdf_2d_plots : mpl.backends.backend_pdf.PdfPages/None
+        Either a mpl PdfPages instance or None.
+    event_track : ndarray(ndim=2)
+        Contains the relevant mc_track info for the event in order to get a nice title for the pdf histos.
+
     """
+
     fig = plt.figure(figsize=(10, 13))
     if event_track is not None:
         particle_type = {16: 'Tau', -16: 'Anti-Tau', 14: 'Muon', -14: 'Anti-Muon', 12: 'Electron', -12: 'Anti-Electron', 'isCC': ['NC', 'CC']}
@@ -169,20 +194,28 @@ def convert_2d_numpy_hists_to_pdf_image(hists, t_start, t_end, pdf_2d_plots, eve
 
 def compute_4d_to_3d_histograms(event_hits, x_bin_edges, y_bin_edges, z_bin_edges, n_bins, all_4d_to_3d_hists, timecut):
     """
-    Computes 3D numpy histogram 'images' from the 4D data.
+    Computes 3D numpy histogram 'images' from the 4D data and appends the 3D histograms to the all_4d_to_3d_hists list,
+    [xyz, xyt, xzt, yzt, rzt].
+
     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.
-    :param ndarray(ndim=1) z_bin_edges: bin edges for the Z-direction.
-    :param tuple n_bins: Declares the number of bins that should be used for each dimension (x,y,z,t).
-    :param list all_4d_to_3d_hists: contains all 3D histogram projections.
-    :param (str, str/None) timecut: Tuple that defines what timecut should be used in hits_to_histograms.py.
-    :return: appends the 3D histograms to the all_4d_to_3d_hists list. [xyz, xyt, xzt, yzt, rzt]
+    Parameters
+    ----------
+    event_hits : ndarray(ndim=2)
+        2D array that contains the hits data for a certain event_id.
+    x_bin_edges, y_bin_edges, z_bin_edges : ndarray(ndim=2)
+        Bin edges for the X/Y/Z-direction.
+    n_bins : tuple of int
+        Contains the number of bins that should be used for each dimension.
+    all_4d_to_3d_hists : list
+        List that contains all 3D histogram projections.
+    timecut : tuple(str, str/None)
+        Tuple that defines what timecut should be used in hits_to_histograms.
+
     """
+
     x, y, z, t = event_hits[:, 0:1], event_hits[:, 1:2], event_hits[:, 2:3], event_hits[:, 3:4]
 
     t_start, t_end = get_time_parameters(event_hits, mode=timecut)
@@ -210,18 +243,25 @@ 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.
-    :param ndarray(ndim=1) z_bin_edges: bin edges for the Z-direction.
-    :param tuple n_bins: Declares the number of bins that should be used for each dimension (x,y,z,t).
-    :param list all_4d_to_4d_hists: contains all 4D histogram projections.
-    :param (str, str/None) timecut: Tuple that defines what timecut should be used in hits_to_histograms.py.
-    :param (bool, str) do4d: Tuple, where [1] declares what should be used as 4th dimension after xyz.
-                             Currently, only 'time' and 'channel_id' are available.
-    :return: appends the 4D histogram to the all_4d_to_4d_hists list. [xyzt]
+    Computes 4D numpy histogram 'images' from the 4D data and appends the 4D histogram to the all_4d_to_4d_hists list,
+    [xyzt / xyzc]
+
+    Parameters
+    ----------
+    event_hits : ndarray(ndim=2)
+        2D array that contains the hits data for a certain event_id.
+    x_bin_edges, y_bin_edges, z_bin_edges : ndarray(ndim=2)
+        Bin edges for the X/Y/Z-direction.
+    n_bins : tuple of int
+        Contains the number of bins that should be used for each dimension.
+    all_4d_to_4d_hists : list
+        List that contains all 4D histogram projections.
+    timecut : tuple(str, str/None)
+        Tuple that defines what timecut should be used in hits_to_histograms.
+    do4d : tuple(bool, str)
+        Tuple, where [1] declares what should be used as 4th dimension after xyz.
+        Currently, only 'time' and 'channel_id' are available.
+
     """
     t_start, t_end = get_time_parameters(event_hits, mode=timecut)