pdemtools.load module

pdemtools.load module#

This module contains functions necessary to open an ArcticDEM/REMA strip as an xarray DataArray, from either local or AWS sources.

pdemtools.load.from_fpath(dem_fpath: str, bounds: tuple | Polygon | None = None, bitmask_fpath: str | None = None, pad: bool | None = False, chunks: int | tuple | dict | None = None) → DataArray#

Given a filepath (local or an AWS link), loads the desired ArcticDEM/REMA DEM strip as an xarray DataArray. Option to filter to bounds and bitmask, if provided.

If AWS link is provided, strip will be downloaded from the relevant AWS bucket. 2 m DEM strips are large in size and loading remotely from AWS may take some time.

Parameters:

  • dem_fpath (str) – Filepath of DEM strip

  • bounds (tuple | Polygon, optional) – Clip to bounds [xmin, ymin, xmax, ymax], in EPSG:3413 (ArcticDEM) or EPSG:3031 (REMA). Will accept a shapely geometry to extract bounds from. Defaults to None

  • mask_fpath (str, optional) – Path to _bitmask.tif file used to mask the DEM, defaults to None

  • pad (bool) – If the DEM strip is not the full extent of the given bounds, pad with NaNs to match the full bounds. Defaults to False.

  • chunks (int | tuple | dict) – Chunk size for rioxarray.open_rasterio, triggering dask parallelisation and lazy evaluation/loading. Defaults to None.

Returns:

xarray DataArray of DEM strip

Return type:

DataArray

pdemtools.load.from_id(dataset: Literal['arcticdem', 'rema'], geocell: str, dem_id: str, bounds: tuple | Polygon | None = None, bitmask: bool | None = True, bucket: str | None = 'https://pgc-opendata-dems.s3.us-west-2.amazonaws.com', version: str | None = 's2s041', preview: bool | None = False, pad: bool | None = False, chunks: int | tuple | dict | None = None) → DataArray#

An alternative method of loading the selected ArcticDEM/REMA strip, which requires only the geocell and the dem_id (e.g. geocell = 'n70w051', dem_id = 'SETSM_s2s041_WV01_20200709_102001009A689B00_102001009B63B200_2m_lsf_seg2').

Downloads from the relevant AWS bucket, as an xarray DataArray. Option to filter to bounds and bitmask. 2 m DEM strips are large in size and loading remotely from AWS may take some time.

NOTE: This function is kept for vestigial purposes, and may be removed or significantly altered in a future release.

Parameters:

  • dataset (str) – Either ‘arcticdem’ or ‘rema’. Case-insensitive.

  • geocell (str) – Geographic grouping of ArcticDEM / REMA strip. e.g. ‘n70w051’.

  • dem_id (str) – ArcticDEM/REMA strip ID. e.g. ‘SETSM_s2s041_WV01_20200709_102001009A689B00_102001009B63B200_2m_lsf_seg2’

  • bounds (tuple, optional) – Clip to bounds [xmin, ymin, xmax, ymax], in EPSG:3413 (ArcticDEM) or EPSG:3031 (REMA), defaults to None

  • bitmask (bool, optional) – Choose whether apply the associated bitmask, defaults to True

  • bucket (str) – AWS buck link, defaults to ‘https://pgc-opendata-dems.s3.us-west-2.amazonaws.com’

  • version (str) – Version string, defaults to ‘s2s041’

  • preview (bool, optional) – Return just a link to the STAC preview page, defaults to False

  • pad (bool) – If the DEM strip is not the full extent of the given bounds, pad with NaNs to match the full bounds. Defaults to False.

  • chunks (int | tuple | dict) – Chunk size for rioxarray.open_rasterio, triggering dask parallelisation and lazy evaluation/loading. Defaults to None.

Returns:

xarray DataArray of DEM strip

Return type:

DataArray

Given a row from the GeoDataFrame output of pdemtools.search(), loads the 2 m DEM strip of the desired ArcticDEM/REMA DEM strip as an xarray DataArray.

Downloads from the relevant AWS bucket, as an xarray DataArray. 2 m DEM strips are large in size and loading remotely from AWS may take some time. Option to filter to bounds and bitmask.

Parameters:

  • row (GeoDataFrame) – A selected row from the GeoDataFrame output of pdemtools.search. Select the row manually using row = gdf.isel[[i]], or loop through the rows using for _, row in gdf.iterrows():.

  • bounds (tuple | Polygon, optional) – Clip to bounds [xmin, ymin, xmax, ymax], in EPSG:3413 (ArcticDEM) or EPSG:3031 (REMA). Will accept a shapely.Polygon geometry to extract bounds from. Defaults to None

  • bitmask (bool, optional) – Choose whether apply the associated bitmask. Defaults to True

  • pad (bool) – If the DEM strip is not the full extent of the given bounds, pad with NaNs to match the full bounds. Defaults to False.

  • chunks (int | tuple | dict) – Chunk size for rioxarray.open_rasterio, triggering dask parallelisation and lazy evaluation/loading. Defaults to None.

Returns:

xarray DataArray of DEM strip

Return type:

DataArray

pdemtools.load.mosaic(dataset: Literal['arcticdem', 'rema'], resolution: Literal['2m', '10m', '32m'], bounds: tuple | Polygon = None, version: Literal['v2.0', 'v3.0', 'v4.1'] | None = None, chunks: int | tuple | dict | None = None)#

Given a dataset, resolution, and bounding box, downloads the ArcticDEM or REMA mosiac from AWS.

Parameters:

  • dataset – The desired dataset, either ‘arcticdem’ or ‘rema’. Case-instensitive.

  • resolution – The desired mosaic resolution to download - must be either 2m, 10m, or 32m (will also accept 2, 10, and 32 as int types)

  • version (str) – Desired ArcticDEM or REMA version. Must be a valid version available from the PGC STAC API (e.g. v3.0 or v4.1 for ArcticDEM, or v2.0 for REMA).

  • bounds (tuple | Polygon, optional) – Clip to bounds [xmin, ymin, xmax, ymax], in EPSG:3413 (ArcticDEM) or EPSG:3031 (REMA). Will accept a shapely geometry to extract bounds from.

  • chunks (int | tuple | dict) – Chunk size for rioxarray.open_rasterio, triggering dask parallelisation and lazy evaluation/loading. Defaults to None.

Returns:

xarray DataArray of DEM mosaic

Return type:

DataArray

pdemtools.load.preview(row: GeoDataFrame, bounds: tuple | Polygon | None = None, bitmask: bool | None = True, pad: bool | None = False)#

Loads a 10 m hillshade preview of the desired ArcticDEM/REMA DEM strip as an xarray DataArray, for preliminary plotting and assessment. Option to filter to bounds.

Parameters:

  • row (GeoDataFrame) – A selected row from the GeoDataFrame output of pdemtools.search. Can either select a row manually using gdf.isel[[i]] where i is the desired row, or provide the entire GeoDataFrame,

  • bounds (tuple | Polygon, optional) – Clip to bounds [xmin, ymin, xmax, ymax], in EPSG:3413 (ArcticDEM) or EPSG:3031 (REMA). Will accept a shapely geometry to extract bounds from. Defaults to None

  • bitmask (bool) – If True, loads the masked hillshade according to the PGC bitmask. If False, loads the unmasked hillshade. Defaults to True

  • pad (bool) – If the DEM strip is not the full extent of the given bounds, pad with NaNs to match the full bounds. Defaults to True.

Returns:

xarray DataArray of DEM strip 10 m hillshade

Return type:

DataArray