diff --git a/paper/paper.bib b/paper/paper.bib index 7277439d..33c9b949 100644 --- a/paper/paper.bib +++ b/paper/paper.bib @@ -9,6 +9,18 @@ @article{vos2019coastsat publisher={Elsevier} } +@article{sayre2019global, + author = {Roger Sayre, Suzanne Noble, Sharon Hamann, Rebecca Smith, Dawn Wright, Sean Breyer, Kevin Butler, Keith Van Graafeiland, Charlie Frye, Deniz Karagulle, Dabney Hopkins, Drew Stephens, Kevin Kelly, Zeenatul Basher, Devon Burton, Jill Cress, Karina Atkins, D. Paco Van Sistine, Beverly Friesen, Rebecca Allee, Tom Allen, Peter Aniello, Irawan Asaad, Mark John Costello, Kathy Goodin, Peter Harris, Maria Kavanaugh, Helen Lillis, Eleonora Manca, Frank Muller-Karger, Bjorn Nyberg, Rost Parsons, Justin Saarinen, Jac Steiner and Adam Reed}, + title = {A new 30 meter resolution global shoreline vector and associated global islands database for the development of standardized ecological coastal units}, + journal = {Journal of Operational Oceanography}, + volume = {12}, + number = {sup2}, + pages = {S47--S56}, + year = {2019}, + publisher = {Taylor \& Francis}, + doi = {10.1080/1755876X.2018.1529714} + } + @article{mclean202350, title={50 Years of Beach--Foredune Change on the Southeastern Coast of Australia: Bengello Beach, Moruya, NSW, 1972--2022}, author={McLean, R. and Thom, B. and Shen, J. and Oliver, T.}, @@ -19,6 +31,13 @@ @article{mclean202350 publisher={Elsevier} } +@misc{CoastSeg, + title={{CoastSat v2.4}}, + author={Fitzpatrick, S. and Buscombe,D. and Lundine, M. and Warrick,J. and Vos, K.}, + year={2024}, + publisher={GitHub}, + howpublished = {\url{https://github.com/kvos/CoastSat/releases/tag/v1.2.5}} + } @article{vos2023benchmarking, title={Benchmarking satellite-derived shoreline mapping algorithms}, diff --git a/paper/paper.md b/paper/paper.md index 045baa31..dabcfe52 100644 --- a/paper/paper.md +++ b/paper/paper.md @@ -40,7 +40,7 @@ bibliography: paper.bib # Summary -`CoastSeg` is an interactive browser-based program that aims to broaden the adoption of satellite-derived shoreline (SDS) detection and coastal landcover mapping workflows among coastal scientists and coastal resource management practitioners. SDS is a sub-field of coastal sciences that aims to detect and post-process a time-series of shoreline locations from publicly available satellite imagery [@turner2021satellite; @vitousek2023future]. `CoastSeg` is a Python package installed via pip into a `conda` environment that serves as an toolkit for building custom SDS workflows. `CoastSeg` also provides full SDS workflow implementations via Jupyter notebooks and Python scripts that call functions and classes in the core `CoastSeg` toolkit for specific workflows. CoastSeg provides two fully functioning SDS workflows and its design allows for collaborators in the SDS software community to contribute additional workflows. All the codes, notebooks, scripts, and documentation are hosted on the `CoastSeg` GitHub repository. +`CoastSeg` is an interactive browser-based program that aims to broaden the adoption of satellite-derived shoreline (SDS) detection and coastal landcover mapping workflows among coastal scientists and coastal resource management practitioners. SDS is a sub-field of coastal sciences that aims to detect and post-process a time-series of shoreline locations from publicly available satellite imagery [@turner2021satellite; @vitousek2023future]. `CoastSeg` is a Python package installed via pip into a `conda` environment that serves as an toolkit for building custom SDS workflows. `CoastSeg` also provides full SDS workflow implementations via Jupyter notebooks and Python scripts that call functions and classes in the core `CoastSeg` toolkit for specific workflows. CoastSeg provides two fully functioning SDS workflows and its design allows for collaborators in the SDS software community to contribute additional workflows. All the codes, notebooks, scripts, and documentation are hosted on the `CoastSeg` GitHub repository [@CoastSeg]. So-called `instantaneous' SDS workflows, where shorelines are extracted from each individual satellite image rather than temporal composites [@bishop2021mapping], follow a basic recipe, namely 1) waterline estimation, where the 2D (x,y) location of the land-sea interface is determined, and 2) water-level correction, where the waterline location is mapped onto a shore-perpendicular transect, converted to a linear distance along that transect, then corrected for water level, and referenced to a particular elevation contour on the beach [@vos2019coastsat]. The resulting measurement is called a 'shoreline' and it is the location that the waterline intersects a particular elevation datum. Water level corrections typically only account for tide [@vos2019coastsat] but recently SDS workflows have incorporated both wave setup and runup correction, which are a function of the instantaneous wave field at the time of image acquisition [@konstantinou2023satellite; @vitousek2023future; @vitousek2023model; @castelle2021satellite]. @@ -48,7 +48,7 @@ So-called `instantaneous' SDS workflows, where shorelines are extracted from eac The second aim of `CoastSeg` is therefore to provide fully functioning SDS implementations in an accessible browser notebook format. Our principal objective to date has been to re-implement and improve upon a popular existing toolbox, `CoastSat` [@vos2019coastsat], allowing the user to carry out the well-established `CoastSat` SDS workflow with a well-supported literature [@castelle2021satellite; @castelle2022primary; @vos2023pacific; @vos2023benchmarking; @warrick2023large; @konstantinou2023satellite; @vitousek2023model; @mclean202350; @vandenhove2024secular], but in a more accessible and convenient way within the `CoastSeg` platform. In order to achieve this, we developed `CoastSat-package` [@voscoastsat], a Python package that is installed into the `CoastSeg` `conda` environment. `CoastSat-package` contains re-implemented versions of the original CoastSat codes, addresses the lack of pip or conda installability of CoastSat, and isolates the CoastSeg-specific enhancements from the original `CoastSat` code. The `CoastSeg` re-implementation of the `CoastSat` workflow is end-to-end within a single notebook. That notebook allows the user to, among other tasks: a) define a Region of Interest (ROI) on a webmap and upload geospatial vector format files; b) define, download and post-process satellite imagery; c) identify waterlines in that imagery using the `CoastSat` method [@vos2019coastsat]; d) correct those waterlines to elevation-based shorelines using tidal elevation-datum corrections provided through interaction with the pyTMD [@alley2017pytmd] API; and e) save output files in a variety of modern geospatial and other formats for subsequent analysis. Additionally, CoastSeg's toolkit-based design enables it to run as non-interactive scripts, catering to larger scale shoreline analysis projects.This flexibility ensures that CoastSeg can accommodate a wide range of research needs, from detailed, interactive exploration to extensive, automated analyses. -The third and final aim of `CoastSeg` is to implement a method to carry out SDS workflows in experimental and collaborative contexts, which aids both oversight and reproducibility as well as practical needs based on division of labor. We do this using `sessions`, a mechanism for saving the current state of the application into a session's folder. This folder contains all necessary inputs, outputs, and references to downloaded data used to generate the results. `Sessions` allow users to iteratively experiment with different combinations of settings and makes `CoastSeg` fully reproducible because everything needed to reproduce the session is saved to the folder. Users can share their `sessions` with others, enabling peers to replicate experiments, build upon previous work, or access data downloaded by someone else. This simplifies handovers to new users from existing users, simplifies teaching of the program, and encourages collective experimentation which may result in better shoreline data. +The third and final aim of `CoastSeg` is to implement a method to carry out SDS workflows in experimental and collaborative contexts, which aids both oversight and reproducibility as well as practical needs based on division of labor. We do this using `sessions`, a mechanism for saving the current state of the application into a session's folder. This folder contains all necessary inputs, outputs, and references to downloaded data used to generate the results. `Sessions` allow users to iteratively experiment with different combinations of settings and makes `CoastSeg` fully reproducible because everything needed to reproduce the session is saved to the folder. Users can share their `sessions` with others, enabling peers to replicate experiments, build upon previous work, or access data downloaded by someone else. This simplifies handovers to new users from existing users, simplifies teaching of the program, and encourages collective experimentation which may result in better shoreline data. Users might expect to adjust settings across several sessions to find the optimal configuration for each site, typically requiring 2 to 5 adjustments to achieve the best quality shorelines. `CoastSeg` is also designed to be extendable, serving as a hub that hosts alternative SDS workflows and similar workflows that can be encoded in a Jupyter notebook built upon the `CoastSeg` and `CoastSat-package` core functionalities. Additional notebooks can be designed to carry out shoreline extraction and coastal landcover mapping using alternative methods. We provide an example of an alternative SDS workflow based on a deep-learning based semantic segmentation model that is briefly summarized at the end of this paper. To implement a custom waterline detection workflow the originator of that workflow would contribute new Jupyter notebook, and add their specific waterline detection algorithm to the `CoastSeg` source code, so it could be used in their notebook's implementation. @@ -58,7 +58,7 @@ The third and final aim of `CoastSeg` is to implement a method to carry out SDS Coastal scientists and resource managers now have access to extensive collections of satellite data spanning more than four decades. However, it's only in recent years that advancements in algorithms, machine learning, and deep learning have enabled the automation of processing this satellite imagery to accurately identify and map shorelines from imagery, a process known as Satellite-Derived Shorelines, or SDS. SDS workflows [@garcia2015evaluating; @almonacid2016evaluation] are gaining rapidly in popularity, and in particular since the publication of the open-source implementation of the `CoastSat` workflow [@coastsat] for instantaneous SDS in 2018 [@vos2019coastsat]. Existing open-source software for SDS often require the user to navigate between platforms (non-reproducible elements), develop custom code, and/or engage in substantial manual effort. -We built CoastSeg with the aim of enhancing the CoastSat workflow. Our design streamlines the entire shoreline extraction process, thus facilitating a more efficient experimental approach to determine the optimal combination of settings to extract the greatest number of accurate shorelines. CoastSeg achieves these improvements through several key advancements: it ensures reproducible sessions for consistent comparison and analysis; introduces additional filtering mechanisms to refine results; and provides an interactive user webmap that allows the users to users to view the quality of the extracted shorelines. Further, `CoastSeg` has been designed specifically to host alternative SDS workflows, recognizing that it is a nascent field of coastal science, and the optimal methodologies for all coastal environments and sources of imagery are yet to be established. Therefore `CoastSeg` provides a means with which to extract shorelines using multiple methods and adopt the one that most suits their needs, or implement a new methods. +We built CoastSeg with the aim of enhancing the CoastSat workflow. Our design streamlines the entire shoreline extraction process, thus facilitating a more efficient experimental approach to determine the optimal combination of settings to extract the greatest number of accurate shorelines. CoastSeg achieves these improvements through several key advancements: it ensures reproducible sessions for consistent comparison and analysis; introduces additional filtering mechanisms to refine results; and provides an interactive user webmap that allows the users to view the quality of the extracted shorelines. Further, `CoastSeg` has been designed specifically to host alternative SDS workflows, recognizing that it is a nascent field of coastal science, and the optimal methodologies for all coastal environments and sources of imagery are yet to be established. Therefore `CoastSeg` provides a means with which to extract shorelines using multiple methods and adopt the one that most suits their needs, or implement new methods. We summarize the needs met by the `CoastSeg` project as follows: @@ -86,7 +86,7 @@ At a high level, `CoastSeg` is designed to be an accessible and extendable hub f `CoastSeg` is installable as a package into a `conda` environment. `CoastSeg` notebooks are accessed from GitHub. We also created a pip package for the `CoastSat` workflow we named `CoastSat-package` in order to a) improve the `CoastSat` method's software implementation without affecting the parent repository, and b) to install as a package into a `conda` environment, rather than duplicate code from CoastSat. -`CoastSeg` is built with a object-oriented architecture, where elements required by the `CoastSat` workflow such as Regions of Interest, reference shorelines, and transects are represented as distinct objects on the map. Each class stores data specific to that feature type as well as encompassing methods for styling the feature on the map, downloading default features, and executing various post-processing functions. +`CoastSeg` is built with an object-oriented architecture, where elements required by the `CoastSat` workflow such as regions of interest, reference shorelines, and transects are represented as distinct objects on the map. Each class stores data specific to that feature type as well as encompassing methods for styling the feature on the map, downloading default features, and executing various post-processing functions. ## Sessions @@ -96,11 +96,11 @@ SDS workflows require manipulating various settings in order to extract optimal ### Accessibility -`CoastSeg` facilitates entirely browser-based workflows with an interactive webmap and `ipywidget` controls. It interfaces with the Zenodo API to download reference shorelines for any location in the world, organized into 5x5 degree chunks in GeoJSON format [@buscombe_2023_7786276] as well as transects, themselves providing beachface slope metadata [@buscombe_2023_8187949] available when users hover over each transect with their cursor. We have improved the reliability of `CoastSeg` through rigorous error handling, which includes developer log files for in-depth diagnostics, user report files for transparency, and detailed error messages that provide guidance for troubleshooting and problem resolution. We have also provided a set of utility scripts for common data input/output tasks, often the result of specific requests from our software testers (see Acknowledgments). In addition to a project wiki and improved documentation, we have researched minimum, maximum, and recommended values for all settings, set suggested default values, and have provided visual project management aids. +`CoastSeg` facilitates entirely browser-based workflows with an interactive webmap and `ipywidget` controls. It interfaces with the Zenodo API to download reference shorelines [@sayre2019global] for any location in the world, organized into 5x5 degree chunks in GeoJSON format [@buscombe_2023_7786276]. CoastSeg also provides transects for specific locations, offering beachface slope metadata [@buscombe_2023_8187949] that is available when users hover over each transect with their cursor. We have improved the reliability of `CoastSeg` through rigorous error handling, which includes developer log files for in-depth diagnostics, user report files for transparency, and detailed error messages that provide guidance for troubleshooting and problem resolution. We have also provided a set of utility scripts for common data input/output tasks, often the result of specific requests from our software testers (see Acknowledgments). In addition to a project wiki and improved documentation, we have researched minimum, maximum, and recommended values for all settings, set suggested default values, and have provided visual project management aids. ### Performance -`CoastSeg` improves upon the Google Earth Engine-based image retrieval process adopted by `CoastSat` by offering a more reliable and efficient download mechanism. Like `CoastSat`, we limit image sources to only the Landsat and Sentinel missions, which are publicly available to all. `CoastSeg` supports downloading multiple regions of interest in a single session, and ensures downloads persist even over an unstable internet connection. This is important because SDS users typically download all available imagery from an ROI, which may amount to several hundred to thousand individual downloaded scenes. Should a download error occur, `CoastSeg` briefly pauses before reconnecting to Google Earth Engine, ensuring the process doesn't halt completely. In cases where image downloading fails repeatedly, the filename is logged to a report file located within the downloaded data folder. This report file tracks the status of all requested images from Google Earth Engine. `CoastSeg`'s reliable image retrieval process enhances coastal monitoring by facilitating easier data management and collaboration. +`CoastSeg` improves upon the Google Earth Engine-based image retrieval process adopted by `CoastSat` by offering a more reliable and efficient download mechanism. Like `CoastSat`, we limit image sources to only the Landsat and Sentinel missions, which are publicly available to all. `CoastSeg` supports downloading multiple regions of interest in a single session, and ensures downloads persist even over an unstable internet connection. This is important because SDS users typically download all available imagery from an ROI, which may amount to several hundred to thousand individual downloaded scenes. Should a download error occur, `CoastSeg` briefly pauses before reconnecting to Google Earth Engine, ensuring the process does not halt completely. In cases where image downloading fails repeatedly, the filename is logged to a report file located within the downloaded data folder. This report file tracks the status of all requested images from Google Earth Engine. `CoastSeg`'s reliable image retrieval process enhances coastal monitoring by facilitating easier data management and collaboration. We added helpful workflow components such as image filtering options; for example, users can now filter their imagery based on image size and the proportion of no data pixels in an image. Additionally, the user can decide to turn off cloud masking, which is necessary when the cloud masking process fails and obscures non-cloudy regions such as bright pixels of sand beaches. Finally, we replaced non-cross-platform components of the original workflow, for example the pickle format was replaced with JSON or geoJSON formats which are both human-readable and compatible with GIS and webGIS. @@ -112,7 +112,7 @@ The CoastSat methodology for applying tide correction to shoreline positions inv In contrast, CoastSeg introduces a significant improvement to this process by leveraging the pyTMD API [@alley2017pytmd] for a more streamlined and accurate approach to tidal correction (Figure 1). pyTMD facilitates downloading a variety of tide models, including FES14 and models specific to polar regions, and automates tide estimations. We provide an automated workflow that downloads and subdivides the FES2014 model data into 11 global regions (an idea adopted from [@krause2021dea]). This subdivision allows the program to access only relevant subsets of data, drastically reducing the time required to estimate tides—from hours to minutes for multi-decadal satellite time series. Furthermore, CoastSeg calculates tide estimates for each transect corresponding to the times shorelines were detected. This ensures tide corrections are based on temporal and spatial matches, enhancing the accuracy of shoreline position adjustments. -![Schematic of the SDS workflows currently available in ``CoastSeg``. a) ``CoastSat`` workflow; b) ``Zoo`` workflow.](figs/coastseg_figure_2.png){#sylt width="100%"} +![Schematic of the SDS workflows currently available in ``CoastSeg``. a) ``CoastSat`` workflow; b) ``Zoo`` workflow. Each session has distinct settings that influence the quality of the extracted shoreline. In this example, the reference shoreline buffer size varies between sessions in both the CoastSat and Zoo workflows.](figs/coastseg_figure_2.png){#sylt width="100%"} @@ -126,7 +126,7 @@ As we noted above, we have developed a notebook that carries out an alternative We intend `CoastSeg` to be a collaborative research project and encourage contributions from the SDS community. As well as implementing alternative SDS waterline detection workflows, other improvements that could continue to be made include more (or more refined) outlier detection methods, image filtering procedures, and other basic image pre- or post-processing routines, especially image restoration on degraded imagery [@vitousek2023future]. Such additions would all be possible without major changes to the existing `CoastSeg` toolkit. -Integration of new models for the deep-learning workflow are planned, based on non-dimensionalized water index (NDWI) and modified non-dimensionalized water index (MNDWI) spectral indices, as is a new `CoastSeg` toolbox extension for daily 3-m Planetscope imagery [@doherty2022python] from Planet Labs [@planet]. Docker may be adopted in the future for managing dependencies in the `conda` virtual environment required to run the program. Other sources of imagery and other spectral indices may have value in SDS workflows, and we encourage SDS users to contribute their advances through a `CoastSeg` Jupyter notebook implementation. +Integration of new models for the deep-learning workflow are planned, based on normalized water index (NDWI) and modified non-dimensionalized water index (MNDWI) spectral indices, as is a new `CoastSeg` toolbox extension for daily 3-m Planetscope imagery [@doherty2022python] from Planet Labs [@planet]. Docker may be adopted in the future for managing dependencies in the `conda` virtual environment required to run the program. Other sources of imagery and other spectral indices may have value in SDS workflows, and we encourage SDS users to contribute their advances through a `CoastSeg` Jupyter notebook implementation. It would be also be possible to incorporate automated satellite image subpixel co-registration in `CoastSeg` using the AROSICS package [@scheffler2017arosics]. This would co-register all available imagery to the nearest-in-time LandSat image. Further, future work could include accounting for the contributions of runup and setup to total water level [@vitousek2023model; @vos2023benchmarking]. In practice, this would merely add/subtract a height from the instantaneous predicted tide, then apply horizontal correction. However, the specific methods used to estimate runup or setup from the prevailing wave field would require integration with observed or hindcasted databases of wave conditions. diff --git a/paper/paper.pdf b/paper/paper.pdf index dc57644d..94ea2e33 100644 Binary files a/paper/paper.pdf and b/paper/paper.pdf differ