wordsmithing paper

paper.md

@@ -31,17 +31,17 @@ bibliography: paper.bib
 
 ## Summary
 
-River and Basin Profiler (`rabpro`) is a Python package to delineate watersheds, extract river flowlines and elevation profiles, and compute watershed statistics for any location on the Earth’s surface. As fundamental hydrologically-relevant units of surface area, watersheds are areas of land that drain via aboveground pathways to the same location. Delineations of watershed boundaries are typically performed on DEMs that represent surface elevations as gridded rasters. Depending on the resolution of the DEM and the size of the watershed, delineation may be very computationally expensive. With this in mind, we designed `rabpro` to provide user-friendly workflows to manage the complexity and computational expense of watershed calculations given an arbitrary coordinate pair. In addition to basic watershed delineation, `rabpro` will extract the elevation profile for a watershed’s main-channel flowline. This enables the computation of river slope, which is a critical parameter in many hydrologic and geomorphologic models. Finally, `rabpro` provides a user-friendly wrapper around Google Earth Engine’s (GEE) Python API to enable cloud-computing of zonal watershed statistics and/or time-varying forcing data from hundreds of available datasets. Altogether, `rabpro` provides the ability to automate or semi-automate complex watershed analysis workflows across broad spatial extents.
+River and Basin Profiler (`rabpro`) is a Python package to delineate watersheds, extract river flowlines and elevation profiles, and compute watershed statistics for any location on the Earth’s surface. As fundamental hydrologically-relevant units of surface area, watersheds are areas of land that drain via aboveground pathways to the same location, or outlet. Delineations of watershed boundaries are typically performed on digital elevation models (DEMs) that represent surface elevations as gridded rasters. Depending on the resolution of the DEM and the size of the watershed, delineation may be very computationally expensive. With this in mind, we designed `rabpro` to provide user-friendly workflows to manage the complexity and computational expense of watershed calculations given an arbitrary coordinate pair. In addition to basic watershed delineation, `rabpro` will extract the elevation profile for a watershed’s main-channel flowline. This enables the computation of river slope, which is a critical parameter in many hydrologic and geomorphologic models. Finally, `rabpro` provides a user-friendly wrapper around Google Earth Engine’s (GEE) Python API to enable cloud-computing of zonal watershed statistics and/or time-varying forcing data from hundreds of available datasets. Altogether, `rabpro` provides the ability to automate or semi-automate complex watershed analysis workflows across broad spatial extents.
 
 ![The core functionality of rabpro demonstrated on the Sigatoka River. (A) Study site with both MERIT and HydroBASINS delineations and river flowline extraction for a hypothetical gage station. Bing VirtualEarth base image. (B) MERIT-Hydro delineation with MERIT-Hydro flowlines underneath. (C) HydroBASINS delineation with level-12 HydroBASINS polygons as white outlines. (D) Extracted elevation profile with gage location denoted by white circle at Distance = 0. (E) Examples of time-averaged (where appropriate) basin characteristics retrieved by rabpro from Google Earth Engine. Data sources are: population [@ciesin_gridded_2017], NDVI [@didankamel_mod13a2_2015], topo slope [@amatulli_geomorpho90m_2020], precipitation [@nasa_gpm_gpm_2019], soil moisture [@oneill_smap_2018], and temperature [@copernicus_climate_change_service_era5_2017]. (F, G) Basin-averaged time-series data fetched by rabpro for the temperature and precipitation datasets in (E).\label{fig:figure_1}](./docs/paper_fig/figure_1.PNG)
 
 ## Statement of Need
 
-Watersheds play a central and vital role in many scientific, engineering, and environmental management applications (See @brooks_hydrology_2003 for a comprehensive overview). While `rabpro` can benefit any watershed-based research or analysis, it was designed to satisfy the needs of data-driven rainfall-runoff models. These models aim to predict streamflow (runoff) time series as a function of precipitation over upstream land area (i.e. the watershed). In addition to watershed delineations and precipitation estimates, they typically require data on both time-varying parameters (or forcing data) like temperature, humidity, soil moisture, and vegetation as well as static watershed properties like topography, soil type, or land use/land cover [@kratzert_toward_2019; @gauch_rainfallrunoff_2021; @nearing_data_2021; @kratzert_note_2021]. The `rabpro` API enables users to manage the complete data pipeline necessary to drive such a model starting from the initial watershed delineation through the calculation of static and time-varying parameters. Some hydrologic and hydraulic models also require channel slope for routing streamflow [@boyle_toward_2001; @piccolroaz_hyperstream_2016; @wilson_water_2008], developing rating curves [@fenton_calculation_2001; @colby_relationship_1956], or modeling local hydraulics [@schwenk_life_2015; @schwenk_high_2017; @schwenk_meander_2016]. Finally, Earth System Models commonly require sampling raster datasets over watersheds or other polygons for parameterizations and validations [@fisher2019parametric; chen2020global].
+Watersheds play a central and vital role in many scientific, engineering, and environmental management applications (See @brooks_hydrology_2003 for a comprehensive overview). While `rabpro` can benefit any watershed-based research or analysis, it was designed to satisfy the needs of data-driven rainfall-runoff models. These models aim to predict streamflow (runoff) time series as a function of precipitation over upstream land area (i.e. the watershed). In addition to watershed delineations and precipitation estimates, they typically require data on both time-varying parameters (or forcing data) like temperature, humidity, soil moisture, and vegetation as well as static watershed properties like topography, soil type, or land use/land cover [@kratzert_toward_2019; @gauch_rainfallrunoff_2021; @nearing_data_2021; @kratzert_note_2021]. The `rabpro` API enables users to manage the complete data pipeline necessary to drive such a model starting from the initial watershed delineation through the calculation of static and time-varying parameters. Some hydrologic and hydraulic models also require channel slope for routing streamflow [@boyle_toward_2001; @piccolroaz_hyperstream_2016; @wilson_water_2008], developing rating curves [@fenton_calculation_2001; @colby_relationship_1956], or modeling local hydraulics [@schwenk_life_2015; @schwenk_high_2017; @schwenk_meander_2016]. 
 
 The need for watershed-based data analysis tools is exemplified by the growing collection of published datasets that provide watershed boundaries, forcing data, and/or watershed attributes in precomputed form, including CAMELS [@addor_camels_2017], CAMELS-CL, -AUS, and -BR [@alvarez-garreton_camels-cl_2018; @fowler_camels-aus_2021; @chagas_camels-br_2020], Hysets [@arsenault_comprehensive_2020], and HydroAtlas [@linke_global_2019]. These datasets provide off-the-shelf options for building streamflow models, but they suffer from a degree of inflexibility. For example, someone desiring to add a watershed attribute, to use a new remotely-sensed data product, or to update the forcing data time-series to include the most recently available data must go through the arduous process of sampling it themselves. `rabpro` was designed to provide flexibility for both building a watershed dataset from scratch or appending to an existing one.
 
-While we point to streamflow modeling as an example, many other applications exist. `rabpro` is currently being used to contextualize streamflow trends, build a data-driven model of riverbank erosion, and generate forcing data for a mosquito population dynamics model. `rabpro`'s focus is primarily on watersheds, but some users may also find `rabpro`'s Google Earth Engine wrapper convenient for sampling raster data over any geopolygon(s).
+While we point to streamflow modeling as an example, many other applications exist. `rabpro` is currently being used to contextualize streamflow trends, build a data-driven model of riverbank erosion, and generate forcing data for a mosquito population dynamics model. `rabpro`'s focus is primarily on watersheds, but some users may also find `rabpro`'s Google Earth Engine wrapper convenient for sampling raster data over any geopolygon(s).  For example, Earth System Models commonly require sampling raster datasets over watersheds or other polygons for parameterizations and validations [@fisher2019parametric; chen2020global].
 
 ## State of the field