sig_x_Q_duration calculates various kinds of flow durations.
Calculates various kinds of flow durations, e.g. no flow duration,
high flow duration. Typical metrics can be chosen from a standard list
(no, high, low), or created manually (e.g. 0.5*median(Q)).
INPUT
Q: streamflow [mm/timestep]
t: time [Matlab datetime]
type: type of flow duration (no, high, low, custom_high, custom_low)
OPTIONAL
threshold: flow threshold above (below) flow duration is calculated
(e.g. 9*median(Q) for high) [mm/timestep]
OUTPUT
x_Q_dur: x flow duration [timestep]
error_flag: 0 (no error), 1 (warning), 2 (error in data check), 3
(error in signature calculation)
error_str: string contraining error description
EXAMPLE
% load example data
data = load('example/example_data/33029_daily.mat');
Q = data.Q;
t = data.t;
x_Q_dur = sig_x_Q_dur(Q,t,'no');
x_Q_dur = sig_x_Q_dur(Q,t,'high');
x_Q_dur = sig_x_Q_dur(Q,t,'low');
x_Q_dur = sig_x_Q_dur(Q,t,'custom_high','threshold',9*median(Q,'omitnan'));
References
Addor, N., Nearing, G., Prieto, C., Newman, A.J., Le Vine, N. and
Clark, M.P., 2018. A ranking of hydrological signatures based on their
predictability in space. Water Resources Research, 54(11), pp.8792-8812.
Copyright (C) 2020
This software is distributed under the GNU Public License Version 3.
See <https://www.gnu.org/licenses/gpl-3.0.en.html> for details.0001 function [x_Q_duration, error_flag, error_str] = sig_x_Q_duration(Q, t, type, varargin) 0002 %sig_x_Q_duration calculates various kinds of flow durations. 0003 % Calculates various kinds of flow durations, e.g. no flow duration, 0004 % high flow duration. Typical metrics can be chosen from a standard list 0005 % (no, high, low), or created manually (e.g. 0.5*median(Q)). 0006 % 0007 % INPUT 0008 % Q: streamflow [mm/timestep] 0009 % t: time [Matlab datetime] 0010 % type: type of flow duration (no, high, low, custom_high, custom_low) 0011 % OPTIONAL 0012 % threshold: flow threshold above (below) flow duration is calculated 0013 % (e.g. 9*median(Q) for high) [mm/timestep] 0014 % 0015 % OUTPUT 0016 % x_Q_dur: x flow duration [timestep] 0017 % error_flag: 0 (no error), 1 (warning), 2 (error in data check), 3 0018 % (error in signature calculation) 0019 % error_str: string contraining error description 0020 % 0021 % EXAMPLE 0022 % % load example data 0023 % data = load('example/example_data/33029_daily.mat'); 0024 % Q = data.Q; 0025 % t = data.t; 0026 % x_Q_dur = sig_x_Q_dur(Q,t,'no'); 0027 % x_Q_dur = sig_x_Q_dur(Q,t,'high'); 0028 % x_Q_dur = sig_x_Q_dur(Q,t,'low'); 0029 % x_Q_dur = sig_x_Q_dur(Q,t,'custom_high','threshold',9*median(Q,'omitnan')); 0030 % 0031 % References 0032 % Addor, N., Nearing, G., Prieto, C., Newman, A.J., Le Vine, N. and 0033 % Clark, M.P., 2018. A ranking of hydrological signatures based on their 0034 % predictability in space. Water Resources Research, 54(11), pp.8792-8812. 0035 % 0036 % Copyright (C) 2020 0037 % This software is distributed under the GNU Public License Version 3. 0038 % See <https://www.gnu.org/licenses/gpl-3.0.en.html> for details. 0039 0040 % check input parameters 0041 if nargin < 3 0042 error('Not enough input arguments.') 0043 end 0044 0045 ip = inputParser; 0046 ip.CaseSensitive = true; 0047 0048 % required input arguments 0049 % time series have to be numeric and either a (n,1) or a (1,n) vector 0050 addRequired(ip, 'Q', @(Q) isnumeric(Q) && (size(Q,1)==1 || size(Q,2)==1)) 0051 % date time series has to be numeric or datetime and either a (n,1) or a (1,n) vector 0052 addRequired(ip, 't', @(t) (isnumeric(t) || isdatetime(t)) && (size(t,1)==1 || size(t,2)==1)) 0053 % type has to be char and only one word 0054 addRequired(ip, 'type', @(type) ischar(type) && size(type,1)==1) 0055 0056 % optional input arguments 0057 addParameter(ip, 'threshold', [], @isnumeric) % flow threshold 0058 0059 parse(ip, Q, t, type, varargin{:}) 0060 threshold = ip.Results.threshold; 0061 0062 % data checks 0063 [error_flag, error_str, timestep, t] = util_DataCheck(Q, t); 0064 if error_flag == 2 0065 x_Q_duration = NaN; 0066 return 0067 end 0068 0069 % calculate signature 0070 switch type 0071 0072 case 'no' 0073 no_Q = Q==0; 0074 % find consecutive timesteps with no flows 0075 start1 = strfind([0,no_Q'],[0 1]); 0076 end1 = strfind([no_Q',0],[1 0]); 0077 interval_lengths = end1 - start1 + 1; 0078 0079 case 'high' 0080 Q_high = 9*median(Q,'omitnan'); 0081 high_Q = Q>Q_high; 0082 % find consecutive timesteps with high flows 0083 start1 = strfind([0,high_Q'],[0 1]); 0084 end1 = strfind([high_Q',0],[1 0]); 0085 interval_lengths = end1 - start1 + 1; 0086 0087 case 'low' 0088 Q_low = 0.2*mean(Q,'omitnan'); 0089 low_Q = Q<Q_low; 0090 % find consecutive timesteps with low flows 0091 start1 = strfind([0,low_Q'],[0 1]); 0092 end1 = strfind([low_Q',0],[1 0]); 0093 interval_lengths = end1 - start1 + 1; 0094 0095 case 'custom_high' 0096 if isempty(threshold) || numel(threshold) > 1 0097 error('No/wrong custom threshold specified.') 0098 end 0099 custom_Q = Q>threshold; 0100 % find consecutive timesteps above x flows 0101 start1 = strfind([0,custom_Q'],[0 1]); 0102 end1 = strfind([custom_Q',0],[1 0]); 0103 interval_lengths = end1 - start1 + 1; 0104 0105 case 'custom_low' 0106 if isempty(threshold) || numel(threshold) > 1 0107 error('No/wrong custom threshold specified.') 0108 end 0109 custom_Q = Q<threshold; 0110 % find consecutive timesteps below x flows 0111 start1 = strfind([0,custom_Q'],[0 1]); 0112 end1 = strfind([custom_Q',0],[1 0]); 0113 interval_lengths = end1 - start1 + 1; 0114 0115 otherwise 0116 error('Incorrect flow duration type specified.') 0117 end 0118 0119 if isempty(interval_lengths) 0120 x_Q_duration = 0; 0121 else 0122 x_Q_duration = mean(interval_lengths); 0123 end 0124 0125 end