code cleanup

.gitignore

@@ -0,0 +1,2 @@
+data/
+prelres/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2016 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,8 @@
+# VIEWS
+The Lake Victoria Intense storm Early Warning System (VIEWS)
+
+Version 1.0 of the package, termed Lake Victoria Intense storm Early Warning System (VIEWS), is available at https://github.com/wthiery/VIEWS and is released under the MIT licence. 
+
+At this stage the prediction system needs to be considered as a prototype; more research as well as input from the user community is needed to improve  its skill. 
+
+When applied, the package runs permanently, and is activated at forecast lead time. The software first downloads the OT images corresponding to the daytime hours from the NASA Langley Research Centre data repository. It subsequently computes the predictor value OT_{day} for each country and the whole lake by performing the appropriate spatial and temporal selection (see equation 2 and table 1 in Thiery et al., 2017 ERL). The OT_day values then serve as input for the respective logistic regressions (see equation 1 and table 1 in Thiery et al., 2017 ERL), yielding the probability for an extreme event. Depending on the threshold probability defined by the user, the software will indicate whether or not a warning is to be issued for a specific lake sector or the whole lake.

main.m

@@ -0,0 +1,137 @@
+
+% --------------------------------------------------------------------
+% The Lake Victoria Intense storm Early Warning System (VIEWS)
+% 
+% When using this model please cite this reference:
+% 
+% Thiery, W., Gudmundsson, L., Bedka, K., Semazzi, F.H.M., Lhermitte, 
+% S., Willems, P., van Lipzig, N.P.M. and Seneviratne, S.I. Early 
+% warnings of hazardous thunderstorms on Lake Victoria, Env. Res. 
+% Lett., in review.
+% --------------------------------------------------------------------
+
+
+% to do:
+% - hours_day differs between whole lake, KEN, TAN and UGA !!!
+% - 'clock' should be UTC not local time  !!!
+
+
+
+% --------------------------------------------------------------------
+% main script to perform intense storm prediction
+% tested on MATLAB 7.12.0 (R2011a)
+% --------------------------------------------------------------------
+
+
+% start clock
+tic
+
+
+% clean up
+clc;
+clear;
+close all;
+
+
+% flags
+flags.user_OTdata = 2; % 0: use historical data
+                       % 1: request input from user about OT data
+                       % 2: operational mode with data from NASA server
+flags.user_config = 0; % 0: use optimised model configuration from Thiery et al., 2017 ERL
+                       % 1: request input from user about model configuration
+flags.plot        = 0; % 0: do not plot
+                       % 1: plot
+
+
+
+% --------------------------------------------------------------------
+% initialisation
+% --------------------------------------------------------------------
+
+
+% define hours considered as "day" and "night"
+hours_night = [22:24 1:9]; % final estimate based on OT diurnal cycle
+hours_day   = 10:15;
+
+
+% define percentile above which events are considered 'severe'
+perc_severe = 99;
+
+
+% initialise model parameters
+res_reg = 0.20; % predefined regular grid
+
+
+% name of the best logistic regression model (obtained by optimisation, see paper section 4)
+model_best = 'OT_models_best.mat';
+
+
+% name of the best logistic regression model (obtained by optimisation, see paper section 4)
+% OT_data_test = 'OT_d_best_20050311.mat';   % example data for testing the model - calm day    (11/03/2005)
+OT_data_test = 'OT_d_best_20050314.mat'; % example data for testing the model - extreme day (14/03/2005)
+
+
+% Define remote path where OT data can be downloaded
+OT_rpath = 'https://clouds.larc.nasa.gov/prod/exp/lake_victoria';
+
+
+% add data path to work path
+addpath('data')
+
+
+% --------------------------------------------------------------------
+% load data
+% --------------------------------------------------------------------
+
+
+% load best logistic regression model
+if     flags.user_config == 0
+    load(model_best)
+elseif flags.user_config == 1
+    model_user = input('Please name the file containing the logistic regression model (e.g. LOGR_OT_best.mat)\n\n','s');
+    load(model_user)
+end
+
+
+% load Overshooting Top (OT) data
+if     flags.user_OTdata == 0    % use historical data
+
+    disp(sprintf(['Loading test data (' OT_data_test ')\n'])) %#ok<*DSPS>
+    load(OT_data_test)
+
+elseif flags.user_OTdata == 1    % request input from user about OT data
+
+    OT_data_user = input('Please name the file containing the afternoon OT map (e.g. OT_d_best_20050311.mat)\n\n','s');
+    load(OT_data_user)
+
+elseif flags.user_OTdata == 2    % operational mode with data from NASA server
+
+    [OT_d, OT_d_regridded_daysum] = mf_get_OT_today(OT_rpath, LOGR_OT_best.hours_day, LOGR_OT_best.lat, LOGR_OT_best.lon);
+
+end
+
+
+
+% --------------------------------------------------------------------
+% Perform prediction
+% --------------------------------------------------------------------
+
+
+% whole lake
+mf_VIEWS('Whole lake', OT_d, LOGR_OT_best);
+
+
+% Sector Uganda
+mf_VIEWS('Uganda'    , OT_d, LOGR_OT_best_Uga);
+
+
+% Sector Kenya
+mf_VIEWS('Kenya'     , OT_d, LOGR_OT_best_Ken);
+
+
+% Sector Tanzania
+mf_VIEWS('Tanzania'  , OT_d, LOGR_OT_best_Tan);
+
+
+% stop clock
+toc

mf_VIEWS.m

@@ -0,0 +1,37 @@
+
+
+% --------------------------------------------------------------------
+% function to perform logistic regression and compute ROC curve
+% --------------------------------------------------------------------
+
+
+function [warning] = mf_VIEWS(sector, OT_d, LOGR_OT)
+
+
+% --------------------------------------------------------------------
+% manipulations
+% --------------------------------------------------------------------
+
+
+% get daytime daytime total OTs over highly correlated regions
+OT_d_gp = nansum(nansum(OT_d(LOGR_OT.iscorr),1),2);
+
+
+% get probability for an extreme night given the input logistic regression model
+p_all = glmval(LOGR_OT.b_all, OT_d_gp, 'logit');
+
+
+% decide whether warning nees to be issued 
+% assume optimal point (threshold probability for the difference between
+% hit rate and false alarm rate is maximum)
+if     p_all <  LOGR_OT.T_opt % do not issue warning
+    warning = 0;
+    disp(sprintf(['NO WARNING (' sector ')\n'])) %#ok<*DSPS>
+elseif p_all >= LOGR_OT.T_opt % issue warning
+    warning = 1;
+    disp(sprintf(['WARNING (' sector '):\n High probability for extreme nighttime thunderstorm activity on Lake Victoria\n']))
+end
+
+
+
+end