website update

docs/appendix/community_guidelines.md

@@ -10,6 +10,7 @@ https://pypromice.readthedocs.io/en/latest/guide_developer.html
 https://icepyx.readthedocs.io/en/latest/contributing/contribution_guidelines.html
 
 -->
+
 # Community guide
 
 We welcome contributions, bug reports and fixes, documentation improvements, and enhancements and ideas, from anyone at any career stage and experience.

docs/appendix/references.md

@@ -26,7 +26,9 @@ Porter, C., _et al._ (2022). ArcticDEM - Strips, Version 4.1. _Harvard Dataverse
 
 Porter, C., _et al._ (2023), ArcticDEM, Version 4.1, _Harvard Dataverse_. https://doi.org/10.7910/DVN/3VDC4W
 
-Scheick et al., (2023). icepyx: querying, obtaining, analyzing, and manipulating ICESat-2 datasets. _Journal of Open Source Software_, 8(84), 4912, https://doi.org/10.21105/joss.04912
+Scheick _et al._, (2023). icepyx: querying, obtaining, analyzing, and manipulating ICESat-2 datasets. _Journal of Open Source Software_, 8(84), 4912, https://doi.org/10.21105/joss.04912
+
+Shean _et al._, (2023). SlideRule: Enabling rapid, scalable, open science for the NASA ICESat-2 mission and beyond. _Journal of Open Source Software_, 8(81), 4982, https://doi.org/10.21105/joss.04982
 
 Shiggins, C. J., _et al._ (2023). Automated ArcticDEM iceberg detection tool: insights into area and volume distributions, and their potential application to satellite imagery and modelling of glacier–iceberg–ocean systems, _The Cryosphere_, 17, 15–32, https://doi.org/10.5194/tc-17-15-2023
 

docs/examples/coregistration.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../notebooks/coregistration.ipynb"
+}

docs/examples/mosaic.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../notebooks/mosaic.ipynb"
+}

docs/examples/strip_search.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../notebooks/strip_search.ipynb"
+}

docs/examples/terrain_parameters.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../notebooks/terrain_parameters.ipynb"
+}

docs/getting_started/cite.md

@@ -1,6 +1,6 @@
 # Cite
 
-A software paper for `pdemtools` is published in the [Journal of Open Source Software](https://joss.theoj.org/), and can be cited as follows:
+A software paper for `pdemtools` is published in the [Journal of Open Source Software](https://joss.theoj.org/), and should be cited as follows when `pdemtools` is used:
 
 > Chudley, T. R., and Howat, I. M. (2024). pDEMtools: conveniently search, download, and process ArcticDEM and REMA products. _Journal of Open Source Software_, _9_(102), 7149, doi.org/10.21105/joss.07149
 

docs/getting_started/supplementary_datasets.md

@@ -1,19 +1,20 @@
 # Supplementary datasets
 
-To make the most of pDEMtools, two supplementary datasets must be available locally.
+Two supplementary datasets can be relied upon locally to enhance the capability of `pdemtools`.
 
-## ArcticDEM/REMA strip index
+## BedMachine
 
-The first dataset is the ArcticDEM or REMA strip index made available by the PGC  (in GeoParquet format), used by the `search` function. Strip index GeoParquet files can be downloaded from the PGC ([Greenland](https://data.pgc.umn.edu/elev/dem/setsm/ArcticDEM/indexes/), [Antarctica](https://data.pgc.umn.edu/elev/dem/setsm/REMA/indexes/)). 
+Greenland BedMachine (v5; Morlighem _et al._ 2022a) or Antarctica BedMachine (v3; Morlighem _et al._ 2022b) provide the default EIGEN-6C4 geoid and ice/bedrock mask used by the geoid correction and coregistration functions (NB: for applications outside of the ice sheets, it is possible to use your own geoid/bedrock mask). 
 
-The appriate files to download are the `ArcticDEM_Strip_Index_s2s041_gpqt.zip` and `REMA_Strip_Index_s2s041_gpkg.zip` - note the __GeoParquet file format__ (ending `_gpqt.zip`), *not* the similarly named GeoPackage (ending `_gpkg.zip`). No mosaic files are necessary - these are included with `pdemtools`. 
+The appropriate versions of BedMachine, in netcdf format, can be downloaded from the NSIDC ([Greenland](https://nsidc.org/data/idbmg4/versions/5), [Antarctica](https://nsidc.org/data/nsidc-0756/versions/3)). Follow these links to the NSIDC website. Once you're there, the most convenient way of downloading is via the 'Data Access Tool'. __Ensure you download the netcdf version__ (ending `*.nc`), not the tif version.
 
-Unzip the files before use. They can be placed anywhere in your file system - the filepath, as a string, is provided to the relevant `pdemtools` functions.
 
-> __NOTE:__ These index files are maintained by the PGC, so we cannot guarantee that newly released updates to ArcticDEM/REMA index files will not temporarily break `pdemtools` functions until we can fix and update the software. From version 0.8.3 onwards, these files are known to work up to and including the latest PGC data update (ArcticDEM Strip Release 2023, released Aug 2024).
+## ArcticDEM/REMA strip index
 
-## BedMachine
+As of `pdemtools v1.0.0`, the `pdt.search()` functions search the ArcticDEM and REMA strips by seamlessly quering to the online PGC dynamic STAC API. Prior to this, a local ArcticDEM or REMA strip index was required to be downloaded. The functionality to search a local copy of the index is still available within the `pdt.search()` function, and may be useful for those that do not wish to rely on an online connection to search the PGC catalogue.
+
+ArcticDEM or REMA strip index GeoParquet files can be downloaded from the PGC ([Greenland](https://data.pgc.umn.edu/elev/dem/setsm/ArcticDEM/indexes/), [Antarctica](https://data.pgc.umn.edu/elev/dem/setsm/REMA/indexes/)). The appriate files to download are the `ArcticDEM_Strip_Index_s2s041_gpqt.zip` and `REMA_Strip_Index_s2s041_gpkg.zip` - note the __GeoParquet file format__ (ending `_gpqt.zip`), *not* the similarly named GeoPackage (ending `_gpkg.zip`). No mosaic files are necessary - these are included with `pdemtools`. 
 
-The second dataset is the Greenland BedMachine (v5; Morlighem _et al._ 2022a) or Antarctica BedMachine (v3; Morlighem _et al._ 2022b) in netcdf format. This dataset provides the default EIGEN-6C4 geoid and ice/bedrock mask used by the geoid correction and coregistration functions (NB: for applications outside of the ice sheets, it is possible to use your own geoid/bedrock mask). 
+Unzip the files before use. They can be placed anywhere in your file system - the filepath, as a string, is provided to the relevant `pdemtools` functions.
 
-The appropriate versions of BedMachine can be downloaded from the NSIDC ([Greenland](https://nsidc.org/data/idbmg4/versions/5), [Antarctica](https://nsidc.org/data/nsidc-0756/versions/3)). Follow these links to the NSIDC website. Once you're there, the most convenient way of downloading is via the 'Data Access Tool'. __Ensure you download the netcdf version__ (ending `*.nc`), not the tif version.
+> __NOTE:__ These index files are maintained by the PGC, so we cannot guarantee that newly released updates to ArcticDEM/REMA index files will not temporarily break `pdemtools` functions until we can fix and update the software. From version 0.8.3 onwards, these files are known to work up to and including the latest PGC data update (ArcticDEM Strip Release 2023, released Aug 2024).

docs/getting_started/why_pdemtools.md

@@ -1,13 +1,13 @@
 # Why pDEMtools?
 
-> This page reproduces the 'Statement of Need' of the [_Journal of Open Source Software_ manuscript](http://dx.doi.org/10.21105/joss.07149) for `pdemtools`.
+> This page is based on the 'Statement of Need' of the [_Journal of Open Source Software_ manuscript](http://dx.doi.org/10.21105/joss.07149) for `pdemtools`, and will be updated as both `pdemtools` and the ArcticDEM and REMA projects evolve. Last updated 2025-01-25 for `pdemtools v1.0.0`.
 
 [ArcticDEM](https://www.pgc.umn.edu/data/arcticdem/) and [REMA](https://www.pgc.umn.edu/data/rema/) are high-resolution, time-stamped 2-metre-resolution DEMs of the polar regions provided by the Polar Geospatial Center (PGC). They are extracted by applying stereo auto-correlation techniques ([Noh & Howat, 2017](https://doi.org/10.1016/j.isprsjprs.2017.04.019)) to pairs of submetre Maxar satellite imagery. The data includes Worldview-1, Worldview-2, Worldview-3, and GeoEye-1, beginning in 2007 (ArcticDEM) or 2009 (REMA) and ongoing to the present day. Products are available as tens of thousands of time-stamped 'strips' ([Porter _et al._ 2022](ttps://doi.org/10.7910/DVN/OHHUKH); [Howat _et al._ 2022a](https://doi.org/10.7910/DVN/X7NDNY)) constructed from individual scene pairs, or as a single mosaic ([Porter _et al._ 2023](https://doi.org/10.7910/DVN/3VDC4W); [Howat _et al._ 2022a](https://doi.org/10.7910/DVN/EBW8UC)) compiled from the combined stack of strips. Strips allow users to perform change detection by comparing data from different seasons or years, whilst mosaics provide a consistent and comprehensive product over the entire polar regions.
 
-As Earth Science has moved into the 'big data' era, increasing amounts of Arctic- and Antarctic-focused resources are available as public, cloud-optimised datasets. New approaches are providing Python tools to act as combined Application Programming Interface (API) and processing tools, such as [`icepyx`](https://icepyx.readthedocs.io) ([Scheick _et al._ 2023](https://doi.org/10.21105/joss.04912)) or [`pypromice`](https://pypromice.readthedocs.io) ([How _et al._ 2023](https://doi.org/10.21105/joss.05298)). From 2022 (ArcticDEM v4.1 and REMA v2), the PGC DEM products are [hosted](https://polargeospatialcenter.github.io/stac-browser/#/external/pgc-opendata-dems.s3.us-west-2.amazonaws.com/pgc-data-stac.json) as Cloud Optimised GeoTIFFs (CoGs) in a SpatioTemporal Asset Catalog (STAC), a standardised structure for cataloguing spatiotemporal data. However, the PGC STAC is currently a 'static' rather than 'dynamic' STAC, which means there is no convenient API for searching the datasets in response to user queries. This limits the ability of users to programmatically interact with ArcticDEM and REMA data in a quick and efficient manner. The `pdemtools` package has two aims: the first is to provide a Python-focussed alternative for searching and downloading ArcticDEM and REMA data, emulating dynamic STAC query tools such as [`pystac`](https://pystac.readthedocs.io); whilst the second is to provide commonly used processing functions specific to the needs of ArcticDEM and REMA users (a focus on ice sheet and cryosphere work), as well as the particular strengths of the ArcticDEM and REMA datasets (high-resolution and multitemporal).
+As Earth Science has moved into the 'big data' era, increasing amounts of Arctic- and Antarctic-focused resources are available as public, cloud-optimised datasets. New approaches are providing Python tools to act as combined Application Programming Interface (API) and processing tools, such as [`icepyx`](https://icepyx.readthedocs.io) ([Scheick _et al._ 2023](https://doi.org/10.21105/joss.04912)) or [`pypromice`](https://pypromice.readthedocs.io) ([How _et al._ 2023](https://doi.org/10.21105/joss.05298)). From 2022 (ArcticDEM v4.1 and REMA v2), the PGC DEM products are [hosted](https://polargeospatialcenter.github.io/stac-browser/#/external/pgc-opendata-dems.s3.us-west-2.amazonaws.com/pgc-data-stac.json) as Cloud Optimised GeoTIFFs (CoGs) in a SpatioTemporal Asset Catalog (STAC), a standardised structure for cataloguing spatiotemporal data. From December 2024, this is a 'dynamic' STAC, which means there is a convenient API for searching the datasets in response to user queries. This greatly enhances the ability of users to programmatically interact with ArcticDEM and REMA data in a quick and efficient manner. The `pdemtools` package has two aims: the first is to provide a Python-based solution for searching and downloading ArcticDEM and REMA data, wrapping and extending dynamic STAC query tools such as [`pystac`](https://pystac.readthedocs.io); whilst the second is to provide commonly used processing functions specific to the needs of ArcticDEM and REMA users (a focus on ice sheet and cryosphere work), as well as the particular strengths of the ArcticDEM and REMA datasets (high-resolution and multitemporal).
 
 The `pdemtools` `search()` tool and `load` module allow for convenient access to the ArcticDEM and REMA datasets. Mosaics can be downloaded from a one-line `load.mosaic()` function, whilst the `search()` function allows for convenient filtering of a locally downloading ArcticDEM/REMA strip index according to variables such as date, region of interest, spatial coverage, temporal baseline, source sensors, accuracy, and cross-track data. The results of searches are returned as a [`geopandas`](https://geopandas.org) dataframe, and can be downloaded using the `load.from_search()` function. Elevation models are returned as [`xarray`](https://docs.xarray.dev) DataArrays [Hoyer _et al. 2017](https://doi.org/10.5334/jors.148) with geospatial metadata via the [`rioxarray`](https://corteva.github.io) extension - a standard format for storing and processing n-dimensional geospatial data within the geospatial Python community. By utilising standardised formats, the aim is to allow the user to quickly move beyond `pdemtools` into their own analysis in whatever format they desire, be that `xarray`, `numpy` or `dask` datasets, DEM analysis Python packages such as [`xdem`](https://xdem.readthedocs.io/) for advanced coregistration or [`richdem`](https://richdem.readthedocs.io) for flow analysis, or exporting to geospatial file formats for analysis beyond Python.
 
-After download, there exist a number of (pre-)processing steps that are near universally common in topographic analyses. These include geoid-correction, co-registration of time-series data, and/or the construction of terrain parameters such as hillshade, slope, aspect, and curvature. `pdemtools` contains pre-built functions to perform these processing steps, as well as further functionality specific to ArcticDEM and REMA use cases. For instance, we include functions to quickly extract the EIGEN-6C4 geoid [Foerste _et al._ 2014](https://doi.org/10.5880/icgem.2015.1) and Greenland/Antarctic bedrock masks directly from local versions of the Greenland and Antarctic BedMachine datasets (Morlighem _et al_, [2022a](https://doi.org/10.5067/GMEVBWFLWA7X), [2022b](https://doi.org/10.5067/FPSU0V1MWUB6)), reprojecting and resampling the data to match the target DEM. Options for ingesting user-provided mask and geoid data are also provided. Additionally, partial derivatives of the surface used to calculate terrain parameters (∂z/∂x, ∂z/∂y, ∂<sup>2</sup>z/∂x<sup>2</sup>, ∂<sup>2</sup>z/∂y<sup>2</sup>, ∂<sup>2</sup>z/∂x∂y) are calculated following [Florinsky (2009)](https://doi.org/10.1080/13658810802527499), as opposed to more common methods such as [Zevenbergen and Thorne (1987)](https://doi.org/10.1002/esp.3290120107). The newer approach computes partial derivatives of elevation based on fitting a third-order polynomial, by the least-squares approach, to a 5 $\times$ 5 window as opposed to the more common 3 $\times$ 3 window. This is more appropriate for high-resolution DEMs: curvature over a 10 m window for the 2 m resolution ArcticDEM/REMA strips will lead to a local denoising effect that limits the impact of noise common in high-resolution photogrammetric products. These methods are also adapted into a co-registration routine, which otherwise follows the commonly used approach of [Nuth & Kääb (2011)](https://doi.org/10.5194/tc-5-271-2011).
+After download, there exist a number of (pre-)processing steps that are near universally common in topographic analyses. These include geoid-correction, co-registration of time-series data, and/or the construction of terrain parameters such as hillshade, slope, aspect, and curvature. `pdemtools` contains pre-built functions to perform these processing steps, as well as further functionality specific to ArcticDEM and REMA use cases. For instance, we include functions to quickly extract the EIGEN-6C4 geoid [Foerste _et al._ 2014](https://doi.org/10.5880/icgem.2015.1) and Greenland/Antarctic bedrock masks directly from local versions of the Greenland and Antarctic BedMachine datasets (Morlighem _et al_, [2022a](https://doi.org/10.5067/GMEVBWFLWA7X), [2022b](https://doi.org/10.5067/FPSU0V1MWUB6)), reprojecting and resampling the data to match the target DEM. Options for ingesting user-provided mask and geoid data are also provided. Additionally, partial derivatives of the surface used to calculate terrain parameters (∂z/∂x, ∂z/∂y, ∂<sup>2</sup>z/∂x<sup>2</sup>, ∂<sup>2</sup>z/∂y<sup>2</sup>, ∂<sup>2</sup>z/∂x∂y) are calculated following [Florinsky (2009)](https://doi.org/10.1080/13658810802527499), as opposed to more common methods such as [Zevenbergen and Thorne (1987)](https://doi.org/10.1002/esp.3290120107). The newer approach computes partial derivatives of elevation based on fitting a third-order polynomial, by the least-squares approach, to a 5 $\times$ 5 window as opposed to the more common 3 $\times$ 3 window. This is more appropriate for high-resolution DEMs: curvature over a 10 m window for the 2 m resolution ArcticDEM/REMA strips will lead to a local denoising effect that limits the impact of noise common in high-resolution photogrammetric products. These methods are also adapted into a co-registration routine, which otherwise follows the commonly used approach of [Nuth & Kääb (2011)](https://doi.org/10.5194/tc-5-271-2011). Strips can be coregistered against other DEMs (mosaics or each other), or against ICESat-2 data. An ICESat-2 download function is also included, that uses the `sliderule` software (Shean _et al._, 2023) to download DEM-contemporaneous ICESat-2 ATLO6-SR data.
 
 We aim to grow `pdemtools` by implementing new methods developed by the ArcticDEM and REMA research community. For instance, we currently include sea-level-filtering and iceberg detection routines outlined by Shiggins _et al._ (2023), and invite community contributions or requests of other routines that will be of use to users of `pdemtools`. Ongoing research projects making use of `pdemtools` are applying ArcticDEM and REMA data to the mapping of crevasses, ice cliff heights, and subglacial lakes, as well as the initiation of ice sheet models. It has also been used within training exercises at the 2024 Polar Geospatial Center Data Workshop, contributing to a growing international network of `pdemtools` users.