5.13.3-dev0
mHM
The mesoscale Hydrological Model
Loading...
Searching...
No Matches
Functions/Subroutines
mo_mrm_signatures Module Reference
mRM - Fortran modules

Module with calculations for several hydrological signatures. More...

Functions/Subroutines

real(dp) function, dimension(size(lags, 1)), public autocorrelation (data, lags, mask)
 Autocorrelation of a given data series.
 
real(dp) function, dimension(size(quantiles, 1)), public flowdurationcurve (data, quantiles, mask, concavity_index, mid_segment_slope, mhigh_segment_volume, high_segment_volume, low_segment_volume)
 Flow duration curves.
 
subroutine, public limb_densities (data, mask, rld, dld)
 Calculates limb densities.
 
real(dp) function maximummonthlyflow (data, mask, yr_start, mo_start, dy_start)
 Maximum of average flows per months.
 
subroutine, public moments (data, mask, mean_data, stddev_data, median_data, max_data, mean_log, stddev_log, median_log, max_log)
 Moments of data and log-transformed data, e.g.
 
real(dp) function, dimension(size(quantiles, 1)), public peakdistribution (data, quantiles, mask, slope_peak_distribution)
 Calculates the peak distribution.
 
real(dp) function, public runoffratio (data, domain_area, mask, precip_series, precip_sum, log_data)
 Runoff ratio (accumulated daily discharge [mm/d] / accumulated daily precipitation [mm/d]).
 
real(dp) function, public zeroflowratio (data, mask)
 Ratio of zero values to total number of data points.
 

Detailed Description

Module with calculations for several hydrological signatures.

This module contains calculations for hydrological signatures.

It contains:

  • Autocorrelation
  • Rising and declining limb densities
  • Flow duration curves
  • Peak distribution
    Authors
    Remko Nijzink,
    Date
    March 2014
    Copyright
    Copyright 2005-2025 , the mHM Developers, Luis Samaniego, Sabine Attinger: All rights reserved. mHM is released under the LGPLv3+ license


    The UFZ(CHS) mesoscale hydrologic model mHM is free software. You can redistribute it and/or modify it under the terms of the GNU General Public License as published by the free Software Foundation either version 3 of the License, or (at your option) any later version.

    This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

    You received a copy of the GNU Lesser General Public License along with the UFZ CHS mesoscale hydrologic model mHM. It can be found in the files COPYING and COPYING.LESSER provided with this software. The complete GNU license text can also be found at http://www.gnu.org/licenses/.

Function/Subroutine Documentation

◆ autocorrelation()

real(dp) function, dimension(size(lags, 1)), public mo_mrm_signatures::autocorrelation ( real(dp), dimension(:), intent(in) data,
integer(i4), dimension(:), intent(in) lags,
logical, dimension(size(data, 1)), intent(in), optional mask )

Autocorrelation of a given data series.

Calculates the autocorrelation of a data series at given lags. An optional argument for masking data points can be given. The function is basically a wrapper of the function autocorr from the module mo_corr. An optional mask of data points can be specified. ADDITIONAL INFORMATION Used as hydrologic signature with lag 1 in Euser, T., Winsemius, H. C., Hrachowitz, M., Fenicia, F., Uhlenbrook, S., & Savenije, H. H. G. (2013). A framework to assess the realism of model structures using hydrological signatures. Hydrology and Earth System Sciences, 17(5), 1893-1912. doi:10.5194/hess-17-1893-2013

Parameters
[in]real(dp), dimension(:) :: dataArray of data
[in]integer(i4), dimension(:) :: lagsArray of lags where autocorrelation is requested
[in]logical, dimension(size(data, 1)), optional :: maskMask for data points givenWorks only with 1d double precision input data.
Authors
Juliane Mai
Date
Jun 2015

Definition at line 72 of file mo_mrm_signatures.f90.

References autocorrelation().

Referenced by autocorrelation().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ flowdurationcurve()

real(dp) function, dimension(size(quantiles, 1)), public mo_mrm_signatures::flowdurationcurve ( real(dp), dimension(:), intent(in) data,
real(dp), dimension(:), intent(in) quantiles,
logical, dimension(:), intent(in), optional mask,
real(dp), intent(out), optional concavity_index,
real(dp), intent(out), optional mid_segment_slope,
real(dp), intent(out), optional mhigh_segment_volume,
real(dp), intent(out), optional high_segment_volume,
real(dp), intent(out), optional low_segment_volume )

Flow duration curves.

Calculates the flow duration curves for a given data vector. The Flow duration curve at a certain quantile x is the data point p where x% of the data points are above the value p. Hence the function percentile of the module mo_percentile is used. But percentile is determining the point p where x% of the data points are below that value. Therfore, the given quantiles are transformed by (1.0-quantile) to get the percentiles of exceedance probabilities. Optionally, the concavity index CI can be calculated [Zhang2014]. CI is defined by

\[ CI = \frac{q_{10\%}-q_{99\%}}{q_{1\%}-q_{99\%}} \]

where \( q_{x} \) is the data point where x% of the data points are above that value. Hence, exceedance probabilities are used. Optionally, the FDC mid-segment slope \(FDC_{MSS}\) as used by Shafii et. al (2014) can be returned. The \(FDC_{MSS}\) is defined as

\[ FDC_{MSS} = \log(q_{m_1})-\log(q_{m_2}) \]

where \( m_1 \) and \( m_2 \) are the lowest and highest flow exceedance probabilities within the midsegment of FDC. The settings \(m_1=0.2\) and \(0.7\) are used by Shafii et. al (2014) and are implemented like that. Optionally, the FDC medium high-segment volume \(FDC_{MHSV}\) as used by Shafii et. al (2014) can be returned. The \(FDC_{MHSV}\) is defined as

\[ FDC_{MHSV} = \sum_{h=1}^{H} q_h \]

where \( h=1,2,...,H \) are flow indeces located within the high-flow segment (exceedance probabilities lower than \(m_1\)). \(H\) is the index of the maximum flow. The settings \(m_1=0.2\) is used here to be consistent with the definitions of the low-segment (0.7-1.0) and the mid-segment (0.2-0.7). Optionally, the FDC high-segment volume \(FDC_{HSV}\) as used by Shafii et. al (2014) can be returned. The \(FDC_{HSV}\) is defined as

\[ FDC_{HSV} = \sum_{h=1}^{H} q_h \]

where \( h=1,2,...,H \) are flow indeces located within the high-flow segment (exceedance probabilities lower than \(m_1\)). \(H\) is the index of the maximum flow. The settings \(m_1=0.02\) is used by Shafii et. al (2014) and is implemented like that. Optionally, the FDC low-segment volume \(FDC_{LSV}\) as used by Shafii et. al (2014) can be returned. The \(FDC_{LSV}\) is defined as

\[ FDC_{LSV} = -\sum_{l=1}^{L} (\log(q_l) - \log(q_L)) \]

where \( l=1,2,...,L \) are flow indeces located within the low-flow segment (exceedance probabilities larger than \(m_1\)). \(L\) is the index of the minimum flow. The settings \(m_1=0.7\) is used by Shafii et. al (2014) and is implemented like that. An optional mask of data points can be specified. ADDITIONAL INFORMATION Thresholds in mid_segment_slope, mhigh_segment_volume, high_segment_volume, low_segment_volume are hard coded. FDC is used as hydrologic signature (quantiles not specified) in Euser, T., Winsemius, H. C., Hrachowitz, M., Fenicia, F., Uhlenbrook, S., & Savenije, H. H. G. (2013). A framework to assess the realism of model structures using hydrological signatures. Hydrology and Earth System Sciences, 17(5), 1893-1912. doi:10.5194/hess-17-1893-2013 Concavity Index used as hydrologic signature in Zhang, Y., Vaze, J., Chiew, F. H. S., Teng, J., & Li, M. (2014). Predicting hydrological signatures in ungauged catchments using spatial interpolation, index model, and rainfall-runoff modelling. Journal of Hydrology, 517(C), 936-948. doi:10.1016/j.jhydrol.2014.06.032 Concavity index is defined using exceedance probabilities by Sauquet, E., & Catalogne, C. (2011). Comparison of catchment grouping methods for flow duration curve estimation at ungauged sites in France. Hydrology and Earth System Sciences, 15(8), 2421-2435. doi:10.5194/hess-15-2421-2011 mid_segment_slope, high_segment_volume, low_segment_volume used as hydrologic signature in Shafii, M., & Tolson, B. A. (2015). Optimizing hydrological consistency by incorporating hydrological signatures into model calibration objectives. Water Resources Research, 51(5), 3796-3814. doi:10.1002/2014WR016520

Parameters
[in]real(dp), dimension(:) :: datadata series
[in]real(dp), dimension(:) :: quantilesPercentages of exceedance (x-axis of FDC)
[in]logical, dimension(:), optional :: maskmask of data array
[out]real(dp), optional :: concavity_indexconcavity index as defined by Sauquet et al. (2011)
[out]real(dp), optional :: mid_segment_slopemid-segment slope as defined by Shafii et al. (2014)
[out]real(dp), optional :: mhigh_segment_volumemedium high-segment volume
[out]real(dp), optional :: high_segment_volumehigh-segment volume as defined by Shafii et al. (2014)
[out]real(dp), optional :: low_segment_volumelow-segment volume as defined by Shafii et al. (2014)
Returns
real(dp), dimension(size(quantiles,1)) :: FlowDurationCurve — Flow Duration Curve value at resp. quantile
Authors
Remko Nijzink, Juliane Mai
Date
March 2014

Definition at line 202 of file mo_mrm_signatures.f90.

References flowdurationcurve().

Referenced by flowdurationcurve(), and mo_mrm_objective_function_runoff::multi_objective_ae_fdc_lsv_nse_djf().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ limb_densities()

subroutine, public mo_mrm_signatures::limb_densities ( real(dp), dimension(:), intent(in) data,
logical, dimension(size(data, 1)), intent(in), optional mask,
real(dp), intent(out), optional rld,
real(dp), intent(out), optional dld )

Calculates limb densities.

Calculates rising and declinging limb densities. The peaks of the given series are first determined by looking for points where preceding and subsequent datapoint are lower. Second, the number of datapoints with rising values (nrise) and declining values (ndecline) are counted basically by comparing neighbors. The duration the data increase (nrise) divided by the number of peaks (npeaks) gives the rising limb density RLD

\[ RLD=t_{rise}/n_{peak} \]

whereas the duration the data decrease (ndecline) divided by the number of peaks (npeaks) gives the declining limb density DLD

\[ DLD=t_{fall}/n_{peak}. \]

An optional mask of data points can be specified. ADDITIONAL INFORMATION Rising limb density used as hydrologic signature in Euser, T., Winsemius, H. C., Hrachowitz, M., Fenicia, F., Uhlenbrook, S., & Savenije, H. H. G. (2013). A framework to assess the realism of model structures using hydrological signatures. Hydrology and Earth System Sciences, 17(5), 1893-1912. doi:10.5194/hess-17-1893-2013

Parameters
[in]real(dp), dimension(:) :: datadata series
[in]logical, dimension(size(data, 1)), optional :: maskmask for data series
[out]real(dp), optional :: RLDrising limb density
[out]real(dp), optional :: DLDdeclining limb density
Authors
Remko Nijzink
Date
March 2014

Definition at line 342 of file mo_mrm_signatures.f90.

◆ maximummonthlyflow()

real(dp) function mo_mrm_signatures::maximummonthlyflow ( real(dp), dimension(:), intent(in) data,
logical, dimension(size(data, 1)), intent(in), optional mask,
integer(i4), intent(in), optional yr_start,
integer(i4), intent(in), optional mo_start,
integer(i4), intent(in), optional dy_start )

Maximum of average flows per months.

Maximum of average flow per month is defined as

\[ max_{monthly flow} = Max( F(i), i=1,..12 ) \]

where $f F(i) $\f is the average flow of month i. ADDITIONAL INFORMATION used as hydrologic signature in Shafii, M., & Tolson, B. A. (2015). Optimizing hydrological consistency by incorporating hydrological signatures into model calibration objectives. Water Resources Research, 51(5), 3796-3814. doi:10.1002/2014WR016520

Parameters
[in]real(dp), dimension(:) :: dataarray of data
[in]logical, dimension(size(data, 1)), optional :: maskmask for data points given
[in]integer(i4), optional :: yr_startyear of date of first data point given
[in]integer(i4), optional :: mo_startmonth of date of first data point given (default: 1)
[in]integer(i4), optional :: dy_startmonth of date of first data point given (default: 1)
Returns
real(dp) :: MaximumMonthlyFlow — Maximum of average flow per month Works only with 1d double precision input data. Assumes data are daily values.
Authors
Juliane Mai
Date
Jun 2015

Definition at line 511 of file mo_mrm_signatures.f90.

References maximummonthlyflow().

Referenced by maximummonthlyflow().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ moments()

subroutine, public mo_mrm_signatures::moments ( real(dp), dimension(:), intent(in) data,
logical, dimension(size(data, 1)), intent(in), optional mask,
real(dp), intent(out), optional mean_data,
real(dp), intent(out), optional stddev_data,
real(dp), intent(out), optional median_data,
real(dp), intent(out), optional max_data,
real(dp), intent(out), optional mean_log,
real(dp), intent(out), optional stddev_log,
real(dp), intent(out), optional median_log,
real(dp), intent(out), optional max_log )

Moments of data and log-transformed data, e.g.

mean and standard deviation.

Returns several moments of data series given, i.e.

  • mean of data
  • standard deviation of data
  • median of data
  • maximum/ peak of data
  • mean of log-transformed data
  • standard deviation of log-transformed data
  • median of log-transformed data
  • maximum/ peak of log-transformed data An optional mask of data points can be specified. ADDITIONAL INFORMATION mean_log and stddev_log used as hydrologic signature in Zhang, Y., Vaze, J., Chiew, F. H. S., Teng, J., & Li, M. (2014). Predicting hydrological signatures in ungauged catchments using spatial interpolation, index model, and rainfall-runoff modelling. Journal of Hydrology, 517(C), 936-948. doi:10.1016/j.jhydrol.2014.06.032 mean_data, stddev_data, median_data, max_data, mean_log, and stddev_log used as hydrologic signature in Shafii, M., & Tolson, B. A. (2015). Optimizing hydrological consistency by incorporating hydrological signatures into model calibration objectives. Water Resources Research, 51(5), 3796-3814. doi:10.1002/2014WR016520
    Parameters
    [in]real(dp), dimension(:) :: dataarray of data
    [in]logical, dimension(size(data, 1)), optional :: maskmask for data points given
    [out]real(dp), optional :: mean_datamean of data
    [out]real(dp), optional :: stddev_datastandard deviation of data
    [out]real(dp), optional :: median_datamedian of data
    [out]real(dp), optional :: max_datamaximum/ peak of data
    [out]real(dp), optional :: mean_logmean of log-transformed data
    [out]real(dp), optional :: stddev_logstandard deviation of log-transformed data
    [out]real(dp), optional :: median_logmedian of log-transformed data
    [out]real(dp), optional :: max_logmaximum/ peak of log-transformed dataWorks only with 1d double precision input data.
    Authors
    Juliane Mai
    Date
    Jun 2015

Definition at line 654 of file mo_mrm_signatures.f90.

◆ peakdistribution()

real(dp) function, dimension(size(quantiles, 1)), public mo_mrm_signatures::peakdistribution ( real(dp), dimension(:), intent(in) data,
real(dp), dimension(:), intent(in) quantiles,
logical, dimension(size(data, 1)), intent(in), optional mask,
real(dp), intent(out), optional slope_peak_distribution )

Calculates the peak distribution.

First, the peaks of the time series given are identified. For the peak distribution only this subset of data points are considered. Second, the peak distribution at the quantiles given is calculated. Calculates the peak distribution at the quantiles given using mo_percentile. Since the exceedance probabilities are usually used in hydrology the function percentile is used with (1.0-quantiles). Optionally, the slope of the peak distribution between 10th and 50th percentile, i.e.

\[ slope = \frac{\mathrm{peak\_{data}}_{0.1}-\mathrm{peak\_{data}}_{0.5}}{0.9-0.5} \]

can be returned. An optional mask for the data points can be given. ADDITIONAL INFORMATION slope_peak_distribution used as hydrologic signature in Euser, T., Winsemius, H. C., Hrachowitz, M., Fenicia, F., Uhlenbrook, S., & Savenije, H. H. G. (2013). A framework to assess the realism of model structures using hydrological signatures. Hydrology and Earth System Sciences, 17(5), 1893-1912. doi:10.5194/hess-17-1893-2013

Parameters
[in]real(dp), dimension(:) :: datadata array
[in]real(dp), dimension(:) :: quantilesrequested quantiles for distribution
[in]logical, dimension(size(data, 1)), optional :: maskmask of data array
[out]real(dp), optional :: slope_peak_distributionslope of the Peak distribution between10th and 50th percentile
Returns
real(dp), dimension(size(quantiles,1)) :: PeakDistribution — Distribution of peak values at resp. quantiles
Authors
Remko Nijzink
Date
March 2014

Definition at line 780 of file mo_mrm_signatures.f90.

References peakdistribution().

Referenced by peakdistribution().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ runoffratio()

real(dp) function, public mo_mrm_signatures::runoffratio ( real(dp), dimension(:), intent(in) data,
real(dp), intent(in) domain_area,
logical, dimension(size(data, 1)), intent(in), optional mask,
real(dp), dimension(size(data, 1)), intent(in), optional precip_series,
real(dp), intent(in), optional precip_sum,
logical, intent(in), optional log_data )

Runoff ratio (accumulated daily discharge [mm/d] / accumulated daily precipitation [mm/d]).

The runoff ratio is defined as

\[ runoff_ratio = \frac{\sum_{t=1}^{N} q_t}{\sum_{t=1}^{N} p_t}\]

where \(p_t\) and \(q_t\) are precipitation and discharge, respectively. Therefore, precipitation over the entire domain is required and both discharge and precipitation have to be converted to the same units [mm/d]. Input discharge is given in [m**3/s] as this is mHM default while precipitation has to be given in [mm/km**2 / day]. Either "precip_sum" or "precip_series" has to be specified. If "precip_series" is used the optional mask is also applied to precipitation values. The "precip_sum" is the accumulated "precip_series". Optionally, a mask for the data (=discharge) can be given. If optional "log_data" is set to .true. the runoff ratio will be calculated as

\[ runoff\_ratio = \frac{\sum_{t=1}^{N} \log(q_t)}{\sum_{t=1}^{N} p_t}\]

where \(p_t\) and \(q_t\) are precipitation and discharge, respectively. ADDITIONAL INFORMATION

Returns
real(dp), dimension(size(lags,1)) :: RunoffRation — Ratio of discharge and precipitation Used as hydrologic signature in Shafii, M., & Tolson, B. A. (2015). Optimizing hydrological consistency by incorporating hydrological signatures into model calibration objectives. Water Resources Research, 51(5), 3796-3814. doi:10.1002/2014WR016520
Parameters
[in]real(dp), dimension(:) :: dataarray of data [m**3/s]
[in]real(dp) :: domain_areaarea of domain [km**2]
[in]logical, dimension(size(data, 1)), optional :: maskmask for data points given
[in]real(dp), dimension(size(data, 1)), optional :: precip_seriesdaily precipitation values [mm/km**2 / day]
[in]real(dp), optional :: precip_sumsum of daily precip. values of whole period[mm/km**2 / day]
[in]logical, optional :: log_dataratio using logarithmic dataWorks only with 1d double precision input data.
Authors
Juliane Mai
Date
Jun 2015

Definition at line 917 of file mo_mrm_signatures.f90.

References runoffratio().

Referenced by runoffratio().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ zeroflowratio()

real(dp) function, public mo_mrm_signatures::zeroflowratio ( real(dp), dimension(:), intent(in) data,
logical, dimension(size(data, 1)), intent(in), optional mask )

Ratio of zero values to total number of data points.

An optional mask of data points can be specified. ADDITIONAL INFORMATION

Returns
real(dp), dimension(size(lags,1)) :: ZeroFlowRatio — Ratio of zero values to total number of data points Used as hydrologic signature in Zhang, Y., Vaze, J., Chiew, F. H. S., Teng, J., & Li, M. (2014). Predicting hydrological signatures in ungauged catchments using spatial interpolation, index model, and rainfall-runoff modelling. Journal of Hydrology, 517(C), 936-948. doi:10.1016/j.jhydrol.2014.06.032
Parameters
[in]real(dp), dimension(:) :: dataarray of data
[in]logical, dimension(size(data, 1)), optional :: maskmask for data points givenWorks only with 1d double precision input data.
Authors
Juliane Mai
Date
Jun 2015

Definition at line 1033 of file mo_mrm_signatures.f90.

References zeroflowratio().

Referenced by zeroflowratio().

Here is the call graph for this function:
Here is the caller graph for this function: