check
=====

.. py:module:: pastas.check

.. autoapi-nested-parse::

   This module provides functions for checking Pastas models and their components.

   This can be useful to define checks that can be applied to multiple models to ensure
   they meet certain criteria.

   .. rubric:: Examples

   Run a checklist of standard checks on a Pastas model::

       checks = [
           {"func": rsq_geq_threshold, "threshold": 0.7},
           {"func": response_memory, "cutoff": 0.95, "factor_length_oseries": 0.5},
           {"func": uncertainty_gain, "n_std": 1.96},
           {"func": parameter_bounds},
       ]

       ps.check.checklist(ml, checks)

   Or use a list of checks defined in literature. Note that these checks were derived for
   specific questions and hydrogeological contexts and are included as inspiration, but
   are by no means exhaustive or applicable to all problems.

   Checklists can be obtained with::

       checks = ps.check.get_checks_literature("brakenhoff_2022")
       ps.check.checklist(ml, checks=checks)

   Checks
   ------
   The following checks built-in checks are available in this module:

    - stat_ufunc_threshold: model statistic compared to threshold using ufunc
    - rsq_geq_threshold: R^2 greater equal than threshold
    - parameter_ufunc_threshold: single parameter value compared to threshold using ufunc
    - parameters_leq_threshold: parameter values less equal than threshold
    - response_memory: memory of response functions less than fraction of calibration
      period
    - response_memory_vs_warmup: memory of response functions less than warmup period
    - uncertainty_gain: estimated gain less than n_std times std. deviation of the gain
    - uncertainty_parameters: estimated parameter value less than n_std times std.
      deviation
    - parameter_bounds: parameter optimal values not on bounds
    - acf_runs_test: check for significant autocorrelation in the noise using runs test
    - acf_stoffer_toloi_test: check for significant autocorrelation in the noise using
      Stoffer-Toloi test
    - acf_ljung_box_test: check for significant autocorrelation in the noise using
      Ljung-Box test (regular timesteps)
    - correlation_sim_vs_res: correlation between simulated and residuals less than
      threshold

   Checklists
   ----------
   The following predefined checklists are available in this module, available via
   the `get_checks_literature()` function:

    - brakenhoff_2022: checklist based on Brakenhoff et al. (2022)
    - zaadnoordijk_2019: checklist based on Zaadnoordijk et al. (2019)

   ..
       !! processed by numpydoc !!


Functions
---------

.. toctree::
   :hidden:

   /api/pastas/check/get_empty_check_dataframe
   /api/pastas/check/stat_ufunc_threshold
   /api/pastas/check/rsq_geq_threshold
   /api/pastas/check/response_memory
   /api/pastas/check/response_memory_vs_warmup
   /api/pastas/check/uncertainty_gain
   /api/pastas/check/parameter_ufunc_threshold
   /api/pastas/check/parameters_leq_threshold
   /api/pastas/check/parameter_bounds
   /api/pastas/check/uncertainty_parameters
   /api/pastas/check/guess_unit_or_dims
   /api/pastas/check/acf_runs_test
   /api/pastas/check/acf_stoffer_toloi_test
   /api/pastas/check/acf_ljung_box_test
   /api/pastas/check/correlation_sim_vs_res
   /api/pastas/check/checklist
   /api/pastas/check/print_check_report
   /api/pastas/check/get_checks_literature

.. autoapisummary::

   pastas.check.get_empty_check_dataframe
   pastas.check.stat_ufunc_threshold
   pastas.check.rsq_geq_threshold
   pastas.check.response_memory
   pastas.check.response_memory_vs_warmup
   pastas.check.uncertainty_gain
   pastas.check.parameter_ufunc_threshold
   pastas.check.parameters_leq_threshold
   pastas.check.parameter_bounds
   pastas.check.uncertainty_parameters
   pastas.check.guess_unit_or_dims
   pastas.check.acf_runs_test
   pastas.check.acf_stoffer_toloi_test
   pastas.check.acf_ljung_box_test
   pastas.check.correlation_sim_vs_res
   pastas.check.checklist
   pastas.check.print_check_report
   pastas.check.get_checks_literature