dep_tools.utils module

This module contains utility functions which don’t belong elsewhere.

dep_tools.utils.join_path_or_url(prefix, file)[source]

Joins a prefix with a file name, with a slash in-between.

Parameters:

prefix (Path | str) – A folder-like thing, local or remote. Can begin with things like ./, https:// and s3://. Can end with a forward-slash or not.
file (str) – A stem-plus-extension file name. Can begin with a forward-slash or not.

Return type:

str

Returns:

A string containing the joined prefix and file, with a forward-slash in between.

dep_tools.utils.mask_to_gadm(xarr, area)[source]

Masks an input xarray object to GADM.

Parameters:

xarr (DataArray | Dataset) – The input xarray object.
area (GeoBox) – An area used to limit the GADM footprint so the operation doesn’t take as long.

Return type:

DataArray | Dataset

Returns:

The input xarray object, masked to GADM.

dep_tools.utils.get_logger(prefix, name)[source]

Set up a simple logger.

Parameters:

prefix (str) – The prefix to attach to each message.
name (str) – The name of the logger.

Returns:

class:Logger:.

Return type:

A

dep_tools.utils.shift_negative_longitudes(geometry)[source]

Fixes lines spanning the antimeridian by adding 360 to any negative longitudes.

Parameters:: geometry (Union[LineString, MultiLineString]) – The geometry to fix.
Return type:: Union[LineString, MultiLineString]
Returns:: The fixed geometry.

dep_tools.utils.bbox_across_180(region)[source]

Calculate a bounding box or boxes for an input region.

If the given region crosses the antimeridian, the bounding box is split into two, which straddle but do not cross it.

Parameters:: region (GeoDataFrame | GeoBox) – The region of interest.
Return type:: list[float] | tuple[list[float], list[float]]
Returns:: A list of floats, or a two-tuple containing lists of floats.

dep_tools.utils.fix_winding(geom)[source]

Orient the geometry coordinates to run counter-clockwise.

This is usually non-essential but resolves a barrage of warnings from the antimeridian package.

Parameters:: geom (Geometry) – An input Geometry
Return type:: Geometry
Returns:: The input Geometry, which orientation fixed if needed.

dep_tools.utils.search_across_180(region, client=None, **kwargs)[source]

Conduct a STAC search that handles data crossing the antimeridian correctly.

Sometimes search results that cross the antimeridian will make the output data span the globe when loaded by e.g. odc.stac.load(). This works by first calling bbox_across_180(), and then searching within each bounding box and combining the results if there is more than one.

Parameters:

region (GeoDataFrame | GeoBox) – A GeoDataFrame.
**kwargs – Arguments besides bbox and intersects passed to pystac_client.Client.search().

Return type:

ItemCollection

Returns:

An ItemCollection.

dep_tools.utils.copy_attrs(source, destination)[source]

Copy attributes from one xarray object to another.

See https://corteva.github.io/rioxarray/html/getting_started/manage_information_loss.html This function Doesn’t account for situations where the inputs don’t have the same variables. :type source: DataArray | Dataset :param source: The source object. :type destination: DataArray | Dataset :param destination: The destination object.

Return type:: DataArray | Dataset
Returns:: The destination object, with source attributes, encoding, and nodata value set.

dep_tools.utils.scale_and_offset(da, scale=[1], offset=0, keep_attrs=True)[source]

Applies a scale and offset to data.

If the process converts e.g. an integer to a floating point, the dtype will change.

Parameters:

da (DataArray | Dataset) – The input data.
scale (List[float]) – The scale to apply.
offset (float) – The offset to apply, after scaling.
keep_attrs (bool) – Whether to retain the input attributes in the output.

Return type:

DataArray | Dataset

Returns:

The input data, with scale and offset applied.

dep_tools.utils.write_to_local_storage(d, path, write_args={}, overwrite=True, use_odc_writer=False, **kwargs)[source]

Write something to local storage.

Parameters:

d (Union[DataArray, Dataset, GeoDataFrame, Item, str]) – What to write.
path (Union[str, Path]) – Where to write it.
write_args (Dict) – Additional arguments to the writer.
overwrite (bool) – Whether to overwrite existing data.
use_odc_writer (bool) – Whether to use write_cog() for xarray objects. Othewise rioxarray.rio.to_raster() is used.
**kwargs – Not used.

Raises:

ValueError – If the input data is not of the available types.

Return type:

None

dep_tools.utils.scale_to_int16(xr, output_multiplier, output_nodata, scale_int16s=False)[source]

Scale an xarray object to a 16-bit integer.

Parameters:

xr (Union[DataArray, Dataset]) – The input data.
output_multiplier (int) – The multiplier to apply to the input data.
output_nodata (int) – The output nodata value. Any null values in the input will be set to this. Additional the “nodata” attribute will be set to this.
scale_int16s (bool) – Whether to scale data which is already an integer.

Return type:

Union[DataArray, Dataset]

Returns:

This input data, with scaling applied.

dep_tools.utils.fix_bad_epsgs(item_collection)[source]

Repair some band EPSG codes in stac items loaded from the MSPC.

This function modifies in place. See https://github.com/microsoft/PlanetaryComputer/discussions/113 for more information.

Parameters:: item_collection (ItemCollection) – The input items.
Return type:: None
Returns:: The input items, with any bad EPSG codes fixed.

dep_tools.utils.remove_bad_items(item_collection)[source]

Remove some error-causing STAC Items from an item collection.

Remove really bad items which clobber processes even if fail_on_error is set to False for odc.stac.load() or the equivalent for stackstac.stack(). See https://github.com/microsoft/PlanetaryComputer/discussions/101

Parameters:: item_collection (ItemCollection) – The items.
Return type:: ItemCollection
Returns:: The items, with any with known bad IDs removed.