% =========================================
% CHIROL_CREEK-ALGORITHM README FILE
% =========================================
ReadMe Author: DR CLEMENTINE CHIROL [ORCID ID https://orcid.org/0000-0003-0932-4725]
% =========================================
% INTRODUCTION
% =========================================
CHIROL-CREEK-ALGORITHM is a semi-automated coastal wetland creek parametrisation tool developed in 2018 by Clementine
Chirol as part of her PhD at the University of Southampton, from 2014 to 2018, in collaboration with Jacobs. This
tool uses a semi-automated elevation and slope thresholds method to detect a creek network, and gives as outputs
an Excel table of morphometric characteristics and several figures.
The scripts are run on MatLAB2015a.
The study used year-specific, gap infilled DSM elevation maps from lidar data at 1 m resolution obtained via the
Environment Agency open survey data platform: https://environment.data.gov.uk/DefraDataDownload/?Mode=survey
More information on the rationale and methods can be found in the following publication:
"Chirol, C., Haigh, I.D., Pontee, N., Thompson, C. and Gallop, S. (2018). Parameterizing tidal creek morphology
in mature saltmarshes using semi-automated extraction from lidar, Remote Sensing of the Environment, 209, 291-311."
% =========================================
% UTILISATION GUIDE
% =========================================
NOTE: To test the script using the demo files provided, go directly to step C).
A) Export elevation and slope maps from ArcGIS 10.2.2 using the tool "Raster to ASCII" for the area of interest into
the "INPUTS" folder.
Notes:
1-If comparing several sites, ensure that georeferencing and elevation units are consistent
2-The area of interest should be a coastal wetland containing one or several creek systems, delimited seaward by
its connection to the wider estuary, landward by the Highest Astronomical Tide level, and laterally by the mean
distance to the surrounding creek systems. Ideally the area of interest should be an isolated drainage basin.
3-The Slope map is obtained from the ArcGIS tool "Slope"
4-Holes in the dataset due to lidar detection errors can be infilled using the ArcGIS tool "Nibble"
B) Run the Matlab function "LOADINFILES" and select the .txt elevation and slope maps in the pop-up window to load
them as Matlab files. Several files may be selected at once.
Note: this function calls the secondary function "loadinmultiLiDAR"
C) Open the "VarDef_TEMPLATE" Notepad file in the INPUTS folder. The file contains the file names, tidal
characteristics, creek detection thresholds and creek repair parameters necessary for running the core script
"CHIROL_CREEK_ALGORITHM".
Note: the template uses the managed realignment site Freiston 2014 as an example
D) Run the core Matlab script "CHIROL_CREEK_ALGORITHM" and follow instructions in the pop-up screens. The function
calls all remaining secondary functions. The main 10 steps of the script are detailed below:
Step 1: User to select "VarDef_TEMPLATE" from the "INPUTS" folder in the pop-up window to read the variables
Step 2: Load in initial datasets: elevation and slope maps
Step 3: Extract raw creek mask using the tidal characteristics and/or creek detection thresholds in "VarDef_TEMPLATE"
Step 4: Repair the creek mask using the creek repair parameters detailed in "VarDef_TEMPLATE"
Step 5: Creek ordering using an automated pruning process
Step 6: Creek ordering corrections using a GUI interface (to correct looping creeks for instance)
Step 7: Plot the creek system with its Reverse Strahler orders
Step 8: Calculate width, depth and cross-sectional area in a normal transect through the middle of each creek segment
Step 9: Calculate lowest juntion angle at the node of each creek segment
Step 10: Create, plot and save result tables
More details on each step can be found in the "CHIROL_CREEK_ALGORITHM" script and in the secondary functions,
accessible in the Matlab Editor.
% =========================================
% RESULTS
% =========================================
-Excel table "Creek Morphometry"
-Table of creek thresholds displayed in a pop-up Matlab table
-Figures of the parameter distribution per order
-Figure of the raw creek area mask
-Figure of the repaired creek area mask
-Figure of the creek single-line skeleton mask
-Figure of the creek skeleton showing the order of each creek
-Figure of the creek cross-sections, their locations and their creek order
-Figure of the junction angle calculation method
% =========================================
% LIST OF FOLDERS, FILES AND FUNCTIONS
% =========================================
% 3 Folders
-INPUTS
-OUTPUTS
-README
% 11 Input files
2 example creek systems are provided to test the algorithm:
-Banks 2014 (Natural mature saltmarsh creek system, analysed in Chirol et al., 2018, DOI = https://doi.org/10.1016/j.rse.2017.11.012)
elevation_banks2014.txt.mat
elevation_banks2014.txt_metadata.mat
slope_banks2014.txt.mat
slope_banks2014.txt_metadata.mat
-Freiston 2014 (Managed realignment site, raw and interpreted data presented in the associated Data Descriptor)
elevation_freiston2014.txt.mat
elevation_freiston2014.txt_metadata.mat
slope_freiston2014.txt.mat
slope_freiston2014.txt_metadata.mat
-UserVar_TEMPLATE.txt
-UserVar_Freiston2014.txt
-UserVar_Banks2014.txt
% 3 Primary Matlab functions (must be run by user)
-LOADINFILES
-CHIROL_CREEK_ALGORITHM
-CHIROL_CREEK_ALGORITHM (calculates the overmarsh path length, see Chirol et al. (2018) for method)
% 19 Secondary Matlab functions called by the primary functions for processing
-bresenham
-CreekDetection
-CreekDetectionManual
-detrend_2d
-freezeColors
-GUItest
-loadinmultiLiDAR
-Loadlidarmaps
-normalcoord3
-Process_Correctedsegments
-Process_Creekordering
-Process_Crosssections
-Process_Detect_threshold
-Process_Junctionangles
-Process_OutletDetection
-readvardef
-Reconnect
-Repair
-RemoveaboveHAT
% 6 Secondary Matlab functions called by the primary functions for: figure generation
-Figure_CreekDetection
-Figure_CreekSkeleton
-Figure_RawCreekMask
-Figure_ReconnectedCreekMask
-Figure_RepairedCreekMask
-Plot_Parameter_Distribution
% =========================================
% ACKNOWLEDGEMENTS
% =========================================
Some of the secondary functions were developed by other researchers and either given to the author or made open access
through Matlab File Exchange. These functions and their authors are listed below:
-bresenham: This function was written by Aaron Wetzler (15/07/2010)
-detrend_2d: This function was written by Munther Gdeisat-The General Engineering Research Institute (GERI) at
Liverpool John Moores University (09/10/2011)
-freezeColors: This function was written by John Iversen (iversen@nsi.edu) (03/23/05)
-imoverlay: This function was written by Steven L. Eddins, Copyright 2006-2012 The MathWorks, Inc.
-LOADINFILES and loadinmultiLiDAR were initially written by Dr Ivan Haigh (2015) then adapted for this work
-readvardef is adapted from a similar function by Dr Ian Townend (2008)
I would like to thank my PhD supervisors, Dr Ivan Haigh, Dr Shari Gallop, Dr Charlie Thompson and Dr Nigel Pontee
for their support over the course of this project