
% Script to explain usage of the scripts for Sentinel-2 and Landsat 8
% analysis as part of the Fully Automated Supraglacial lake Tracking at
% Enhanced Resolution (FASTER) algorithm. 

% Full details are provided in the paper on The Cryosphere
% (https://doi.org/10.5194/tc-2018-56). Anyone using any of the scripts
% below should ensure full and proper reference is made to that article. 

% Andrew Williamson, July 2018 

%% Pre-processing 

% The two scripts: 
L8_preprocess.m 
S2_preprocess.m 
% should be used first to process all imagery. Take individual raw .jp2 S-2
% images, get NDWI masks from them, save processed bands as .mat files, and
% save RGB images for each day. 

% Both the S-2 and L-8 scripts involve filtering of small lakes and include
% steps to filter out no-data values based on the original imagery. This
% largely follows Pope and others (2016), and references the function: 
SGL_mask_filter.m 

% S2_cloud_filter.m takes the NDWI SGL masks and then semi-manually removes
% clouds and shadows from them using the B11.jp2 files also downloaded from
% the Sentinel-2 AWS. This script is now incorproated into the 
% S2_preprocess.m script, so should not need running separately (unless it
% is discovered later that an extra image needs clouds removing, perhaps). 
S2_cloud_filter.m

% The Landsat 8 script does the same but also includes cloud masking to
% remove clouds, also includes Neil Arnold's function to get surface
% reflectance from digital numbers (ls8_dn2refl.m), and to use the 
% Landsat-8 metadata with a parser (ls8_meta_parser.m) to break up these 
% text files. In addition, this script includes calculations of the
% percentage of data cover and cloud cover. 
% These are: 
ls8_dn2refl.m 
ls8_meta_parser.m 

%% Making RGBs 

S2_make_RGBs.m 
% A script to make an RGB image for a given Sentinel-2 image.
% Designed to be used individually for an image without batch processing
% capability. 

%% NDWI sensitivity 

% This script is to test the sensitivity of the classification approach for
% S-2 to a variety of thresholds. Does it for each image individually. 
S2_NDWI_sensitivity.m 

% Ideally use this script before then using the threshold defined as best
% which is required as part of the main S2_preprocess.m script. 

% This script calls on function 
S2_NDWI.m
% This is a simple function to just do the NDWI calculation 

% To compare the Sentinel-2 and Landsat-8 NDWI methods to ensure that we
% aren't getting different lake outlines from the two, we use the script 
S2_L8_NDWI_comp.m 
% which compares total lake area from both for overlapping images, and
% defines the RMSE per lake based on this method (for the S2 data). 

%% Lake depth calculations 

L8_lake_depth.m
% is a method to calculate lake depths for each image from the Landsat-8
% series within the boundaries of the lakes defined from the NDWI method.
% Saves depth arrays at both 30 m and 10 m resolution (the 10 m resolution
% data for consistency with the Sentinel-2 resolution). This is to be
% regarded as a validated method, which produces effective ground-truth
% data. 

% EMPIRICAL method 
S2_L8_depth_empirical_comp.m 
% is a script to compare Sentinel-2 digital numbers for each pixel against
% the Landsat-8 lake depths (calculated with Pope and others, 2016,
% physically based method). Makes plots for the data and helps to identify
% a regression that can then be used on the S2 band data as part of the
% S2 lake-depth empirical calculation script. This is therefore a
% validation script. 

S2_lake_depth_empirical.m 
% is a script to use the regression relationship defined from the
% S2_L8_depth_regression.m to get the lake depths for each of the lakes
% defined from the NDWI applied to Sentinel-2 imagery. 

% PHYSICAL method 
S2_L8_depth_physical_comp.m 
% is a script to compare Landsat-8 lake depths (in m) derived from the
% physically based method applied to the red and pan bands, which are 
% regarded as ground-truth data, against the Sentinel-2 lake depths (in m)
% derived from the same physically based method applied to Sentinel-2's red
% band. This is therefore a validation script. 

S2_lake_depth_physical.m 
% is a script to calculate lake depths with the physically based method for
% all of the lakes defined from the NDWI with Sentinel-2 imagery for the
% whole season. 

%% Lake tracking

% This scripts takes the final masks of lakes (once cleaned up to remove
% clouds, small lakes and linear features), and requires no-data values to
% be set properly to track the lakes through a series of imagery and
% identify rapid drainage events, as per Williamson and others' (2017) FAST
% Algorithm, in adapted FASTER algorithm version... 

% So essentially these are the last script that should be run once all of the
% other pre-processing ones have been completed. If done earlier (e.g. if
% no-data values have not been correctly marked, and are instead marked as,
% e.g. 0s, then this will not work and drainage events will be
% misclassified). 

S2_L8_make_max_extent.m
% is used to make maximum summer lake extents using either the Sentinel-2,
% Landsat-8 or both sets of imagery together by superimposing all of the
% summer images on top of one another. It also includes a minor step to
% remove cloud shadows from a couple of the Landsat-8 images with issues

S2_L8_lake_tracking.m 
% Tracks changes to lake areas and volumes within the maximum extent mask
% created above. 

%% Lake drainage 

S2_L8_lake_drainage.m 
% Identifies rapid lake drainage after the earlier scripts have been run
% and lake areas have been tracked over the season. Can identify based on
% area or volume loss thresholds. Some fiddling with parameters will be
% required to ensure that this works correctly with different data. 

S2_L8_drainage_analysis.m 
% Does some very simple analysis (using hard-coded parameters) on the
% drainage output data. 
