sig_HFD_mean

sig_HFD_mean calculates mean half flow date.
   Calculates day since start of water year on which the cumulative 
   discharge (default: October) reaches (here: exceeds) half of the annual 
   discharge.

   INPUT
   Q: streamflow [mm/timestep]
   t: time [Matlab datetime]
   OPTIONAL
   start_water_year: first month of water year, default = 10 (October)

   OUTPUT
   HFD_mean: mean half flow date [day since start of water year]
   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;
   HFD_mean = sig_HFD_mean(Q,t);
   HFD_mean = sig_HFD_mean(Q,t,'start_water_year',1);

   References
   Court, A., 1962. Measures of streamflow timing. Journal of Geophysical
   Research, 67(11), pp.4335-4339.

   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 [HFD_mean, error_flag, error_str] = sig_HFD_mean(Q, t, varargin)
0002 %sig_HFD_mean calculates mean half flow date.
0003 %   Calculates day since start of water year on which the cumulative
0004 %   discharge (default: October) reaches (here: exceeds) half of the annual
0005 %   discharge.
0006 %
0007 %   INPUT
0008 %   Q: streamflow [mm/timestep]
0009 %   t: time [Matlab datetime]
0010 %   OPTIONAL
0011 %   start_water_year: first month of water year, default = 10 (October)
0012 %
0013 %   OUTPUT
0014 %   HFD_mean: mean half flow date [day since start of water year]
0015 %   error_flag: 0 (no error), 1 (warning), 2 (error in data check), 3
0016 %       (error in signature calculation)
0017 %   error_str: string contraining error description
0018 %
0019 %   EXAMPLE
0020 %   % load example data
0021 %   data = load('example/example_data/33029_daily.mat');
0022 %   Q = data.Q;
0023 %   t = data.t;
0024 %   HFD_mean = sig_HFD_mean(Q,t);
0025 %   HFD_mean = sig_HFD_mean(Q,t,'start_water_year',1);
0026 %
0027 %   References
0028 %   Court, A., 1962. Measures of streamflow timing. Journal of Geophysical
0029 %   Research, 67(11), pp.4335-4339.
0030 %
0031 %   Copyright (C) 2020
0032 %   This software is distributed under the GNU Public License Version 3.
0033 %   See <https://www.gnu.org/licenses/gpl-3.0.en.html> for details.
0034 
0035 % check input parameters
0036 if nargin < 2
0037     error('Not enough input arguments.')
0038 end
0039 
0040 ip = inputParser;
0041 ip.CaseSensitive = true;
0042 
0043 % required input arguments
0044 % time series have to be numeric and either a (n,1) or a (1,n) vector
0045 addRequired(ip, 'Q', @(Q) isnumeric(Q) && (size(Q,1)==1 || size(Q,2)==1)) 
0046 % date time series has to be numeric or datetime and either a (n,1) or a (1,n) vector
0047 addRequired(ip, 't', @(t) (isnumeric(t) || isdatetime(t)) && (size(t,1)==1 || size(t,2)==1)) 
0048 
0049 % optional input arguments
0050 validationFcn = @(x) isnumeric(x) && isscalar(x) && (x >= 1) && (x <= 12) && floor(x)==x;
0051 addParameter(ip, 'start_water_year', 10, validationFcn) % when does the water year start? Default: 10
0052 
0053 parse(ip, Q, t, varargin{:})
0054 start_water_year = ip.Results.start_water_year;
0055 
0056 % data checks
0057 [error_flag, error_str, timestep, t] = util_DataCheck(Q, t);
0058 if error_flag == 2
0059     HFD_mean = NaN;
0060     return
0061 end
0062 timestep_days = days(timestep); % adjust for timestep
0063 
0064 % calculate signature
0065 % get individual years
0066 [year_vec, month_vec, day_vec] = ymd(t);
0067 year_start = min(year_vec);
0068 year_end = max(year_vec);
0069 year_list = [year_start:year_end]';
0070 
0071 Q_temp = Q;
0072 % Q_annual = NaN(year_end-year_start,1);
0073 % Q_daily = NaN(365,year_end-year_start);
0074 HFD = NaN(year_end-year_start,1);
0075 
0076 % extract years
0077 error_tmp = false;
0078 for y = 2:length(year_list) % since we use water years, we always start in the "2nd year"
0079     try
0080         year = year_list(y);
0081         Q_water_year = ...
0082             [Q_temp(year_vec==year-1 & month_vec>=start_water_year); ...
0083             Q_temp(year_vec==year & month_vec<start_water_year)];
0084         Q_half_sum = 0.5*sum(Q_water_year);
0085         Q_cumsum = cumsum(Q_water_year);
0086         aux_index = 1:length(Q_water_year);
0087         HFD_aux = aux_index(Q_cumsum>Q_half_sum);
0088         HFD(y-1) = HFD_aux(1);
0089     catch
0090         error_tmp = true;
0091     end
0092 end
0093 
0094 if error_tmp
0095     error_flag = 1;
0096     error_str = ['Warning: Years containing NaN values are ignored. ', error_str];
0097 end
0098 
0099 % get mean half flow date
0100 HFD_mean = mean(HFD,'omitnan')*timestep_days;
0101 
0102 end
0103 
0104