seastats 0.1.0__tar.gz

seastats-0.1.0/LICENSE

@@ -0,0 +1,274 @@
+European Union Public Licence
+V. 1.2
+
+EUPL © the European Union 2007, 2016
+
+This European Union Public Licence (the ‘EUPL’) applies to the Work (as
+defined below) which is provided under the terms of this Licence. Any use of
+the Work, other than as authorised under this Licence is prohibited (to the
+extent such use is covered by a right of the copyright holder of the Work).
+
+The Work is provided under the terms of this Licence when the Licensor (as
+defined below) has placed the following notice immediately following the
+copyright notice for the Work: “Licensed under the EUPL”, or has expressed by
+any other means his willingness to license under the EUPL.
+
+1. Definitions
+
+In this Licence, the following terms have the following meaning:
+— ‘The Licence’: this Licence.
+— ‘The Original Work’: the work or software distributed or communicated by the
+  ‘Licensor under this Licence, available as Source Code and also as
+  ‘Executable Code as the case may be.
+— ‘Derivative Works’: the works or software that could be created by the
+  ‘Licensee, based upon the Original Work or modifications thereof. This
+  ‘Licence does not define the extent of modification or dependence on the
+  ‘Original Work required in order to classify a work as a Derivative Work;
+  ‘this extent is determined by copyright law applicable in the country
+  ‘mentioned in Article 15.
+— ‘The Work’: the Original Work or its Derivative Works.
+— ‘The Source Code’: the human-readable form of the Work which is the most
+  convenient for people to study and modify.
+
+— ‘The Executable Code’: any code which has generally been compiled and which
+  is meant to be interpreted by a computer as a program.
+— ‘The Licensor’: the natural or legal person that distributes or communicates
+  the Work under the Licence.
+— ‘Contributor(s)’: any natural or legal person who modifies the Work under
+  the Licence, or otherwise contributes to the creation of a Derivative Work.
+— ‘The Licensee’ or ‘You’: any natural or legal person who makes any usage of
+  the Work under the terms of the Licence.
+— ‘Distribution’ or ‘Communication’: any act of selling, giving, lending,
+  renting, distributing, communicating, transmitting, or otherwise making
+  available, online or offline, copies of the Work or providing access to its
+  essential functionalities at the disposal of any other natural or legal
+  person.
+
+2. Scope of the rights granted by the Licence
+
+The Licensor hereby grants You a worldwide, royalty-free, non-exclusive,
+sublicensable licence to do the following, for the duration of copyright
+vested in the Original Work:
+
+— use the Work in any circumstance and for all usage,
+— reproduce the Work,
+— modify the Work, and make Derivative Works based upon the Work,
+— communicate to the public, including the right to make available or display
+  the Work or copies thereof to the public and perform publicly, as the case
+  may be, the Work,
+— distribute the Work or copies thereof,
+— lend and rent the Work or copies thereof,
+— sublicense rights in the Work or copies thereof.
+
+Those rights can be exercised on any media, supports and formats, whether now
+known or later invented, as far as the applicable law permits so.
+
+In the countries where moral rights apply, the Licensor waives his right to
+exercise his moral right to the extent allowed by law in order to make
+effective the licence of the economic rights here above listed.
+
+The Licensor grants to the Licensee royalty-free, non-exclusive usage rights
+to any patents held by the Licensor, to the extent necessary to make use of
+the rights granted on the Work under this Licence.
+
+3. Communication of the Source Code
+
+The Licensor may provide the Work either in its Source Code form, or as
+Executable Code. If the Work is provided as Executable Code, the Licensor
+provides in addition a machine-readable copy of the Source Code of the Work
+along with each copy of the Work that the Licensor distributes or indicates,
+in a notice following the copyright notice attached to the Work, a repository
+where the Source Code is easily and freely accessible for as long as the
+Licensor continues to distribute or communicate the Work.
+
+4. Limitations on copyright
+
+Nothing in this Licence is intended to deprive the Licensee of the benefits
+from any exception or limitation to the exclusive rights of the rights owners
+in the Work, of the exhaustion of those rights or of other applicable
+limitations thereto.
+
+5. Obligations of the Licensee
+
+The grant of the rights mentioned above is subject to some restrictions and
+obligations imposed on the Licensee. Those obligations are the following:
+
+Attribution right: The Licensee shall keep intact all copyright, patent or
+trademarks notices and all notices that refer to the Licence and to the
+disclaimer of warranties. The Licensee must include a copy of such notices and
+a copy of the Licence with every copy of the Work he/she distributes or
+communicates. The Licensee must cause any Derivative Work to carry prominent
+notices stating that the Work has been modified and the date of modification.
+
+Copyleft clause: If the Licensee distributes or communicates copies of the
+Original Works or Derivative Works, this Distribution or Communication will be
+done under the terms of this Licence or of a later version of this Licence
+unless the Original Work is expressly distributed only under this version of
+the Licence — for example by communicating ‘EUPL v. 1.2 only’. The Licensee
+(becoming Licensor) cannot offer or impose any additional terms or conditions
+on the Work or Derivative Work that alter or restrict the terms of the
+Licence.
+
+Compatibility clause: If the Licensee Distributes or Communicates Derivative
+Works or copies thereof based upon both the Work and another work licensed
+under a Compatible Licence, this Distribution or Communication can be done
+under the terms of this Compatible Licence. For the sake of this clause,
+‘Compatible Licence’ refers to the licences listed in the appendix attached to
+this Licence. Should the Licensee's obligations under the Compatible Licence
+conflict with his/her obligations under this Licence, the obligations of the
+Compatible Licence shall prevail.
+
+Provision of Source Code: When distributing or communicating copies of the
+Work, the Licensee will provide a machine-readable copy of the Source Code or
+indicate a repository where this Source will be easily and freely available
+for as long as the Licensee continues to distribute or communicate the Work.
+
+Legal Protection: This Licence does not grant permission to use the trade
+names, trademarks, service marks, or names of the Licensor, except as required
+for reasonable and customary use in describing the origin of the Work and
+reproducing the content of the copyright notice.
+
+6. Chain of Authorship
+
+The original Licensor warrants that the copyright in the Original Work granted
+hereunder is owned by him/her or licensed to him/her and that he/she has the
+power and authority to grant the Licence.
+
+Each Contributor warrants that the copyright in the modifications he/she
+brings to the Work are owned by him/her or licensed to him/her and that he/she
+has the power and authority to grant the Licence.
+
+Each time You accept the Licence, the original Licensor and subsequent
+Contributors grant You a licence to their contributions to the Work, under the
+terms of this Licence.
+
+7. Disclaimer of Warranty
+
+The Work is a work in progress, which is continuously improved by numerous
+Contributors. It is not a finished work and may therefore contain defects or
+‘bugs’ inherent to this type of development.
+
+For the above reason, the Work is provided under the Licence on an ‘as is’
+basis and without warranties of any kind concerning the Work, including
+without limitation merchantability, fitness for a particular purpose, absence
+of defects or errors, accuracy, non-infringement of intellectual property
+rights other than copyright as stated in Article 6 of this Licence.
+
+This disclaimer of warranty is an essential part of the Licence and a
+condition for the grant of any rights to the Work.
+
+8. Disclaimer of Liability
+
+Except in the cases of wilful misconduct or damages directly caused to natural
+persons, the Licensor will in no event be liable for any direct or indirect,
+material or moral, damages of any kind, arising out of the Licence or of the
+use of the Work, including without limitation, damages for loss of goodwill,
+work stoppage, computer failure or malfunction, loss of data or any commercial
+damage, even if the Licensor has been advised of the possibility of such
+damage. However, the Licensor will be liable under statutory product liability
+laws as far such laws apply to the Work.
+
+9. Additional agreements
+
+While distributing the Work, You may choose to conclude an additional
+agreement, defining obligations or services consistent with this Licence.
+However, if accepting obligations, You may act only on your own behalf and on
+your sole responsibility, not on behalf of the original Licensor or any other
+Contributor, and only if You agree to indemnify, defend, and hold each
+Contributor harmless for any liability incurred by, or claims asserted against
+such Contributor by the fact You have accepted any warranty or additional
+liability.
+
+10. Acceptance of the Licence
+
+The provisions of this Licence can be accepted by clicking on an icon ‘I
+agree’ placed under the bottom of a window displaying the text of this Licence
+or by affirming consent in any other similar way, in accordance with the rules
+of applicable law. Clicking on that icon indicates your clear and irrevocable
+acceptance of this Licence and all of its terms and conditions.
+
+Similarly, you irrevocably accept this Licence and all of its terms and
+conditions by exercising any rights granted to You by Article 2 of this
+Licence, such as the use of the Work, the creation by You of a Derivative Work
+or the Distribution or Communication by You of the Work or copies thereof.
+
+11. Information to the public
+
+In case of any Distribution or Communication of the Work by means of
+electronic communication by You (for example, by offering to download the Work
+from a remote location) the distribution channel or media (for example, a
+website) must at least provide to the public the information requested by the
+applicable law regarding the Licensor, the Licence and the way it may be
+accessible, concluded, stored and reproduced by the Licensee.
+
+12. Termination of the Licence
+
+The Licence and the rights granted hereunder will terminate automatically upon
+any breach by the Licensee of the terms of the Licence. Such a termination
+will not terminate the licences of any person who has received the Work from
+the Licensee under the Licence, provided such persons remain in full
+compliance with the Licence.
+
+13. Miscellaneous
+
+Without prejudice of Article 9 above, the Licence represents the complete
+agreement between the Parties as to the Work.
+
+If any provision of the Licence is invalid or unenforceable under applicable
+law, this will not affect the validity or enforceability of the Licence as a
+whole. Such provision will be construed or reformed so as necessary to make it
+valid and enforceable.
+
+The European Commission may publish other linguistic versions or new versions
+of this Licence or updated versions of the Appendix, so far this is required
+and reasonable, without reducing the scope of the rights granted by the
+Licence. New versions of the Licence will be published with a unique version
+number.
+
+All linguistic versions of this Licence, approved by the European Commission,
+have identical value. Parties can take advantage of the linguistic version of
+their choice.
+
+14. Jurisdiction
+
+Without prejudice to specific agreement between parties,
+— any litigation resulting from the interpretation of this License, arising
+  between the European Union institutions, bodies, offices or agencies, as a
+  Licensor, and any Licensee, will be subject to the jurisdiction of the Court
+  of Justice of the European Union, as laid down in article 272 of the Treaty
+  on the Functioning of the European Union,
+— any litigation arising between other parties and resulting from the
+  interpretation of this License, will be subject to the exclusive
+  jurisdiction of the competent court where the Licensor resides or conducts
+  its primary business.
+
+15. Applicable Law
+
+Without prejudice to specific agreement between parties,
+— this Licence shall be governed by the law of the European Union Member State
+  where the Licensor has his seat, resides or has his registered office,
+— this licence shall be governed by Belgian law if the Licensor has no seat,
+  residence or registered office inside a European Union Member State.
+
+Appendix
+
+‘Compatible Licences’ according to Article 5 EUPL are:
+— GNU General Public License (GPL) v. 2, v. 3
+— GNU Affero General Public License (AGPL) v. 3
+— Open Software License (OSL) v. 2.1, v. 3.0
+— Eclipse Public License (EPL) v. 1.0
+— CeCILL v. 2.0, v. 2.1
+— Mozilla Public Licence (MPL) v. 2
+— GNU Lesser General Public Licence (LGPL) v. 2.1, v. 3
+— Creative Commons Attribution-ShareAlike v. 3.0 Unported (CC BY-SA 3.0) for
+  works other than software
+— European Union Public Licence (EUPL) v. 1.1, v. 1.2
+— Québec Free and Open-Source Licence — Reciprocity (LiLiQ-R) or
+  Strong Reciprocity (LiLiQ-R+)
+
+— The European Commission may update this Appendix to later versions of the
+  above licences without producing a new version of the EUPL, as long as they
+  provide the rights granted in Article 2 of this Licence and protect the
+  covered Source Code from exclusive appropriation.
+— All other changes or additions to this Appendix require the production of a
+  new EUPL version.

seastats-0.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.1
+Name: seastats
+Version: 0.1.0
+Summary: package for metocean statistics
+Home-page: https://github.com/oceanmodeling/seastats.git
+License: EUPL-1.2
+Author: tomsail
+Author-email: saillour.thomas@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Other Environment
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: European Union Public Licence 1.2 (EUPL 1.2)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Dist: numpy
+Requires-Dist: pandas[performance,pyarrow]
+Requires-Dist: pyextremes
+Project-URL: Repository, https://github.com/oceanmodeling/seastats.git
+Description-Content-Type: text/markdown
+
+# SeaStats
+
+`seastats` is a simple package to compare and analyse 2 time series. We use the following convention in this repo:
+ * `sim`: modelled surge time series
+ * `mod`: observed surge time series
+
+The main function is:
+
+```python
+def get_stats(
+    sim: Series,
+    obs: Series,
+    metrics: Sequence[str] = SUGGESTED_METRICS,
+    quantile: float = 0,
+    cluster: int = 72,
+    round: int = -1
+) -> dict[str, float]
+```
+Calculates various statistical metrics between the simulated and observed time series data.
+## Parameters:
+ * **sim** (pd.Series). The simulated time series data.
+ * **obs** (pd.Series). The observed time series data.
+ * **metrics** (list[str]). (Optional) The list of statistical metrics to calculate. If metrics = ["all"], all items in `SUPPORTED_METRICS` will be calculated. Default is all items in `SUGGESTED_METRICS`.
+ * **quantile** (float). (Optional) Quantile used to calculate the metrics. Default is `0` (no selection)
+ * **cluster** (int). (Optional) Cluster duration for grouping storm events. Default is `72` hours.
+ * **round** (int). (Optional) Apply rounding to the results to. Default is no rounding (value is `-1`)
+
+Returns a dictionary containing the calculated metrics and their corresponding values. With 2 types of metrics:
+* [The "general" metrics](#general-metrics): All the basic metrics needed for signal comparison (RMSE, RMS, Correlation etc..). See details below
+  * `bias`: Bias
+  * `rmse`: Root Mean Square Error
+  * `rms`: Root Mean Square
+  * `rms_95`: Root Mean Square for data points above 95th percentile
+  * `sim_mean`: Mean of simulated values
+  * `obs_mean`: Mean of observed values
+  * `sim_std`: Standard deviation of simulated values
+  * `obs_std`: Standard deviation of observed values
+  * `mae`: Mean Absolute Error
+  * `mse`: Mean Square Error
+  * `nse`: Nash-Sutcliffe Efficiency
+  * `lamba`: Lambda index
+  * `cr`: Pearson Correlation coefficient
+  * `cr_95`: Pearson Correlation coefficient for data points above 95th percentile
+  * `slope`: Slope of Model/Obs correlation
+  * `intercept`: Intercept of Model/Obs correlation
+  * `slope_pp`: Slope of Model/Obs correlation of percentiles
+  * `intercept_pp`: Intercept of Model/Obs correlation of percentiles
+  * `mad`: Mean Absolute Deviation
+  * `madp`: Mean Absolute Deviation of percentiles
+  * `madc`: `mad + madp`
+  * `kge`: Kling–Gupta Efficiency
+* [The storm metrics](#storm-metrics): a PoT selection is done on the observed signal (using the `match_extremes()` function). Function returns the decreasing extreme event peak values for observed and modeled signals (and time lag between events). See details below.
+  * `R1`: Difference between observed and modelled for the biggest storm
+  * `R1_norm`: Normalized R1 (R1 divided by observed value)
+  * `R3`: Average difference between observed and modelled for the three biggest storms
+  * `R3_norm`: Normalized R3 (R3 divided by observed value)
+  * `error`: Average difference between observed and modelled for all storms
+  * `error_norm`: Normalized error (error divided by observed value)
+
+## General metrics
+### A. Dimensional Statistics:
+#### Mean Error (or Bias)
+$$\langle x_c - x_m \rangle = \langle x_c \rangle - \langle x_m \rangle$$
+#### RMSE (Root Mean Squared Error)
+$$\sqrt{\langle(x_c - x_m)^2\rangle}$$
+#### Mean-Absolute Error (MAE):
+$$\langle |x_c - x_m| \rangle$$
+### B. Dimentionless Statistics (best closer to 1)
+
+#### Performance Scores (PS) or Nash-Sutcliffe Eff (NSE): $$1 - \frac{\langle (x_c - x_m)^2 \rangle}{\langle (x_m - x_R)^2 \rangle}$$
+#### Correlation Coefficient (R):
+$$\frac {\langle x_{m}x_{c}\rangle -\langle x_{m}\rangle \langle x_{c}\rangle }{{\sqrt {\langle x_{m}^{2}\rangle -\langle x_{m}\rangle ^{2}}}{\sqrt {\langle x_{c}^{2}\rangle -\langle x_{c}\rangle ^{2}}}}$$
+#### Kling–Gupta Efficiency (KGE):
+$$1 - \sqrt{(r-1)^2 + b^2 + (g-1)^2}$$
+with :
+ * `r` the correlation
+ * `b` the modified bias term (see [ref](https://journals.ametsoc.org/view/journals/clim/34/16/JCLI-D-21-0067.1.xml)) $$\frac{\langle x_c \rangle - \langle x_m \rangle}{\sigma_m}$$
+ * `g` the std dev term $$\frac{\sigma_c}{\sigma_m}$$
+
+#### Lambda index ($\lambda$), values closer to 1 indicate better agreement:
+$$\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|$$
+
+## Storm metrics
+The functions uses the `match_extremes()` function (detailed below) and returns:
+ * `R1`: the error for the biggest storm
+ * `R3`: the mean error for the 3 biggest storms
+ * `error`: the mean error for all the storms above the threshold.
+ * `R1_norm`/`R3_norm`/`error`: Same methodology, but values are in normalised (in %) relatively to the observed peaks.
+
+
+### case of NaNs
+The `storm_metrics()` might return:
+```python
+{'R1': np.nan,
+ 'R1_norm': np.nan,
+ 'R3': np.nan,
+ 'R3_norm': np.nan,
+ 'error': np.nan,
+ 'error_norm': np.nan}
+```
+## Extreme events
+
+Example of implementation:
+```python
+from seastats.storms import match_extremes
+extremes_df = match_extremes(sim, obs, 0.99, cluster = 72)
+extremes_df
+```
+The modeled peaks are matched with the observed peaks. Function returns a pd.DataFrame of the decreasing observed storm peaks as follows:
+
+| time observed       |   observed | time observed       |    model | time model          |       diff |     error |   error_norm |   tdiff |
+|:--------------------|-----------:|:--------------------|---------:|:--------------------|-----------:|----------:|-------------:|--------:|
+| 2022-01-29 19:30:00 |   0.803 | 2022-01-29 19:30:00 | 0.565 | 2022-01-29 17:00:00 | -0.237  | 0.237  |    0.296  |    -2.5 |
+| 2022-02-20 20:30:00 |   0.639 | 2022-02-20 20:30:00 | 0.577 | 2022-02-20 20:00:00 | -0.062 | 0.062 |    0.0963 |    -0.5 |
+...
+| 2022-11-27 15:30:00 |   0.386  | 2022-11-27 15:30:00 | 0.400 | 2022-11-27 17:00:00 |  0.014 | 0.014 |    0.036 |     1.5 |
+
+with:
+ * `diff` the difference between modeled and observed peaks
+ * `error` the absolute difference between modeled and observed peaks
+ * `tdiff` the time difference between modeled and observed peaks
+
+NB: the function uses [pyextremes](https://georgebv.github.io/pyextremes/quickstart/) in the background, with PoT method, using the `quantile` value of the observed signal as physical threshold and passes the `cluster_duration` argument.
+
+
+this happens when the function `storms/match_extremes.py` couldn't finc concomitent storms for the observed and modeled time series.
+
+## Usage
+see [notebook](/notebooks/example_abed.ipynb) for details
+
+get all metrics in a 3 liner:
+```python
+from seastats import get_stats, GENERAL_METRICS_ALL, STORM_METRICS_ALL
+general = get_stats(sim, obs, metrics = GENERAL_METRICS)
+storm = get_stats(sim, obs, quantile = 0.99, metrics = STORM_METRICS) # we use a different quantile for PoT selection
+pd.DataFrame(dict(general, **storm), index=['abed'])
+```
+
+|      |   bias |   rmse |   rms |   rms_95 |   sim_mean |   obs_mean |   sim_std |   obs_std |   nse |   lamba |    cr |   cr_95 |   slope |   intercept |   slope_pp |   intercept_pp |   mad |   madp |   madc |   kge |       R1 |   R1_norm |       R3 |   R3_norm |     error |   error_norm |
+|:-----|-------:|-------:|------:|---------:|-----------:|-----------:|----------:|----------:|------:|--------:|------:|--------:|--------:|------------:|-----------:|---------------:|------:|-------:|-------:|------:|---------:|----------:|---------:|----------:|----------:|-------------:|
+| abed | -0.007 |  0.086 | 0.086 |    0.088 |         -0 |      0.007 |     0.142 |     0.144 | 0.677 |   0.929 | 0.817 |   0.542 |   0.718 |      -0.005 |      1.401 |         -0.028 | 0.052 |  0.213 |  0.265 |  0.81 | 0.237364 |  0.295719 | 0.147163 |  0.207019 | 0.0938142 |     0.177533 |
+

seastats-0.1.0/README.md

@@ -0,0 +1,142 @@
+# SeaStats
+
+`seastats` is a simple package to compare and analyse 2 time series. We use the following convention in this repo:
+ * `sim`: modelled surge time series
+ * `mod`: observed surge time series
+
+The main function is:
+
+```python
+def get_stats(
+    sim: Series,
+    obs: Series,
+    metrics: Sequence[str] = SUGGESTED_METRICS,
+    quantile: float = 0,
+    cluster: int = 72,
+    round: int = -1
+) -> dict[str, float]
+```
+Calculates various statistical metrics between the simulated and observed time series data.
+## Parameters:
+ * **sim** (pd.Series). The simulated time series data.
+ * **obs** (pd.Series). The observed time series data.
+ * **metrics** (list[str]). (Optional) The list of statistical metrics to calculate. If metrics = ["all"], all items in `SUPPORTED_METRICS` will be calculated. Default is all items in `SUGGESTED_METRICS`.
+ * **quantile** (float). (Optional) Quantile used to calculate the metrics. Default is `0` (no selection)
+ * **cluster** (int). (Optional) Cluster duration for grouping storm events. Default is `72` hours.
+ * **round** (int). (Optional) Apply rounding to the results to. Default is no rounding (value is `-1`)
+
+Returns a dictionary containing the calculated metrics and their corresponding values. With 2 types of metrics:
+* [The "general" metrics](#general-metrics): All the basic metrics needed for signal comparison (RMSE, RMS, Correlation etc..). See details below
+  * `bias`: Bias
+  * `rmse`: Root Mean Square Error
+  * `rms`: Root Mean Square
+  * `rms_95`: Root Mean Square for data points above 95th percentile
+  * `sim_mean`: Mean of simulated values
+  * `obs_mean`: Mean of observed values
+  * `sim_std`: Standard deviation of simulated values
+  * `obs_std`: Standard deviation of observed values
+  * `mae`: Mean Absolute Error
+  * `mse`: Mean Square Error
+  * `nse`: Nash-Sutcliffe Efficiency
+  * `lamba`: Lambda index
+  * `cr`: Pearson Correlation coefficient
+  * `cr_95`: Pearson Correlation coefficient for data points above 95th percentile
+  * `slope`: Slope of Model/Obs correlation
+  * `intercept`: Intercept of Model/Obs correlation
+  * `slope_pp`: Slope of Model/Obs correlation of percentiles
+  * `intercept_pp`: Intercept of Model/Obs correlation of percentiles
+  * `mad`: Mean Absolute Deviation
+  * `madp`: Mean Absolute Deviation of percentiles
+  * `madc`: `mad + madp`
+  * `kge`: Kling–Gupta Efficiency
+* [The storm metrics](#storm-metrics): a PoT selection is done on the observed signal (using the `match_extremes()` function). Function returns the decreasing extreme event peak values for observed and modeled signals (and time lag between events). See details below.
+  * `R1`: Difference between observed and modelled for the biggest storm
+  * `R1_norm`: Normalized R1 (R1 divided by observed value)
+  * `R3`: Average difference between observed and modelled for the three biggest storms
+  * `R3_norm`: Normalized R3 (R3 divided by observed value)
+  * `error`: Average difference between observed and modelled for all storms
+  * `error_norm`: Normalized error (error divided by observed value)
+
+## General metrics
+### A. Dimensional Statistics:
+#### Mean Error (or Bias)
+$$\langle x_c - x_m \rangle = \langle x_c \rangle - \langle x_m \rangle$$
+#### RMSE (Root Mean Squared Error)
+$$\sqrt{\langle(x_c - x_m)^2\rangle}$$
+#### Mean-Absolute Error (MAE):
+$$\langle |x_c - x_m| \rangle$$
+### B. Dimentionless Statistics (best closer to 1)
+
+#### Performance Scores (PS) or Nash-Sutcliffe Eff (NSE): $$1 - \frac{\langle (x_c - x_m)^2 \rangle}{\langle (x_m - x_R)^2 \rangle}$$
+#### Correlation Coefficient (R):
+$$\frac {\langle x_{m}x_{c}\rangle -\langle x_{m}\rangle \langle x_{c}\rangle }{{\sqrt {\langle x_{m}^{2}\rangle -\langle x_{m}\rangle ^{2}}}{\sqrt {\langle x_{c}^{2}\rangle -\langle x_{c}\rangle ^{2}}}}$$
+#### Kling–Gupta Efficiency (KGE):
+$$1 - \sqrt{(r-1)^2 + b^2 + (g-1)^2}$$
+with :
+ * `r` the correlation
+ * `b` the modified bias term (see [ref](https://journals.ametsoc.org/view/journals/clim/34/16/JCLI-D-21-0067.1.xml)) $$\frac{\langle x_c \rangle - \langle x_m \rangle}{\sigma_m}$$
+ * `g` the std dev term $$\frac{\sigma_c}{\sigma_m}$$
+
+#### Lambda index ($\lambda$), values closer to 1 indicate better agreement:
+$$\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|$$
+
+## Storm metrics
+The functions uses the `match_extremes()` function (detailed below) and returns:
+ * `R1`: the error for the biggest storm
+ * `R3`: the mean error for the 3 biggest storms
+ * `error`: the mean error for all the storms above the threshold.
+ * `R1_norm`/`R3_norm`/`error`: Same methodology, but values are in normalised (in %) relatively to the observed peaks.
+
+
+### case of NaNs
+The `storm_metrics()` might return:
+```python
+{'R1': np.nan,
+ 'R1_norm': np.nan,
+ 'R3': np.nan,
+ 'R3_norm': np.nan,
+ 'error': np.nan,
+ 'error_norm': np.nan}
+```
+## Extreme events
+
+Example of implementation:
+```python
+from seastats.storms import match_extremes
+extremes_df = match_extremes(sim, obs, 0.99, cluster = 72)
+extremes_df
+```
+The modeled peaks are matched with the observed peaks. Function returns a pd.DataFrame of the decreasing observed storm peaks as follows:
+
+| time observed       |   observed | time observed       |    model | time model          |       diff |     error |   error_norm |   tdiff |
+|:--------------------|-----------:|:--------------------|---------:|:--------------------|-----------:|----------:|-------------:|--------:|
+| 2022-01-29 19:30:00 |   0.803 | 2022-01-29 19:30:00 | 0.565 | 2022-01-29 17:00:00 | -0.237  | 0.237  |    0.296  |    -2.5 |
+| 2022-02-20 20:30:00 |   0.639 | 2022-02-20 20:30:00 | 0.577 | 2022-02-20 20:00:00 | -0.062 | 0.062 |    0.0963 |    -0.5 |
+...
+| 2022-11-27 15:30:00 |   0.386  | 2022-11-27 15:30:00 | 0.400 | 2022-11-27 17:00:00 |  0.014 | 0.014 |    0.036 |     1.5 |
+
+with:
+ * `diff` the difference between modeled and observed peaks
+ * `error` the absolute difference between modeled and observed peaks
+ * `tdiff` the time difference between modeled and observed peaks
+
+NB: the function uses [pyextremes](https://georgebv.github.io/pyextremes/quickstart/) in the background, with PoT method, using the `quantile` value of the observed signal as physical threshold and passes the `cluster_duration` argument.
+
+
+this happens when the function `storms/match_extremes.py` couldn't finc concomitent storms for the observed and modeled time series.
+
+## Usage
+see [notebook](/notebooks/example_abed.ipynb) for details
+
+get all metrics in a 3 liner:
+```python
+from seastats import get_stats, GENERAL_METRICS_ALL, STORM_METRICS_ALL
+general = get_stats(sim, obs, metrics = GENERAL_METRICS)
+storm = get_stats(sim, obs, quantile = 0.99, metrics = STORM_METRICS) # we use a different quantile for PoT selection
+pd.DataFrame(dict(general, **storm), index=['abed'])
+```
+
+|      |   bias |   rmse |   rms |   rms_95 |   sim_mean |   obs_mean |   sim_std |   obs_std |   nse |   lamba |    cr |   cr_95 |   slope |   intercept |   slope_pp |   intercept_pp |   mad |   madp |   madc |   kge |       R1 |   R1_norm |       R3 |   R3_norm |     error |   error_norm |
+|:-----|-------:|-------:|------:|---------:|-----------:|-----------:|----------:|----------:|------:|--------:|------:|--------:|--------:|------------:|-----------:|---------------:|------:|-------:|-------:|------:|---------:|----------:|---------:|----------:|----------:|-------------:|
+| abed | -0.007 |  0.086 | 0.086 |    0.088 |         -0 |      0.007 |     0.142 |     0.144 | 0.677 |   0.929 | 0.817 |   0.542 |   0.718 |      -0.005 |      1.401 |         -0.028 | 0.052 |  0.213 |  0.265 |  0.81 | 0.237364 |  0.295719 | 0.147163 |  0.207019 | 0.0938142 |     0.177533 |

seastats-0.1.0/pyproject.toml

@@ -0,0 +1,123 @@
+[tool.poetry]
+name = "seastats"
+version = "0.1.0"
+description = "package for metocean statistics"
+authors = [
+  "tomsail <saillour.thomas@gmail.com>",
+  "pmav99 <pmav99@gmail.com>",
+]
+license = 'EUPL-1.2'
+readme = "README.md"
+repository = "https://github.com/oceanmodeling/seastats.git"
+classifiers = [
+    "Operating System :: OS Independent",
+    "Development Status :: 4 - Beta",
+    "Environment :: Other Environment",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Physics",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+numpy = "*"
+pandas = {version = "*", extras = ["pyarrow", "performance"]}
+pyextremes = "*"
+
+[tool.poetry.group.dev.dependencies]
+covdefaults = "*"
+hvplot = "*"
+ipykernel = "*"
+mypy = "*"
+pytest = "*"
+pytest-cov = "*"
+pandas-stubs = "*"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.mypy]
+python_version = "3.10"
+plugins = [
+    "numpy.typing.mypy_plugin"
+]
+# ignore_missing_imports = true
+show_column_numbers = true
+show_error_codes = true
+show_error_context = true
+warn_no_return = true
+warn_redundant_casts = true
+warn_return_any = true
+warn_unreachable = true
+warn_unused_ignores = true
+strict = true
+disable_error_code = [ ]
+enable_error_code = [
+  "comparison-overlap",
+  "explicit-override",
+  "ignore-without-code",
+  "no-any-return",
+  "no-any-unimported",
+  "no-untyped-call",
+  "no-untyped-def",
+  "possibly-undefined",
+  "redundant-cast",
+  "redundant-expr",
+  "redundant-self",
+  "truthy-bool",
+  "truthy-iterable",
+  "type-arg",
+  "unimported-reveal",
+  "unreachable",
+  "unused-ignore",
+]
+
+# mypy per-module options:
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = true
+
+[tool.ruff]
+target-version = "py310"
+line-length = 108
+lint.select = [
+    "E",  # pycodestyle
+    "F",  # pyflakes
+    "C90",  # mccabe
+    "A",  # flake8-builtins
+    "COM",  # flake8-commas
+    # "UP",  # pyupgrade
+    # "YTT",  # flake-2020
+    # "S",  # floke8-bandit
+    # "BLE",  # flake8-blind-except
+    # "B",  # flake8-bugbear
+    # "T20",  # flake8-print
+    # "PD",  # pandas-vet
+    # "NPY",  # numpy-specific rules
+    # "RUF",  # ruff-specific rules
+    # "D",  # pydocstyle
+    # "I",  # isort
+    # "N",  # pep8-naming
+]
+lint.ignore = [
+    "E501", # line-too-long
+    "D103",  # undocumented-public-function
+    "PD901",  # pandas-df-variable-name
+]
+
+[tool.coverage.run]
+plugins = ["covdefaults"]
+source = ["seastats"]
+omit = []
+parallel = true
+sigterm = true
+
+[tool.coverage.report]
+fail_under = 86.8

seastats-0.1.0/seastats/__init__.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+import logging
+from collections.abc import Sequence
+
+import numpy as np
+import pandas as pd
+
+from seastats.stats import get_bias
+from seastats.stats import get_corr
+from seastats.stats import get_kge
+from seastats.stats import get_lambda
+from seastats.stats import get_mad
+from seastats.stats import get_madc
+from seastats.stats import get_madp
+from seastats.stats import get_mae
+from seastats.stats import get_mse
+from seastats.stats import get_nse
+from seastats.stats import get_rms
+from seastats.stats import get_rmse
+from seastats.stats import get_slope_intercept
+from seastats.stats import get_slope_intercept_pp
+from seastats.storms import match_extremes
+
+logger = logging.getLogger(__name__)
+
+GENERAL_METRICS_ALL = [
+    "bias",
+    "rmse",
+    "mae",
+    "mse",
+    "rms",
+    "sim_mean",
+    "obs_mean",
+    "sim_std",
+    "obs_std",
+    "nse",
+    "lamba",
+    "cr",
+    "slope",
+    "intercept",
+    "slope_pp",
+    "intercept_pp",
+    "mad",
+    "madp",
+    "madc",
+    "kge",
+]
+GENERAL_METRICS = ["bias", "rms", "rmse", "cr", "nse", "kge"]
+STORM_METRICS = ["R1", "R3", "error"]
+STORM_METRICS_ALL = ["R1", "R1_norm", "R3", "R3_norm", "error", "error_norm"]
+
+SUGGESTED_METRICS = sorted(GENERAL_METRICS + STORM_METRICS)
+SUPPORTED_METRICS = sorted(GENERAL_METRICS_ALL + STORM_METRICS_ALL)
+
+
+def get_stats(
+    sim: pd.Series[float],
+    obs: pd.Series[float],
+    metrics: Sequence[str] = SUGGESTED_METRICS,
+    quantile: float = 0,
+    cluster: int = 72,
+    round: int = -1,  # noqa: A002
+) -> dict[str, float]:
+    """
+    Calculates various statistical metrics between the simulated and observed time series data.
+
+    :param pd.Series sim: The simulated time series data.
+    :param pd.Series obs: The observed time series data.
+    :param list[str] metrics: (Optional) The list of statistical metrics to calculate. If metrics = ["all"], all items in SUPPORTED_METRICS will be calculated. Default is all items in SUGGESTED_METRICS.
+    :param float quantile: (Optional) Quantile used to calculate the metrics. Default is 0 (no selection)
+    :param int cluster: (Optional) Cluster duration for grouping storm events. Default is 72 hours.
+    :param int round: (Optional) Apply rounding to the results to. Default is no rounding (value is -1)
+
+    :return dict stats: dictionary containing the calculated metrics.
+
+    The dictionary contains the following keys and their corresponding values:
+
+    - `bias`: The bias between the simulated and observed time series data.
+    - `rmse`: The Root Mean Square Error between the simulated and observed time series data.
+    - `mae`: The Mean Absolute Error the simulated and observed time series data.
+    - `mse`: The Mean Square Error the simulated and observed time series data.
+    - `rms`: The raw mean square error between the simulated and observed time series data.
+    - `sim_mean`: The mean of the simulated time series data.
+    - `obs_mean`: The mean of the observed time series data.
+    - `sim_std`: The standard deviation of the simulated time series data.
+    - `obs_std`: The standard deviation of the observed time series data.
+    - `nse`: The Nash-Sutcliffe efficiency between the simulated and observed time series data.
+    - `lamba`: The lambda statistic between the simulated and observed time series data.
+    - `cr`: The correlation coefficient between the simulated and observed time series data.
+    - `slope`: The slope of the linear regression between the simulated and observed time series data.
+    - `intercept`: The intercept of the linear regression between the simulated and observed time series data.
+    - `slope_pp`: The slope of the linear regression between the percentiles of the simulated and observed time series data.
+    - `intercept_pp`: The intercept of the linear regression between the percentiles of the simulated and observed time series data.
+    - `mad`: The median absolute deviation of the simulated time series data from its median.
+    - `madp`: The median absolute deviation of the simulated time series data from its median, calculated using the percentiles of the observed time series data.
+    - `madc`: The median absolute deviation of the simulated time series data from its median, calculated by adding `mad` to `madp`
+    - `kge`: The Kling-Gupta efficiency between the simulated and observed time series data.
+    - `R1`: Difference between observed and modelled for the biggest storm
+    - `R1_norm`: Normalized R1 (R1 divided by observed value)
+    - `R3`: Average difference between observed and modelled for the three biggest storms
+    - `R3_norm`: Normalized R3 (R3 divided by observed value)
+    - `error`: Average difference between observed and modelled for all storms
+    - `error_norm`: Normalized error (error divided by observed value)
+    """
+    if not isinstance(metrics, list):
+        raise ValueError("metrics must be a list")
+
+    if metrics == ["all"]:
+        metrics = SUPPORTED_METRICS
+
+    if not np.any([m in SUPPORTED_METRICS for m in metrics]):
+        raise ValueError("metrics must be a list of supported variables in SUPPORTED_METRICS or ['all']")
+
+    # Storm metrics part with PoT Selection
+    if np.any([m in STORM_METRICS_ALL for m in metrics]):
+        extreme_df = match_extremes(sim, obs, quantile=quantile, cluster=cluster)
+    else:
+        extreme_df = pd.DataFrame()  # Just to make mypy happy
+
+    if quantile:  # signal subsetting is only to be done on general metrics
+        sim = sim[sim > sim.quantile(quantile)]
+        obs = obs[obs > obs.quantile(quantile)]
+
+    stats = {}
+
+    for metric in metrics:
+        match metric:
+            case "bias":
+                stats["bias"] = get_bias(sim, obs)
+            case "rmse":
+                stats["rmse"] = get_rmse(sim, obs)
+            case "rms":
+                stats["rms"] = get_rms(sim, obs)
+            case "sim_mean":
+                stats["sim_mean"] = sim.mean()
+            case "obs_mean":
+                stats["obs_mean"] = obs.mean()
+            case "sim_std":
+                stats["sim_std"] = sim.std()
+            case "obs_std":
+                stats["obs_std"] = obs.std()
+            case "mae":
+                stats["mae"] = get_mae(sim, obs)
+            case "mse":
+                stats["mse"] = get_mse(sim, obs)
+            case "nse":
+                stats["nse"] = get_nse(sim, obs)
+            case "lamba":
+                stats["lamba"] = get_lambda(sim, obs)
+            case "cr":
+                stats["cr"] = get_corr(sim, obs)
+            case "slope":
+                stats["slope"], _ = get_slope_intercept(sim, obs)
+            case "intercept":
+                _, stats["intercept"] = get_slope_intercept(sim, obs)
+            case "slope_pp":
+                stats["slope_pp"], _ = get_slope_intercept_pp(sim, obs)
+            case "intercept_pp":
+                _, stats["intercept_pp"] = get_slope_intercept_pp(sim, obs)
+            case "mad":
+                stats["mad"] = get_mad(sim, obs)
+            case "madp":
+                stats["madp"] = get_madp(sim, obs)
+            case "madc":
+                stats["madc"] = get_madc(sim, obs)
+            case "kge":
+                stats["kge"] = get_kge(sim, obs)
+            case "R1":
+                stats["R1"] = extreme_df["error"].iloc[0]
+            case "R1_norm":
+                stats["R1_norm"] = extreme_df["error_norm"].iloc[0]
+            case "R3":
+                stats["R3"] = extreme_df["error"].iloc[0:3].mean()
+            case "R3_norm":
+                stats["R3_norm"] = extreme_df["error_norm"].iloc[0:3].mean()
+            case "error":
+                stats["error"] = extreme_df["error"].mean()
+            case "error_norm":
+                stats["error_norm"] = extreme_df["error_norm"].mean()
+    else:
+        logger.info("no storm metric specified")
+
+    if round > 0:
+        for metric in metrics:
+            stats[metric] = np.round(stats[metric], round)
+
+    return stats

seastats-0.1.0/seastats/stats.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+import logging
+
+import numpy as np
+import pandas as pd
+
+logger = logging.getLogger(__name__)
+
+
+def get_bias(sim: pd.Series[float], obs: pd.Series[float]) -> float:
+    return float(sim.mean() - obs.mean())
+
+
+def get_mse(sim: pd.Series[float], obs: pd.Series[float]) -> float:
+    return float(np.square(np.subtract(obs, sim)).mean())
+
+
+def get_rmse(sim: pd.Series[float], obs: pd.Series[float]) -> float:
+    return float(np.sqrt(get_mse(sim, obs)))
+
+
+def get_mae(sim: pd.Series[float], obs: pd.Series[float]) -> float:
+    return float(np.abs(np.subtract(obs, sim)).mean())
+
+
+def get_mad(sim: pd.Series[float], obs: pd.Series[float]) -> float:
+    return float(np.abs(np.subtract(obs, sim)).std())
+
+
+def get_madp(sim: pd.Series[float], obs: pd.Series[float]) -> float:
+    pc1, pc2 = get_percentiles(sim, obs)
+    return get_mad(pc1, pc2)
+
+
+def get_madc(sim: pd.Series[float], obs: pd.Series[float]) -> float:
+    madp = get_madp(sim, obs)
+    return get_mad(sim, obs) + madp
+
+
+def get_rms(sim: pd.Series[float], obs: pd.Series[float]) -> float:
+    crmsd = ((sim - sim.mean()) - (obs - obs.mean())) ** 2
+    return float(np.sqrt(crmsd.mean()))
+
+
+def get_corr(sim: pd.Series[float], obs: pd.Series[float]) -> float:
+    return float(sim.corr(obs))
+
+
+def get_nse(sim: pd.Series[float], obs: pd.Series[float]) -> float:
+    nse = 1 - np.nansum(np.subtract(obs, sim) ** 2) / np.nansum((obs - float(np.nanmean(obs))) ** 2)
+    return float(nse)
+
+
+def get_lambda(sim: pd.Series[float], obs: pd.Series[float]) -> float:
+    Xmean = float(np.nanmean(obs))
+    Ymean = float(np.nanmean(sim))
+    nObs = len(obs)
+    corr = get_corr(sim, obs)
+    if corr >= 0:
+        kappa = 0
+    else:
+        kappa = 2 * abs(np.nansum((obs - Xmean) * (sim - Ymean)))
+
+    numerator = np.nansum((obs - sim) ** 2)
+    denominator = (
+        np.nansum((obs - Xmean) ** 2)
+        + np.nansum((sim - Ymean) ** 2)
+        + nObs * ((Xmean - Ymean) ** 2)
+        + kappa
+    )
+    lambda_index = 1 - numerator / denominator
+    return float(lambda_index)
+
+
+def get_kge(sim: pd.Series[float], obs: pd.Series[float]) -> float:
+    corr = get_corr(sim, obs)
+    b = (sim.mean() - obs.mean()) / obs.std()
+    g = sim.std() / obs.std()
+    return float(1 - np.sqrt((corr - 1) ** 2 + b**2 + (g - 1) ** 2))
+
+
+def truncate_seconds(ts: pd.Series[float]) -> pd.Series[float]:
+    df = pd.DataFrame({"time": ts.index, "value": ts.values})
+    df = df.assign(time=df.time.dt.floor("min"))
+    if df.time.duplicated().any():
+        # There are duplicates. Keep the first datapoint per minute.
+        msg = "Duplicate timestamps have been detected after the truncation of seconds. Keeping the first datapoint per minute"
+        logger.warning(msg)
+        df = df.iloc[df.time.drop_duplicates().index].reset_index(drop=True)
+    df.index = df.time  # type: ignore[assignment]
+    df = df.drop("time", axis=1)
+    ts = pd.Series(index=df.index, data=df.value)
+    return ts
+
+
+def align_ts(
+    sim: pd.Series[float],
+    obs: pd.Series[float],
+    resample_to_model: bool = True,
+) -> tuple[pd.Series[float], pd.Series[float]]:
+    # requisite: obs is the observation time series
+    obs = obs.dropna()
+    obs = truncate_seconds(obs)
+    if resample_to_model:
+        freq = sim.index.to_series().diff().median()
+        obs = obs.resample(pd.Timedelta(freq)).mean()
+    sim_, obs_ = sim.align(obs, axis=0)
+    nan_mask1 = pd.isna(sim_)
+    nan_mask2 = pd.isna(obs_)
+    nan_mask = np.logical_or(nan_mask1, nan_mask2)
+    sim_ = sim_[~nan_mask]
+    obs_ = obs_[~nan_mask]
+    return sim_, obs_
+
+
+def get_percentiles(
+    sim: pd.Series[float],
+    obs: pd.Series[float],
+    higher_tail: bool = False,
+) -> tuple[pd.Series[float], pd.Series[float]]:
+    x = np.arange(0, 0.99, 0.01)
+    if higher_tail:
+        x = np.hstack([x, np.arange(0.99, 1, 0.001)])
+
+    pc_sim = sim.quantile(x).to_numpy()
+    pc_obs = obs.quantile(x).to_numpy()
+
+    return pd.Series(pc_sim), pd.Series(pc_obs)
+
+
+def get_slope_intercept(sim: pd.Series[float], obs: pd.Series[float]) -> tuple[float, float]:
+    # Calculate means of x and y
+    x_mean = float(np.mean(obs))
+    y_mean = float(np.mean(sim))
+
+    numerator = np.sum((obs - x_mean) * (sim - y_mean))
+    denominator = np.sum((obs - x_mean) ** 2)
+
+    # Calculate slope (A) and intercept (B) in A*X + B
+    slope = numerator / denominator
+    intercept = y_mean - slope * x_mean
+    return slope, intercept
+
+
+def get_slope_intercept_pp(sim: pd.Series[float], obs: pd.Series[float]) -> tuple[float, float]:
+    pc1, pc2 = get_percentiles(sim, obs)
+    slope, intercept = get_slope_intercept(pc1, pc2)
+    return slope, intercept

seastats-0.1.0/seastats/storms.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import typing as T
+
+import numpy as np
+import pandas as pd
+from pyextremes import get_extremes
+
+
+def match_extremes(
+    sim: pd.Series[float],
+    obs: pd.Series[float],
+    quantile: float,
+    cluster: int = 72,
+) -> pd.DataFrame:
+    """
+    Calculate metrics for comparing simulated and observed storm events.
+    Parameters:
+    - sim (pd.Series): Simulated storm series.
+    - obs (pd.Series): Observed storm series.
+    - quantile (float): Quantile value for defining extreme events.
+    - cluster (int, optional): Cluster duration for grouping storm events. Default is 72 hours.
+
+    Returns:
+    - df: pd.DataFrame of the matched extremes between the observed and modeled pd.Series.
+          with following columns:
+           * `observed`: observed extreme event value
+           * `time observed`: observed extreme event time
+           * `model`: modeled extreme event value
+           * `time model`: modeled extreme event time
+           * `diff`: difference between model and observed
+           * `error`: absolute difference between model and observed
+           * `error_norm`: normalised difference between model and observed
+           * `tdiff`: time difference between model and observed (in hours)
+
+    !Important: The modeled values are matched on the observed events calculated by POT analysis.
+                The user needs to be mindful about the order of the observed and modeled pd.Series.
+    """
+    # resample observation to 1H time series
+    obs = obs.resample("1h").mean().shift(freq="30min")
+    # get observed extremes
+    ext = get_extremes(obs, "POT", threshold=obs.quantile(quantile), r=f"{cluster}h")
+    ext_values_dict: dict[str, T.Any] = {}
+    ext_values_dict["observed"] = ext.values
+    ext_values_dict["time observed"] = ext.index.values
+    #
+    max_in_window = []
+    tmax_in_window = []
+    # match simulated values with observed events
+    for it, itime in enumerate(ext.index):
+        snippet = sim[itime - pd.Timedelta(hours=cluster / 2) : itime + pd.Timedelta(hours=cluster / 2)]
+        try:
+            tmax_in_window.append(snippet.index[int(snippet.argmax())])
+            max_in_window.append(snippet.max())
+        except Exception:
+            tmax_in_window.append(itime)
+            max_in_window.append(np.nan)
+    ext_values_dict["model"] = max_in_window
+    ext_values_dict["time model"] = tmax_in_window
+    #
+    df = pd.DataFrame(ext_values_dict)
+    df = df.dropna(subset="model")
+    df = df.sort_values("observed", ascending=False)
+    df["diff"] = df["model"] - df["observed"]
+    df["error"] = abs(df["diff"])
+    df["error_norm"] = abs(df["diff"] / df["observed"])
+    df["tdiff"] = df["time model"] - df["time observed"]
+    df["tdiff"] = df["tdiff"].apply(lambda x: x.total_seconds() / 3600)
+    df = df.set_index("time observed")
+    return df