API Reference

Full information about xdem’s functionality is provided on this page.

coreg

DEM coregistration classes and functions.

dem

DEM class and functions.

filters

Filters to remove outliers and reduce noise in DEMs.

spatial_tools

Basic operations to be run on 2D arrays and DEMs

spstats

Spatial statistical tools to estimate uncertainties related to DEMs

volume

Volume change calculation tools (aimed for glaciers).

xdem

DEM

class xdem.DEM(filename_or_dataset, vref_name=None, vref_grid=None, silent=False, **kwargs)[source]

Bases: geoutils.satimg.SatelliteImage

__init__(filename_or_dataset, vref_name=None, vref_grid=None, silent=False, **kwargs)[source]

Load digital elevation model data through the Raster class, parse additional attributes from filename or metadata trougth the SatelliteImage class, and then parse vertical reference from DEM product name. For manual input, only one of “vref”, “vref_grid” or “ccrs” is necessary to set the vertical reference.

Parameters

  • filename_or_dataset (str, DEM, SatelliteImage, Raster, rio.io.Dataset, rio.io.MemoryFile) – The filename of the dataset.

  • vref_name (str) – Vertical reference name

  • vref_grid (str) – Vertical reference grid (any grid file in https://github.com/OSGeo/PROJ-data)

  • silent – Whether to display vertical reference setting

  • silent – boolean

copy(new_array=None)[source]

Copy the Raster object in memory

Parameters

new_array – New array to use for the copied Raster

Returns

set_vref(vref_name=None, vref_grid=None, compute_ccrs=False)[source]

Set vertical reference with a name or with a grid

Parameters

  • vref_name (str) – Vertical reference name

  • vref_grid (str) – Vertical reference grid (any grid file in https://github.com/OSGeo/PROJ-data)

  • compute_ccrs (boolean) – Whether to compute the ccrs (read pyproj-data grid file)

Returns

to_vref(vref_name='EGM96', vref_grid=None)[source]

Convert between vertical references: ellipsoidal heights or geoid grids

Parameters
Returns

DEMCollection

class xdem.DEMCollection(dems, timestamps=None, outlines=None, reference_dem=0)[source]

Bases: object

A temporal collection of DEMs.

__init__(dems, timestamps=None, outlines=None, reference_dem=0)[source]

Create a new temporal DEM collection.

Parameters

  • dems – A list of DEMs.

  • timestamps – A list of DEM timestamps.

  • outlines – Polygons to separate the changing area of interest. Could for example be glacier outlines.

  • reference_dem – An instance or index of which DEM in the ‘dems’ list is the reference.

Returns

A new DEMCollection instance.

get_cumulative_series(kind='dh', outlines_filter=None, mask=None, nans_ok=False)[source]

Get the cumulative dH (elevation) or dV (volume) since the first timestamp.

Parameters

  • kind (str) – The kind of series. Can be dh or dv.

  • outlines_filter (Optional[str]) – A query to filter the outline vectors. Example: “name_column == ‘specific glacier’”.

  • mask (Optional[ndarray]) – Optional. A mask for areas of interest.

  • nans_ok (bool) – Warn if NaNs are encountered in a dDEM (it should have been gap-filled).

Return type

Series

Returns

A series of cumulative dH/dV with a Timestamp index.

get_ddem_mask(ddem, outlines_filter=None)[source]

Get a fitting dDEM mask for a provided dDEM.

The mask is created by evaluating these factors, in order:

If self.outlines do not exist, a full True boolean mask is returned. If self.outlines have keys for the start and end time, their union is returned. If self.outlines only have contain the start_time, its mask is returned. If len(self.outlines) == 1, the mask of that outline is returned.

Parameters

  • ddem (dDEM) – The dDEM to create a mask for.

  • outlines_filter (Optional[str]) – A query to filter the outline vectors. Example: “name_column == ‘specific glacier’”.

Return type

ndarray

Returns

A mask from the above conditions.

get_dh_series(outlines_filter=None, mask=None, nans_ok=False)[source]

Return a dataframe of mean dDEM values and respective areas for every timestamp.

The values are always compared to the reference DEM timestamp.

Parameters

  • mask (Optional[ndarray]) – Optional. A mask for areas of interest. Overrides potential outlines of the same date.

  • nans_ok (bool) – Warn if NaNs are encountered in a dDEM (it should have been gap-filled).

Return type

DataFrame

Returns

A dataframe of dH values and respective areas with an Interval[Timestamp] index.

get_dv_series(outlines_filter=None, mask=None, nans_ok=False)[source]

Return a series of mean volume change (dV) for every timestamp.

The values are always compared to the reference DEM timestamp.

Parameters

  • outlines_filter (Optional[str]) – A query to filter the outline vectors. Example: “name_column == ‘specific glacier’”.

  • mask (Optional[ndarray]) – Optional. A mask for areas of interest. Overrides potential outlines of the same date.

  • nans_ok (bool) – Warn if NaNs are encountered in a dDEM (it should have been gap-filled).

Return type

Series

Returns

A series of dV values with an Interval[Timestamp] index.

interpolate_ddems(method='linear')[source]

Interpolate all the dDEMs in the DEMCollection object using the chosen interpolation method.

Parameters

method – The chosen interpolation method.

property reference_dem: geoutils.georaster.Raster

Get the DEM acting reference.

Return type

Raster

property reference_timestamp: numpy.datetime64

Get the reference DEM timestamp.

Return type

datetime64

subtract_dems(resampling_method='cubic_spline')[source]

Generate dDEMs by subtracting all DEMs to the reference.

Parameters

resampling_method – The resampling method to use if reprojection is needed.

Returns

A list of dDEM objects.

dDEM

class xdem.dDEM(raster, start_time, end_time, error=None)[source]

Bases: xdem.dem.DEM

A difference-DEM object.

__init__(raster, start_time, end_time, error=None)[source]

Create a dDEM object from a Raster.

Parameters

  • raster (Raster) – A georeferenced Raster object.

  • start_time (datetime64) – The starting time of the dDEM.

  • end_time (datetime64) – The end time of the dDEM.

  • error (Optional[Any]) – An error measure for the dDEM (UNUSED).

Returns

A new dDEM instance.

copy()[source]

Return a copy of the DEM.

Return type

dDEM

property fill_method: str

Return the fill method used for the filled_data.

Return type

str

property filled_data: Optional[numpy.ndarray]

Get the filled data array if it exists, or else the original data if it has no nans.

Returns None if the filled_data array does not exist, and the original data has nans.

Return type

Optional[ndarray]

Returns

An array or None

from_array(transform, crs, start_time, end_time, error=None, nodata=None)[source]

Create a new dDEM object from an array.

Parameters

  • data (ndarray) – The dDEM data array.

  • transform – A geometric transform.

  • crs – The coordinate reference system of the dDEM.

  • start_time – The starting time of the dDEM.

  • end_time – The end time of the dDEM.

  • error – An error measure for the dDEM.

  • nodata – The nodata value.

Return type

dDEM

Returns

A new dDEM instance.

interpolate(method='linear', reference_elevation=None, mask=None)[source]

Interpolate the dDEM using the given method.

Parameters

  • method (str) – The method to use for interpolation.

  • reference_elevation (Union[ndarray, MaskedArray, DEM, None]) – Reference DEM. Only required for hypsometric approaches.

property time: numpy.timedelta64

Get the time duration.

Return type

timedelta64