first release

TOSSHtoolbox · Feb 8, 2021 · e76cf32 · e76cf32
1 parent 377a0ab
commit e76cf32
Show file tree

Hide file tree

Showing 120 changed files with 1,755 additions and 1,685 deletions.
diff --git a/.gitignore b/.gitignore
@@ -12,6 +12,6 @@ signature_test_script_old
 example/example_data/CAMELS_v2.0
 example/example_data/CAMELS_GB
 example/example_data/old
-example/old
+old
 example/results/CAMELS_GB_TOSSH_signatures.mat
 example/results/CAMELS_TOSSH_signatures.mat
diff --git a/README.md b/README.md
@@ -1,17 +1,15 @@
-<span style="color:red">**IN DEVELOPMENT - please be aware that this toolbox is currently under review and not finalised yet.**</span>
-
-
 <img src="docs/images/TOSSH_logo.svg" alt="TOSSH logo" style="width:70%;" >
 
 
 [![GitHub license](https://img.shields.io/badge/license-GPLv3-blue.svg)](https://github.com/TOSSHtoolbox/TOSSH/blob/master/LICENSE)
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.4451846.svg)](https://doi.org/10.5281/zenodo.4451846)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.4313275.svg)](https://doi.org/10.5281/zenodo.4313275)
 
 
-This repository contains TOSSH: A Toolbox for Streamflow Signatures in Hydrology (Gnann et al., submitted).
+This repository contains TOSSH: A Toolbox for Streamflow Signatures in Hydrology (Gnann et al., 2021).
 TOSSH is a Matlab toolbox that provides accessible, standardised signature calculations, with clear information on methodological decisions and recommended parameter values.
 The online documentation for TOSSH can be found here: <https://TOSSHtoolbox.github.io/TOSSH/>.
 
+
 ## Contact
 If you have any questions or feedback, or if you spotted an error or bug, please create an issue on Github 
 (<a href="https://github.com/TOSSHtoolbox/TOSSH/issues" target="_blank">https://github.com/TOSSHtoolbox/TOSSH/issues</a>).
@@ -22,8 +20,13 @@ Alternatively, email Hilary McMillan (<[email protected]>) or Sebastian Gnann (
 <https://github.com/TOSSHtoolbox/TOSSH>
 
 
+## Acknowledgements
+Thanks to Yves Tramblay for providing helpful feedback.
+
+
 ## Credits
-Gnann, S.J., Coxon, G., Woods, R.A., Howden, N.J.K., McMillan H.K., submitted. TOSSH: A Toolbox for Streamflow Signatures in Hydrology.
+Gnann, S.J., Coxon, G., Woods, R.A., Howden, N.J.K., McMillan H.K., 2021. TOSSH: A Toolbox for Streamflow Signatures in Hydrology. Environmental Modelling & Software. 
+<https://doi.org/10.1016/j.envsoft.2021.104983>
 
 
 ## License

diff --git a/TOSSH_code/calculation_functions/calc_Addor.m b/TOSSH_code/calculation_functions/calc_Addor.m
@@ -1,4 +1,4 @@
-function [results] = calc_Addor(Q_mat, t_mat, P_mat)
+function [results] = calc_Addor(Q_mat, t_mat, P_mat, varargin)
 %calc_Addor calculates signatures from Addor et al. (2018).
 %   Addor et al. (2018) use 15 signatures that "characterize different
 %   parts of the hydrograph, and [...] are sensitive to processes occurring
@@ -10,7 +10,9 @@
 %   Q_mat: streamflow [mm/timestep] matrix (cell array)
 %   t_mat: time [Matlab datenum] matrix (cell array)
 %   P_mat: precipitation [mm/timestep] matrix (cell array)
-%   
+%   OPTIONAL
+%   start_water_year: first month of water year, default = 10 (October)
+%
 %   OUTPUT
 %   results: struc array with all results (each signature for each time
 %       series and associated error strings)
@@ -50,9 +52,11 @@
 addRequired(ip, 't_mat', @(t_mat) iscell(t_mat))
 addRequired(ip, 'P_mat', @(P_mat) iscell(P_mat))
 
-parse(ip, Q_mat, t_mat, P_mat)
+% optional input arguments
+addParameter(ip, 'start_water_year', 10, @isnumeric) % when does the water year start? Default: 10
 
-% calculate signatures
+parse(ip, Q_mat, t_mat, P_mat, varargin{:})
+start_water_year = ip.Results.start_water_year;
 
 % initialise arrays
 Q_mean = NaN(size(Q_mat,1),1);
@@ -88,10 +92,10 @@
     [Q_mean(i),~,Q_mean_error_str(i)] = sig_Q_mean(Q_mat{i},t_mat{i});
     [TotalRR(i),~,TotalRR_error_str(i)] = sig_TotalRR(Q_mat{i},t_mat{i},P_mat{i});
     [QP_elasticity(i),~,QP_elasticity_error_str(i)] = ...
-        sig_QP_elasticity(Q_mat{i},t_mat{i},P_mat{i},'method','Sanka','start_water_year',10); %,'start_water_year',4 in Southern Hemisphere
+        sig_QP_elasticity(Q_mat{i},t_mat{i},P_mat{i},'method','Sanka','start_water_year',start_water_year); 
     [FDC_slope(i),~,FDC_slope_error_str(i)] = sig_FDC_slope(Q_mat{i},t_mat{i});
     [BFI(i),~,BFI_error_str(i)] = sig_BFI(Q_mat{i},t_mat{i},'method','Lyne_Hollick','parameters',[0.925 3]);
-    [HFD_mean(i),~,HFD_mean_error_str(i)] = sig_HFD_mean(Q_mat{i},t_mat{i},'start_month',10); %,'start_month',4 in Southern Hemisphere
+    [HFD_mean(i),~,HFD_mean_error_str(i)] = sig_HFD_mean(Q_mat{i},t_mat{i},'start_water_year',start_water_year); 
     [Q5(i),~,Q5_error_str(i)] = sig_x_percentile(Q_mat{i},t_mat{i},5);
     [Q95(i),~,Q95_error_str(i)] = sig_x_percentile(Q_mat{i},t_mat{i},95);
     [high_Q_freq(i),~,high_Q_freq_error_str(i)] = sig_x_Q_frequency(Q_mat{i},t_mat{i},'high');

diff --git a/TOSSH_code/calculation_functions/calc_All.m b/TOSSH_code/calculation_functions/calc_All.m
@@ -1,4 +1,4 @@
-function [results] = calc_All(Q_mat, t_mat, P_mat, PET_mat, T_mat)
+function [results] = calc_All(Q_mat, t_mat, P_mat, PET_mat, T_mat, varargin)
 %calc_All calculates all signatures in the toolbox.
 %   If a signature function can calculate multiple signatures
 %   (e.g. sig_x_percentile) only one signature is calculated (e.g. Q95).
@@ -10,6 +10,9 @@
 %   P_mat: precipitation [mm/timestep] matrix (cell array)
 %   PET_mat: pot. evapotranspiration [mm/timestep] matrix (cell array)
 %   T_mat: temperature [degC] matrix (cell array)
+%   OPTIONAL
+%   start_water_year: first month of water year, default = 10 (October)
+%   plot_results: whether to plot results, default = false
 %
 %   OUTPUT
 %   results: struc array with all results (each signature for each time
@@ -49,9 +52,13 @@
 addRequired(ip, 'PET_mat', @(PET_mat) iscell(PET_mat))
 addRequired(ip, 'T_mat', @(T_mat) iscell(T_mat))
 
-parse(ip, Q_mat, t_mat, P_mat, PET_mat, T_mat)
+% optional input arguments
+addParameter(ip, 'start_water_year', 10, @isnumeric) % when does the water year start? Default: 10
+addParameter(ip, 'plot_results', false, @islogical) % whether to plot results 
 
-% calculate signatures
+parse(ip, Q_mat, t_mat, P_mat, PET_mat, T_mat, varargin{:})
+start_water_year = ip.Results.start_water_year;
+plot_results = ip.Results.plot_results;
 
 % initialise arrays
 AC1 = NaN(size(Q_mat,1),1);
@@ -133,8 +140,6 @@
 high_Q_frequency = NaN(size(Q_mat,1),1);
 high_Q_frequency_error_str = strings(size(Q_mat,1),1);
 
-% warning('off','all')
-
 % loop over all catchments
 for i = 1:size(Q_mat,1)
 
@@ -197,8 +202,6 @@
 
 end
 
-% warning('on','all')
-
 % add results to struct array
 results.AC1 = AC1;
 results.AC1_error_str = AC1_error_str;

diff --git a/TOSSH_code/calculation_functions/calc_BasicSet.m b/TOSSH_code/calculation_functions/calc_BasicSet.m
@@ -1,4 +1,4 @@
-function [results] = calc_BasicSet(Q_mat, t_mat)
+function [results] = calc_BasicSet(Q_mat, t_mat, varargin)
 %calc_BasicSet calculates basic set of signatures.
 %   The basic set of signatures are designed to cover the five components 
 %   of a natural streamflow regime as defined by Poff et al. (1997) and 
@@ -11,6 +11,9 @@
 %   INPUT
 %   Q_mat: streamflow [mm/timestep] matrix (cell array)
 %   t_mat: time [Matlab datenum] matrix (cell array)
+%   OPTIONAL
+%   start_water_year: first month of water year, default = 10 (October)
+%   plot_results: whether to plot results, default = false
 %
 %   OUTPUT
 %   results: struc array with all results (each signature for each time
@@ -51,9 +54,13 @@
 addRequired(ip, 'Q_mat', @(Q_mat) iscell(Q_mat))
 addRequired(ip, 't_mat', @(t_mat) iscell(t_mat))
 
-parse(ip, Q_mat, t_mat)
+% optional input arguments
+addParameter(ip, 'start_water_year', 10, @isnumeric) % when does the water year start? Default: 10
+addParameter(ip, 'plot_results', false, @islogical) % whether to plot results 
 
-% calculate signatures
+parse(ip, Q_mat, t_mat, varargin{:})
+start_water_year = ip.Results.start_water_year;
+plot_results = ip.Results.plot_results;
 
 % initialise arrays
 Q_mean = NaN(size(Q_mat,1),1);
@@ -97,11 +104,12 @@
     [CoV(i),~,CoV_error_str(i)] = sig_Q_CoV(Q_mat{i},t_mat{i});
     [x_Q_frequency(i),~,x_Q_frequency_error_str(i)] = sig_x_Q_frequency(Q_mat{i},t_mat{i},'low');
     [x_Q_duration(i),~,x_Q_duration_error_str(i)] = sig_x_Q_duration(Q_mat{i},t_mat{i},'low');
-    [HFD_mean(i),~,HFD_mean_error_str(i)] = sig_HFD_mean(Q_mat{i},t_mat{i});
-    [HFI_mean(i),~,HFI_mean_error_str(i)] = sig_HFI_mean(Q_mat{i},t_mat{i});
+    [HFD_mean(i),~,HFD_mean_error_str(i)] = sig_HFD_mean(Q_mat{i},t_mat{i},'start_water_year',start_water_year);
+    [HFI_mean(i),~,HFI_mean_error_str(i)] = sig_HFI_mean(Q_mat{i},t_mat{i},'start_water_year',start_water_year);
     [AC1(i),~,AC1_error_str(i)] = sig_Autocorrelation(Q_mat{i},t_mat{i},'lag',1);
     [FDC_slope(i),~,FDC_slope_error_str(i)] = sig_FDC_slope(Q_mat{i},t_mat{i});
-    [BaseflowRecessionK(i),~,BaseflowRecessionK_error_str(i)] = sig_BaseflowRecessionK(Q_mat{i},t_mat{i},'eps',0.001*median(Q_mat{i},'omitnan'));
+    [BaseflowRecessionK(i),~,BaseflowRecessionK_error_str(i)] = sig_BaseflowRecessionK(...
+        Q_mat{i},t_mat{i},'eps',0.001*median(Q_mat{i},'omitnan'));
 
 end
 

diff --git a/TOSSH_code/calculation_functions/calc_Euser.m b/TOSSH_code/calculation_functions/calc_Euser.m
@@ -55,8 +55,6 @@
 
 parse(ip, Q_mat, t_mat)
 
-% calculate signatures
-
 % initialise arrays
 AC1 = NaN(size(Q_mat,1),1);
 AC1_error_str = strings(size(Q_mat,1),1);

diff --git a/TOSSH_code/calculation_functions/calc_McMillan_Groundwater.m b/TOSSH_code/calculation_functions/calc_McMillan_Groundwater.m
@@ -12,6 +12,9 @@
 %   t_mat: time [Matlab datenum] matrix (cell array)
 %   P_mat: precipitation [mm/timestep] matrix (cell array)
 %   PET_mat: pot. evapotranspiration [mm/timestep] matrix (cell array)
+%   OPTIONAL
+%   start_water_year: first month of water year, default = 10 (October)  
+%   plot_results: whether to plot results, default = false
 %
 %   OUTPUT
 %   results: struc array with all results (each signature for each time
@@ -54,14 +57,13 @@
 addRequired(ip, 'PET_mat', @(PET_mat) iscell(PET_mat))
 
 % optional input arguments
+addParameter(ip, 'start_water_year', 10, @isnumeric) % when does the water year start? Default: 10
 addParameter(ip, 'plot_results', false, @islogical) % whether to plot results (2 graphs)
 
 parse(ip, Q_mat, t_mat, P_mat, PET_mat, varargin{:})
-
+start_water_year = ip.Results.start_water_year;
 plot_results = ip.Results.plot_results;
 
-% calculate signatures
-
 % initialise arrays
 
 % Section: Groundwater 
@@ -139,7 +141,8 @@
 
     % Section: Groundwater
     [TotalRR(i),~,TotalRR_error_str(i)] = sig_TotalRR(Q_mat{i},t_mat{i},P_mat{i});
-    [RR_Seasonality(i),~,RR_Seasonality_error_str(i)] = sig_RR_Seasonality(Q_mat{i}, t_mat{i}, P_mat{i});
+    [RR_Seasonality(i),~,RR_Seasonality_error_str(i)] = sig_RR_Seasonality(Q_mat{i}, t_mat{i}, P_mat{i}, ...
+        'summer_start', start_water_year-6);
     [EventRR(i),~,EventRR_error_str(i)] = sig_EventRR(Q_mat{i},t_mat{i},P_mat{i});
     [StorageFraction(i,1),StorageFraction(i,2),StorageFraction(i,3),~,StorageFraction_error_str(i)] = ...
         sig_StorageFraction(Q_mat{i},t_mat{i},P_mat{i},PET_mat{i});
@@ -148,7 +151,7 @@
     [Recession_a_Seasonality(i),~,Recession_a_Seasonality_error_str(i)] = ...
         sig_SeasonalVarRecessions(Q_mat{i},t_mat{i},'eps',median(Q_mat{i},'omitnan')*0.001,'plot_results',plot_results);
     [AverageStorage(i),~,AverageStorage_error_str(i)] = ...
-        sig_StorageFromBaseflow(Q_mat{i},t_mat{i},P_mat{i},PET_mat{i},'plot_results',plot_results);
+        sig_StorageFromBaseflow(Q_mat{i},t_mat{i},P_mat{i},PET_mat{i},'start_water_year',start_water_year,'plot_results',plot_results);
     [RecessionParameters(i,:),~,~,RecessionParameters_error_str(i)] = ...
         sig_RecessionAnalysis(Q_mat{i},t_mat{i},'fit_individual',false,'plot_results',plot_results);
     [MRC_num_segments(i),Segment_slopes,~,MRC_num_segments_error_str(i)] = ...

diff --git a/TOSSH_code/calculation_functions/calc_McMillan_OverlandFlow.m b/TOSSH_code/calculation_functions/calc_McMillan_OverlandFlow.m
@@ -12,6 +12,8 @@
 %   t_mat: time [Matlab datenum] matrix (cell array)
 %   P_mat: precipitation [mm/timestep] matrix (cell array)
 %   PET_mat: pot. evapotranspiration [mm/timestep] matrix (cell array)
+%   OPTIONAL
+%   plot_results: whether to plot results, default = false
 %
 %   OUTPUT
 %   results: struc array with all results (each signature for each time
@@ -54,10 +56,9 @@
 addRequired(ip, 'PET_mat', @(PET_mat) iscell(PET_mat))
 
 % optional input arguments
-addParameter(ip, 'plot_results', false, @islogical) % whether to plot results (2 graphs)
+addParameter(ip, 'plot_results', false, @islogical) % whether to plot results
 
 parse(ip, Q_mat, t_mat, P_mat, PET_mat, varargin{:})
-
 plot_results = ip.Results.plot_results;
 
 % initialise arrays

diff --git a/TOSSH_code/calculation_functions/calc_Sawicz.m b/TOSSH_code/calculation_functions/calc_Sawicz.m
@@ -1,4 +1,4 @@
-function [results] = calc_Sawicz(Q_mat, t_mat, P_mat, T_mat)
+function [results] = calc_Sawicz(Q_mat, t_mat, P_mat, T_mat, varargin)
 %calc_Sawicz calculates signatures from Sawicz et al. (2011).
 %   Sawicz et al. (2011) use 6 signatures drawn largely from Yadav et al. 
 %   (2007), that are chosen to be uncorrelated and to be linked to 
@@ -11,6 +11,8 @@
 %   t_mat: time [Matlab datenum] matrix (cell array)
 %   P_mat: precipitation [mm/timestep] matrix (cell array)
 %   T_mat: temperature [degC] matrix (cell array)
+%   OPTIONAL
+%   start_water_year: first month of water year, default = 10 (October)
 %
 %   OUTPUT
 %   results: struc array with all results (each signature for each time
@@ -33,7 +35,7 @@
 %   and Earth System Sciences, 15(9), pp.2895-2911.
 %   Yadav, M., Wagener, T. and Gupta, H., 2007. Regionalization of 
 %   constraints on expected watershed response behavior for improved
-%   predictions in ungauged basins. Advances in water resources, 30(8), 
+%   predictions in ungauged basins. Advances in Water Resources, 30(8), 
 %   pp.1756-1774.
 %
 %   Copyright (C) 2020
@@ -58,9 +60,11 @@
 addRequired(ip, 'P_mat', @(P_mat) iscell(P_mat))
 addRequired(ip, 'T_mat', @(T_mat) iscell(T_mat))
 
-parse(ip, Q_mat, t_mat, P_mat, T_mat)
+% optional input arguments
+addParameter(ip, 'start_water_year', 10, @isnumeric) % when does the water year start? Default: 10
 
-% calculate signatures
+parse(ip, Q_mat, t_mat, P_mat, T_mat, varargin{:})
+start_water_year = ip.Results.start_water_year;
 
 % initialise arrays
 Total_RR = NaN(size(Q_mat,1),1);
@@ -82,8 +86,10 @@
     [Total_RR(i),~,Total_RR_error_str(i)] = sig_TotalRR(Q_mat{i},t_mat{i},P_mat{i});    
     [FDC_slope(i),~,FDC_slope_error_str(i)] = sig_FDC_slope(Q_mat{i},t_mat{i});    
     [BFI(i),~,BFI_error_str(i)] = sig_BFI(Q_mat{i},t_mat{i});    
-    [QP_elasticity(i),~,QP_elasticity_error_str(i)] = sig_QP_elasticity(Q_mat{i},t_mat{i},P_mat{i});    
-    [SnowDayRatio(i),~,SnowDayRatio_error_str(i)] = sig_SnowDayRatio(Q_mat{i},t_mat{i},P_mat{i},T_mat{i});    
+    [QP_elasticity(i),~,QP_elasticity_error_str(i)] = sig_QP_elasticity(...
+        Q_mat{i},t_mat{i},P_mat{i},'start_water_year',start_water_year);    
+    [SnowDayRatio(i),~,SnowDayRatio_error_str(i)] = sig_SnowDayRatio(...
+        Q_mat{i},t_mat{i},P_mat{i},T_mat{i});    
     [RLD(i),~,RLD_error_str(i)] = sig_RisingLimbDensity(Q_mat{i},t_mat{i});
 
 end

diff --git a/TOSSH_code/signature_functions/sig_EventGraphThresholds.m b/TOSSH_code/signature_functions/sig_EventGraphThresholds.m
@@ -106,7 +106,7 @@
 %   Tani, M., 1997. Runoff generation processes estimated from hydrological
 %   observations on a steep forested hillslope with a thin soil layer.
 %   Journal of Hydrology, 200(1-4), pp.84-109.
-%   Wrede, S., Fenicia, F., MartÃnezâ€?Carreras, N., Juilleret, J., Hissler,
+%   Wrede, S., Fenicia, F., Martinez-Carreras, N., Juilleret, J., Hissler,
 %   C., Krein, A., Savenije, H.H., Uhlenbrook, S., Kavetski, D. and
 %   Pfister, L., 2015. Towards more systematic perceptual model
 %   development: a case study using 3 Luxembourgish catchments.

diff --git a/TOSSH_code/signature_functions/sig_FDC.m b/TOSSH_code/signature_functions/sig_FDC.m
@@ -65,9 +65,9 @@
 FDC = 1 - Q_ranked./length(Q_ranked); % flow duration curve with unique ranks
 
 % add warning for intermittent streams
-if length(Q_tmp(Q_tmp==0)) > length(Q_tmp)*0.05
+if ~isempty(Q_tmp(Q_tmp==0))
     error_flag = 2;
-    error_str = ['Warning: Flow is zero at least 5% of the time (intermittent flow). ', error_str];
+    error_str = ['Warning: Flow is zero at least once (intermittent flow). ', error_str];
 end
 
 % optional plotting

diff --git a/TOSSH_code/signature_functions/sig_FDC_slope.m b/TOSSH_code/signature_functions/sig_FDC_slope.m
@@ -118,9 +118,9 @@
 end
 
 % add warning for intermittent streams
-if length(Q_tmp(Q_tmp==0)) > length(Q_tmp)*0.05
+if ~isempty(Q_tmp(Q_tmp==0))
     error_flag = 2;
-    error_str = ['Warning: Flow is zero at least 5% of the time (intermittent flow). ', error_str];
+    error_str = ['Warning: Flow is zero at least once (intermittent flow). ', error_str];
 end
 
 % optional plotting