Documentation / poetry improvements and fixes

NuRadioMC/simulation/simulation.py

@@ -595,8 +595,9 @@ def build_dummy_event(station_id, det, config):
     config : dict
         The NuRadioMC configuration dictionary (from the yaml file)
 
-    Returns:
-        object: The built event object.
+    Returns
+    -------
+    object: The built event object.
     """
 
     evt = NuRadioReco.framework.event.Event(0, 0)
@@ -869,8 +870,8 @@ def group_into_events(station, event_group, particle_mode, split_event_time_diff
     """
     Group the signals from a station into multiple events based on signal arrival times.
 
-    Parameters:
-    -----------
+    Parameters
+    ----------
     station : NuRadioReco.framework.station.Station
         The station object containing the signals.
     event_group : NuRadioMC.framework.event.Event
@@ -882,8 +883,8 @@ def group_into_events(station, event_group, particle_mode, split_event_time_diff
     zerosignal : bool, optional
         Flag indicating whether to zero out the signals. Default is False.
 
-    Returns:
-    --------
+    Returns
+    -------
     events : list of NuRadioReco.framework.event.Event
         The list of events created from the grouped signals.
     """

NuRadioReco/detector/RNO_G/db_mongo_read.py

@@ -1,3 +1,18 @@
+"""
+Interface to the MongoDB that contains RNO-G hardware and calibration information
+
+The :mod:`NuRadioReco.detector.RNO_G.db_mongo_read` module and the `Database` class herein mostly serve as the
+backend of the `NuRadioReco.detector.RNO_G.rnog_detector.Detector` class. Most users
+will want to use that class to obtain information about deployed RNO-G stations and hardware.
+`NuRadioReco.detector.RNO_G.rnog_detector.Detector` class has an interface similar to that of
+other detector descriptions in NuRadioMC, and is documented there.
+
+However, for some specific use cases (e.g. finding measurements for individual hardware components
+that have not been deployed to the field), one can use the `Database` class directly, using the
+`Database.get_component_data` method.
+
+"""
+
 import six
 import os
 import urllib.parse
@@ -720,7 +735,38 @@ def get_channel_signal_chain_measurement(self, station_id=None, channel_id=None,
 
 
     def get_component_data(self, component_type, component_id, supplementary_info, primary_time, verbose=True, sparameter='S21'):
-        """ returns the current primary measurement of the component, reads in the component collection"""
+        """
+        returns the current primary measurement of the component, reads in the component collection
+
+        Returns a single measurement (e.g. gain of an IGLU)
+
+        Examples
+        --------
+
+        .. code-block::
+
+            import NuRadioReco.detector.RNO_G.db_mongo_read
+            import datetime
+
+            db = NuRadioReco.detector.RNO_G.db_mongo_read.Database()
+
+            # gives you the entry in the database
+            database_entry = db.get_component_data(
+                component_type='iglu_board',
+                component_id='C0069',
+                supplementary_info={}, # if you want a DRAB you have to specify the channel: {'channel_id':0}
+                verbose=True,
+                sparameter='S21', # you can also read the other S parameters
+                primary_time=datetime.datetime.now())
+
+
+            # extract the gain + phase data
+            y_axis_units = database_entry['y-axis_units']
+            frequencies = database_entry['frequencies']
+            gain_data = database_entry['mag']
+            phase_data = database_entry['phase']
+
+        """
 
         # define a search filter
         search_filter = [{'$match': {'name': component_id}}, {'$unwind': '$measurements'}, {'$match': {}}]

NuRadioReco/framework/base_station.py

@@ -101,7 +101,11 @@ def set_station_time(self, time, format=None):
 
     def get_station_time(self, format='isot'):
         """
-        Returns a astropy.time.Time object
+        Returns the station time as an astropy.time.Time object
+
+        The station time corresponds to the absolute time at which the event
+        starts, i.e. all times in Channel, Trigger and ElectricField objects
+        are measured relative to this time.
 
         Parameters
         ----------
@@ -112,7 +116,7 @@ def get_station_time(self, format='isot'):
         Returns
         -------
 
-        _station_time: astropy.time.Time
+        station_time: astropy.time.Time
         """
         if self._station_time is None:
             return None

NuRadioReco/framework/trigger.py

@@ -103,7 +103,19 @@ def set_trigger_time(self, time):
 
     def get_trigger_time(self):
         """
-        get the trigger time (absolute time with respect to the beginning of the event)
+        Get the trigger time.
+
+        Returns trigger time, i.e. the first time in the event where the trigger condition was fulfilled.
+        This is defined relative to the `station_time <NuRadioReco.framework.station.Station.get_station_time>`.
+
+        Returns
+        -------
+        trigger_time : float
+            The trigger time
+
+        See Also
+        --------
+        get_trigger_times : function to return all times where the trigger condition was fulfilled
         """
         return self._trigger_time
 
@@ -119,7 +131,25 @@ def set_trigger_times(self, times):
 
     def get_trigger_times(self):
         """
-        get the trigger times (time with respect to beginning of trace)
+        Get the trigger times
+
+        For some triggers, in addition to the time of the first trigger,
+        also all subsequent times where the trigger condition were fulfilled are
+        stored. For triggers that do not store this information, this method
+        is equivalent to `get_trigger_time` with the exception that it returns
+        an array (of shape (1,)) instead of a scalar.
+        Note that the trigger times are defined relative to the
+        `station_time <NuRadioReco.framework.station.Station.get_station_time>`.
+
+
+        Returns
+        -------
+        trigger_times : np.ndarray
+            Array of all times where the trigger condition was satisfied
+
+        See Also
+        --------
+        get_trigger_time : method to return the (first) trigger time
         """
         if self._trigger_times is None and not np.isnan(self._trigger_time):
             return np.array(self._trigger_time)
@@ -231,6 +261,12 @@ def __init__(self, name, threshold, channels=None, number_of_coincidences=1,
             default: 1
         channel_coincidence_window: float or None (default)
             the coincidence time between triggers of different channels
+        pre_trigger_times: float or dict of floats
+            the time before the trigger time that should be read out
+            if a dict is given, the keys are the channel_ids, and the value is the pre_trigger_time between the
+            start of the trace and the trigger time.
+            if only a float is given, the same pre_trigger_time is used for all channels
+
         """
         Trigger.__init__(self, name, channels, 'simple_threshold', pre_trigger_times=pre_trigger_times)
         self._threshold = threshold
@@ -269,6 +305,12 @@ def __init__(self, name, threshold_factor, power_mean, power_std,
         output_passband: (float, float) tuple
             Frequencies for a 6th-order Butterworth filter to be applied after
             the diode filtering.
+        pre_trigger_times: float or dict of floats
+            the time before the trigger time that should be read out
+            if a dict is given, the keys are the channel_ids, and the value is the pre_trigger_time between the
+            start of the trace and the trigger time.
+            if only a float is given, the same pre_trigger_time is used for all channels
+
         """
         Trigger.__init__(self, name, triggered_channels, 'envelope_phased', pre_trigger_times=pre_trigger_times)
         self._triggered_channels = triggered_channels
@@ -318,6 +360,12 @@ def __init__(self, name, threshold, channels=None, secondary_channels=None,
             the size of the stride between calculating the phasing (units of ADC time ticks)
         maximum_amps: list of floats (length equal to that of `phasing_angles`)
             the maximum value of all the integration windows for each of the phased waveforms
+        pre_trigger_times: float or dict of floats
+            the time before the trigger time that should be read out
+            if a dict is given, the keys are the channel_ids, and the value is the pre_trigger_time between the
+            start of the trace and the trigger time.
+            if only a float is given, the same pre_trigger_time is used for all channels
+
         """
         Trigger.__init__(self, name, channels, 'simple_phased', pre_trigger_times=pre_trigger_times)
         self._primary_channels = channels
@@ -357,6 +405,12 @@ def __init__(self, name, threshold_high, threshold_low, high_low_window,
         number_of_coincidences: int
             the number of channels that need to fulfill the trigger condition
             default: 1
+        pre_trigger_times: float or dict of floats
+            the time before the trigger time that should be read out
+            if a dict is given, the keys are the channel_ids, and the value is the pre_trigger_time between the
+            start of the trace and the trigger time.
+            if only a float is given, the same pre_trigger_time is used for all channels
+
         """
         Trigger.__init__(self, name, channels, 'high_low', pre_trigger_times=pre_trigger_times)
         self._number_of_coincidences = number_of_coincidences
@@ -387,6 +441,12 @@ def __init__(self, name, threshold, channel_coincidence_window, channels=None, n
         number_of_coincidences: int
             the number of channels that need to fulfill the trigger condition
             default: 1
+        pre_trigger_times: float or dict of floats
+            the time before the trigger time that should be read out
+            if a dict is given, the keys are the channel_ids, and the value is the pre_trigger_time between the
+            start of the trace and the trigger time.
+            if only a float is given, the same pre_trigger_time is used for all channels
+
         """
         Trigger.__init__(self, name, channels, 'int_power', pre_trigger_times=pre_trigger_times)
         self._number_of_coincidences = number_of_coincidences
@@ -422,6 +482,12 @@ def __init__(self, name, passband, order, threshold, number_of_coincidences=2,
             default: 1
         channel_coincidence_window: float or None (default)
             the coincidence time between triggers of different channels
+        pre_trigger_times: float or dict of floats
+            the time before the trigger time that should be read out
+            if a dict is given, the keys are the channel_ids, and the value is the pre_trigger_time between the
+            start of the trace and the trigger time.
+            if only a float is given, the same pre_trigger_time is used for all channels
+
         """
         Trigger.__init__(self, name, channels, 'envelope_trigger', pre_trigger_times=pre_trigger_times)
         self._passband = passband
@@ -433,7 +499,8 @@ def __init__(self, name, passband, order, threshold, number_of_coincidences=2,
 class RNOGSurfaceTrigger(Trigger):
     from NuRadioReco.utilities import units
     def __init__(self, name, threshold, number_of_coincidences=1,
-                 channel_coincidence_window=60*units.ns, channels=[13, 16, 19], temperature=250*units.kelvin, Vbias=2*units.volt, pre_trigger_times=55 * units.ns):
+                 channel_coincidence_window=60*units.ns, channels=[13, 16, 19],
+                 temperature=250*units.kelvin, Vbias=2*units.volt, pre_trigger_times=55 * units.ns):
         """
         initialize trigger class
 
@@ -455,6 +522,12 @@ def __init__(self, name, threshold, number_of_coincidences=1,
             temperature of the trigger board
         Vbias: float
             bias voltage on the trigger board
+        pre_trigger_times: float or dict of floats
+            the time before the trigger time that should be read out
+            if a dict is given, the keys are the channel_ids, and the value is the pre_trigger_time between the
+            start of the trace and the trigger time.
+            if only a float is given, the same pre_trigger_time is used for all channels
+
         """
         Trigger.__init__(self, name, channels, 'rnog_surface_trigger', pre_trigger_times=pre_trigger_times)
         self._threshold = threshold

NuRadioReco/modules/io/RNO_G/readRNOGDataMattak.py

@@ -213,8 +213,11 @@ def __init__(self, run_table_path=None, load_run_table=True, log_level=logging.N
                         self.logger.warn("No connect to RunTable database could be established. "
                                         "Runs can not be filtered.")
                 except ImportError:
-                    self.logger.warn("Import of run table failed. Runs can not be filtered.! \n"
-                            "You can get the interface from GitHub: [email protected]:RNO-G/rnog-runtable.git")
+                    self.logger.warn(
+                        "import run_table failed. You can still use readRNOGData, but runs can not be filtered. "
+                        "To install the run table, run\n\n"
+                        "\tpip install git+ssh://[email protected]/RNO-G/rnog-runtable.git\n"
+                    )
             else:
                 # some users may mistakenly try to pass the .root files to __init__
                 # we check for this and raise a (hopefully) helpful error message

NuRadioReco/utilities/variableWindowSizeCorrelation.py

@@ -55,8 +55,10 @@ def run(self, dataTrace, templateTrace, window_size, sampling_rate=3.2*units.GHz
             if true, the time difference (for the maximal correlation value) between the starting of the data trace and the starting of the (cut) template trace is returned (returned time is in units.ns)
 
         Returns
-        ----------
-        correlation (time_diff)
+        -------
+        correlation : array of floats
+        time_diff : float, optional
+            The time difference of the maximal correlation value. Returned only if ``return_time_difference==True``
         """
         if self.__debug:
             start = timeit.default_timer()

documentation/make_docs.py

@@ -105,7 +105,7 @@
             logger.info("excluding modules: {}".format(exclude_modules))
             subprocess.run(
                 [
-                    'sphinx-apidoc', '-efMT', '--ext-autodoc', '--ext-intersphinx',
+                    'sphinx-apidoc', '-efMT', '-d', '1', '--ext-autodoc', '--ext-intersphinx',
                     '--ext-coverage', '--ext-githubpages', '-o', output_folder,
                     module_path, *exclude_modules
                 ], stdout=pipe_stdout

documentation/source/Introduction/pages/contributing.rst

@@ -174,17 +174,17 @@ Dependencies are also maintained in ``pyproject.toml``. To update the dependenci
   under ``[tool.poetry.dependencies]``. Acceptable version specifications are ``"4.1.1"`` (4.1.1 only),
   ``">=4.1.1"`` (4.1.1 or greater), or ``"*"`` (any version). Please do not use poetry-specific version
   specifiers like ``^`` or ``~``.
-* If you are adding an **optional** dependency, add your dependency under ``[tool.poetry.dev-dependencies]``.
+* If you are adding an **optional** dependency, you can specify this by adding ``optional=true``.
   Additionally, please name the feature that requires this dependency, and add it under ``[tool.poetry.extras]``.
   E.g. in order to generate the documentation, we require ``Sphinx``, ``sphinx-rtd-theme`` and ``numpydoc`` to be installed.
   This is specified in ``pyproject.toml`` as follows:
 
   .. code-block::
 
-    [tool.poetry.dev-dependencies]
-    Sphinx = "*"
-    sphinx-rtd-theme = "*"
-    numpydoc = "*"
+    [tool.poetry.dependencies]
+    Sphinx = {version = "*", optional = true}
+    sphinx-rtd-theme = {version = "*", optional = true}
+    numpydoc = {version = "*", optional = true}
 
     [tool.poetry.extras]
     documentation = ["Sphinx", "sphinx-rtd-theme", "numpydoc"]