pdemtools.data module

pdemtools.data module#

This module contains functions necessary extracting relevant datasets for DEM processing (geoids, masks, etc), resampled to match the DEM xarray object.

pdemtools.data.bedrock_mask_from_bedmachine(bm_fpath: str, target_rxd: DataArray, mask_crs: str | int | None = None) → DataArray#

Construct boolean bedrock mask from bedmachine and a given target rioxarray dataset. Returns mask where bedrock values are 1 and outside are 0.

Parameters:

  • bm_fpath (str) – Filepath to BedMachine dataset, defaults to None

  • target_rxd (DataArray) – (rio)xarray dataset that BedMachine will be resampled to match

  • mask_crs (Optional[Union[str, int]]) – CRS of the BedMachine dataset, if not stored in the file metadata. Optional, defaults to None

Returns:

bedrock mask for the target_rxd region as a (rio)xarray DataArray

Return type:

DataArray

pdemtools.data.bedrock_mask_from_vector(vector: str | GeoDataFrame, target_rxd: DataArray, mask_crs: str | int | None = None) → DataArray#

Construct boolean bedrock mask from a Geopandas vector file of bedrock areas and a given target rioxarray dataset. Returns mask where bedrock values are 1 and outside are 0.

Parameters:

  • vector – either a GeoPandas GeoDataFrame of bedrock areas, or a filepath to a Geopandas-readable vector file (e.g. shapefile, geopackage, etc.).

  • target_rxd (DataArray) – (rio)xarray dataset that BedMachine will be resampled to match

  • mask_crs (Optional[Union[str, int]]) – CRS of the vector file, if not stored in the file metadata. Optional, defaults to None

Returns:

bedrock mask for the target_rxd region as a (rio)xarray DataArray

Return type:

DataArray

pdemtools.data.geoid_from_bedmachine(bm_fpath: str, target_rxd: DataArray, geoid_crs: str | int | None = None) → DataArray#

Extracts the BedMachine geoid (EIGEN-6C4), bilinearly resampled to match the target dataset.

Parameters:

  • bm_fpath (str) – Filepath to BedMachine dataset, defaults to None

  • target_rxd (DataArray) – (rio)xarray dataset that BedMachine will be resampled to match

  • geoid_crs (Optional[Union[str, int]]) – CRS of the geoid raster, if not stored in the geoid file metadata. Optional, defaults to None

Returns:

geoid for the target_rxd region as an xarray DataArray

Return type:

DataArray

pdemtools.data.geoid_from_raster(fpath: str, target_rxd: DataArray = None, geoid_crs: str | int | None = None) → DataArray#

Extracts an arbritary geoid stored as a raster dataset, bilinearly resampled to match the target dataset.

Parameters:

  • fpath (str) – Filepath to geoid raster

  • target_rxd (DataArray) – (rio)xarray dataset/array that the raster will be resampled to match. Optional, defaults to None

  • geoid_crs (Optional[Union[str, int]]) – CRS of the geoid raster, if not stored in the geoid file metadata. Optional, defaults to None

Returns:

geoid for the target_rxd region as an xarray DataArray

Return type:

DataArray

pdemtools.data.icesat2_atl06(target_rxd: DataArray | tuple, date: str | date, stable_mask: DataArray | None = None, days_r: int | None = [7, 14, 28, 45], min_is2_points: int | None = 100, filter_points: bool | None = True, include_dt_column: bool | None = True, epsg: int | None = None, sr_srt: int | None = 3, sr_cnf: int | None = 1, sr_ats: float | None = 20.0, sr_cnt: int | None = 10, sr_len: float | None = 20.0, sr_res: float | None = 10.0, sr_track: int | None = 0, sr_sigma_r_max: int | None = 5)#

Get ICESat-2 ATL06 data for a given target rioxarray dataset. Returns geopandas dataframe of ATL06-SR, processed and downloaded using the sliderule package.

Parameters beginning with sr_ are the sliderule parameters for sliderule.icesat2.atl06p(). All parameters are left to default, apart from the length len (20 m rather than 40 m) and step distance res (10 m rather than 20 m), in order to increase the resolution of the returned data to approximate the 10 m resolution of the default coregsitration DEM resolution. More information on parameters are provided here: https://slideruleearth.io/web/rtd/user_guide/ICESat-2.html

Parameters:

  • target_rxd (DataArray) – (rio)xarray dataset that ICESat-2 will be downloaded for. Also accepts a tuple of bounds in format [xmin, ymin, xmax, ymax], if the epsg parameter is provided.

  • date (str | datetime.date) – Date of dataset, as an interpretable string or datetime.date object.

  • stable_mask (DataArray) – (rio)xarray mask dataset where 1=valid, 0=masked. Will be used to spatially filter the ICESat-2 data. Defaults to None.

  • days_r (List[int]) – Day range within which to search for ICESat-2 data. Should be ascending list. Defaults to [7, 14, 28, 45], meaning that all ICESat-2 data within 7 days will be returned, and then, if not returning more points than min_is2_points (default 100), 28 days, 14 days, etc.

  • min_is2_points (int) – Minimum number of ICESat-2 points. If there are fewer, then the param days_r will be increased. If, after the maximum days_r has been searched and there are still insufficient points, then the function will return the available results with a warning. Defaults to 50.

  • filter_points (bool) – If True, then only ICESat-2 points that cover valid pixels in the target_rxd and stable_mask will be returned. Defaults to True.

  • include_dt_column (bool) – If True, then the datetime column dt will be included in the returned datafram that shows the temporal offset between the ICESat-2 point and the provided date. Defaults to True.

  • epsg (int) – EPSG code for the target_rxd dataset. If target_rxd is a tuple, this must be provided.

  • sr_srt (int) – sliderule surface type parameter. 0-land, 1-ocean, 2-seaice, 3-landice, 4-inlandwater. Defaults to 3.

  • sr_cnf (int) – sliderule confidence threshold. Default 1 (within 10 m).

  • sr_ats (float) – sliderule minimum along track spread. Defaults to 20.0 m.

  • sr_cnt (int) – sliderule minimum photon count in segment. Defaults to 10.

  • sr_len (float) – sliderule length of each extent in metres. Defaults to 20.0.

  • sr_res (float) – sliderule step distance for extents. Defaults to 10.0.

  • sr_track (int) – sliderule track. 0: all tracks, 1: gt1, 2: gt2, 3: gt3 Defaults to 0.

  • sr_sigma_r_max (int) – sliderule maximum robust dispersion in metres. Defaults to 5.

Returns:

geopandas dataframe of ICESat-2 data

Return type:

geopandas.DataFrame