You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: updated every tutorial with additional links to pycsep functions/classes. Added hints pointing users to advance documentation when a new concept is introduced. Added an extra section pyCSEP under the hood, so users can see which pyCSEP functions where used in the tutorials. Upgraded some typos in cases g and h, due to config.yml updates. Removed depreacted use_db from case_e.rst.
Copy file name to clipboardExpand all lines: docs/tutorials/case_a.rst
+42-15Lines changed: 42 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -42,17 +42,17 @@ The source code can be found in the ``tutorials/case_a`` folder or in `GitHub <
42
42
└── config.yml
43
43
44
44
45
-
* The testing region ``region.txt`` consists of a grid with two 1ºx1º bins, defined by its bottom-left nodes. The grid spacing is obtained automatically. The nodes are:
45
+
* The testing region ``region.txt`` consists of a grid with two 1ºx1º bins, defined by its bottom-left nodes. (see :doc:`pycsep:concepts/regions` in **pyCSEP***)/ The grid spacing is obtained automatically. The nodes are:
* The testing catalog ``catalog.csep`` contains only one event and is formatted in the :meth:`~pycsep.utils.readers.csep_ascii` style (see :doc:`pycsep:concepts/catalogs`). Catalog formats are detected automatically
50
+
* The testing catalog ``catalog.csep`` contains only one event and is formatted in the :meth:`~pycsep.utils.readers.csep_ascii` style (see :doc:`pycsep:concepts/catalogs` in **pyCSEP***). Catalog formats are detected automatically
* The forecast ``best_model.dat`` to be evaluated is written in the ``.dat`` format (see :doc:`pycsep:concepts/forecasts`). Forecast formats are detected automatically (see :mod:`floatcsep.utils.file_io.GriddedForecastParsers`)
55
+
* The forecast ``best_model.dat`` to be evaluated is written in the ``.dat`` format (see :doc:`pycsep:concepts/forecasts` in **pyCSEP**). Forecast formats are detected automatically (see :mod:`floatcsep.utils.file_io.GriddedForecastParsers`)
@@ -61,12 +61,12 @@ The source code can be found in the ``tutorials/case_a`` folder or in `GitHub <
61
61
Configuration
62
62
-------------
63
63
64
-
The experiment is defined by a time-, region-, model- and test-configurations, as well as a catalog and a region. In this example, they are written together in the ``config.yml`` file.
64
+
The experiment is defined by a time-, region-, model- and test-configurations, as well as a catalog and a region. In this example, they are written together in the ``config.yml`` file.
65
65
66
66
67
-
.. important::
67
+
.. warning::
68
68
69
-
Every file path (e.g., of a catalog) specified in the ``config.yml`` file should be relative to the directory containing the configuration file.
69
+
Every file path (e.g., of a catalog) specified in the ``config.yml`` file should be relative to the directory containing the configuration file.
70
70
71
71
72
72
@@ -100,7 +100,7 @@ Region
100
100
Catalog
101
101
~~~~~~~
102
102
103
-
It is defined in the ``catalog`` inset. This should only make reference to a catalog **file** or a catalog **query function** (e.g. :func:`~csep.query_comcat`). **floatCSEP** will automatically filter the catalog to the experiment time, spatial and magnitude frames:
103
+
It is defined in the ``catalog`` inset. This should only make reference to a catalog **file** or a catalog **query function** (see catalog loaders in :mod:`csep`). **floatCSEP** will automatically filter the catalog to the experiment time, spatial and magnitude frames:
The model configuration is set in the ``models`` inset with a list of model names, which specify their file paths (and other attributes). Here, we just set the path as ``best_model.dat``, whose format is automatically detected.
112
+
The model configuration is set in the ``models`` inset with a list of model names, which specify their file paths (and other attributes). Here, we just set the path as ``best_model.dat``, whose format is automatically detected (see `Working with conventional gridded forecasts <https://docs.cseptesting.org/concepts/forecasts.html#working-with-conventional-gridded-forecasts>`_ in **pyCSEP**) .
The experiment's evaluations are defined in the ``tests`` inset. It should be a list of test names making reference to their function and plotting function. These can be either from **pyCSEP** (see :doc:`pycsep:concepts/evaluations`) or defined manually. Here, we use the Poisson consistency N-test: its function is :func:`poisson_evaluations.number_test <csep.core.poisson_evaluations.number_test>` with a plotting function :func:`plot_poisson_consistency_test <csep.utils.plots.plot_poisson_consistency_test>`
See here all available `Evaluation Functions <https://floatcsep.readthedocs.io/en/latest/guide/evaluation_config.html#evaluations-functions>`_, along with their corresponding `Plotting Functions <https://floatcsep.readthedocs.io/en/latest/guide/evaluation_config.html#plotting-functions>`_.
135
+
136
+
.. note::
131
137
138
+
For further details on how to configure an experiment, models and evaluations, see:
139
+
140
+
- :ref:`experiment_config`
141
+
- :ref:`model_config`
142
+
- :ref:`evaluation_config`
132
143
133
144
Running the experiment
134
145
----------------------
@@ -160,9 +171,25 @@ Results
160
171
* The complete results are summarized in ``results/report.md``
161
172
162
173
163
-
Advanced
164
-
~~~~~~~~
174
+
pyCSEP under the hood
175
+
---------------------
176
+
177
+
This tutorial uses *floatCSEP* as the orchestrator, but relies on *pyCSEP* for functions and objects.
The experiment run logic can be seen in the file ``case_a.py``, which executes the same example but in python source code. The run logic of the terminal commands ``run``, ``plot`` and ``reproduce`` can be found in :mod:`floatcsep.commands.main`, and can be customized by creating a script similar to ``case_a.py``.
Copy file name to clipboardExpand all lines: docs/tutorials/case_b.rst
+47-2Lines changed: 47 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -88,10 +88,19 @@ Evaluations
88
88
:caption: tutorials/case_b/tests.yml
89
89
90
90
.. note::
91
-
Plotting keyword arguments can be set in the ``plot_kwargs`` option - see :func:`~csep.utils.plots.plot_poisson_consistency_test` and :func:`~csep.utils.plots.plot_comparison_test` -.
91
+
Plotting keyword arguments can be set in the ``plot_kwargs`` option (see :func:`~csep.utils.plots.plot_poisson_consistency_test` and :func:`~csep.utils.plots.plot_comparison_test`).
92
92
93
93
.. important::
94
-
Comparison tests (such as the ``paired_t_test``) requires a reference model, whose name should be set in ``ref_model`` at the given test configuration.
94
+
Comparison tests (such as the :py:func:`poisson_evaluations.paired_t_test <csep.core.poisson_evaluations.paired_t_test>`) requires a reference model, whose name should be set in ``ref_model`` at the given test configuration.See all available `Evaluation Functions <https://floatcsep.readthedocs.io/en/latest/guide/evaluation_config.html#evaluations-functions>`_ and `Plotting Functions <https://floatcsep.readthedocs.io/en/latest/guide/evaluation_config.html#plotting-functions>`_.
95
+
96
+
.. note::
97
+
98
+
For further details on how to configure an experiment, models and evaluations, see:
99
+
100
+
- :ref:`experiment_config`
101
+
- :ref:`model_config`
102
+
- :ref:`evaluation_config`
103
+
95
104
96
105
Running the experiment
97
106
----------------------
@@ -106,3 +115,39 @@ The experiment can be run by simply navigating to the ``tutorials/case_b`` folde
106
115
This will automatically set all the file paths of the calculation (testing catalogs, evaluation results, figures) and will display a summarized report in ``results/report.md``.
107
116
108
117
118
+
pyCSEP under the hood
119
+
---------------------
120
+
121
+
This tutorial uses *floatCSEP* as the orchestrator, but relies on *pyCSEP* for functions and objects.
Copy file name to clipboardExpand all lines: docs/tutorials/case_c.rst
+41-1Lines changed: 41 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -78,7 +78,12 @@ Evaluations
78
78
79
79
.. note::
80
80
81
-
Plot arguments (title, labels, font sizes, axes limits, etc.) can be passed as a dictionary in ``plot_args`` (see the arguments details in :func:`~csep.utils.plots.plot_poisson_consistency_test`)
81
+
Plot arguments (title, labels, font sizes, axes limits, etc.) can be passed as a dictionary in ``plot_args`` (see the arguments details in :func:`~csep.utils.plot_poisson_consistency_test`)
82
+
83
+
.. important::
84
+
85
+
See here all available `Evaluation Functions <https://floatcsep.readthedocs.io/en/latest/guide/evaluation_config.html#evaluations-functions>`_ and their corresponding `Plotting Functions <https://floatcsep.readthedocs.io/en/latest/guide/evaluation_config.html#plotting-functions>`_.
86
+
82
87
83
88
Results
84
89
-------
@@ -99,3 +104,38 @@ now creates the result path tree for all time windows.
99
104
The report shows the temporal evaluations for all time-windows, whereas the discrete evaluations are shown only for the last time window.
100
105
101
106
107
+
108
+
pyCSEP under the hood
109
+
---------------------
110
+
111
+
This tutorial uses *floatCSEP* as the orchestrator, but relies on *pyCSEP* for functions and objects.
Copy file name to clipboardExpand all lines: docs/tutorials/case_d.rst
+36-1Lines changed: 36 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -61,7 +61,7 @@ Once the catalog and models have been downloaded, the experiment structure will
61
61
└── tests.yml
62
62
63
63
.. note::
64
-
In this experiment no region file is needed, because the region is encoded in the forecasts themselves (QuadTree models, see https://zenodo.org/record/6289795 and https://zenodo.org/record/6255575 ).
64
+
In this experiment no region file is needed because the region is encoded in the forecasts themselves, which are based on the QuadTree description (See `Working with quadtree-gridded forecasts <https://docs.cseptesting.org/concepts/forecasts.html#working-with-quadtree-gridded-forecasts>`_, and the Zenodo repositories https://zenodo.org/record/6289795 and https://zenodo.org/record/6255575 ).
65
65
66
66
Configuration
67
67
-------------
@@ -120,3 +120,38 @@ Running the experiment
120
120
121
121
122
122
123
+
pyCSEP under the hood
124
+
---------------------
125
+
126
+
This tutorial uses *floatCSEP* as the orchestrator, but relies on *pyCSEP* for functions and objects.
Copy file name to clipboardExpand all lines: docs/tutorials/case_e.rst
+42-3Lines changed: 42 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -97,9 +97,6 @@ Models
97
97
98
98
The forecasts are defined in ``[Earthquakes / 10-years]``, which is specified with the ``forecast_unit`` option (The default is `forecast_unit: 1`).
99
99
100
-
.. note::
101
-
102
-
The ``use_db`` flag allows ``floatcsep`` to transform the forecasts into a database (HDF5), which speeds up the calculations.
103
100
104
101
Post-Process
105
102
~~~~~~~~~~~~
@@ -144,6 +141,48 @@ Plot command
144
141
145
142
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.
146
143
144
+
.. note::
145
+
146
+
For further details on how to configure the **post-process** of an experiment, see:
147
+
148
+
- :ref:`postprocess`
149
+
150
+
151
+
pyCSEP under the hood
152
+
---------------------
153
+
154
+
This tutorial uses *floatCSEP* as the orchestrator, but relies on *pyCSEP* for functions and objects.
0 commit comments