Merge pull request #12 from TOSSHtoolbox/ry-patch

Add Wu et al., (2021) signature

Author: RY4GIT

.gitignore

@@ -15,4 +15,6 @@ example/example_data/old
 old/
 example/results/CAMELS_GB_TOSSH_signatures.mat
 example/results/CAMELS_TOSSH_signatures.mat
-_build/
+_build/
+main_test.m
+log.txt

TOSSH_code/calculation_functions/calc_All.m

@@ -70,7 +70,7 @@
 BaseflowMagnitude_error_str = strings(size(Q_mat,1),1);
 BFI = NaN(size(Q_mat,1),1);
 BFI_error_str = strings(size(Q_mat,1),1);
-EventGraphThresholds = NaN(size(Q_mat,1),10);
+EventGraphThresholds = NaN(size(Q_mat,1),12);
 EventGraphThresholds_error_str = strings(size(Q_mat,1),1);
 EventRR = NaN(size(Q_mat,1),1);
 EventRR_error_str = strings(size(Q_mat,1),1);
@@ -154,6 +154,7 @@
         EventGraphThresholds(i,5),EventGraphThresholds(i,6),...
         EventGraphThresholds(i,7),EventGraphThresholds(i,8),...
         EventGraphThresholds(i,9),EventGraphThresholds(i,10),...
+        EventGraphThresholds(i,11),EventGraphThresholds(i,12),...
         ~,EventGraphThresholds_error_str(i)] = ...
         sig_EventGraphThresholds(Q_mat{i},t_mat{i},P_mat{i});
     [EventRR(i),~,EventRR_error_str(i)] = sig_EventRR(Q_mat{i},t_mat{i},P_mat{i});

TOSSH_code/calculation_functions/calc_McMillan_OverlandFlow.m

@@ -106,7 +106,7 @@
 
     [IE_effect(i),SE_effect(i),IE_thresh_signif(i),IE_thresh(i), ...
         SE_thresh_signif(i),SE_thresh(i),SE_slope(i),Storage_thresh(i), ...
-        Storage_thresh_signif(i),min_Qf_perc(i),~,OF_error_str(i)] ...
+        Storage_thresh_signif(i),min_Qf_perc(i),~,~,~,OF_error_str(i)] ...
         = sig_EventGraphThresholds(Q_mat{i},t_mat{i},P_mat{i},...
         'plot_results',plot_results,'max_recessiondays',max_recessiondays);
 

TOSSH_code/signature_functions/sig_EventGraphThresholds.m

@@ -1,6 +1,6 @@
 function [IE_effect, SE_effect, IE_thresh_signif, IE_thresh, ...
     SE_thresh_signif, SE_thresh, SE_slope, ...
-    Storage_thresh, Storage_thresh_signif, min_Qf_perc, ...
+    Storage_thresh, Storage_thresh_signif, min_Qf_perc, R_Pvol_RC, R_Pint_RC,...
     error_flag, error_str, fig_handles] = sig_EventGraphThresholds(Q,t,P,varargin)
 %%   sig_EventGraphThresholds calculates a variety of signatures related to saturation and infiltration excess flow.
 %   Calculates a variety of signatures related to saturation excess (SE)
@@ -68,6 +68,18 @@
 %   Indicates impermeable area contribution (qualitative description in
 %   Becker and McDonnell, 1998).
 %
+%   Event signatures from Wu et al., (2021); translated to Matlab in
+%   Bolotin and McMillan (2025).
+%   R_Pvol_RC: Pearson correlation beween total precipitation vs. normalized quick flow
+%   (equivalent to event runoff coefficient = (quickflow volume / total P))
+%   Related to stormflow processes which are sensitive to rainfall volume,
+%   for example, SSF2, SOF, SSF1, and GWF. Called "SE_correlation" in
+%   Bolotin and McMillan (2025).
+%   R_Pint_RC: Pearson correlation beween average precipitation intensity vs. normalized quick flow
+%   Related to Stormflow processes which are sensitive to rainfall
+%   intensity, for example, HOF. Called "IE_correlation" in
+%   Bolotin and McMillan (2025).
+%
 %   error_flag: 0 (no error), 1 (warning), 2 (error in data check), 3
 %       (error in signature calculation)
 %   error_str: string contraining error description
@@ -95,6 +107,9 @@
 %   controls of runoff generation and lateral flows in mountain catchments.
 %   IAHS Publications-Series of Proceedings and Reports-Intern Assoc
 %   Hydrological Sciences, 248, pp.199-206.
+%   Bolotin, L. A., & McMillan, H. (2024). A hydrologic signature approach
+%   to analysing wildfire impacts on overland flow. Hydrological Processes,
+%   38(6). https://doi.org/10.1002/hyp.15215
 %   Estrany, J., Garcia, C. and Batalla, R.J., 2010. Hydrological response
 %   of a small mediterranean agricultural catchment. Journal of Hydrology,
 %   380(1-2), pp.180-190.
@@ -111,7 +126,11 @@
 %   Pfister, L., 2015. Towards more systematic perceptual model
 %   development: a case study using 3 Luxembourgish catchments.
 %   Hydrological Processes, 29(12), pp.2731-2750.
-%
+%   Wu, S., Zhao, J., Wang, H., & Sivapalan, M. (2021).
+%   Regional patterns and physical controls of streamflow generation across
+%   the conterminous United States. Water Resources Research, 57(6),
+%   e2020WR028086. https://doi.org/10.1029/2020wr028086
+
 %   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.
@@ -172,6 +191,8 @@
     Storage_thresh = NaN;
     Storage_thresh_signif = NaN;
     min_Qf_perc = NaN;
+    R_Pvol_RC = NaN;
+    R_Pint_RC = NaN;
     return
 end
 timestep_factor = 1/days(timestep); % adjust for timestep
@@ -222,31 +243,31 @@
 for i = 1:size(stormarray,1)
     % total event precipitation [mm] (Estrany names this as X3 coefficient)
     event_array(i,1) = sum(P(stormarray(i,1):stormarray(i,3)),'omitnan');
-    
+
     % event average precipitation intensity [mm/timestep] (Estrany X4)
     event_array(i,2) = mean(P(stormarray(i,1):stormarray(i,3)),'omitnan');
-    
+
     % event maximum precipitation intensity [mm/timestep] (Estrany X5; but they used 5 min data)
     event_array(i,3) = max(P(stormarray(i,1):stormarray(i,3)));
-    
+
     % antecedent precipitation 3 days before [mm] (Estrany X1)
     time_antecedent = max(stormarray(i,1) - 3*24/timestep,1);
     event_array(i,4) = sum(P(time_antecedent:stormarray(i,1)),'omitnan');
-    
+
     % antecedent precipitation 7 days before [mm] (Estrany X2)
     time_antecedent = max(stormarray(i,1) - 7*24/timestep,1);
     event_array(i,5) = sum(P(time_antecedent:stormarray(i,1)),'omitnan');
-    
+
     % total event flow volume [mm]
     event_array(i,6) = sum(Q(stormarray(i,1):stormarray(i,3)),'omitnan');
-    
+
     % total event quickflow volume [mm]
     event_array(i,7) = sum(Q(stormarray(i,1):stormarray(i,3)),'omitnan')-...
         sum(B(stormarray(i,1):stormarray(i,3)),'omitnan');
-    
+
     % maximum event runoff [mm/timestep]
     event_array(i,8) = max(Q(stormarray(i,1):stormarray(i,3)));
-    
+
     % antecedent precipitation index (API) using Mosley (1979) method
     % (sum Pi/i for 30 days)
     % get total antecedent time
@@ -367,11 +388,32 @@
 Storage_thresh_signif = p_value_st_qf;
 Storage_thresh = thresh_st_qf;
 
+%% Wu et al. (2021) correlations for SE and IE
+
+% Event Runoff coefficients = quickflow volume / total P
+rcq = event_array(:,7)./event_array(:,1);
+
+% Use Wu et al definition of significant events
+% Ratio of start and end Q to peak is less than BFI
+bfi = sum(B,'omitnan')/sum(Q,'omitnan');
+start_ratio = Q(stormarray(:,1))./event_array(:,8);
+end_ratio = Q(stormarray(:,3))./event_array(:,8);
+large_events = and(start_ratio < bfi, end_ratio < bfi);
+
+if sum(large_events)>2
+    %Spearman rank Corr of total P and average intensity with RC
+    [R_Pvol_RC,~] = corr(event_array(large_events,1), rcq(large_events), 'Type', 'Spearman');
+    [R_Pint_RC,~] = corr(event_array(large_events,2), rcq(large_events), 'Type', 'Spearman');
+else
+    R_Pvol_RC = NaN;
+    R_Pint_RC = NaN;
+end
+
 %% optional plotting
 if plot_results
-    
+
     % plot flow, baseflow and events
-    fig_events = figure('Position',[300 300 700*2 250*2]);
+    fig_events = figure('Position',[100 100 700*2 250*2]);
     title(['Flow, Baseflow and Event Separation'])
     dates_dt = t;%datetime(dates,'ConvertFrom','datenum');
     P_max = max(P);
@@ -384,13 +426,12 @@
             dates_dt(stormarray(i,3)),dates_dt(stormarray(i,3))],...
             [0, P_max, P_max, 0],[198, 219, 239]/255,'LineStyle','none');
     end
-
+    p5=plot(dates_dt(:),P(:),'color',[250,159,18]/255,'linewidth',1);
     p1 = plot(t,Q,'k-','linewidth',1);
     p2 = plot(t,B,'k--','linewidth',1);
-    p5=plot(dates_dt(:),P(:),'color',[250,159,18]/255,'linewidth',1);
 
     xlabel('Time')
-    ylabel('Flow or Rainfall [mm]')
+    ylabel('Flow [mm]')
     legend([p1, p2, p3, p4, p5],{'Flow','Baseflow','Events','Recessions','Rainfall'},'location','best')
 
     % plot total precip against quickflow, with threshold
@@ -407,7 +448,7 @@
     xlabel('Event precipitation [mm]')
     ylabel('Event quickflow volume [mm]')
     legend([p1, p2, p3],{'Data','No threshold','With threshold'},'location','best')
-    
+
     % maximum intensity against quickflow, with threshold
     subplot(1,3,2)
     title(['Quickflow vs intensity, p = ',num2str(round(p_value_mi_qf,6))])
@@ -421,7 +462,7 @@
     xlabel('Event maximum intensity [mm/timestep]')
     ylabel('Event quickflow volume [mm]')
     legend([p1, p2, p3],{'Data','No threshold','With threshold'},'location','best')
-    
+
     % API + total precipitation against quickflow, with threshold
     subplot(1,3,3)
     title(['Quickflow vs API + P, p = ',num2str(round(p_value_st_qf,6))])
@@ -435,7 +476,7 @@
     ylabel('Event quickflow volume [mm]')
     legend([p1, p2, p3],{'Data','No threshold','With threshold'},'location','best')
     fig_handles.EventGraphThresholds = fig;
-    
+
     % Wrede et al. (2015) say "high intensity storms that don't produce
     % flow imply no IE processes". We plot max intensity against quickflow
     % on a seasonal basis for the user to evaluate this.
@@ -457,5 +498,5 @@
     legend('DJF','MAM','JJA','SON','location','best')
     title('Quickflow vs intensity per season') % Wrede 2015
     fig_handles.EventGraphThresholdsSeasons = fig2;
-    
-end
+
+end

docs/_static/overland_flow_Wu.csv

@@ -0,0 +1,3 @@
+Signature;Function (click for code);Unit;Description
+R_Pvol_RC;`sig_EventGraphThresholds.m <./_static/matlab/TOSSH_code/TOSSH/TOSSH_code/signature_functions/sig_EventGraphThresholds.html>`_ ;--; Pearson correlation between total precipitation volume and quickflow, related to saturation excess overlandflow process
+R_Pint_RC;`sig_EventGraphThresholds.m <./_static/matlab/TOSSH_code/TOSSH/TOSSH_code/signature_functions/sig_EventGraphThresholds.html>`_ ;--; Pearson correlation between precipitation intensity and quickflow, related to infiltration excess overlandflow process

docs/p2_signatures.rst

@@ -116,6 +116,16 @@ Note that these signatures are all calculated with the same function.
    :header-rows: 1
    :delim: ;
 
+Wu et al., (2021) overland flow set
+"""""""""""""""""""""""""""""""""
+A function `sig_EventGraphThresholds.m <./_static/matlab/TOSSH_code/TOSSH/TOSSH_code/signature_functions/sig_EventGraphThresholds.html>`_ contains 2 overland flow 
+signatures from Wu et al., (2021) [8]_. The implementation in this toolbox is the adapted and coded version by Bolotin and McMillan (2025) [9]_. 
+
+.. csv-table:: Wu et al., (2021) overland flow set
+   :file: ./_static/overland_flow_Wu.csv
+   :header-rows: 1
+   :delim: ;
+
 
 TOSSH: all remaining signatures
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -150,3 +160,7 @@ References
 
 .. [7] McMillan, H.K., 2020. Linking hydrologic signatures to hydrologic processes: A review. Hydrological Processes, 34(6), pp.1393-1409.
 
+.. [8] Wu, S., Zhao, J., Wang, H., & Sivapalan, M. (2021). Regional patterns and physical controls of streamflow generation across the conterminous United States. Water Resources Research, 57(6), e2020WR028086.
+
+.. [9] Bolotin, L. A., & McMillan, H. (2024). A hydrologic signature approach to analysing wildfire impacts on overland flow. Hydrological Processes, 38(6). 
+

example/workflow_2_advanced.m

@@ -137,7 +137,7 @@
 % Some signatures focus on patterns that are best analysed visually. For 
 % example, the quickflow response during a rainfall event can indicate 
 % which runoff generation processes occur in a catchment. 
-[ie_effect, se_effect, ~, ~, ~, ~, ~, ~, ~, ~, ~, ~, fig_EventGraphThresholds] = ...
+[ie_effect, se_effect, ~, ~, ~, ~, ~, ~, ~, ~, ~, ~, ~, ~, fig_EventGraphThresholds] = ...
     sig_EventGraphThresholds(Q_3,t_3,P_3,'plot_results',true);
 % We can see that most summer storms lead to little runoff, while all 
 % winter storms produce runoff. This indicates saturation excess quickflow.