Minor fixes to code & edits of docs +++ textual feedback

docs/intro/installation.rst

@@ -9,35 +9,52 @@ Installation
 Latest Version
 --------------
 
-Recommended to learn the software, run the tutorials, and drafting **Testing Experiments**.
+This option is recommended to learn the software, run the tutorials, and drafting **Testing Experiments**.
 
 1. Using ``conda``
 ~~~~~~~~~~~~~~~~~~
 
-To install **floatCSEP**, first a ``conda`` manager should be installed (https://conda.io). Checkout `Anaconda`, `Miniconda` or `Miniforge` (recommended). Once installed, create an environment with:
+First, clone the **floatCSEP** source code into a new directory by typing into a terminal:
+
+    .. code-block:: console
+
+        $ git clone https://github.com/cseptesting/floatcsep
+        $ cd floatcsep
+
+Then, let ``conda`` automatically install all required dependencies of **floatCSEP** (from its ``environment.yml`` file) into a new environment, and activate it:
 
     .. code-block:: console
 
         $ conda create -n csep_env
         $ conda activate csep_env
 
-Then, clone and install the floatCSEP source code using ``pip``
+.. note::
+
+    For this to work, you need to have ``conda`` installed (see `conda.io <https://conda.io>`_), either by installing the `Anaconda Distribution <https://docs.anaconda.com/anaconda/install/>`_,
+    or its more minimal variants `Miniconda <https://docs.anaconda.com/miniconda/>`_ or `Miniforge <https://conda-forge.org/download>`_ (recommended).
+    If you install `Miniforge`, we further recommend to use the ``mamba`` command instead of ``conda`` (a faster drop-in replacement).
+
+
+Lastly, install **floatCSEP** into the new environment using ``pip``:
 
     .. code-block:: console
 
-        $ git clone https://github.com/cseptesting/floatcsep
-        $ cd floatcsep
         $ pip install .
 
 .. note::
 
-    Use the ``mamba`` command instead of ``conda`` if `Miniforge` was installed.
+    To *update* **floatCSEP** and its dependencies at a later date, simply execute:
 
+        .. code-block:: console
 
-2. Using ``pip`` only
+            $ conda env update --file environment.yml
+            $ pip install . -U
+
+
+2. Using only ``pip``
 ~~~~~~~~~~~~~~~~~~~~~
 
-To install using the ``pip`` manager only, we require to install the binary dependencies of **pyCSEP** (see `Installing pyCSEP <https://docs.cseptesting.org/getting_started/installing.html>`_}. The **floatCSEP** latest version can then be installed as:
+To install using the ``pip`` manager only, we require to install the binary dependencies of **pyCSEP** (see `Installing pyCSEP <https://docs.cseptesting.org/getting_started/installing.html>`_). The **floatCSEP** latest version can then be installed as:
 
     .. code-block:: console
 
@@ -50,13 +67,12 @@ To install using the ``pip`` manager only, we require to install the binary depe
 Latest Stable Release
 ---------------------
 
-Recommended for deploying live Floating Testing Experiments
+This option is recommended for deploying *Floating Testing Experiments* live.
 
 1. From the ``conda-forge`` channel
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Having a ``conda`` manager installed (https://conda.io), type in a console:
-
+Having a ``conda`` manager installed (see **Note** box above), type in a console:
 
     .. code-block:: console
 
@@ -91,7 +107,7 @@ Having installed the binary dependencies of **pyCSEP** (see `Installing pyCSEP <
 For Developers
 --------------
 
-It is recommended (not obligatory) to use a ``conda`` environment to make sure your contributions do not depend on your system local libraries. For contributions to the **floatCSEP** codebase, please consider using a `fork <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo>`_ and creating pull-requests from there.
+It is recommended (not obligatory) to use a ``conda`` environment to make sure your contributions do not depend on your system local libraries. For contributing to the **floatCSEP** codebase, please consider `forking the repository <https://docs.github.com/articles/fork-a-repo>`_ and `create pull-requests <https://docs.github.com/articles/creating-a-pull-request>`_ from there.
 
     .. code-block:: console
 
@@ -101,4 +117,4 @@ It is recommended (not obligatory) to use a ``conda`` environment to make sure y
         $ cd floatcsep
         $ pip install .[dev]
 
-This will install and configure all the unit-testing, linting and documentation packages.
+This will install and configure all the unit-testing, linting, and documentation packages.

docs/tutorials/case_e.rst

@@ -3,7 +3,7 @@
 E - A Time-Independent Experiment
 =================================
 
-This example shows how to run a realistic testing experiment (based on https://doi.org/10.4401/ag-4844) while summarizing the concepts from the previous tutorials.
+This example shows how to run a realistic testing experiment (based on :ref:`Schorlemmer et al. 2010<References>`) while summarizing the concepts from the previous tutorials.
 
 .. currentmodule:: floatcsep
 
@@ -25,7 +25,7 @@ This example shows how to run a realistic testing experiment (based on https://d
 Experiment Components
 ---------------------
 
-The source code can be found in the ``tutorials/case_e`` folder or in  `GitHub <https://github.com/cseptesting/floatcsep/blob/main/tutorials/case_e>`_. The input structure of the experiment is:
+The source code can be found in the ``tutorials/case_e`` folder or in `the GitHub repository <https://github.com/cseptesting/floatcsep/blob/main/tutorials/case_e>`_. The input structure of the experiment is:
 
 ::
 
@@ -137,3 +137,9 @@ Plot command
             colormap: magma
 
     and re-run with the ``plot`` command. A forecast figure will re-appear in ``results/{window}/forecasts`` with a different colormap. Additional forecast and catalog plotting options can be found in the :func:`csep.utils.plots.plot_spatial_dataset` and :func:`csep.utils.plots.plot_catalog` ``pycsep`` functions.
+
+
+References
+----------
+
+    * Schorlemmer, D., Christophersen, A., Rovida, A., Mele, F., Stucchi, M. and Marzocchi, W. (2010). Setting up an earthquake forecast experiment in Italy. Annals of Geophysics, 53(3), 1–9. doi: `10.4401/ag-4844 <https://doi.org/10.4401/ag-4844>`_

docs/tutorials/case_f.rst

@@ -25,7 +25,7 @@ Experiment Components
 ---------------------
 
 
-The source files can be found in the ``tutorials/case_e`` folder or in  `GitHub <https://github.com/cseptesting/floatcsep/blob/main/tutorials/case_e>`_. The experiment structure is as follows:
+The source files can be found in the ``tutorials/case_e`` folder or in  `the GitHub repository <https://github.com/cseptesting/floatcsep/blob/main/tutorials/case_e>`_. The experiment structure is as follows:
 
 ::
 
@@ -49,7 +49,7 @@ The source files can be found in the ``tutorials/case_e`` folder or in  `GitHub
 Model
 -----
 
-The time-dependency of a model is manifested here by the provision of different forecasts, i.e., statistical descriptions of seismicity, for different time-windows. In this example, the forecasts were created from an external model https://github.com/lmizrahi/etas (`doi:10.1785/0220200231 <https://doi.org/10.1785/0220200231>`_), with which the experiment has no interface. This means that we use **only the forecast files** and no source code. We leave the handling of a model source code for subsequent tutorials.
+The time-dependency of a model is manifested here by the provision of different forecasts, i.e., statistical descriptions of seismicity, for different time-windows. In this example, the forecasts were created from an external model https://github.com/lmizrahi/etas (:ref:`Mizrahi et al. 2021<References>`_), with which the experiment has no interface. This means that we use **only the forecast files** and no source code. We leave the handling of a model source code for subsequent tutorials.
 
 
 
@@ -73,7 +73,7 @@ Time
 Catalog
 ~~~~~~~
 
-    The catalog ``catalog.json`` was obtained *previously* by using ``query_geonet`` and it was filtered to the testing period. However, it can be re-queried by changing its definition to:
+    The catalog ``catalog.json`` was obtained *prior* to the experiment by using ``query_geonet`` and it was filtered to the testing period. However, it can be re-queried by changing its definition to:
 
     .. code-block:: yaml
 
@@ -93,29 +93,34 @@ Models
     For consistency with time-dependent models that will create forecasts from a source code, the ``path`` should point to the folder of the model, which itself should contain a sub-folder named ``{path}/forecasts`` where the files are located.
 
 .. important::
-    Note that for catalog-based forecasts, the model should explicit the number of simulations. This is meant for forecast files that contain synthetic catalogs with zero-event simulations, and therefore do not contain the total number of synthetic catalogs used.
+    Note that for catalog-based forecast models, the number of catalog simulations (``n_sims``) must be specified – because a forecast may contain synthetic catalogs with zero-event simulations and therefore does not imply the total number of simulated synthetic catalogs.
 
 Tests
 ~~~~~
 
-    With time-dependent models, now catalog evaluations found in :obj:`csep.core.catalog_evaluations` can be used.
+    Having a time-dependent and catalog-based forecast model, catalog-based evaluations found in :obj:`csep.core.catalog_evaluations` can now be used.
 
 
     .. literalinclude:: ../../tutorials/case_f/tests.yml
        :language: yaml
 
     .. note::
-        It is possible to assign two plotting functions to a test, whose ``plot_args`` and ``plot_kwargs`` can be placed indented beneath
+        It is possible to assign two plotting functions to a test, whose ``plot_args`` and ``plot_kwargs`` can be placed indented beneath.
 
 
 Running the experiment
 ----------------------
 
-    The experiment can be run by simply navigating to the ``tutorials/case_h`` folder in the terminal and typing.
+    The experiment can be run by simply navigating to the ``tutorials/case_h`` folder in the terminal and typing:
 
     .. code-block:: console
 
        $ floatcsep run config.yml
 
     This will automatically set all the calculation paths (testing catalogs, evaluation results, figures) and will create a summarized report in ``results/report.md``.
 
+
+References
+----------
+
+    * Mizrahi, L., Nandan, S., & Wiemer, S. (2021). The effect of declustering on the size distribution of mainshocks. _Seismological Research Letters, 92_(4), 2333–2342. doi: `10.1785/0220200231 <https://doi.org/10.1785/0220200231>`_