Plot

These need the plot extra (pip install "disp_xr[plot]"). The functions live in disp_xr.plot and are methods of the accessor: ds.disp.plot_map(), ds.disp.plot_point(lon, lat).

Quick-look maps and point time series (plot extra).

Plotting is one of the two places disp-xr computes (with export): a map loads one epoch, a point loads one pixel series. Both convert lengths to units (millimeters by default) and label the axes with them.

Displacement is signed (positive toward the satellite), so maps use a diverging blue-gray-red scale centered on zero, with limits symmetric about it. Point plots draw a dashed rule at every reference-date change, where a chained series is joined or an unchained one restarts at zero.

plot_map

plot_map(obj: Union[Dataset, DataArray], time: Optional[Any] = None, *, layer: str = 'displacement', units: Optional[str] = 'mm', vmax: Optional[float] = None, percentile: float = 98.0, cmap: Optional[Union[str, Colormap]] = None, max_pixels: int = 2000, ax: Optional[Axes] = None, title: Optional[str] = None) -> Axes

Map one epoch of a layer (or a 2D layer such as velocity).

Parameters:

Name	Type	Description	Default
obj	Dataset or DataArray	A DISP dataset (layer is plotted) or one layer, (time, y, x) or (y, x), with a CRS.	required
time	date - like	Epoch to plot, the nearest one to this date. Defaults to the last.	None
layer	str	Layer of a Dataset to plot.	'displacement'
units	str	Length unit for the color scale ("mm", "cm", "m"); None keeps the stored unit. Non-length layers are not converted.	'mm'
vmax	float	Color limit; the scale runs from -vmax to vmax. Defaults to the percentile of the absolute values, so outliers do not wash out the map.	None
percentile	float	Percentile of |value| used when vmax is not given.	98.0
cmap	str or Colormap	Defaults to :func:diverging_cmap.	None
max_pixels	int	Larger maps are block-averaged so that neither side exceeds this many pixels before loading.	2000
ax	matplotlib Axes	Axes to draw on; a new figure otherwise.	None
title	str	Defaults to the layer, the epoch and the reference date.	None

Returns:

Type	Description
Axes

Examples:

>>> ax = ds.disp.plot_map()
>>> ax = plot_map(ds, time="2024-06-01", units="cm", vmax=5)

plot_point

plot_point(obj: Union[Dataset, DataArray], lon: Optional[float] = None, lat: Optional[float] = None, *, row: Optional[int] = None, col: Optional[int] = None, buffer_m: float = 0.0, layer: str = 'displacement', units: Optional[str] = 'mm', ax: Optional[Axes] = None, title: Optional[str] = None) -> Axes

Plot the time series at one point, with reference-change markers.

Parameters:

Name	Type	Description	Default
obj	Dataset or DataArray	A DISP dataset (layer is plotted) or one (time, y, x) layer.	required
lon	float	Point location; or give row and col.	None
lat	float	Point location; or give row and col.	None
row	int	Pixel indices, instead of lon/lat.	None
col	int	Pixel indices, instead of lon/lat.	None
buffer_m	float	Plot the median of the pixels within this distance (a square window) instead of one pixel.	0.0
layer	str	Layer of a Dataset to plot.	'displacement'
units	str	Length unit of the y axis; None keeps the stored unit.	'mm'
ax	matplotlib Axes	Axes to draw on; a new figure otherwise.	None
title	str	Defaults to the layer and the point.	None

Returns:

Type	Description
Axes

Raises:

Type	Description
OutOfBoundsError	If the point is outside the grid.

Examples:

>>> ax = plot_point(ds, lon=-120.43, lat=35.90, buffer_m=90)

plot_hex

plot_hex(hexes: Dataset, time: Optional[Any] = None, *, layer: str = 'displacement', units: Optional[str] = 'mm', vmax: Optional[float] = None, percentile: float = 98.0, cmap: Optional[Union[str, Colormap]] = None, ax: Optional[Axes] = None, title: Optional[str] = None) -> Axes

Map one epoch of a layer of :func:disp_xr.downsample_hex cells.

Draws each hexagon as a polygon (PolyCollection); empty cells are left blank. Parameters as in :func:plot_map.

Returns:

Type	Description
Axes

Examples:

>>> ax = plot_hex(dxr.downsample_hex(ds, spacing=1000.0))

diverging_cmap

diverging_cmap() -> Colormap

Return the disp-xr diverging colormap (blue negative, red positive).

Examples:

>>> from matplotlib.colors import to_hex
>>> cmap = diverging_cmap()
>>> to_hex(cmap(0.0)), to_hex(cmap(1.0))
('#123d73', '#7a1716')