diff --git a/.gitignore b/.gitignore
index 6a8f542..c7f4bdf 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,4 +6,6 @@ gitignore*
example_data/
.DS_Store
*.tif
-docs/_build/
\ No newline at end of file
+docs/_build/
+.coverage
+dist/
diff --git a/README.md b/README.md
index 9c56105..8f1cb56 100644
--- a/README.md
+++ b/README.md
@@ -1,22 +1,28 @@
# pDEMtools
-**_Conveniently search, download, and preprocess ArcticDEM and REMA products_**
+__Conveniently search, download, and preprocess ArcticDEM and REMA products__
+
+[](https://pdemtools.readthedocs.io/en/latest/?badge=latest) [](https://github.com/trchudley/pdemtools/actions/workflows/unit_test.yml)
-pDEMtool aims to provide a convenient set of functions to explore, download, and preprocess high-resolution DEMs of the polar regions from the ArcticDEM (Porter _et al._ 2022; 2023) and Reference Elevation Model of Antarctica (REMA; Howat _et al._ 2022a, b) products, courtesy of the Polar Geospatial Center (PGC).
+pDEMtool provides a convenient set of functions to explore, download, and preprocess high-resolution DEMs of the polar regions from the ArcticDEM (Porter _et al._ 2022; 2023) and Reference Elevation Model of Antarctica (REMA; Howat _et al._ 2022a, b) products, courtesy of the Polar Geospatial Center (PGC).
+
+The first aim of pDEMtools is to enable access to ArcticDEM and REMA mosaics and multitemporal strips using the `search()` function and `load` module:
-The primary aim of pDEMtools is to enable access to ArcticDEM and REMA mosaics and multitemporal strips using the `search()` function and `load` module:
- **`search()`**: This function aims to replicate the kind of convenient catalogue searching available when querying a dynamic STAC catalogue (e.g. `pystac_client`), allowing users to easily find relevant ArcticDEM and REMA strips for their areas of interest.
- **`load`**: This module provides simple one-line functions to preview and download strips and mosaics from the relevant AWS bucket to an `xarray` Dataset.
-pDEMtool does not aim to provide a comprehensive DEM analysis environment (there are other excellent tools for that, such as [`xdem`](https://github.com/GlacioHack/xdem) for advanced coregistration or [`richdem`](https://github.com/r-barnes/richdem) for flow analysis), but some simple (pre)processing functions are provided. It is hoped that they are _specific_ to the sort of uses that ArcticDEM and REMA users might want (e.g. a focus on ice sheet and cryosphere work), as well as the particular _strengths_ of ArcticDEM and REMA datasets (high-resolution and multitemporal). Tools include:
- - Identifying/masking sea level and icebergs.
+The second aim is to provide (pre)processing functions _specific_ to the sort of uses that ArcticDEM and REMA users might want (e.g. a focus on ice sheet and cryosphere work), as well as the particular _strengths_ of ArcticDEM and REMA datasets (high-resolution and multitemporal). Tools include:
+
- Terrain attribute derivation (hillshade, slope, aspect, various curvatures) using a 5x5 polynomial fit suited for high-resolution data.
- Quick geoid correction using BedMachine source data.
- Simple coregistration for quick elevation change analysis.
+ - Identifying/masking sea level and icebergs.
-Rather than introducing custom classes, pDEMtools will always try and return DEM data as an [xarray](https://docs.xarray.dev/en/stable/) DataArray with geospatial metadata via the [rioxarray](https://corteva.github.io/rioxarray/stable/) extension. The aim is to allow the user to quickly move beyond pDEMtools into their own analysis in whatever format they desire, be that `xarray` datasets, `numpy` or `dask` arrays, or exporting to geospatial file formats for analysis beyond Python.
+Rather than introducing custom classes, pDEMtools will always try and return DEM data as an [xarray](https://docs.xarray.dev/en/stable/) DataArray with geospatial metadata via the [rioxarray](https://corteva.github.io/rioxarray/stable/) extension. 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-specific Python packages such as [`xdem`](https://github.com/GlacioHack/xdem) for advanced coregistration or [`richdem`](https://github.com/r-barnes/richdem) for flow analysis, or exporting to geospatial file formats for analysis beyond Python.
+
+Please visit the [pDEMtools ReadTheDocs](https://pdemtools.readthedocs.io/en/latest/index.html) for more information on installing and using pDEMtools.
# Examples
@@ -46,6 +52,7 @@ Easy filtering of ocean/mélange, allowing for assessment of calving fronts and
An example batch download and coregistration script is also included in the `batch` directory as a jumping-off point for large-scale projects.
+
# Cite
+ ### - [`mask_blunders`](#mask_blunders)
- [`mask_ocean()`](#pdtmask_ocean)
- [`mask_icebergs()`](#pdtcurvature)
- [`get_sea_level()`](#pdtget_sea_level)
@@ -401,56 +360,48 @@ terrain = dem_masked.pdt.terrain(
If you have requested multiple variables, the output of the `.pdt.terrain()` is a (rio)xarray DataSet containing all the selected variables, as well as the original DEM. If you have requested a single variable, the output is a (rio)xarray DataArray of that variable.
-
-
+
+-->
-# Version updates
-| Version | Date | Notes |
-| ------- | ---- | ----- |
-| 0.6 | February 2024 | Added `data.bedrock_mask_from_vector()` function. |
-| 0.5 | January 2024 | Fixed bug in `_coreg.py` to improve Nuth and Kääb (2011)-style coregistration. |
-| 0.4 | November 2023 | Made batch processing script available as an example. |
-| 0.3 | September 2023 | Aligned search function with the new PGC-provided GeoParquet files |
-| 0.2 | August 2023 | Update `load.mosaic()` function to include the new ArcticDEM mosaic v4.1 |
-| 0.1 | May 2023 | Initial release |
-
-# To do
+
+
# Refererences
- Expand
+
-Florinsky, I. V. (2009). Computation of the third‐order partial derivatives from a digital elevation model. _International journal of geographical information science_, 23(2), 213-231. https://doi.org/10.1080/13658810802527499
+
Howat, I., _et al._ (2022a). The Reference Elevation Model of Antarctica – Strips, Version 4.1. _Harvard Dataverse_ https://doi.org/10.7910/DVN/X7NDNY
Howat, I., _et al._ (2022b). The Reference Elevation Model of Antarctica – Mosaics, Version 2, _Harvard Dataverse_ https://doi.org/10.7910/DVN/EBW8UC
-Mark, R. K. (1992). Multidirectional, oblique-weighted, shaded-relief image of the Island of Hawaii. _United States Geological Survey_. Open-File Report 92-422. https://doi.org/10.3133/ofr92422
+
-Morlighem, M. _et al._ (2022a). IceBridge BedMachine Greenland, Version 5 [Data Set]. _NASA National Snow and Ice Data Center Distributed Active Archive Center_. https://doi.org/10.5067/GMEVBWFLWA7X
+
-Morlighem, M. _et al._ (2022b). MEaSUREs BedMachine Antarctica, Version 3 [Data Set]. _NASA National Snow and Ice Data Center Distributed Active Archive Center_. https://doi.org/10.5067/FPSU0V1MWUB6
+
-Nuth, C. and Kääb, A. (2011) Co-registration and bias corrections of satellite elevation data sets for quantifying glacier thickness change, _The Cryosphere_, 5, 271–290, https://doi.org/10.5194/tc-5-271-2011
+
Porter, C., _et al._ (2022). ArcticDEM - Strips, Version 4.1. _Harvard Dataverse_. https://doi.org/10.7910/DVN/OHHUKH
Porter, C., _et al._ (2023), ArcticDEM, Version 4.1, _Harvard Dataverse_. https://doi.org/10.7910/DVN/3VDC4W
-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
+
-Zevenbergen, L. W. and Thorne, C. R. (1987). Quantitative analysis of land surface topography. Earth surface processes and landforms, 12(1), 47-56.
+
+
+
-
-
# Acknowledgements
diff --git a/docs/api/pdt_accessor.rst b/docs/api/pdt_accessor.rst
index 788ea21..0d184fa 100644
--- a/docs/api/pdt_accessor.rst
+++ b/docs/api/pdt_accessor.rst
@@ -4,7 +4,3 @@ xarray `.pdt` accessor
.. autoclass:: pdemtools.DemAccessor
:members:
-.. .. automodule:: pdemtools
-.. :members:
-.. :exclude-members: search
-
diff --git a/docs/appendix/community_guidelines.md b/docs/appendix/community_guidelines.md
new file mode 100644
index 0000000..58623b7
--- /dev/null
+++ b/docs/appendix/community_guidelines.md
@@ -0,0 +1,55 @@
+
+
+# Community guide
+
+We welcome contributions, bug reports and fixes, documentation improvements, and enhancements and ideas, from anyone at any career stage and experience.
+
+We ask those participating to contribute to a positive community environment, as outlined by the [Contributor Convenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+## Report issues or problems
+
+Issue, bugs, and feature requests can be reported in the _Issues_ tab of the [GitHub repository](https://github.com/trchudley/pdemtools/issues).
+
+Please give your issue a clear title. If describing a bug, include (i) a description of how your pDEMtools is set up (e.g. pip, repository cloning) and the version being used; (ii) a concise Python snippet reproducing the problem; and (iii) and explanation of why the current behaviour is wrong, and what is expected.
+
+## Contribute to pDEMtools
+
+You can work directly with the development of pDEMtools if you have a solution for an issue or enhancement.
+
+Before doing so, please check that the GitHub issues page to ensure that your problem or proposed solution has not already been identified or is being worked upon.
+
+We follow a [standard git workflow](https://www.asmeurer.com/git-workflow/) for code fixes and additions. To contribute, begin by fork the pDEMtools GitHub repository into your own GitHub space, before creating an appropriately named development branch. All code is submitted via the pull request process rather than pushed directly to the main branch. Please ensure that commit and pull request messages are descriptive. The pull request will be reviewed and, if valid and suitable, accepted.
+
+### Developer install
+
+pDEMtools can be installed for development by cloning the github repository. We recommend installing dependencies via `conda`/`mamba` using the included `environment.yml` file.
+
+```bash
+git clone git@github.com:trchudley/pdemtools.git
+cd pypromice/
+mamba env create --file environment.yml -n pdemtools_env
+mamba activate pdemtools_env
+pip install -e .
+```
+
+### Unit Testing
+
+pDEMtools has built-in unit tests, which can be run to test the package installation. Please ensure that you have installed the `pytest` package from `pip` or `conda`/`mamba` prior to testing. Tests can then be run by running the `pytest` command from the `pdemtools` directory.
+
+```bash
+pip install pytest
+cd .../pdemtools
+pytest
+```
+
+Pushing changes to the GitHub repository will initiate automated CI unit testing via Github Actions.
diff --git a/docs/index.rst b/docs/index.rst
index 4699a61..07e94f6 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -19,21 +19,22 @@ pDEMtools
:align: center
:alt: A hillshaded DEM of Helheim Glacier
-pDEMtool aims to provide a convenient set of functions to explore, download, and preprocess high-resolution DEMs of the polar regions from the ArcticDEM (Porter *et al.* 2022; 2023) and Reference Elevation Model of Antarctica (REMA; Howat *et al.* 2022a, b) products, courtesy of the Polar Geospatial Center (PGC).
+pDEMtool provides a convenient set of functions to explore, download, and preprocess high-resolution DEMs of the polar regions from the ArcticDEM (Porter *et al.* 2022; 2023) and Reference Elevation Model of Antarctica (REMA; Howat *et al.* 2022a, b) products, courtesy of the Polar Geospatial Center (PGC).
-The primary aim of pDEMtools is to enable access to ArcticDEM and REMA mosaics and multitemporal strips using the ``search()`` function and ``load`` module:
+The first aim of pDEMtools is to enable access to ArcticDEM and REMA mosaics and multitemporal strips using the ``search()`` function and ``load`` module:
- ``search()``: This function aims to replicate the kind of convenient catalogue searching available when querying a dynamic STAC catalogue (e.g. ``pystac_client``), allowing users to easily find relevant ArcticDEM and REMA strips for their areas of interest.
- ``load``: This module provides simple one-line functions to preview and download strips and mosaics from the relevant AWS bucket to an ``xarray`` Dataset.
-pDEMtools does not aim to provide a comprehensive DEM analysis environment (there are other excellent tools for that, such as `xdem `_ for advanced coregistration or `richdem `_ for flow analysis), but some simple (pre)processing functions are provided. It is hoped that they are *specific* to the sort of uses that ArcticDEM and REMA users might want (e.g. a focus on ice sheet and cryosphere work), as well as the particular *strengths* of ArcticDEM and REMA datasets (high-resolution and multitemporal). Tools include:
- - Identifying/masking sea level and icebergs.
+The second aim is to provide (pre)processing functions *specific* to the sort of uses that ArcticDEM and REMA users might want (e.g. a focus on ice sheet and cryosphere work), as well as the particular *strengths* of ArcticDEM and REMA datasets (high-resolution and multitemporal). Tools include:
+
- Terrain attribute derivation (hillshade, slope, aspect, various curvatures) using a 5x5 polynomial fit suited for high-resolution data.
- Quick geoid correction using BedMachine source data.
- Simple coregistration for quick elevation change analysis.
+ - Identifying/masking sea level and icebergs.
-Rather than introducing custom classes, pDEMtools will always try and return DEM data as an `xarray `_ DataArray with geospatial metadata via the `rioxarray `_ extension. The aim is to allow the user to quickly move beyond pDEMtools into their own analysis in whatever format they desire, be that `xarray` datasets, `numpy` or `dask` arrays, or exporting to geospatial file formats for analysis beyond Python.
+Rather than introducing custom classes, pDEMtools will always try and return DEM data as an `xarray `_ DataArray with geospatial metadata via the `rioxarray `_ extension. 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-specific Python packages such as `xdem `_ for advanced coregistration or `richdem `_ for flow analysis, or exporting to geospatial file formats for analysis beyond Python.
**Contact me:** Tom Chudley, thomas.r.chudley@durham.ac.uk
@@ -47,7 +48,7 @@ Rather than introducing custom classes, pDEMtools will always try and return DEM
.. toctree::
:maxdepth: 2
- :caption: Tutorials:
+ :caption: Examples:
examples/mosaic_and_terrain
examples/strip_search_and_dem_difference
@@ -69,6 +70,7 @@ Rather than introducing custom classes, pDEMtools will always try and return DEM
:glob:
:caption: Appendix:
+ appendix/community_guidelines.md
appendix/version_updates.md
appendix/references.md
appendix/acknowledgements.md
diff --git a/docs/notes.txt b/docs/notes.txt
index ef31b86..7385d97 100644
--- a/docs/notes.txt
+++ b/docs/notes.txt
@@ -12,6 +12,5 @@ Go to readthedocs and create a new build
To think about:
- Automatic versioning?
-
Pages:
https://lpn-doc-sphinx-primer-devel.readthedocs.io/
diff --git a/notebooks/mosaic_and_terrain.ipynb b/notebooks/mosaic_and_terrain.ipynb
index 6951249..04cb6b6 100644
--- a/notebooks/mosaic_and_terrain.ipynb
+++ b/notebooks/mosaic_and_terrain.ipynb
@@ -393,7 +393,7 @@
"source": [
"The geomorphometric parameters used to calculate these variables ($\\frac{\\partial z}{\\partial x}$, $\\frac{\\partial z}{\\partial y}$, $\\frac{\\partial^2 z}{\\partial x^2}$, $\\frac{\\partial^2 z}{\\partial y^2}$, $\\frac{\\partial^2 z}{\\partial x \\partial y}$) are derived following Florinsky (2009), as opposed to more common methods (e.g. Horn, 1981, or Zevenbergen & Thorne, 1987). \n",
"\n",
- "The motivation here is that Florinsky (2009) 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 deonising effect that limits the impact of noise."
+ "The motivation here is that Florinsky (2009) 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 deonising effect that limits the impact of noise."
]
},
{
@@ -1048,14 +1048,6 @@
"\n",
"plt.savefig('../images/example_mosaic_terrain.jpg', dpi=300)"
]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "id": "b0a5acaf-32d9-4f11-b663-3d9079cb2aff",
- "metadata": {},
- "outputs": [],
- "source": []
}
],
"metadata": {
diff --git a/pyproject.toml b/pyproject.toml
index 52f5b89..aae1889 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -28,6 +28,9 @@ Documentation = "https://pdemtools.readthedocs.io/en/latest/"
Repository = "https://github.com/trchudley/pdemtools"
Issues = "https://github.com/trchudley/pdemtools/issues"
+[tool.setuptools.dynamic]
+version = {attr = "pdemtools.__version__"}
+
[tool.setuptools]
include-package-data = true
diff --git a/src/pdemtools/__init__.py b/src/pdemtools/__init__.py
index da8040d..457a6f0 100644
--- a/src/pdemtools/__init__.py
+++ b/src/pdemtools/__init__.py
@@ -6,6 +6,6 @@
from ._accessor import DemAccessor
-__version__ = version("pdemtools")
+__version__ = "0.7.0"
__all__ = ["search", "DemAccessor"]
diff --git a/src/pdemtools/_accessor.py b/src/pdemtools/_accessor.py
index 88ffc3c..2be388f 100644
--- a/src/pdemtools/_accessor.py
+++ b/src/pdemtools/_accessor.py
@@ -167,7 +167,26 @@ def terrain(
hillshade_z_factor: Optional[float] = 2.0,
) -> DataArray | Dataset:
"""
- Returns terrain attributes as an xarray DataSet.
+ Returns terrain attributes as an xarray DataSet. Available attributes are as
+ follows:
+
+ - Slope
+ - Aspect
+ - Hillshade
+ - Horizontal curvature
+ - Vertical curvature
+ - Mean curvature
+ - Gaussian curvature
+ - Unsphericity curvature
+ - Minimal curvature
+ - Maximal curvature
+
+ By default, computation of partial derivatives for geomorphometric variable
+ calculation is performed following Florinsky (2009), who calculate the third-
+ order partial derivative from a 5 x 5 window, which may be more appropriate
+ for high-resolution DEMs with some amount of noise. The `method` parameter
+ allows for the selection of a more traditional method using a second-order
+ derivative from a 3 x 3 window, as outlined by Zevenbergen and Throrne (1987).
:param attribute: The attribute(s) to calculate, as a string or list.
:param method: Method to calculate geomorphometric parameters: "Florisnky" or
@@ -496,9 +515,10 @@ def mask_icebergs(
return_mask: Optional[bool] = False,
connectivity: Literal[4, 8] = 4,
) -> DataArray:
- """After masking the ocean, icebergs will remain. This function gives you the
- opportunity to mask them as well by identifying the size of connected groups of
- pixels and masking above/below a threshold.
+ """After masking the ocean using the `mask_ocean()` function, icebergs will
+ remain. This function gives you the opportunity to mask them as well by
+ identifying the size of connected groups of pixels and masking above/below a
+ threshold.
:param area_thresh_m2: Size threshold between icebergs and terrestrial ice/land, in
m2. Defaults to 1e6 m2 (1 km2)