added notebook, tests and ci

.github/workflows/run_tests.yml

@@ -0,0 +1,57 @@
+name: test
+
+on:
+  push:
+    branches:
+      - "main"
+      - "master"
+      - "dev"
+    paths:
+      - "**.py"
+      - ".github/workflows/*test*.yml"
+      - "pyproject.toml"
+      - "poetry.lock"
+      - "requirements/requirements*.txt"
+  pull_request:
+    paths:
+      - "**.py"
+      - ".github/workflows/*test*.yml"
+      - "pyproject.toml"
+      - "poetry.lock"
+      - "requirements/requirements*.txt"
+
+jobs:
+  test:
+    name: "test Python ${{ matrix.python }} on ${{ matrix.os }}"
+    runs-on: "${{ matrix.os }}"
+    strategy:
+      fail-fast: false
+      matrix:
+        os: ["ubuntu-latest"]
+        python: ["3.9", "3.10", "3.11", "3.12"]
+        include:
+          - os: "macos-latest"
+            python: "3.10"
+    defaults:
+      run:
+        shell: "bash -eo pipefail {0}"
+
+    steps:
+      - uses: "actions/checkout@v2"
+      - uses: "actions/setup-python@v2"
+        with:
+          python-version: "${{ matrix.python }}"
+      - uses: "actions/cache@v2"
+        id: "cache"
+        with:
+          path: "${{ env.pythonLocation }}"
+          key: "test-${{ runner.os }}-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml', 'requirements/*') }}"
+      - run: "python --version"
+      - run: "python -mpip install -U pip"
+      - run: "python -mpip --version"
+      - run: "python -mpip install -r requirements/requirements-dev.txt"
+      - run: "python -mpip install ./"
+      - name: "Run tests"
+        run: "pytest tests/"
+        env:
+          PYTHONPATH: ${{ github.workspace }}/tests

.pre-commit-config.yaml

@@ -0,0 +1,91 @@
+ci:
+  autofix_prs: false
+default_language_version:
+  python: "python3"
+fail_fast: false
+
+repos:
+  - repo: "https://github.com/pre-commit/pre-commit-hooks"
+    rev: "v4.5.0"
+    hooks:
+      - id: "check-added-large-files"
+        args: ["--maxkb=40000"]
+      - id: "check-ast"
+      - id: "check-byte-order-marker"
+      - id: "check-docstring-first"
+      - id: "check-executables-have-shebangs"
+      - id: "check-json"
+      - id: "check-symlinks"
+      - id: "check-merge-conflict"
+      - id: "check-vcs-permalinks"
+      - id: "check-xml"
+      - id: "check-yaml"
+      - id: "debug-statements"
+      - id: "end-of-file-fixer"
+        exclude: ".+\\.ipynb"
+      - id: "name-tests-test"
+      - id: "trailing-whitespace"
+
+  - repo: "https://github.com/pre-commit/pygrep-hooks"
+    rev: "v1.10.0"
+    hooks:
+      - id: "python-check-blanket-noqa"
+      - id: "python-check-blanket-type-ignore"
+      - id: "python-use-type-annotations"
+
+  - repo: "https://github.com/asottile/reorder_python_imports"
+    rev: "v3.12.0"
+    hooks:
+      - id: "reorder-python-imports"
+        args:
+          - "--py38-plus"
+
+  - repo: "https://github.com/psf/black"
+    rev: "23.11.0"
+    hooks:
+      - id: "black"
+
+  - repo: "https://github.com/astral-sh/ruff-pre-commit"
+    # Ruff version.
+    rev: "v0.1.7"
+    hooks:
+      - id: "ruff"
+
+  - repo: "https://github.com/kynan/nbstripout"
+    rev: "0.6.1"
+    hooks:
+      - id: "nbstripout"
+
+  - repo: "https://github.com/python-poetry/poetry"
+    rev: "1.7.0"
+    hooks:
+      - id: "poetry-check"
+        name: "poetry check"
+      - id: "poetry-check"
+        name: "poetry check --lock"
+        args: ["--lock"]
+      - id: "poetry-lock"
+        name: "poetry lock --no-update"
+        args: ["--no-update"]
+      - id: "poetry-export"
+        name: "poetry export main"
+        args:
+          [
+            "--only",
+            "main",
+            "-f",
+            "requirements.txt",
+            "-o",
+            "requirements/requirements.txt",
+          ]
+      - id: "poetry-export"
+        name: "poetry export dev"
+        args:
+          [
+            "--with",
+            "dev",
+            "-f",
+            "requirements.txt",
+            "-o",
+            "requirements/requirements-dev.txt",
+          ]

README.md

@@ -1,12 +1,12 @@
 # SeaStats
 
-Simple package to compare and anylyse 2 time series. We use the following conventionn in this repo: 
+Simple package to compare and anylyse 2 time series. We use the following conventionn in this repo:
  * `sim`: modelled surge time series
  * `mod`: observed surge time series
 
-## Metrics available: 
+## Metrics available:
 
-These are following metrics available in this repository: 
+These are following metrics available in this repository:
 
 We need metrics to assess the quality of the model.
 We define the most important ones, as stated on this [Stats wiki](https://cirpwiki.info/wiki/Statistics):
@@ -33,8 +33,42 @@ with :
 $$\lambda = 1 - \frac{\sum{(x_c - x_m)^2}}{\sum{(x_m - \overline{x}_m)^2} + \sum{(x_c - \overline{x}_c)^2} + n(\overline{x}_m - \overline{x}_c)^2 + \kappa}$$
  * with `kappa` $$2 \cdot \left| \sum{((x_m - \overline{x}_m) \cdot (x_c - \overline{x}_c))} \right|$$
 
-### ADD STORM SELECTION PROCESS
-from methodology explained in this [notebook](https://tomsail.github.io/static/Model_metrics.html)
-### ADD "Slope" parameters
-more info can be found [in this preprint](https://doi.org/10.5194/egusphere-2024-1415) from Campos-Caba et. al.
-"""
+### Storm metrics:
+The metrics are returned by the function
+```python
+storm_metrics(sim: pd.Series, obs: pd.Series, quantile: float, cluster_duration:int = 72)
+```
+which returns this dictionary:
+```
+"db_match" : val,
+"R1_norm": val,
+"R1": val,
+"R3_norm": val,
+"R3": val,
+"error": val,
+"error_metric": val
+```
+we defined the following metrics for the storms events:
+
+* `R1`/`R3`/`error_metric`: we select the biggest observated storms, and then calculate error (so the absolute value of differenc between the model and the observed peaks)
+  * `R1` is the error for the biggest storm
+  * `R3` is the mean error for the 3 biggest storms
+  * `error_metric` is the mean error for all the storms above the threshold.
+
+* `R1_norm`/`R3_norm`/`error`: Same methodology, but values are in normalised (in %) by the observed peaks.
+
+### case of NaNs
+The `storm_metrics()` might return:
+```
+"db_match" : np.nan,
+"R1_norm": np.nan,
+"R1": np.nan,
+"R3_norm": np.nan,
+"R3": np.nan,
+"error": np.nan,
+"error_metric": np.nan
+```
+
+this happens when the function `storms/match_extremes.py` couldn't finc concomitent storms for the observed and modeled time series.
+
+## Usage