From ec85c82b8fd5505ac72f928801b65a185cc3c236 Mon Sep 17 00:00:00 2001 From: RY4GIT <400mhs2@gmail.com> Date: Thu, 13 Mar 2025 16:32:06 -0700 Subject: [PATCH 1/2] add Wu signature: update signature and docs --- .gitignore | 3 +- .../sig_EventGraphThresholds.m | 79 ++++++++++++++----- docs/_static/overland_flow_Wu.csv | 3 + docs/p2_signatures.rst | 15 ++++ 4 files changed, 80 insertions(+), 20 deletions(-) create mode 100644 docs/_static/overland_flow_Wu.csv diff --git a/.gitignore b/.gitignore index ec8d1e5..2f4f1ab 100644 --- a/.gitignore +++ b/.gitignore @@ -15,4 +15,5 @@ example/example_data/old old/ example/results/CAMELS_GB_TOSSH_signatures.mat example/results/CAMELS_TOSSH_signatures.mat -_build/ \ No newline at end of file +_build/ +main_test.m \ No newline at end of file diff --git a/TOSSH_code/signature_functions/sig_EventGraphThresholds.m b/TOSSH_code/signature_functions/sig_EventGraphThresholds.m index be312de..bff641a 100644 --- a/TOSSH_code/signature_functions/sig_EventGraphThresholds.m +++ b/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 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,9 +388,30 @@ 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]); title(['Flow, Baseflow and Event Separation']) @@ -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 \ No newline at end of file diff --git a/docs/_static/overland_flow_Wu.csv b/docs/_static/overland_flow_Wu.csv new file mode 100644 index 0000000..457ad78 --- /dev/null +++ b/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 +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 \ No newline at end of file diff --git a/docs/p2_signatures.rst b/docs/p2_signatures.rst index 030af15..c28c276 100644 --- a/docs/p2_signatures.rst +++ b/docs/p2_signatures.rst @@ -116,6 +116,17 @@ Note that these signatures are all calculated with the same function. :header-rows: 1 :delim: ; +Wu et al., (2021) overland flow set +""""""""""""""""""""""""""""""""" +Calculates 2 overland flow (infiltration excess and saturation excess) +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 +161,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). + From cda21ade9cb74510f4ac56b0bc71426b01824e6a Mon Sep 17 00:00:00 2001 From: RY4GIT <400mhs2@gmail.com> Date: Fri, 14 Mar 2025 11:08:51 -0700 Subject: [PATCH 2/2] update workflow for Wu sigs --- .gitignore | 3 ++- TOSSH_code/calculation_functions/calc_All.m | 3 ++- .../calculation_functions/calc_McMillan_OverlandFlow.m | 2 +- TOSSH_code/signature_functions/sig_EventGraphThresholds.m | 2 +- docs/_static/overland_flow_Wu.csv | 4 ++-- docs/p2_signatures.rst | 5 ++--- example/workflow_2_advanced.m | 2 +- 7 files changed, 11 insertions(+), 10 deletions(-) diff --git a/.gitignore b/.gitignore index 2f4f1ab..8cd59cd 100644 --- a/.gitignore +++ b/.gitignore @@ -16,4 +16,5 @@ old/ example/results/CAMELS_GB_TOSSH_signatures.mat example/results/CAMELS_TOSSH_signatures.mat _build/ -main_test.m \ No newline at end of file +main_test.m +log.txt \ No newline at end of file diff --git a/TOSSH_code/calculation_functions/calc_All.m b/TOSSH_code/calculation_functions/calc_All.m index 921a499..2837918 100644 --- a/TOSSH_code/calculation_functions/calc_All.m +++ b/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}); diff --git a/TOSSH_code/calculation_functions/calc_McMillan_OverlandFlow.m b/TOSSH_code/calculation_functions/calc_McMillan_OverlandFlow.m index fcca8bf..948f40c 100644 --- a/TOSSH_code/calculation_functions/calc_McMillan_OverlandFlow.m +++ b/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); diff --git a/TOSSH_code/signature_functions/sig_EventGraphThresholds.m b/TOSSH_code/signature_functions/sig_EventGraphThresholds.m index bff641a..358468c 100644 --- a/TOSSH_code/signature_functions/sig_EventGraphThresholds.m +++ b/TOSSH_code/signature_functions/sig_EventGraphThresholds.m @@ -413,7 +413,7 @@ 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); diff --git a/docs/_static/overland_flow_Wu.csv b/docs/_static/overland_flow_Wu.csv index 457ad78..c53fa28 100644 --- a/docs/_static/overland_flow_Wu.csv +++ b/docs/_static/overland_flow_Wu.csv @@ -1,3 +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 -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 \ No newline at end of file +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 \ No newline at end of file diff --git a/docs/p2_signatures.rst b/docs/p2_signatures.rst index c28c276..f66a8b1 100644 --- a/docs/p2_signatures.rst +++ b/docs/p2_signatures.rst @@ -118,9 +118,8 @@ Note that these signatures are all calculated with the same function. Wu et al., (2021) overland flow set """"""""""""""""""""""""""""""""" -Calculates 2 overland flow (infiltration excess and saturation excess) -signatures from Wu et al., (2021) [8]_. The implementation in this toolbox - is the adapted and coded version by Bolotin and McMillan (2025) [9]_. +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 diff --git a/example/workflow_2_advanced.m b/example/workflow_2_advanced.m index a9d266a..a6fb5ef 100644 --- a/example/workflow_2_advanced.m +++ b/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.