util_ExtractSubPeriod

util_ExtractSubPeriod extracts subperiod (months) from time series.
   Extracts certain months from time series, e.g. the low flow season and 
   the high flow season. See also Euser et al. (2013) who use May to
   September as low flow season and November to April as high flow season.

   INPUT
   X: time series - should be continuous (e.g. Q, typically [mm/timestep])
   t: time [Matlab datetime]
   subperiod: subperiod to be extracted, e.g. [11:12, 1:4] for November
       to April or [5:9] for May to September
   OPTIONAL
   option: option to delete values outside subperiod ('delete') or assign
       NaN to values outside subperiod ('nan')

   OUTPUT
   X_sub: subperiod time series
   t_sub: subperiod time

   EXAMPLE
   % load example data
   data = load('example/example_data/33029_daily.mat');
   Q = data.Q;
   t = data.t;
   subperiod = [11:12, 1:4];
   [Q_sub, t_sub] = ...
       util_ExtractSubPeriod(Q, t, subperiod);

   References
   Euser, T., Winsemius, H.C., Hrachowitz, M., Fenicia, F., Uhlenbrook, S.
   and Savenije, H.H.G., 2013. A framework to assess the realism of model
   structures using hydrological signatures. Hydrology and Earth System
   Sciences, 17 (5), 2013.

   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_sub, t_sub] = util_ExtractSubPeriod(X, t, subperiod, option)
0002 %util_ExtractSubPeriod extracts subperiod (months) from time series.
0003 %   Extracts certain months from time series, e.g. the low flow season and
0004 %   the high flow season. See also Euser et al. (2013) who use May to
0005 %   September as low flow season and November to April as high flow season.
0006 %
0007 %   INPUT
0008 %   X: time series - should be continuous (e.g. Q, typically [mm/timestep])
0009 %   t: time [Matlab datetime]
0010 %   subperiod: subperiod to be extracted, e.g. [11:12, 1:4] for November
0011 %       to April or [5:9] for May to September
0012 %   OPTIONAL
0013 %   option: option to delete values outside subperiod ('delete') or assign
0014 %       NaN to values outside subperiod ('nan')
0015 %
0016 %   OUTPUT
0017 %   X_sub: subperiod time series
0018 %   t_sub: subperiod time
0019 %
0020 %   EXAMPLE
0021 %   % load example data
0022 %   data = load('example/example_data/33029_daily.mat');
0023 %   Q = data.Q;
0024 %   t = data.t;
0025 %   subperiod = [11:12, 1:4];
0026 %   [Q_sub, t_sub] = ...
0027 %       util_ExtractSubPeriod(Q, t, subperiod);
0028 %
0029 %   References
0030 %   Euser, T., Winsemius, H.C., Hrachowitz, M., Fenicia, F., Uhlenbrook, S.
0031 %   and Savenije, H.H.G., 2013. A framework to assess the realism of model
0032 %   structures using hydrological signatures. Hydrology and Earth System
0033 %   Sciences, 17 (5), 2013.
0034 %
0035 %   Copyright (C) 2020
0036 %   This software is distributed under the GNU Public License Version 3.
0037 %   See <https://www.gnu.org/licenses/gpl-3.0.en.html> for details.
0038 
0039 if nargin < 4
0040     option = 'delete';
0041 end
0042 
0043 % get months
0044 [~, month_vec, ~] = ymd(t);
0045 
0046 if strcmp(option,'delete')
0047     % option 1 - delete values outside subperiod
0048     t_sub = t(ismember(month_vec,subperiod));
0049     X_sub = X(ismember(month_vec,subperiod));
0050 elseif strcmp(option,'nan')
0051     % option 2 - assign NaN to values outside subperiod
0052     t_sub = t;
0053     X_sub = X;
0054     X_sub(ismember(month_vec,subperiod)) = NaN;
0055 else
0056     error('Subperiod option specified incorrectly, the options are delete or nan.')
0057 end
0058 
0059 %{
0060 figure; hold on;
0061 plot(t,X);
0062 plot(t_sub,X_sub,'--')
0063 xlabel('Date')
0064 ylabel('Flow')
0065 %}
0066 
0067 end