Documentation / poetry improvements and fixes

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/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 the absolute time of the trigger with respect to the beginning of the event,
+        i.e. the first time in the event where the trigger condition was fulfilled
+
+        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,22 @@ 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.
+
+        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 +258,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 +302,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 +357,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 +402,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 +438,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 +479,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 +496,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 +519,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

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"]

documentation/source/Introduction/pages/installation.rst

@@ -16,7 +16,8 @@ using ``pip``:
       pip install NuRadioMC
 
 NuRadioMC/NuRadioReco will then be available from Python using ``import NuRadioMC`` and ``import NuRadioReco``, respectively.
-The pip installation will also install all core dependencies. 
+The pip installation will install all core dependencies. Some :ref:`optional dependencies <Introduction/pages/installation:Optional Dependencies>`
+can be installed by appending ``[option]``, i.e. ``pip install NuRadioMC[option]``.
 
 .. Important::
 
@@ -80,7 +81,7 @@ To install all (optional and non-optional) dependencies available in pip at once
 
 .. code-block:: Bash
 
-  pip install numpy scipy matplotlib astropy tinydb tinydb-serialization aenum h5py mysql-python pymongo dash plotly toml peakutils
+  pip install numpy scipy matplotlib astropy tinydb tinydb-serialization aenum h5py mysql-connector-python pymongo dash plotly toml peakutils future radiotools filelock mattak pygdsm MCEq crflux
 
 Note that some optional dependencies are not pip-installable and need to be 
 :ref:`installed manually <Introduction/pages/installation:Not pip-installable packages>`
@@ -136,30 +137,17 @@ Core Dependencies
 
     pip install aenum
 
-Optional Dependencies
-^^^^^^^^^^^^^^^^^^^^^
-
-These packages are recommended to be able to use all of NuRadioMC/NuRadioReco's features:
-
 - h5py to open HDF5 files:
 
-.. code-block:: Bash
-
-  pip install h5py
-
-- uproot to open RNO-G root files:
-
-.. code-block:: bash
-
-  pip install uproot awkward
+  .. code-block:: Bash
 
-- To access some detector databases:
+    pip install h5py
 
-- For SQL datbases install `MySQL <https://www.mysql.com/>`_ and mysql-python:
+- filelock:
 
   .. code-block:: Bash
 
-    pip install mysql-python
+    pip install filelock
 
 - For `MongoDB <https://www.mongodb.com>`_ databases install:
 
@@ -174,24 +162,23 @@ These packages are recommended to be able to use all of NuRadioMC/NuRadioReco's
     pip install dash
     pip install plotly
 
-  If you want templates to show up in the Event Display, you need to set up an environment variable NURADIORECOTEMPLATES and have it point to the template directory.
+Optional Dependencies
+^^^^^^^^^^^^^^^^^^^^^
 
-- The documentation is created using `Sphinx <https://www.sphinx-doc.org>`_. We use the ``readthedocs`` theme, and the ``numpydoc`` format is used in our docstrings.
-  This dependency is needed only if you want to generate the documentation locally - the `online documentation <https://nu-radio.github.io/NuRadioMC/main.html>`_ is generated by a Github action automatically.
-  Note that we use the `sphinx autodoc <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#module-sphinx.ext.autodoc>`_
-  feature, which tries to import all modules it documents. So if you are missing some optional dependencies, it will not generate correct documentation for all the code.
+These packages are recommended to be able to use all of NuRadioMC/NuRadioReco's features.
+They can be installed by including adding ``[option]`` when installing NuRadioMC.
 
-  .. code-block:: Bash
+- ``[RNO_G]``
 
-    pip install sphinx sphinx_rtd_theme numpydoc
+  `mattak <https://github.com/RNO-G/mattak>`__ is required to open RNO-G root files:
 
-- Some debug plots need peakutils:
+  .. code-block:: bash
 
-  .. code-block:: Bash
+    pip install mattak
 
-    pip install peakutils
+- ``[proposal]``
 
-- Proposal to use :mod:`NuRadioMC.EvtGen.NuRadioProposal` module:
+  ``proposal`` is needed to use :mod:`NuRadioMC.EvtGen.NuRadioProposal` module (simulating secondary particles):
 
   .. code-block:: bash
 
@@ -203,13 +190,46 @@ These packages are recommended to be able to use all of NuRadioMC/NuRadioReco's
 
   - if the linux kernel is too old (eg. on some computing clusters), refer to `this step-by-step guide <https://github.com/tudo-astroparticlephysics/PROPOSAL/wiki/Installing-PROPOSAL-on-a-Linux-kernel---4.11>`_
 
+- ``[galacticnoise]``
 
-- To use the channelGalacticNoiseAdder, you need the `PyGDSM <https://github.com/telegraphic/pygdsm>`_ package.
+  To use the channelGalacticNoiseAdder, you need the `PyGDSM <https://github.com/telegraphic/pygdsm>`_ package.
 
   .. code-block:: Bash
 
     pip install git+https://github.com/telegraphic/pygdsm
 
+- ``[muon_flux]``
+
+  Needed for some muon flux calculations
+
+  .. code-block:: bash
+
+    pip install MCEq crflux
+
+- ``[documentation]``
+
+  The documentation is created using `Sphinx <https://www.sphinx-doc.org>`_. We use the ``readthedocs`` theme, and the ``numpydoc`` format is used in our docstrings.
+  This dependency is needed only if you want to generate the documentation locally - the `online documentation <https://nu-radio.github.io/NuRadioMC/main.html>`_ is generated by a Github action automatically.
+  Note that we use the `sphinx autodoc <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#module-sphinx.ext.autodoc>`_
+  feature, which tries to import all modules it documents. So if you are missing some optional dependencies, it will not generate correct documentation for all the code.
+
+  .. code-block:: Bash
+
+    pip install sphinx sphinx_rtd_theme numpydoc
+
+- Some debug plots need peakutils:
+
+  .. code-block:: Bash
+
+    pip install peakutils
+
+- For SQL databases install `MySQL <https://www.mysql.com/>`_ and mysql-python:
+
+  .. code-block:: Bash
+
+    pip install mysql-connector-python
+
+
 Not pip-installable packages
 ____________________________
 

documentation/source/NuRadioMC/pages/code_documentation.rst

@@ -1,9 +1,9 @@
 
 Code Documentation
-===============================
+==================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    ../apidoc/NuRadioMC.EvtGen
    ../apidoc/NuRadioMC.SignalGen