review and restructure

docs/paper/paper.md

@@ -46,27 +46,27 @@ At it's core, `eo_tides` upscales sophisticated ocean tide modelling from the `p
 
 [TODO: Insert text here about the core functions of the `pyTMD` package with comment on the range of supported global tide models. Segue into how `eo-tides` enables the application of `pyTMD` modelling at EO appropriate scale]
 
-The tide modelling functionality in `eo-tides` can be used independently of EO data, e.g. for any application where you need to generate a time series of tide heights. However, it also underpins the more complex EO-related functions in the `eo-tides` package. Tide modelling functionality is also provided to support modelling of tidal phase at any location and time. This can be used to classify tides into high and low tide observations, or determine whether the tide was rising (i.e. flow tide) or falling (i.e. ebb tide) at any point in time.
+The tide modelling functionality in `eo-tides` can be used independently of EO data, e.g. for any application where you need to generate a time series of tide heights. However, it also underpins the more complex EO-related functions in the `eo-tides` package. Tide modelling functionality is further provided to support modelling of tidal phases at any location and time. This can be used to classify tides into high and low tide observations, or determine whether the tide was rising (i.e. flow tide) or falling (i.e. ebb tide) at any point in time.
 
 ## Combining tides with satellite data
-When combining tide heights with satellite data, `eo-tides` offers two approaches that differ in their complexity and performance. A fast and efficient method for assigning tide heights to whole timesteps is offered that best suits small scale applications where tides are unlikely to vary across a study area. In contrast, for large scale, seamless coastal EO datasets, `eo-tides` offers an approach that models tides through both time and space, returning a tide height for every satellite pixel in the dataset. However, the complexity of this approach naturally comes at the expense of performance.
+The attribution of corresponding tide heights to coastal EO data is the major focus of the `eo-tides` package. When combining tide heights with satellite data, `eo-tides` offers two approaches that differ in  complexity and performance. A fast and efficient method for assigning tide heights to whole dataset timesteps is offered for small scale applications where tides are unlikely to vary across a study area. In contrast, for large scale, seamless coastal EO datasets, `eo-tides` offers an approach that models tides through both time and space, returning a tide height for every satellite pixel in every dataset timestep.
 
-Using the former approach, the tide height at the geographic-centroid of the dataset is attributed to each timestep, representing the relative trend of the tide dynamics for the area of interest at that moment in time. Having tide height as a variable allows the selection and analysis of satellite data using information about tides. For example, in any area of interest, we could sort all available timesteps by tide height, then identify and compare the lowest and highest tide images in our time series.
+Using the former approach, the tide height at the geographic-centroid of the dataset is attributed to each timestep, representing the relative trend of the tide dynamics for the area of interest at that moment in time. Having tide height as a variable allows the selection and analysis of satellite data using information about tides. For example, in any area of interest, all available timesteps could be sorted by tide height, then the lowest and highest tide images in the time series are identifiable and able to be compared.
 
-However, in reality, tides vary spatially – potentially by several metres in areas of complex tidal dynamics. This means that an individual satellite image can capture a range of tide conditions. The pixel-based, seamless tide height attribution approach is well suited for applications that require localised information on tides. For efficient processing, this approach first models tides into a low resolution grid surrounding each satellite image in the time series. This lower resolution data includes a buffer around the extent of the satellite data so that tides can be modelled seamlessly across analysis boundaries. Optionally, users can interpolate and re-project the low resolution tide data back into the resolution of the input satellite image, resulting in an individual tide height for every pixel in the dataset through time and space.
+However, in reality, tides vary spatially – potentially by several metres in areas of complex tidal dynamics. This means that an individual satellite dataset can capture a range of tide conditions. The pixel-based, seamless tide height attribution approach is well suited for applications that require localised information on tides. For efficient processing, this approach first models tides into a low resolution grid surrounding each satellite image in the time series. This lower resolution data includes a buffer around the extent of the satellite data so that tides can be modelled seamlessly across analysis boundaries. Optionally, users can interpolate and re-project the low resolution tide data back into the resolution of the input satellite image, resulting in an individual tide height for every pixel in the dataset through time and space.
 
-Further functionality in this latter approach allows users to calculate and return timesteps from the modelled tide height array that reveal important features of the input satellite time series. These include the minimum, maximum and median satellite-observed tide heights in the array and are returned by supplying the desired quantiles to the analysis parameters.
+Further functionality in this approach allows users to calculate and return timesteps from the modelled tide height array to reveal important features of the input satellite time series. These include the minimum, maximum and median satellite-observed tide heights in the array which can be exploited for deeper analysis, such as coastline delineation [@bishop2021mapping].
 
 ## Calculating tide statistics and satellite biases
-Complex interactions between temporal tide dynamics and the regular mid-morning overpass timing of sun-synchronous sensors like Landsat or Sentinel-2 mean that satellites often do not observe the entire tidal cycle. Biases in satellite coverage of the tidal cycle can mean that tidal extremes (e.g. the lowest or highest tides at a location) may either never be captured by satellites, or be over-represented in the satellite EO record. Local tide dynamics can cause these biases to vary greatly both through time and spatially [@bishop2019NIDEM], making it challenging to consistently analyse and compare coastal processes consistently - particularly for large-scale (e.g. regional or global) analyses.
+Complex interactions between temporal tide dynamics and the regular overpass timing of orbiting sensors like Landsat, Sentinel-1 and Sentinel-2 mean that satellites often do not observe the entire tidal cycle. Biases in satellite coverage of the tidal cycle can mean that tidal extremes (e.g. the lowest or highest tides at a location) may either never be captured by satellites, or be over-represented in the satellite EO record. Local tide dynamics can cause these biases to vary greatly both through time and spatially [@bishop2019NIDEM], making it challenging to consistently analyse and compare coastal processes consistently - particularly for large-scale (e.g. regional or global) analyses. 
 
-To ensure that coastal EO analyses are not inadvertently affected by tide biases, it is important to understand and compare how well the tides observed by satellites match the full range of modelled tides at a location. Statistical capabilities in `eo-tides` compare the subset of tides observed by satellite data against the full range of tides modelled at a regular interval through time across the entire time period covered by the satellite dataset. This comparison is used to calculate several useful statistics that summarise how well your satellite data capture real-world tidal conditions. These statistics include: 
+To ensure that coastal EO analyses are not inadvertently affected by tide biases, it is important to understand and compare how well the tides observed by satellites match the full range of modelled tides at a location. Statistical capabilities in `eo-tides` compare the subset of tides observed by satellite data against the full range of tides modelled at a regular interval through time across the entire time period covered by the satellite dataset. This comparison is used to calculate several useful statistics that summarise how well your satellite data captures real-world tidal conditions. These statistics include: 
 
   1. Spread: The proportion of the full modelled astronomical tidal range that was observed by satellites. A high value indicating good coverage of the tide range.
   2. Offset high: The proportion of the highest tides not observed by satellites at any time, as a proportion of the full modelled astronomical tidal range. A high value indicates that the satellite data is biased towards never capturing high tides.
   3. Offset low: The proportion of the lowest tides not observed by satellites at any time, as a proportion of the full modelled astronomical tidal range. A high value indicates that the satellite data is biased towards never capturing low tides.
 
-For either an area-of-interest or pixel-based application of tide modelling using `eo-tides`, the statistical functionality can be used to summarise your dataset, adding insightful tide-based context to your coastal satellite data. For example, application of an `eo-tides` statistical function over your dataset will return a report of the tidal characteristics for your dataset with an associated plot to visualise the data (*Figure 1*).
+An interrogation of satellite tide-bias in any area of interest using `eo-tides` statistical functionality will return a report and plot (*Figure 1*), adding insightful tide-based context to your coastal EO analysis.
 
 ```
   Using tide modelling location: 122.21, -18.00
@@ -86,35 +86,21 @@ For either an area-of-interest or pixel-based application of tide modelling usin
 ```
 ![](../assets/Sen2_tide_stats.png)
 <div style="margin-left: 40px; margin-right: 40px; margin-bottom: 20px;">
-<b> Figure 1 </b> In this satellite dataset where tide modelling is applied for the geometric centroid 122.21, -18.00, using tide model EOT20,the satellite captured a biased proportion of the tide range at this location: only observing ~68% of the tide range, and never observing the lowest 24% of tides. The plot visually demonstrates the relationships between satellite observed tide-height and modelled astronomical tide height for this location.</div>
-
-Applying `eo-tides` statistical functionality at the pixel scale produces rasterised output datasets of the tidal statistics and biases represented in *Figure 1* that can be used to explore spatial relationships to satellite-tide bias in your input dataset.
+<b> Figure 1 </b> In this satellite dataset where tide modelling was applied for the geometric centroid 122.21, -18.00, using tide model EOT20, the satellite captured a biased proportion of the tide range at this location: only observing ~68% of the full modelled (astronomical) tide range, and never observing the lowest 24% of tides. The plot visually demonstrates the relationships between satellite observed tide-heights (black dots) and modelled astronomical tide height (blue) for this location. Additionally, the report provides absolute values describing the satellite-observed tidal behaviours for any given location. </div>
 
 ## Validating modelled tide heights
-The tide models supported by `eo-tides` can vary significantly in accuracy across the world's coastlines. Evaluating the accuracy of your modelled tides is critical for ensuring that resulting marine or coastal EO analyses are reliable and useful.
+The tide models supported by `eo-tides` can vary significantly in accuracy across the world's coastlines. Evaluating the accuracy of modelled tides is critical for ensuring that resulting marine or coastal EO analyses are reliable and useful.
 
-Validation functionality in `eo-tides` provides a convenient tool for loading high-quality sea-level measurements from the GESLA Global Extreme Sea Level Analysis [@GESLAv3] archive – a global archive of almost 90,713 years of sea level data from 5,119 records across the world. This data can be used to compare against tides modelled using `eo-tides` to calculate the accuracy of your tide modelling and identify the optimal tide models to use for your study area.
+Validation functionality in `eo-tides` provides a convenient tool for loading high-quality sea-level measurements from the GESLA Global Extreme Sea Level Analysis [@GESLAv3] archive – a global dataset of almost 90,713 years of sea level data from 5,119 records across the world. This data can be used to compare against tides modelled using `eo-tides` to calculate the accuracy of your tide modelling and identify the optimal tide models to use for your study area.
 
-To streamline validation analyses and ensure comparability with tide height datasets, `eo-tides` has designed the loading of GESLA data to be identical in format to the tide modelling data load. Correlations between GESLA data and modelled tide heights are quantified in `eo-tides` with the calculation of accuracy statistics that include the Root Mean Square Error (RMSE), Mean Absolute Error (MAE), R-squared and bias.
+ `eo-tides` has designed the loading of GESLA data to be identical in format to the tide modelling data load and correlations between GESLA data and modelled tide heights are quantified through the calculation of accuracy statistics that include the Root Mean Square Error (RMSE), Mean Absolute Error (MAE), R-squared and bias.
 
-Furthermore, different ocean tide models perform differently in different locations, meaning it can be valuable to compare the accuracy of multiple different models against measured gauge data. This can help users make an informed decision about the best model to use for a given application or study area. `eo-tides` allows users to compare tide models and evaluate them against GESLA data, empowering users to consider the accuracy metrics and choose the optimal tide model that best suits their location with confidence.
+Furthermore, different ocean tide models perform differently in different locations. `eo-tides` supports the comparison of multiple tide models, evaluating them against GESLA data, to empower users to make informed decisions and choose the optimal tide model that best suits their location or application with confidence.
 
 # Research projects
 Mention (if applicable) a representative set of past or ongoing research projects using the software and recent scholarly publications enabled by it.
 
 # Acknowledgements
 Acknowledgement of any financial support.
 
-# Notes
-CP notes:
-
-https://joss.readthedocs.io/en/latest/paper.html#what-should-my-paper-contain
-
-- I think that the summary and statement of need could be better defined and perhaps expanded upon.
-- I worry that the functionality section may be considered a replication of the API documentation and removed by reviewers. This content, along with the pyTMD section may need to be absorbed into the statement of need (or re-framed)
-
-
-Deleted section from summary of need:
-The `eo-tides` tool-suite supports a wide variety of global ocean models to "tag" satellite data with tide heights corresponding to exact moments of image acquisition. Furthermore, it supports pixel based tide modelling through time to produce three-dimensional `xarray` style datacubes that can be integrated with satellite data. Additional functionality enables parallelized modelling of tide heights and phases (e.g. high, low, ebb, flow tides), calculation of statistics describing local tide dynamics and biases caused by interactions between tidal processes and satellite orbits as well as validation of modelled tides against measured sea levels from coastal tide gauges (e.g. GESLA Global Extreme Sea Level Analysis [@GESLAv3]). `eo-tides` provides a suite of flexible, parallelized tools for efficient analysis of coastal and ocean Earth observation data – from regional to continental and the global scale.
-
 # References