Skip to content

Commit

Permalink
refac: Renamed examples folder to tutorials
Browse files Browse the repository at this point in the history
  • Loading branch information
@pabloitu
pabloitu committed Sep 24, 2024
1 parent b973be1 commit 6e299a7
Show file tree
Hide file tree
Showing 85 changed files with 211 additions and 173 deletions.
45 changes: 31 additions & 14 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,11 @@
<a href="https://doi.org/10.5281/zenodo.7953816"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.7953816.svg" alt="DOI"></a>
</p>

* Set up a testing **experiment** for your earthquake forecasts using authoritative data sources and benchmarks.
* Set up a testing **experiment** for your earthquake forecasts using authoritative data sources
and benchmarks.
* **Encapsulate** the complete experiment's definition and rules in a couple of lines.
* **Reproduce**, **reuse**, and **share** forecasting experiments from you, other researchers and institutions.
* **Reproduce**, **reuse**, and **share** forecasting experiments from you, other researchers
and institutions.

# Table of Contents

Expand All @@ -34,12 +36,14 @@
* [Contributing](#contributing)
* [License](#license)


# Installing floatCSEP

The core of `floatCSEP` is built around the `pyCSEP` package (https://github.com/sceccode/pycsep), which itself contains the core dependencies.
The core of `floatCSEP` is built around the `pyCSEP`
package (https://github.com/sceccode/pycsep), which itself contains the core dependencies.

The simplest way to install `floatCSEP`, is by creating a `conda` environment (https://conda.io - checkout Anaconda or Miniconda) and install `pyCSEP` from `conda-forge`
The simplest way to install `floatCSEP`, is by creating a `conda`
environment (https://conda.io - checkout Anaconda or Miniconda) and install `pyCSEP`
from `conda-forge`

```
conda env create -n $NAME
Expand All @@ -48,21 +52,29 @@ conda install -c conda-forge pycsep
```

Clone and install the floatCSEP source code using `pip`

```
git clone https://github.com/cseptesting/floatcsep
cd floatcsep
pip install .
```

Please read the [Installation](https://floatcsep.readthedocs.io/en/latest/intro/installation.html) documentation for detailed instructions and additional installation methods.
Please read
the [Installation](https://floatcsep.readthedocs.io/en/latest/intro/installation.html)
documentation for detailed instructions and additional installation methods.

# Run an Experiment

Using the command terminal, navigate to an example experiment in `floatcsep/examples/` and type
Using the command terminal, navigate to an example experiment in ``floatcsep/tutorials/`` and
type

```
floatcsep run config.yml
```
A runtime directory will be created in a `results` folder. The experiment results can be visualized in `results/report.md`. **Check out the experiment, models and tests definition in the examples**!

A runtime directory will be created in a `results` folder. The experiment results can be
visualized in `results/report.md`. **Check out the experiment, models and tests definition in
the tutorials**!

# Important Links

Expand All @@ -71,7 +83,6 @@ A runtime directory will be created in a `results` folder. The experiment result
* `pyCSEP` [Github](https://github.com/sceccode/pycsep)
* `pyCSEP` [Documentation](https://docs.cseptesting.org/)


# Roadmap and Known Issues

* Add report customization
Expand All @@ -80,21 +91,27 @@ A runtime directory will be created in a `results` folder. The experiment result
* Implement spatial database and HDF5 experiment storage feature
* Set up task paralellization


# Contributing

We encourage all types of contributions, from reporting bugs, suggesting enhancements, adding new features and more. Please refer to the [Contribution Guidelines](https://github.com/cseptesting/floatcsep/blob/main/CONTRIBUTING.md) and the [Code of Conduct](https://github.com/cseptesting/floatcsep/blob/main/CODE_OF_CONDUCT.md) for more information
We encourage all types of contributions, from reporting bugs, suggesting enhancements, adding
new features and more. Please refer to
the [Contribution Guidelines](https://github.com/cseptesting/floatcsep/blob/main/CONTRIBUTING.md)
and the [Code of Conduct](https://github.com/cseptesting/floatcsep/blob/main/CODE_OF_CONDUCT.md)
for more information

# License

The `floatCSEP` (as well as `pyCSEP`) software is distributed under the BSD 3-Clause open-source license. Please see the [license file](https://github.com/cseptesting/floatcsep/blob/main/LICENSE) for more information.
The `floatCSEP` (as well as `pyCSEP`) software is distributed under the BSD 3-Clause open-source
license. Please see
the [license file](https://github.com/cseptesting/floatcsep/blob/main/LICENSE) for more
information.

## Support

<div style="max-width: 100px; margin: auto;">

| <img src="https://i.postimg.cc/tC1LdjYf/scec.png" width="150"/> | <img src="https://i.postimg.cc/2S7ThcFM/eu-flag.jpg" width="150"/> |
|:---|:---|
| <img src="https://i.postimg.cc/tC1LdjYf/scec.png" width="150"/> | <img src="https://i.postimg.cc/2S7ThcFM/eu-flag.jpg" width="150"/> |
|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| <div style="text-align: left;">This research was supported by the <a href="https://www.scec.org/">Statewide California Earthquake Center</a>. SCEC is funded by NSF Cooperative Agreement EAR-2225216 and USGS Cooperative Agreement G24AC00072-00.</div> | <div style="text-align: left;">The work in this repository has received funding from the European Union’s Horizon research and innovation programme under grant agreements No.s 101058518 and 821115 of the projects <a href="https://www.geo-inquire.eu/">GeoInquire</a> and <a href="https://www.rise-eu.org/">RISE</a>.</div> |

</div>
36 changes: 18 additions & 18 deletions docs/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ floatCSEP: Floating Experiments
:height: 48px

.. |tutorials| image:: https://img.icons8.com/nolan/64/checklist.png
:target: examples/case_a.html
:target: tutorials/case_a.html
:height: 48px


Expand All @@ -56,14 +56,14 @@ Quickstart
+--------------------------------------------------+-------------------------------------+
| |start| **Get Started** | |tutorials| **Tutorials** |
| | |
| |learn1| **Forecasting Concepts** | - :ref:`example_a` |
| | - :ref:`example_b` |
| |learn2| **Testing Theory** | - :ref:`example_c` |
| | - :ref:`example_d` |
| |experiment| **Floating Experiments** | - :ref:`example_e` |
| | - :ref:`example_f` |
| |api| **API Reference** | - :ref:`example_g` |
| | - :ref:`example_h` |
| |learn1| **Forecasting Concepts** | - :ref:`case_a` |
| | - :ref:`case_b` |
| |learn2| **Testing Theory** | - :ref:`case_c` |
| | - :ref:`case_d` |
| |experiment| **Floating Experiments** | - :ref:`case_e` |
| | - :ref:`case_f` |
| |api| **API Reference** | - :ref:`case_g` |
| | - :ref:`case_h` |
+--------------------------------------------------+-------------------------------------+

What is floatCSEP
Expand All @@ -84,7 +84,7 @@ Goals
Running
-------

Start using **floatCSEP** by `installing <intro/installation.html>`_ the latest version and running the ``examples`` with simply:
Start using **floatCSEP** by `installing <intro/installation.html>`_ the latest version and running the ``tutorials`` with simply:

.. code-block::
Expand Down Expand Up @@ -146,14 +146,14 @@ Collaborators
:maxdepth: 1
:caption: Tutorial Experiments

examples/case_a.rst
examples/case_b.rst
examples/case_c.rst
examples/case_d.rst
examples/case_e.rst
examples/case_f.rst
examples/case_g.rst
examples/case_h.rst
tutorials/case_a.rst
tutorials/case_b.rst
tutorials/case_c.rst
tutorials/case_d.rst
tutorials/case_e.rst
tutorials/case_f.rst
tutorials/case_g.rst
tutorials/case_h.rst

.. toctree::
:hidden:
Expand Down
2 changes: 1 addition & 1 deletion docs/intro/forecasting_experiments.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,4 @@ Forecasting Experiments
=======================


TBI
TBW
58 changes: 39 additions & 19 deletions docs/intro/installation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,15 +12,12 @@ Installing the latest version
Using ``conda``
~~~~~~~~~~~~~~~

The core of `floatCSEP` is built around the `pyCSEP` package (https://github.com/sceccode/pycsep), which itself contains the core dependencies.
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:

The simplest way to install `floatCSEP`, is by creating a `conda` environment (https://conda.io - checkout Anaconda or Miniconda) and install `pyCSEP` from `conda-forge`
.. code-block:: sh
.. code-block:: console
$ conda env create -n $NAME
$ conda activate $NAME
$ conda install -c conda-forge pycsep
$ conda env create -n csep_env
$ conda activate csep_env
Then, clone and install the floatCSEP source code using ``pip``

Expand All @@ -30,27 +27,50 @@ Then, clone and install the floatCSEP source code using ``pip``
cd floatcsep
pip install .
Using ``apt`` and ``pip``
~~~~~~~~~~~~~~~~~~~~~~~~~
To install from ``pip``, we require to install the binary dependencies of ``pyCSEP`` (see `Installing pyCSEP <https://docs.cseptesting.org/getting_started/installing.html>`_}
Using ``pip``
~~~~~~~~~~~~~

Then, install the ``pycsep`` latest version
To install using the ``pip`` manager, we require to install the binary dependencies of **pyCSEP** (see `Installing pyCSEP <https://docs.cseptesting.org/getting_started/installing.html>`_}. The **floatcsep** latest version then can be installed as:

.. code-block::
git clone https://github.com/SCECcode/pycsep
cd pycsep
python -m virtualenv venv
source venv/bin/activate
pip install -e .[all]
cd ..
git clone https://github.com/cseptesting/floatcsep
cd floatcsep
pip install .
Installing the stable version
-----------------------------


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:

and the ``floatcsep`` latest version
.. code-block:: sh
$ conda env create -n csep_env
$ conda activate csep_env
Then, clone and install the floatCSEP source code using ``pip``

.. code-block:: console
git clone https://github.com/cseptesting/floatcsep
cd floatcsep
pip install .
Using ``pip``
~~~~~~~~~~~~~

To install using the ``pip`` manager, 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::
cd ..
git clone https://github.com/cseptesting/floatcsep
cd floatcsep
pip install .[all]
pip install .
40 changes: 20 additions & 20 deletions docs/examples/case_a.rst → docs/tutorials/case_a.rst
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
.. _example_a:
.. _case_a:

A - Testing a Simple Model
==========================
Expand All @@ -9,7 +9,7 @@ The following example shows the definition of a testing experiment of a single *

.. admonition:: **TL; DR**

In a terminal, navigate to ``floatcsep/examples/case_a`` and type:
In a terminal, navigate to ``floatcsep/tutorials/case_a`` and type:

.. code-block:: console
Expand All @@ -25,7 +25,7 @@ The following example shows the definition of a testing experiment of a single *
Experiment Components
---------------------

The source code can be found in the ``examples/case_a`` folder or in `GitHub <https://github.com/cseptesting/floatcsep/blob/main/examples/case_a>`_. The directory structure of the experiment is:
The source code can be found in the ``tutorials/case_a`` folder or in `GitHub <https://github.com/cseptesting/floatcsep/blob/main/tutorials/case_a>`_. The directory structure of the experiment is:

::

Expand All @@ -38,18 +38,18 @@ The source code can be found in the ``examples/case_a`` folder or in `GitHub <h

* 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:

.. literalinclude:: ../../examples/case_a/region.txt
:caption: examples/case_a/region.txt
.. literalinclude:: ../../tutorials/case_a/region.txt
:caption: tutorials/case_a/region.txt

* 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

.. literalinclude:: ../../examples/case_a/catalog.csep
:caption: examples/case_a/catalog.csep
.. literalinclude:: ../../tutorials/case_a/catalog.csep
:caption: tutorials/case_a/catalog.csep

* 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.readers.ForecastParsers`)

.. literalinclude:: ../../examples/case_a/best_model.dat
:caption: examples/case_a/best_model.dat
.. literalinclude:: ../../tutorials/case_a/best_model.dat
:caption: tutorials/case_a/best_model.dat


Configuration
Expand All @@ -69,8 +69,8 @@ Time

The time configuration is manifested in the ``time_config`` inset. The simplest definition is to set only the start and end dates of the experiment. These are always UTC date-times in isoformat (``%Y-%m-%dT%H:%M:%S.%f`` - ISO861):

.. literalinclude:: ../../examples/case_a/config.yml
:caption: examples/case_a/config.yml
.. literalinclude:: ../../tutorials/case_a/config.yml
:caption: tutorials/case_a/config.yml
:language: yaml
:lines: 3-5

Expand All @@ -85,8 +85,8 @@ Region

The region - a file path or a :mod:`pycsep` function, such as :obj:`~csep.core.regions.italy_csep_region` (check the available regions in :mod:`csep.core.regions`) -, the depth limits and magnitude discretization are defined in the ``region_config`` inset.

.. literalinclude:: ../../examples/case_a/config.yml
:caption: examples/case_a/config.yml
.. literalinclude:: ../../tutorials/case_a/config.yml
:caption: tutorials/case_a/config.yml
:language: yaml
:lines: 7-13

Expand All @@ -96,17 +96,17 @@ Catalog

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:

.. literalinclude:: ../../examples/case_a/config.yml
:caption: examples/case_a/config.yml
.. literalinclude:: ../../tutorials/case_a/config.yml
:caption: tutorials/case_a/config.yml
:language: yaml
:lines: 15-15

Models
~~~~~~
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.

.. literalinclude:: ../../examples/case_a/config.yml
:caption: examples/case_a/config.yml
.. literalinclude:: ../../tutorials/case_a/config.yml
:caption: tutorials/case_a/config.yml
:language: yaml
:lines: 17-19

Expand All @@ -118,8 +118,8 @@ Evaluations
~~~~~~~~~~~
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 defined in ``pycsep`` (see :doc:`pycsep:concepts/evaluations`) or manually. In this example, we employ the consistency N-test: its function is :func:`csep.core.poisson_evaluations.number_test`, whereas its plotting function correspond to :func:`csep.utils.plots.plot_poisson_consistency_test`

.. literalinclude:: ../../examples/case_a/config.yml
:caption: examples/case_a/config.yml
.. literalinclude:: ../../tutorials/case_a/config.yml
:caption: tutorials/case_a/config.yml
:language: yaml
:lines: 21-24

Expand All @@ -130,7 +130,7 @@ Running the experiment
Run command
~~~~~~~~~~~

The experiment can be run by simply navigating to the ``examples/case_a`` folder in the terminal and typing.
The experiment can be run by simply navigating to the ``tutorials/case_a`` folder in the terminal and typing.

.. code-block:: console
Expand Down
Loading

0 comments on commit 6e299a7

Please sign in to comment.