raster_tools package

property band#: The band coordinate values.

property bandwise#

Returns an adapter for band-wise operations on this raster

The returned adapter allows lists/arrays of values to be mapped to the raster’s bands for binary operations.

property bounds#: Bounds tuple (minx, miny, maxx, maxy)

burn_mask()[source]#

Fill null-masked cells with null value.

Use this as a way to return the underlying data to a known state. If dtype is boolean, the null cells are set to True instead of promoting to fit the null value.

chunk(chunks)[source]#

Rechunk the underlying raster

Parameters: chunks (tuple of int) – The chunk sizes for each dimension (“band”, “y”, “x”, in that order). Must be a 3-tuple.
Returns: The rechunked raster
Return type: Raster

close()[source]#: Close the underlying source

copy()[source]#: Returns a copy of this Raster.

property crs#

The raster’s CRS.

This is a rasterio.crs.CRS object.

property data#: The underlying dask array of data

property dtype#: The dtype of the data.

eval()[source]#

Compute any applied operations and return the result as new Raster.

Note that the unerlying sources will be loaded into memory for the computations and the result will be fixed in memory. The original Raster will be unaltered.

Note

This method has been replaced by load() and will eventually be deprecated and then removed.

explore(band, *args, **kwargs)[source]#

Plot the raster band on an interactive folium map.

This allows for rapid data exploration. Any extra arguments or keyword arguments are passed on to odc-geo’s explore function.

Note

This function is very experimental.

Parameters: band (int) – The band to plot. Bands use 1-based indexing so this value must be greater than 0.
Returns: map – The resulting py:mod:folium map.
Return type: folium.folium.Map

property geobox#: GeoBox object describing the raster’s grid.

property geochunks#: Produce an array of GeoChunks that correspond to the underlying chunks in the data.

get_bands(bands)[source]#

Retrieve the specified bands as a new Raster. Indexing starts at 1.

Parameters: bands (int or sequence of ints) – The band or bands to be retrieved. A single band Raster is returned if bands is an int and a multiband Raster is returned if it is a sequence. The band numbers may be out of order and contain repeated elements. if bands is a sequence, the multiband raster’s bands will be in the order provided.
Returns: The resulting raster composed of the specified bands in the order given.
Return type: Raster

get_chunk_bounding_boxes(include_band=False)[source]#

Return GeoDataFrame with the chunk bounding boxes.

This method generates a GeoDataFrame of bounding boxes for the underlying data chunks. By default it does this for a single band since the bounding boxes are the same across bands. The result also contains columns for the chunk position in the data.

By default, the result has two position columns: ‘chunk_row’ and ‘chunk_col’. Setting include_band adds ‘chunk_band’.

Parameters: include_band (bool, optional) – Duplicates the result across bands and adds a third position column named ‘chunk_band’. Default is False.

Examples

>>> dem = Raster("data/dem.tif")
>>> dem.get_chunk_bounding_boxes()
    chunk_row  chunk_col                                           geometry
0           0          0  POLYGON ((-32863.383 53183.938, -32863.383 681...
1           0          1  POLYGON ((-17863.383 53183.938, -17863.383 681...
2           0          2  POLYGON ((-2863.383 53183.938, -2863.383 68183...
3           0          3  POLYGON ((12136.617 53183.938, 12136.617 68183...
4           0          4  POLYGON ((27136.617 53183.938, 27136.617 68183...
...
>>> dem.get_chunk_bounding_boxes(True)
    chunk_band  chunk_row  chunk_col                                           geometry
0            0          0          0  POLYGON ((-32863.383 53183.938, -32863.383 681...
1            0          0          1  POLYGON ((-17863.383 53183.938, -17863.383 681...
2            0          0          2  POLYGON ((-2863.383 53183.938, -2863.383 68183...
3            0          0          3  POLYGON ((12136.617 53183.938, 12136.617 68183...
4            0          0          4  POLYGON ((27136.617 53183.938, 27136.617 68183...
...

get_chunk_rasters()[source]#

Return the underlying data chunks as an array of Rasters.

This returns a 3D array where each element corresponds to a chunk of data. Each element is a Raster wrapping the corresponding chunk. The dimensions of the array are (n-bands, y-chunks, x-chunks). For example, if a Raster has 2 bands, 3 chunks in the y direction, and 4 chunks in the x direction, this method would produce an array of Rasters with shape (2, 3, 4).

Returns: The 3D numpy array of chunk Rasters.
Return type: numpy.ndarray

get_chunked_coords()[source]#: Get lazy coordinate arrays, in x-y order, chunked to match data.

index(x, y)[source]#

Return the (row, col) index of the pixel at (x, y).

Parameters

x (float, array-like) – x value(s) in the raster’s CRS
y (float, array-like) – y value(s) in the raster’s CRS

Returns

(row value(s), col value(s)). If the inputs where array-like, the output values will be arrays.

Return type

tuple

load()[source]#

Compute delayed operations and load the result into memory.

This computes all delayed operations built up so far and then stores the resulting raster in memory. This can have significant performance implications if the raster data being computed is large relative to the available computer memory. The original raster is unaltered.

property mask#: The null value mask as a dask array.

max(*args, **kwargs)#

Reduce the raster to a single dask value by applying max across all bands.

All arguments are ignored.

mean(*args, **kwargs)#

Reduce the raster to a single dask value by applying mean across all bands.

All arguments are ignored.

min(*args, **kwargs)#

Reduce the raster to a single dask value by applying min across all bands.

All arguments are ignored.

model_predict(model, n_outputs=1)[source]#

Generate a new raster using the provided model to predict new values.

The model argument must provide a predict method. If the desired model does not provide a predict function, ModelPredictAdaptor can be used to wrap it and make it compatible with this function.

Parameters

model (object) – The model used to estimate new values. It must have a predict method that takes an array-like object of shape (N, M), where N is the number of samples and M is the number of features/predictor variables. The predict method should return an (N, [n_outputs]) shape result. If only one variable is resurned, then the n_outputs dimension is optional.
n_outputs (int, optional) – The number of output variables from the model. Each output variable produced by the model is converted to a band in output raster. The default is 1.

Returns

The resulting raster of estimated values. Each band corresponds to an output variable produced by the model.

Return type

property nbands#: The number of bands.

property null_value#: The raster’s null value used to fill missing or invalid entries.

plot(*args, **kwargs)[source]#: Plot the raster. Args and kwargs are passed to xarray’s plot function.

prod(*args, **kwargs)#

Reduce the raster to a single dask value by applying prod across all bands.

All arguments are ignored.

property pxrs#

reclassify(remapping, unmapped_to_null=False)[source]#

Reclassify raster values based on a mapping.

The raster must have an integer type.

Parameters

remapping (str, dict) – Can be either a dict or a path string. If a dict is provided, the keys will be reclassified to the corresponding values. It is possible to map values to the null value by providing None in the mapping. If a path string, it is treated as an ASCII remap file where each line looks like a:b and a and b are scalars. b can also be “NoData”. This indicates that a will be mapped to the null value. The output values of the mapping can cause type promotion. If the input raster has integer data and one of the outputs in the mapping is a float, the result will be a float raster.
unmapped_to_null (bool, optional) – If True, values not included in the mapping are instead mapped to the null value. Default is False.

Returns

The remapped raster.

Return type

remap_range(mapping, inclusivity='left')[source]#

Remaps values based on a mapping or list of mappings.

Mappings are applied all at once with earlier mappings taking precedence.

Parameters

mapping (3-tuple of scalars or list of 3-tuples of scalars) – A tuple or list of tuples containing (min, max, new_value) scalars. The mappiing(s) map values between the min and max to the new_value. If new_value is None, the matching pixels will be marked as null. If mapping is a list and there are mappings that conflict or overlap, earlier mappings take precedence. inclusivity determines which sides of the range are inclusive and exclusive.
inclusivity (str, optional) –
Determines whether to be inclusive or exclusive on either end of the range. Default is ‘left’.

’left’ [min, max)
Left (min) side is inclusive and right (max) side is exclusive.

’right’ (min, max]
Left (min) side is exclusive and right (max) side is inclusive.

’both’ [min, max]
Both sides are inclusive.

’none’ (min, max)
Both sides are exclusive.

Returns

The resulting Raster.

Return type

raster_tools.general.remap_range

See also

replace_null(value)[source]#

Replaces null values with value.

Parameters: value (scalar) – The new value to replace null values with.
Returns: The new resulting Raster. If value is a float and the raster dtype is int, the raster type will be promoted to float.
Return type: Raster

reproject(crs_or_geobox=None, resample_method='nearest', resolution=None)[source]#

Reproject to a new projection or resolution.

This is a lazy operation.

Parameters

crs_or_geobox (int, str, CRS, GeoBox, optional) – The target grid to reproject the raster to. This can be a projection string, EPSG code string or integer, a CRS object, or a GeoBox object. resolution can also be specified to change the output raster’s resolution in the new CRS. If crs_or_geobox is not provided, resolution must be specified.
resample_method (str, optional) –
The data resampling method to use. Null pixels are ignored for all methods. Some methods require specific versions of GDAL. These are noted below. Valid methods are:

’nearest’
Nearest neighbor resampling. This is the default.

’bilinear’
Bilinear resmapling.

’cubic’
Cubic resmapling.

’cubic_spline’
Cubic spline resmapling.

’lanczos’
Lanczos windowed sinc resmapling.

’average’
Average resampling, computes the weighted average of all contributing pixels.

’mode’
Mode resampling, selects the value which appears most often.

’max’
Maximum resampling. (GDAL 2.0+)

’min’
Minimum resampling. (GDAL 2.0+)

’med’
Median resampling. (GDAL 2.0+)

’q1’
Q1, first quartile resampling. (GDAL 2.0+)

’q3’
Q3, third quartile resampling. (GDAL 2.0+)

’sum’
Sum, compute the weighted sum. (GDAL 3.1+)

’rms’
RMS, root mean square/quadratic mean. (GDAL 3.3+)
resolution (int, float, tuple of int or float, optional) – The desired resolution of the reprojected raster. If crs_or_geobox is unspecified, this is used to reproject to the new resolution while maintaining the same CRS. One of crs_or_geobox or resolution must be provided. Both can also be provided.

Returns

The reprojected raster on the new grid.

Return type

property resolution#: The x and y cell sizes as a tuple. Values are always positive.

round(decimals=0)[source]#

Evenly round to the given number of decimals

Parameters: decimals (int, optional) – The number of decimal places to round to. If negative, value specifies the number of positions to the left of the decimal point. Default is 0.
Returns: Rounded raster.
Return type: Raster

save(path, no_data_value=None, **gdal_kwargs)[source]#

Compute the final raster and save it to the provided location.

Parameters

path (str) – The target location to save the raster to.
no_data_value (scalar, optional) – A new null value to use when saving.
**gdal_kwargs (kwargs, optional) – Additional keyword arguments to to pass to rasterio and GDAL when writing the raster data.

Returns

A raster pointing to the saved location.

Return type

set_crs(crs)[source]#

Set the CRS for the underlying data.

Parameters: crs (object) – The desired CRS. This can be anything accepted by rasterio.crs.CRS.from_user_input (i.e. 4326, “epsg:4326”, etc).
Returns: A new raster with the specified CRS.
Return type: Raster

set_null(mask_raster)[source]#

Update the raster’s null pixels using the provided mask

Parameters: mask_raster (str, Raster) – Raster or path to a raster that is used to update the masked out pixels. This raster updates the mask. It does not replace the mask. Pixels that were already marked as null stay null and pixels that are marked as null in mask_raster become marked as null in the resulting raster. This is a logical “OR” operation. mask_raster must have data type of boolean, int8, or uint8. mask_raster must have either 1 band or the same number of bands as the raster it is being applied to. A single band mask_raster is broadcast across all bands of the raster being modified.
Returns: The resulting raster with updated mask.
Return type: Raster

set_null_value(value)[source]#

Sets or replaces the null value for the raster.

If there was previously no null value for the raster, one is set. If there was already a null value, then it is replaced. If the raster has an integer dtype and value is a float, the dtype will be promoted to a float dtype. If value is None, the null value is cleared. The raster data is not changed in this case.

Parameters: value (scalar or None) – The new null value for the raster. If None, the resulting raster will have no null value, i.e. the null value is cleared.
Returns: The new resulting Raster.
Return type: Raster

property shape#

The shape of the underlying raster. Dim 0 is the band dimension.

The shape will always be of the form (B, Y, X) where B is the band dimension, Y is the y dimension, and X is the x dimension.

property size#: The number of grid cells across all bands.

std(*args, **kwargs)#

Reduce the raster to a single dask value by applying std across all bands.

All arguments are ignored.

sum(*args, **kwargs)#

Reduce the raster to a single dask value by applying sum across all bands.

All arguments are ignored.

to_dataset()[source]#: Returns the underlying xarray.Dataset.

to_null_mask()[source]#

Returns a boolean Raster with True at null values and False otherwise.

Returns: The resulting mask Raster. It is True where this raster contains null values and False everywhere else.
Return type: Raster

to_numpy()[source]#: Return the raw internal raster as a numpy array.

Note

This triggers computation and loads the raster data into memory.

to_points()[source]#

Convert the raster into a vector where each non-null cell is a point.

The resulting points are located at the center of each grid cell.

Returns: The result is a dask_geopandas GeoDataFrame with the following columns: value, band, row, col, geometry. The value is the cell value at the row and column in the raster. Each row has a unique integer in the index. This is true across data frame partitions.
Return type: dask_geopandas.GeoDataFrame

See also

to_polygons(neighbors=4)[source]#

Convert the raster to a vector of polygons.

Null cells are ignored. The resulting vector is randomly ordered.

Parameters: neighbors ({4, 8} int, optional) – This determines how many neighboring cells to consider when joining cells together to form polygons. Valid values are 4 and 8. 8 causes diagonal neighbors to be used. Default is 4.
Returns: A GeoDataFrame with columns: value, band, geometry. The geometry column contains polygons/multi-polygons.
Return type: dask_geopandas.GeoDataFrame

Notes

The algorithm used by this method is best used with simple thematic data. This is because the algorithm consumes memory proportional to the number and complexity of the produced polygons. Data that produces a large number of polygons, i.e. data with high pixel-to-pixel variability, will cause a large amount of memory to be consumed.

See also

to_quadrants()[source]#

Split the raster into quadrants

This returns the quadrants of the raster in the order northwest, northeast, southwest, southeast.

Returns: result – The returned result is a namedtuple with attributes: nw, ne, sw, and se. Unpacking or indexing the object provides the quadrants in the stated order.
Return type: RasterQuadrantsResult

to_vector(as_polygons=False, neighbors=4)[source]#

Convert the raster to a vector.

Parameters

as_polygons (bool, optional) – If True, the raster is converted to polygons/multi-polygon, each polyon/mult-polygon is made up of like-valued cells. Null cells are ignored. to_polygons() for more information. If False, the raster is converted to points. Each non-null cell is a point in the output. See to_points() for more information. Default is False.
neighbors ({4, 8} int, optional) – Used when as_polygons is True. This determines how many neighboring cells to consider when joining cells together to form polygons. Valid values are 4 and 8. 8 causes diagonal neighbors to be used. Default is 4.

Returns

A GeoDataFrame. If as_polygons is True, the result is a dataframe with columns: value, band, geometry. The geometry column will contain polygons. If False, the result has columns: value, band, row, col, geometry. The geometry column will contain points.

Return type

dask_geopandas.GeoDataFrame

property values#: The raw internal raster as a numpy array.

Note

This triggers computation and loads the raster data into memory.

var(*args, **kwargs)#

Reduce the raster to a single dask value by applying var across all bands.

All arguments are ignored.

where(condition, other)[source]#

Filter elements from this raster according to condition.

The mask for the result is a combination of all three rasters. Any cells that are masked in the condition raster will be masked in the output. The rest of the cells are masked based on which raster they were taken from, as determined by the condition raster, and if the cell in that raster was null. Effectively, the resulting mask is determined as follows: where(condition.mask, True, where(condition, true_rast.mask, false_rast.mask).

Parameters

condition (str or Raster) – A boolean or int raster that indicates where elements in this raster should be preserved and where other should be used. If the condition is an int raster, it is coerced to bool using condition > 0. True cells pull values from this raster and False cells pull from other. str is treated as a path to a raster.
other (scalar, str or Raster, None) – A raster or value to use in locations where condition is False. str is treated as a path to a raster. If None, this is treated as a null value.

Returns

The resulting filtered Raster.

Return type

property x#: The x (horizontal) coordinate values.

property xdata#: The underlying xarray.DataArray (read only)

property xmask#: The null value mask as an xarray DataArray.

property xrs#

xy(row, col, offset='center')[source]#

Return the (x, y) coordinates of the pixel at (row, col).

Parameters

row (int, float, array-like) – row value(s) in the raster’s CRS
col (int, float, array-like) – row value(s) in the raster’s CRS
offset (str, optional) –
Determines if the returned coordinates are for the center or a corner. Default is ‘center’

’center’
The pixel center.

’ul’
The upper left corner.

’ur’
The upper right corner.

’ll’
The lower left corner.

’lr’
The lower right corner.

Returns

(x value(s), y value(s)). If the inputs where array-like, the output values will be arrays.

Return type

tuple

property y#: The y (vertical) coordinate values.

class raster_tools.raster.RasterQuadrantsResult(nw, ne, sw, se)#

Bases: tuple

ne#: Alias for field number 1

nw#: Alias for field number 0

se#: Alias for field number 3

sw#: Alias for field number 2

raster_tools.raster.data_to_raster(data, mask=None, x=None, y=None, affine=None, crs=None, nv=None, burn=False)[source]#

Create a Raster from a data array.

Parameters

data (np.ndarray, dask.array.Array) – The data array.
mask (np.ndarray, dask.array.Array) – A boolean mask array. The default is to generate a mask from the data using nv.
x (list, np.ndarra, optional) – The x coordinate value. If x and y are not specified, affine is used to generate x and y coordinates.
y (list, np.ndarra, optional) – The y coordinate value. If x and y are not specified, affine is used to generate x and y coordinates.
affine (affine.Affine, optional) –
If None, the affine matrix is created using x and y. If affine is None and x and y are not specified, default affine matrix of:
```
| 1.0 0.0 0.0 |
| 0.0 1.0   N |
```
where N is the size of the y dim.
crs (int, str, rasterio.CRS, optional) – The CRS to use for the result. The default is no CRS.
nv (scalar, optional) – The nodata/null value to use. The default is no null value.
burn (bool, optional) – If True, mask is used to ‘burn’ the null value into the data array (e.g. np.where(mask, nv, data)). The default is False.

Returns

raster – The resulting Raster object.

Return type

raster_tools.raster.data_to_raster_like(data, like, mask=None, nv=None, burn=False, match_chunks=True)[source]#

Create a Raster, based on a template Raster, from a data array.

The CRS and x/y information are pulled from xlike.

Parameters

data (np.ndarray, dask.array.Array) – The data array.
like (xarray.DataArray, Raster) – The template to pull geospatial information from. Can be a DataArray or Raster.
mask (np.ndarray, dask.array.Array) – A boolean mask array. The default is to generate a mask from the data using nv.
nv (scalar, optional) – The nodata/null value to use. The default is no null value.
burn (bool, optional) – If True, mask is used to ‘burn’ the null value into the data array (e.g. np.where(mask, nv, data)). The default is False.
match_chunks (bool, optional) – If True, the chunks of the output will match the chunks in xlike. The default is True.

Returns

raster – The resulting raster matching like.

Return type

raster_tools.raster.data_to_xr_raster(data, x=None, y=None, affine=None, crs=None, nv=None)[source]#

Create a standard raster DataArray from a data array.

Parameters

data (np.ndarray, dask.array.Array) – The data array.
x (list, np.ndarra, optional) – The x coordinate value. If x and y are not specified, affine is used to generate x and y coordinates.
y (list, np.ndarra, optional) – The y coordinate value. If x and y are not specified, affine is used to generate x and y coordinates.
affine (affine.Affine, optional) –
If None, the affine matrix is created using x and y. If affine is None and x and y are not specified, default affine matrix of:
```
| 1.0 0.0 0.0 |
| 0.0 1.0   N |
```
where N is the size of the y dim.
crs (int, str, rasterio.CRS, optional) – The CRS to use for the result. The default is no CRS.
nv (scalar, optional) – The nodata/null value to use. The default is no null value.

Returns

raster – The resulting raster DataArray.

Return type

xarray.DataArray

raster_tools.raster.data_to_xr_raster_ds(data, mask=None, x=None, y=None, affine=None, crs=None, nv=None, burn=False)[source]#

Create a standard raster Dataset from a data array.

Parameters

data (np.ndarray, dask.array.Array) – The data array.
mask (np.ndarray, dask.array.Array) – A boolean mask array. The default is to generate a mask from the data using nv.
x (list, np.ndarra, optional) – The x coordinate value. If x and y are not specified, affine is used to generate x and y coordinates.
y (list, np.ndarra, optional) – The y coordinate value. If x and y are not specified, affine is used to generate x and y coordinates.
affine (affine.Affine, optional) –
If None, the affine matrix is created using x and y. If affine is None and x and y are not specified, default affine matrix of:
```
| 1.0 0.0 0.0 |
| 0.0 1.0   N |
```
where N is the size of the y dim.
crs (int, str, rasterio.CRS, optional) – The CRS to use for the result. The default is no CRS.
nv (scalar, optional) – The nodata/null value to use. The default is no null value.
burn (bool, optional) – If True, mask is used to ‘burn’ the null value into the data array (e.g. np.where(mask, nv, data)). The default is False.

Returns

raster – Theresulting raster Dataset object.

Return type

xarray.Dataset

raster_tools.raster.data_to_xr_raster_ds_like(data, xlike, mask=None, nv=None, burn=False, match_chunks=True)[source]#

Create a standard raster Dataset using a template raster DataArray.

The CRS and x/y information are pulled from xlike.

Parameters

data (np.ndarray, dask.array.Array) – The data array.
xlike (xarray.DataArray) – The template to pull geospatial information from.
mask (np.ndarray, dask.array.Array) – A boolean mask array. The default is to generate a mask from the data using nv.
nv (scalar, optional) – The nodata/null value to use. The default is no null value.
burn (bool, optional) – If True, mask is used to ‘burn’ the null value into the data array (e.g. np.where(mask, nv, data)). The default is False.
match_chunks (bool, optional) – If True, the chunks of the output will match the chunks in xlike. The default is True

Returns

raster – The resulting raster Dataset object matching xlike.

Return type

xarray.Dataset

raster_tools.raster.data_to_xr_raster_like(data, xlike, nv=None, match_band_dim=False, match_chunks=True)[source]#

Create a standard raster DataArray based on a template DataArray.

The CRS and x/y information are pulled from xlike.

Parameters

data (np.ndarray, dask.array.Array) – The data array.
xlike (xarray.DataArray) – The template to pull geospatial information from.
nv (scalar, optional) – The nodata/null value to use. The default is no null value.
match_band_dim (bool, optional) – If data has only 1 band, this will stack data to match the number of bands in xlike. The default is to not match the number of bands.
match_chunks (bool, optional) – If True, the chunks of the output will match the chunks in xlike. The default is True.

Returns

raster – The resulting raster DataArray matcing xlike.

Return type

xarray.DataArray

raster_tools.raster.dataarray_to_raster(xdata, xmask=None, crs=None)[source]#

Create a Raster from a DataArray object.

The null value is pulled from xdata using rioxarray.

Parameters

xdata (xarray.DataArray) – The object to make a Raster from.
xmask (xarray.DataArray, optional) – The matching mask to use with the xdata object when creating the raster Dataset. Must have boolean dtype. The default is to generate a mask from xdata based on the value returned by xdata.rio.nodata.
crs (int, str, rasterio.CRS, optional) – The CRS to use when creating the result. The default is to take the CRS from xdata, if present.

Returns

raster – The resulting Raster.

Return type

ref: https://pro.arcgis.com/en/pro-app/latest/tool-reference/spatial-analyst/an-overview-of-the-surface-tools.htm ref: makepath/xarray-spatial

raster_tools.raster.dataarray_to_xr_raster(xdata)[source]#

Transform a DataArray object into standard raster DataArray.

The CRS and null value are pulled from xdata using rioxarray.

Parameters: xdata (xarray.DataArray,) – The object to convert to a raster form.
Returns: raster – The resulting DataArray in standard raster format with dims: ("band", "y", "x") and encoded CRS and null value.
Return type: xarray.DataArray

raster_tools.raster.dataarray_to_xr_raster_ds(xdata, xmask=None, crs=None)[source]#

Create a raster Dataset object from a DataArray object.

The null value is pulled from xdata using rioxarray.

Parameters

xdata (xarray.DataArray,) – The object to convert to a raster Dataset
xmask (xarray.DataArray[bool], optional) – The matching mask to use with the xdata object when creating the raster Dataset. Must have boolean dtype. The default is to generate a mask from xdata based on the value returned by xdata.rio.nodata.
crs (int, str, rasterio.CRS, optional) – The CRS to use when creating the result. The default is to take the CRS from xdata, if present.

Returns

raster – The resulting raster Dataset with two data variables: “raster” and “mask”.

Return type

xarray.Dataset

raster_tools.raster.get_mask_from_data(data, nv=None)[source]#

raster_tools.raster.get_raster(src, strict=True, null_to_nan=False)[source]#

raster_tools.raster.get_raster_ds(raster)[source]#

raster_tools.raster.make_raster_ds(raster_dataarray, mask_dataarray)[source]#: Takes data and mask DataArrays and produces a raster Dataset with the data in the data variable “raster” and the mask in the “mask” data variable.

raster_tools.raster.normalize_data(data, yx_chunks=None)[source]#

2d/3d np.ndarray or da.Array –> 3D da.Array.

This transforms the data array into the standard data format, which has the following properties:

3D with band dimension first.
Is a dask array
Chunksize of 1 in the band dim.

Parameters

data (np.ndarray, dask.array.Array) – The data array.
yx_chunks (tuple, optional) – Tuple of chunks for the y and x dimensions, in that order. The default is to leave the chunks as is in this dimension or to chunk with "auto", if data is a numpy array.

Returns

data – The resulting dask array.

Return type

dask.array.Array

raster_tools.raster.normalize_xarray_data(xdata)[source]#

Transform the DataArray to the standard raster DataArray format.

A standard raster DataArray has the following:

3 dimensions in this order: ("band", "y", "x")
The band dim coordinates starts at one. ex: [1, 2, ...]
The x dim coordinates are always increasing.
The y dim coordinates are always decreasing.
The CRS is encoded at obj.rio.crs
The nodata/null value is encoded at obj.rio.nodata
The data within the DataArray is a dask array.
The dask chunks have size 1 in the band dim.

raster_tools.raster.rowcol_to_xy(row, col, affine, offset)[source]#: Convert (row, col) index values to (x, y) coords using the transformation.

raster_tools.raster.xr_where_with_meta(cond, left, right, crs=None, nv=None)[source]#

raster_tools.raster.xy_to_rowcol(x, y, affine)[source]#: Convert (x, y) coords to (row, col) index values using the transformation.

raster_tools.rasterize module#

raster_tools.rasterize.rasterize(features, like, field=None, overlap_resolve_method='last', mask=False, mask_invert=False, null_value=None, all_touched=True, use_spatial_aware=False, show_progress=False)[source]#

Convert vector feature data to a raster.

This function can be used to either rasterize features using values from a particular data field or to create a raster mask of zeros and ones. Using values to rasterize is the default. Use mask=True to generate a raster mask. If no data field is specified, the underlying dataframe’s index plus one is used. NOTE: because of limitations in dask, dataframe index values are not guaranteed to be unique across the dataframe. Cells that do not touch or overlap any features are marked as null.

To add a column of unique IDs for each feature, see raster_tools.vector.add_objectid_column() or raster_tools.vector.Vector.add_objectid_column().

This operation can be greatly accelerated if the provided features object has been spatially shuffled or had spatial partitions calculated. There are a few ways to do this. For Vector or GeoDataFrame/GeoSeries objects, you can use the spatial_shuffle or calculate_spatial_partitions methods. calculate_spatial_partitions simply computes the spatial bounds of each partition in the data. spatial_shuffle shuffles the data into partitions of spatially near groups and calculates the spatial bounds at the same time. This second method is more expensive but provides a potentially greater speed up for rasterization. The use_spatial_aware flag can also be provided to this function. This causes the spatial partitions to be calculated before rasterization.

Note

If the CRS for features does not match the CRS for like, features will be transformed to like’s CRS. This operation causes spatial partition information to be lost. It is recommended that the CRSs for both are matched ahead of time.

Parameters

features (Vector, GeoDataFrame, dask_geopandas.GeoDataFrame) – Vector data to rasterize.
like (Raster) – A raster to use for grid and CRS information. The resulting raster will be on the same grid as like.
field (str, optional) – The name of a field to use for cell values when rasterizing the vector features. If None or not specified, the underlying dataframe’s index plus 1 is used. The default is to use the index plus 1.
overlap_resolve_method (str, optional) –
The method used to resolve overlaping features. Default is “last”. The available methods are:

’first’
Cells with overlapping features will receive the value from the feature that appears first in the feature table.

’last’
Cells with overlapping features will receive the value from the feature that appears last in the feature table.

’min’
Cells with overlap will receive the value from the feature with the smallest value.

’max’
Cells with overlap will receive the value from the feature with the largest value.
mask (bool, optional) – If True, the features are rasterized as a mask. Cells that do not touch a feature are masked out. Cells that touch the features are set to 1. If mask_invert is also True, this is inverted. If mask is False, the features are rasterized using field to retrieve values from the underlying dataframe. field is ignored, if this option is a used. Default is False.
mask_invert (bool, optional) – If True cells that are inside or touch a feature are masked out. If False, cells that do not touch a feature are masked out. Default is False.
null_value (scalar, optional) – The value to use in cells with no feature data, when not masking.
all_touched (bool, optional) – If True, grid cells that the vector touches will be burned in. If False, only cells with a center point inside of the vector perimeter will be burned in.
use_spatial_aware (bool, optional) – Force the use of spatial aware rasterization. If True and features is not already spatially indexed, a spatial index will be computed. Alternatively, if True and features’s CRS differs from like, a new spatial index in a common CRS will be computed. If features already has a spatial index and its CRS matches like, this argument is ignored. Default is False.
show_progress (bool, optional) – If use_spatial_aware is True, this flag causes a progress bar to be displayed for spatial indexing. Default is False.

Returns

The resulting single band raster of rasterized features. This raster will be on the same grid as like.

Return type

Raster

raster_tools.stat_common module#

raster_tools.stat_common.nan_unique_count_jit(x)[source]#

raster_tools.stat_common.nanargmax_jit(x)[source]#

raster_tools.stat_common.nanargmin_jit(x)[source]#

raster_tools.stat_common.nanasm_jit(x)[source]#

raster_tools.stat_common.nanentropy_jit(x)[source]#

raster_tools.stat_common.nanmax_jit(x)[source]#

raster_tools.stat_common.nanmean_jit(x)[source]#

raster_tools.stat_common.nanmedian_jit(x)[source]#

raster_tools.stat_common.nanmin_jit(x)[source]#

raster_tools.stat_common.nanmode_jit(x)[source]#

raster_tools.stat_common.nanstd_jit(x)[source]#

raster_tools.stat_common.nansum_jit(x)[source]#

raster_tools.stat_common.nanvar_jit(x)[source]#

raster_tools.surface module#

Surface module used to perform common surface analyses on Raster objects.

raster_tools.surface.aspect(raster)[source]#

Calculates the aspect of each raster cell for each raster band.

The approach is based on ESRI’s aspect calculation.

Parameters: raster (Raster or path str) – The raster to perform the calculation on (typically an elevation surface).
Returns: The resulting raster of aspect (degrees). The bands will have the same shape as the original Raster.
Return type: Raster

References

ESRI aspect

raster_tools.surface.curvature(raster)[source]#

Calculates the curvature of each raster cell for each raster band.

The approach is based on ESRI’s curvature calculation.

Parameters: raster (Raster or path str) – The raster to perform the calculation on (typically an elevation surface).
Returns: The resulting raster of curvature. The bands will have the same shape as the original Raster.
Return type: Raster

References

ESRI curvature

raster_tools.surface.easting(raster, is_aspect=False)[source]#

Calculates the easting component of each raster cell for each band.

Parameters

raster (Raster or path str) – The raster to perform the calculation on (typically an aspect or elevation surface).
is_aspect (bool) – Indicates if raster is an aspect raster or an elevation raster. The default is false and assumes that an elevation raster is used.

Returns

The resulting raster of easting (-1 to 1). The bands will have the same shape as the original raster.

Return type

Raster

raster_tools.surface.hillshade(raster, azimuth=315, altitude=45)[source]#

Calculates the hillshade component of each raster cell for each band.

This approach is based on ESRI’s hillshade calculation.

Parameters

raster (Raster or path str) – The raster to perform the calculation on (typically a elevation surface).
azimuth (scalar) – The azimuth of the sun (degrees).
altitude (scalar) – The altitude of the sun (degrees).

Returns

The resulting raster of hillshade values (0-255, uint8). The bands will have the same shape as the original Raster. The null value is set to 255.

Return type

Raster

References

ESRI hillshade

raster_tools.surface.northing(raster, is_aspect=False)[source]#

Calculates the nothing component of each raster cell for each band.

Parameters

raster (Raster or path str) – The raster to perform the calculation on (typically an aspect or elevation surface).
is_aspect (bool, optional) – Indicates if raster is an aspect raster or an elevation raster. The default is false and assumes that an elevation raster is used.

Returns

The resulting raster of northing (-1 to 1). The bands will have the same shape as the original Raster.

Return type

Raster

raster_tools.surface.slope(raster, degrees=True)[source]#

Calculates the slope (degrees) of each raster cell for each raster band.

The approach is based on ESRI’s degree slope calculation.

Parameters

raster (Raster or path str) – The raster to perform the calculation on (typically an elevation surface).
degrees (bool) – Indicates whether to output as degrees or percent slope values. Default is True (degrees).

Returns

The resulting raster of slope values (degrees or percent). The bands will have the same shape as the original Raster.

Return type

Raster

References

ESRI slope

raster_tools.surface.surface_area_3d(raster)[source]#

Calculates the 3D surface area of each raster cell for each raster band.

The approach is based on Jense, 2004.

Parameters: raster (Raster or path str) – The raster to perform the calculation on (typically an elevation surface).
Returns: The resulting raster of 3D surface area. The bands will have the same shape as the original Raster.
Return type: Raster

References

Jense, 2004

raster_tools.surface.tpi(dem, annulus_inner, annulus_outer)[source]#

Compute the Topographic Position Index of a DEM.

This function compares each elevation value to the mean of its neighborhood to produce a scale-dependent index that highlights ridges (positive values) and valleys (negative valleys). Values close to zero, indicate areas with constant slope such as plains (slope of zero). The basic function looks like this: tpi = int(dem - focalmean(dem, annulus_inner, annulus_outer) + 0.5)

An annulus (donut) is used to select the neighborhood of each pixel. Larger radii values select features at larger scales.

The annulus radii values are in grid cell units or pixels so annulus_inner=10 for a 30m resoution raster, specifies a radius of 300m.

Parameters

dem (Raster or path str) – The DEM raster to use for TPI analysis.
annulus_inner (int) – The inner radius of the annulus in pixels. If 0, a circle of radius annulus_outer is used to select the neighborhood.
annulus_outer (int) – The outer radius of the annulus in pixels. Must be greater than annulus_inner.

Returns

tpi – The resulting TPI index for dem at the scale determined by the annulus radii.

Return type

Raster

References

Weiss AD (2001) Topographic position and landforms analysis. Conference poster for ‘21st Annual ESRI International User Conference’, 9–13 July 2001, San Diego, CA. Available at http://www.jennessent.com/arcview/TPI_Weiss_poster.htm

raster_tools.utils module#

raster_tools.utils.can_broadcast(*shapes, max_dim=3, min_dim=3)[source]#

raster_tools.utils.is_strictly_decreasing(x)[source]#

raster_tools.utils.is_strictly_increasing(x)[source]#

raster_tools.utils.list_reshape_2d(lst, shape, flat_start=0)[source]#

raster_tools.utils.list_reshape_3d(lst, shape)[source]#

raster_tools.utils.merge_masks(masks)[source]#

raster_tools.utils.single_band_mappable(func_=None, *, no_input_chunk=False, pass_block_info=False)[source]#

Decorator allowing functions that operate on 2D chunks to handle single band 3D chunks.

This allows functions to be mapped to (1, y, x) chunks in a dask map_blocks operation.

raster_tools.utils.to_chunk_dict(chunks, dims=None)[source]#

raster_tools.utils.validate_file(path)[source]#

raster_tools.utils.validate_path(path)[source]#

raster_tools.utils.version_to_tuple(version_str)[source]#

raster_tools.vector module#

class raster_tools.vector.Vector(geo, size=None)[source]#

Bases: object

A class representing vector data.

Take care to provide the actual number of features in the data when creating a new Vector.

add_objectid_column(name=None)[source]#

Add a column of unique ID values to the set of features.

Parameters: name (str, optional) – The name for the column. If not given, the ESRI OBJECTID convention is used. For example, if no name is given, ‘OBJECTID’ will be used. If ‘OBJECTID’ is already present, ‘OBJECTID_1’ is used, etc.
Returns: result – The updated vector with the new column of unique values.
Return type: Vector

property bounds#

(minx, miny, maxx, maxy).

If the vector is lazy, the output is a dask array.

Type: Return a bounds array or dask array

buffer(*args, **kwargs)[source]#

Apply the buffer operation to the vector geometries.

Parameters

*args (positional args) – Arguments to be passed on to GoePandas.
**kwargs (keyword args) – Keyword arguments to be passed onto GeoPandas.

Returns

The buffered vector.

Return type

calculate_spatial_partitions(show_progress=False)[source]#

Calculate the spatial bounds of the underlying data.

Parameters

show_progress (bool, optional) – Show a progressbar for the calculation. This operation can take a significant amount of time, so a progressbar may be helpful. Default is False.
note:: (..) – This causes partial computation to take place.

cast_field(name, dtype)[source]#

Cast a field to the specified dtype.

Parameters

name (str) – The field name to cast.
dtype (str, type, or numpy.dtype) – The dtype to cast to.

Returns

A new vector with the updated attribute table.

Return type

copy()[source]#: Copies the vector.

property crs#: The vector CRS.

property data#

eval()[source]#: Computes the built-up chain of operations on the underlying data.

property field_dtypes#: The field dtypes.

property field_names#: The field names.

property field_schema#: A mapping of the field names to dtypes.

property geometry#: The vector geometry series.

load()[source]#: Compute delayed operations and load the result into memory.

model_predict(model, fields, n_outputs=1, out_prefix='pred_')[source]#

Predict new columns using a model.

layer’s values are used as predictors for the model to produce new predictions. The resulting predictions are used to create a new vector with the results appended as new columns.

Parameters

layer (vector or path str) – Vector with attribute columns.
model (object) – The model used to estimate new values. It must have a predict method that takes an array-like object of shape (N, M), where N is the number of samples and M is the number of features/predictor variables. The predict method should return an (N, [n_outputs]) shape result. If only one variable is resurned, then the n_outputs dimension is optional.
fields (list of str) – The names of columns used in the model
n_outputs (int, optional) – The number of output variables from the model. Each output variable produced by the model is converted to a band in the output raster. The default is 1.
out_prefix (str, optional) – The prefix to use when naming the resulting column(s). The prefix will be combined with the 1-based number of the output variable. The Default is “pred_”.

Returns

The resulting vector with estimated values appended as a columns (pred_1, pred_2, pred_3 …).

Return type

save(path, **fiona_kwargs)[source]#

Save the vector data to a file.

By default, an ESRI shapefile is written.

Parameters

path (str) – Output location to save the vector data to.
**fiona_kwargs (keyword args) – Keyword arguments to pass on to fiona.open() such as layer='name', driver='GPKG', or mode='a'

Returns

Returns a new vector pointing to the saved location.

Return type

property shape#: The shape of the attribute table.

simplify(*args, **kwargs)[source]#

Simplify the vector geometries.

Parameters

*args (positional args) – Arguments to be passed on to GoePandas.
**kwargs (keyword args) – Keyword arguments to be passed onto GeoPandas.

Returns

The simplify vector.

Return type

property size#

The number of vectors contained. NaN is returned if the vector is lazy.

Use len(vector) to trigger computation of the length.

spatial_shuffle(show_progress=False)[source]#

Shuffle the features into spatially grouped partitions.

This sorts the features into partitions such that each partition contains features that are near to one another. This has the added benefit of computing the spatial extents of each partition.

Note

This causes partial computation to take place.

property table#: The vector attribute table.

property tasks#: The number of lazy operations left to be computed.

to_crs(crs)[source]#

Transform the vector coordinates to the specified crs.

Parameters: crs (str, pyproj.CRS) – The crs to transform the vector coordinates to. The value can be anything accepted by pyproj.CRS.from_user_input(), such as an EPSG string (eg “EPSG:4326”) or a WKT string.
Return type: The transformed vector(s).

to_dask()[source]#: Returns the underlying data as a dask_geopandas.GeoDataFrame.

to_dataframe()[source]#: Returns the underlying GeoDataFrame.

to_lazy(npartitions=None)[source]#

Converts to a lazy dask-backed Vector.

Parameters: npartitions (int) – The number of partitions to use.
Returns: A lazy copy of the vector.
Return type: Vector

to_raster(like, field=None, overlap_resolve_method='last', mask=False, mask_invert=False, null_value=None, all_touched=True, use_spatial_aware=False, show_progress=False)[source]#

Convert vector feature data to a raster.

This method can be used to either rasterize features using values from a particular data field or to create a raster mask of zeros and ones. Using values to rasterize is the default. Use mask=True to generate a raster mask. If no data field is specified, the underlying dataframe’s index is used. NOTE: because of limitations in dask, dataframe index values are not guaranteed to be unique across the dataframe. Cells that do not touch or overlap any features are marked as null.

To add a column of unique IDs for each feature, see raster_tools.vector.add_objectid_column() or raster_tools.vector.Vector.add_objectid_column().

Note

If the CRS for this vector does not match the CRS for like, this vector will be transformed to like’s CRS. This operation causes spatial partition information to be lost. It is recommended that the CRSs for both are matched ahead of time.

Parameters

like (Raster) – A raster to use for grid and CRS information. The resulting raster will be on the same grid as like.
field (str, optional) – The name of a field to use for cell values when rasterizing the vector features. If None or not specified, the underlying dataframe’s index is used. The default is to use the index.
overlap_resolve_method (str, optional) –
The method used to resolve overlaping features. Default is “last”. The available methods are:

’first’
Cells with overlapping features will receive the value from the feature that appears first in the feature table.

’last’
Cells with overlapping features will receive the value from the feature that appears last in the feature table.

’min’
Cells with overlap will receive the value from the feature with the smallest value.

’max’
Cells with overlap will receive the value from the feature with the largest value.
mask (bool, optional) – If True, the features are rasterized as a mask. Cells that do not touch a feature are masked out. Cells that touch the features are set to 1. If mask_invert is also True, this is inverted. If mask is False, the features are rasterized using field to retrieve values from the underlying dataframe. field is ignored, if this option is a used. Default is False.
mask_invert (bool, optional) – If True cells that are inside or touch a feature are masked out. If False, cells that do not touch a feature are masked out. Default is False.
null_value (scalar, optional) – The value to use in cells with no feature data, when not masking.
all_touched (bool, optional) – If True, grid cells that the vector touches will be burned in. If False, only cells with a center point inside of the vector perimeter will be burned in.
use_spatial_aware (bool, optional) – Force the use of spatial aware rasterization. If True and features is not already spatially indexed, a spatial index will be computed. Alternatively, if True and features’s CRS differs from like, a new spatial index in a common CRS will be computed. If features already has a spatial index and its CRS matches like, this argument is ignored. Default is False.
show_progress (bool, optional) – If use_spatial_aware is True, this flag causes a progress bar to be displayed for spatial indexing. Default is False.

Returns

The resulting single band raster of rasterized features. This raster will be on the same grid as like.

Return type

Raster

to_shapely()[source]#: Returns the vector data as a list of shapely geometries objects.

raster_tools.vector.add_objectid_column(features, name=None, _base=1000000000)[source]#

Add a column of unique ID values to the set of features.

Parameters

features (Vector, str, GeoDataFrame, GeoSeries) – The features to add the column to.
name (str, optional) – The name for the column. If not given, the ESRI OBJECTID convention is used. For example, if no name is given, ‘OBJECTID’ will be used. If ‘OBJECTID’ is already present, ‘OBJECTID_1’ is used.

Returns

result – The updated vector or dataframe with the new column of unique values.

Return type

Vector, dask_geopandas.GeoDataFrame

raster_tools.vector.count_layer_features(path, layer)[source]#

Count the number of features in a layer of a vector source file.

Parameters

path (str) – The path to a vector source file.
layer (str, int) – The layer to count features from. Can be the 0-based index or a string.

Returns

The number of features.

Return type

int

raster_tools.vector.get_vector(src)[source]#

raster_tools.vector.list_layers(path)[source]#: List the layers in a vector source file.

raster_tools.vector.open_vectors(path, layers=None)[source]#

Open a vector source.

This can be any GDAL/OGR compatible source.

Parameters

path (str, Path) – The vector source path.
layers (list of int, int, list of str, str, or None, optional) – The layer(s) to read from the source. This can be a single layer int or string, a list of layer ints/strings, or None. If None, all layers are read in. If int(s) are given, they are treated as 0-based layer indices.

Returns

If only a single layer was specified or found, a single Vector object is returned. Otherwise, a list of Vector objects is returned.

Return type

Vector, list of Vector

raster_tools.warp module#

raster_tools.warp.reproject(raster, crs_or_geobox=None, resample_method='nearest', resolution=None)[source]#

Reproject to a new projection or resolution.

This is a lazy operation.

Parameters

raster (str, Raster) – The raster to reproject.
crs_or_geobox (int, str, CRS, GeoBox, optional) – The target grid to reproject the raster to. This can be a projection string, EPSG code string or integer, a CRS object, or a GeoBox object. resolution can also be specified to change the output raster’s resolution in the new CRS. If crs_or_geobox is not provided, resolution must be specified.
resample_method (str, optional) –
The data resampling method to use. Null pixels are ignored for all methods. Some methods require specific versions of GDAL. These are noted below. Valid methods are:

’nearest’
Nearest neighbor resampling. This is the default.

’bilinear’
Bilinear resmapling.

’cubic’
Cubic resmapling.

’cubic_spline’
Cubic spline resmapling.

’lanczos’
Lanczos windowed sinc resmapling.

’average’
Average resampling, computes the weighted average of all contributing pixels.

’mode’
Mode resampling, selects the value which appears most often.

’max’
Maximum resampling. (GDAL 2.0+)

’min’
Minimum resampling. (GDAL 2.0+)

’med’
Median resampling. (GDAL 2.0+)

’q1’
Q1, first quartile resampling. (GDAL 2.0+)

’q3’
Q3, third quartile resampling. (GDAL 2.0+)

’sum’
Sum, compute the weighted sum. (GDAL 3.1+)

’rms’
RMS, root mean square/quadratic mean. (GDAL 3.3+)
resolution (int, float, tuple of int or float, optional) – The desired resolution of the reprojected raster. If crs_or_geobox is unspecified, this is used to reproject to the new resolution while maintaining the same CRS. One of crs_or_geobox or resolution must be provided. Both can also be provided.

Returns

The reprojected raster on the new grid.

Return type

Raster

raster_tools.zonal module#

raster_tools.zonal.extract_points_eager(points, raster, column_name='extracted', skip_validation=True, axis=0)[source]#

Extract the raster cell values using point features

Note

This function is partially eager. The x and y values for the target points are computed. The result is still a lazy dask DataFrame.

This finds the grid cells that the points fall into and extracts the value at each point. The input feature will be partially computed to make sure that all of the geometries are points, unless skip_validation is set to True.

Parameters

points (str, Vector) – The points to use for extracting data.
raster (str, Raster) – The raster to pull data from.
column_name (str, optional) – The column name to use for the extracted data points. Default is “extracted”.
skip_validation (bool, optional) – If True, the input points is not validated to make sure that all features are points. This prevents partially computing the data. Default is True.
axis (int, optional) – If 0 band column and values will be appended to a dataframe. Otherwise band values will be append to the columns named after the prefix and band of a dataframe

Returns

The columns names depend on the value of axis and are based on the “band” and `column_name variable. If axis = 0, the output band column within the dataframe identifies the band the value was extracted from. The values within the column named after the column name variable are the extracted values from the given band. Otherwise, the column names within the dataframe are appended to the column_name prefix and provide the extracted values. NaN values in the extracted column are where there was missing data in the raster or the point was outside the raster’s domain.

Return type

dask.dataframe.DataFrame

raster_tools.zonal.zonal_stats(features, data_raster, stats, features_field=None, wide_format=True, handle_overlap=False)[source]#

Apply stat functions to a raster based on a set of features.

Parameters

features (str, Vector, Raster) – A Vector or path string pointing to a vector file or a categorical Raster. The vector features are used like cookie cutters to pull data from the data_raster bands. If features is a Raster, it must be an int dtype and have only one band.
data_raster (Raster, str) – A Raster or path string pointing to a raster file. The data raster to pull data from and apply the stat functions to.
stats (str, list of str) –
A single string or list of strings corresponding to stat functions. These functions will be applied to the raster data for each of the features in features. Valid string values:

’asm’
Angular second moment. Applies -sum(P(g)**2) where P(g) gives the probability of g within the neighborhood.

’count’
Count valid cells.

’entropy’
Calculates the entropy. Applies -sum(P(g) * log(P(g))). See ‘asm’ above.

’max’
Find the maximum value.

’mean’
Calculate the mean.

’median’
Calculate the median value.

’min’
Find the minimum value.

’mode’
Compute the statistical mode of the data. In the case of a tie, the lowest value is returned.

’nunique’
Count unique values.

’prod’
Calculate the product.

’size’
Calculate zone size.

’std’
Calculate the standard deviation.

’sum’
Calculate the sum.

’var’
Calculate the variance.
features_field (str, optional) – If the features argument is a vector, this determines which field to use when rasterizing the features. It must match one of the fields in features. The default is to use features’ index.
wide_format (bool, optional) –
If True, the resulting dataframe is returned in wide format where the columns are a cartesian product of the data_raster bands and the specified stats and the index contains the feature zone IDs.
```
pandas.MultiIndex(
  [
    ('band_1', 'stat1'),
    ('band_1', 'stat2'),
    ...
    ('band_2', 'stat1'),
    ('band_2', 'stat2'),
    ...
  ],
)
```
If False, the resulting dataframe has columns ‘zone’, ‘band’, ‘stat1’, ‘stat2’, … and an integer index. In this case, the zone column contains the feature zone IDs and band contains the one-base integer band number. The rest of the columns correspond to the specified stats.

The default is wide format.
handle_overlap (bool, optional) – Normally, polygon inputs for features are converted to a raster. This means that a cell can have only one value. In the case of overlapping polygons, one polygon will trump the others and the resulting statistics for all of the incident polygons may be affected. If True, overlapping polygons are accounted for and zonal statistics will be calculated independent of overlap. Currently this will trigger computation of features. The default is False.

Returns

A delayed dask DataFrame where the specified stats have been applied to the bands in data_raster. See the wide_format option for a description of the dataframe’s structure.

Return type

dask.dataframe.DataFrame

Module contents#

class raster_tools.Raster(raster, _fast_path=False)[source]#

Bases: raster_tools.raster._RasterBase

Abstraction of georeferenced raster data with lazy function evaluation.

All operations on a Raster return a new Raster.

Parameters: raster (str, Raster, xarray.DataArray, xarray.Dataset, numpy.ndarray) – The raster source to use for this Raster. If raster is a string, it is treated like a path. If raster is a Raster, a copy is made and its raster source is used. If raster is an xarray DataArray, Dataset, or numpy array, it is used as the source. Dataset objects must contain ‘raster’ and ‘mask’ variables. The dimensions of these variables are assumed to be “band”, “y”, “x”, in that order. The ‘mask’ variable must have boolean dtype.

property affine#

The affine transformation for the raster data.

This is an affine.Affine object.

all(*args, **kwargs)#

Reduce the raster to a single dask value by applying all across all bands.

All arguments are ignored.

any(*args, **kwargs)#

Reduce the raster to a single dask value by applying any across all bands.

All arguments are ignored.

astype(dtype, warn_about_null_change=True)[source]#

Return a copy of the Raster cast to the specified type.

Parameters

dtype (str, type, numpy.dtype) – The new type to cast the raster to. The null value will also be cast to this type. If the null value cannot be safely cast to the new type, a default null value for the given dtype is used. This will produce a warning unless warn_about_null_change is set to False.
warn_about_null_change (bool, optional) – Can be used to silence warnings. The default is to always warn about null value changes.

Returns

The new dtype raster.

Return type

property band#: The band coordinate values.

property bandwise#

Returns an adapter for band-wise operations on this raster

The returned adapter allows lists/arrays of values to be mapped to the raster’s bands for binary operations.

property bounds#: Bounds tuple (minx, miny, maxx, maxy)

burn_mask()[source]#

Fill null-masked cells with null value.

Use this as a way to return the underlying data to a known state. If dtype is boolean, the null cells are set to True instead of promoting to fit the null value.

chunk(chunks)[source]#

Rechunk the underlying raster

Parameters: chunks (tuple of int) – The chunk sizes for each dimension (“band”, “y”, “x”, in that order). Must be a 3-tuple.
Returns: The rechunked raster
Return type: Raster

close()[source]#: Close the underlying source

copy()[source]#: Returns a copy of this Raster.

property crs#

The raster’s CRS.

This is a rasterio.crs.CRS object.

property data#: The underlying dask array of data

property dtype#: The dtype of the data.

eval()[source]#

Compute any applied operations and return the result as new Raster.

Note that the unerlying sources will be loaded into memory for the computations and the result will be fixed in memory. The original Raster will be unaltered.

Note

This method has been replaced by load() and will eventually be deprecated and then removed.

explore(band, *args, **kwargs)[source]#

Plot the raster band on an interactive folium map.

This allows for rapid data exploration. Any extra arguments or keyword arguments are passed on to odc-geo’s explore function.

Note

This function is very experimental.

Parameters: band (int) – The band to plot. Bands use 1-based indexing so this value must be greater than 0.
Returns: map – The resulting py:mod:folium map.
Return type: folium.folium.Map

property geobox#: GeoBox object describing the raster’s grid.

property geochunks#: Produce an array of GeoChunks that correspond to the underlying chunks in the data.

get_bands(bands)[source]#

Retrieve the specified bands as a new Raster. Indexing starts at 1.

Parameters: bands (int or sequence of ints) – The band or bands to be retrieved. A single band Raster is returned if bands is an int and a multiband Raster is returned if it is a sequence. The band numbers may be out of order and contain repeated elements. if bands is a sequence, the multiband raster’s bands will be in the order provided.
Returns: The resulting raster composed of the specified bands in the order given.
Return type: Raster

get_chunk_bounding_boxes(include_band=False)[source]#

Return GeoDataFrame with the chunk bounding boxes.

By default, the result has two position columns: ‘chunk_row’ and ‘chunk_col’. Setting include_band adds ‘chunk_band’.

Parameters: include_band (bool, optional) – Duplicates the result across bands and adds a third position column named ‘chunk_band’. Default is False.

Examples

>>> dem = Raster("data/dem.tif")
>>> dem.get_chunk_bounding_boxes()
    chunk_row  chunk_col                                           geometry
0           0          0  POLYGON ((-32863.383 53183.938, -32863.383 681...
1           0          1  POLYGON ((-17863.383 53183.938, -17863.383 681...
2           0          2  POLYGON ((-2863.383 53183.938, -2863.383 68183...
3           0          3  POLYGON ((12136.617 53183.938, 12136.617 68183...
4           0          4  POLYGON ((27136.617 53183.938, 27136.617 68183...
...
>>> dem.get_chunk_bounding_boxes(True)
    chunk_band  chunk_row  chunk_col                                           geometry
0            0          0          0  POLYGON ((-32863.383 53183.938, -32863.383 681...
1            0          0          1  POLYGON ((-17863.383 53183.938, -17863.383 681...
2            0          0          2  POLYGON ((-2863.383 53183.938, -2863.383 68183...
3            0          0          3  POLYGON ((12136.617 53183.938, 12136.617 68183...
4            0          0          4  POLYGON ((27136.617 53183.938, 27136.617 68183...
...

get_chunk_rasters()[source]#

Return the underlying data chunks as an array of Rasters.

Returns: The 3D numpy array of chunk Rasters.
Return type: numpy.ndarray

get_chunked_coords()[source]#: Get lazy coordinate arrays, in x-y order, chunked to match data.

index(x, y)[source]#

Return the (row, col) index of the pixel at (x, y).

Parameters

x (float, array-like) – x value(s) in the raster’s CRS
y (float, array-like) – y value(s) in the raster’s CRS

Returns

(row value(s), col value(s)). If the inputs where array-like, the output values will be arrays.

Return type

tuple

load()[source]#

Compute delayed operations and load the result into memory.

property mask#: The null value mask as a dask array.

max(*args, **kwargs)#

Reduce the raster to a single dask value by applying max across all bands.

All arguments are ignored.

mean(*args, **kwargs)#

Reduce the raster to a single dask value by applying mean across all bands.

All arguments are ignored.

min(*args, **kwargs)#

Reduce the raster to a single dask value by applying min across all bands.

All arguments are ignored.

model_predict(model, n_outputs=1)[source]#

Generate a new raster using the provided model to predict new values.

The model argument must provide a predict method. If the desired model does not provide a predict function, ModelPredictAdaptor can be used to wrap it and make it compatible with this function.

Parameters

model (object) – The model used to estimate new values. It must have a predict method that takes an array-like object of shape (N, M), where N is the number of samples and M is the number of features/predictor variables. The predict method should return an (N, [n_outputs]) shape result. If only one variable is resurned, then the n_outputs dimension is optional.
n_outputs (int, optional) – The number of output variables from the model. Each output variable produced by the model is converted to a band in output raster. The default is 1.

Returns

The resulting raster of estimated values. Each band corresponds to an output variable produced by the model.

Return type

property nbands#: The number of bands.

property null_value#: The raster’s null value used to fill missing or invalid entries.

plot(*args, **kwargs)[source]#: Plot the raster. Args and kwargs are passed to xarray’s plot function.

prod(*args, **kwargs)#

Reduce the raster to a single dask value by applying prod across all bands.

All arguments are ignored.

property pxrs#

reclassify(remapping, unmapped_to_null=False)[source]#

Reclassify raster values based on a mapping.

The raster must have an integer type.

Parameters

remapping (str, dict) – Can be either a dict or a path string. If a dict is provided, the keys will be reclassified to the corresponding values. It is possible to map values to the null value by providing None in the mapping. If a path string, it is treated as an ASCII remap file where each line looks like a:b and a and b are scalars. b can also be “NoData”. This indicates that a will be mapped to the null value. The output values of the mapping can cause type promotion. If the input raster has integer data and one of the outputs in the mapping is a float, the result will be a float raster.
unmapped_to_null (bool, optional) – If True, values not included in the mapping are instead mapped to the null value. Default is False.

Returns

The remapped raster.

Return type

remap_range(mapping, inclusivity='left')[source]#

Remaps values based on a mapping or list of mappings.

Mappings are applied all at once with earlier mappings taking precedence.

Parameters

mapping (3-tuple of scalars or list of 3-tuples of scalars) – A tuple or list of tuples containing (min, max, new_value) scalars. The mappiing(s) map values between the min and max to the new_value. If new_value is None, the matching pixels will be marked as null. If mapping is a list and there are mappings that conflict or overlap, earlier mappings take precedence. inclusivity determines which sides of the range are inclusive and exclusive.
inclusivity (str, optional) –
Determines whether to be inclusive or exclusive on either end of the range. Default is ‘left’.

’left’ [min, max)
Left (min) side is inclusive and right (max) side is exclusive.

’right’ (min, max]
Left (min) side is exclusive and right (max) side is inclusive.

’both’ [min, max]
Both sides are inclusive.

’none’ (min, max)
Both sides are exclusive.

Returns

The resulting Raster.

Return type

raster_tools.general.remap_range

See also

replace_null(value)[source]#

Replaces null values with value.

Parameters: value (scalar) – The new value to replace null values with.
Returns: The new resulting Raster. If value is a float and the raster dtype is int, the raster type will be promoted to float.
Return type: Raster

reproject(crs_or_geobox=None, resample_method='nearest', resolution=None)[source]#

Reproject to a new projection or resolution.

This is a lazy operation.

Parameters

crs_or_geobox (int, str, CRS, GeoBox, optional) – The target grid to reproject the raster to. This can be a projection string, EPSG code string or integer, a CRS object, or a GeoBox object. resolution can also be specified to change the output raster’s resolution in the new CRS. If crs_or_geobox is not provided, resolution must be specified.
resample_method (str, optional) –
The data resampling method to use. Null pixels are ignored for all methods. Some methods require specific versions of GDAL. These are noted below. Valid methods are:

’nearest’
Nearest neighbor resampling. This is the default.

’bilinear’
Bilinear resmapling.

’cubic’
Cubic resmapling.

’cubic_spline’
Cubic spline resmapling.

’lanczos’
Lanczos windowed sinc resmapling.

’average’
Average resampling, computes the weighted average of all contributing pixels.

’mode’
Mode resampling, selects the value which appears most often.

’max’
Maximum resampling. (GDAL 2.0+)

’min’
Minimum resampling. (GDAL 2.0+)

’med’
Median resampling. (GDAL 2.0+)

’q1’
Q1, first quartile resampling. (GDAL 2.0+)

’q3’
Q3, third quartile resampling. (GDAL 2.0+)

’sum’
Sum, compute the weighted sum. (GDAL 3.1+)

’rms’
RMS, root mean square/quadratic mean. (GDAL 3.3+)
resolution (int, float, tuple of int or float, optional) – The desired resolution of the reprojected raster. If crs_or_geobox is unspecified, this is used to reproject to the new resolution while maintaining the same CRS. One of crs_or_geobox or resolution must be provided. Both can also be provided.

Returns

The reprojected raster on the new grid.

Return type

property resolution#: The x and y cell sizes as a tuple. Values are always positive.

round(decimals=0)[source]#

Evenly round to the given number of decimals

Parameters: decimals (int, optional) – The number of decimal places to round to. If negative, value specifies the number of positions to the left of the decimal point. Default is 0.
Returns: Rounded raster.
Return type: Raster

save(path, no_data_value=None, **gdal_kwargs)[source]#

Compute the final raster and save it to the provided location.

Parameters

path (str) – The target location to save the raster to.
no_data_value (scalar, optional) – A new null value to use when saving.
**gdal_kwargs (kwargs, optional) – Additional keyword arguments to to pass to rasterio and GDAL when writing the raster data.

Returns

A raster pointing to the saved location.

Return type

set_crs(crs)[source]#

Set the CRS for the underlying data.

Parameters: crs (object) – The desired CRS. This can be anything accepted by rasterio.crs.CRS.from_user_input (i.e. 4326, “epsg:4326”, etc).
Returns: A new raster with the specified CRS.
Return type: Raster

set_null(mask_raster)[source]#

Update the raster’s null pixels using the provided mask

Parameters: mask_raster (str, Raster) – Raster or path to a raster that is used to update the masked out pixels. This raster updates the mask. It does not replace the mask. Pixels that were already marked as null stay null and pixels that are marked as null in mask_raster become marked as null in the resulting raster. This is a logical “OR” operation. mask_raster must have data type of boolean, int8, or uint8. mask_raster must have either 1 band or the same number of bands as the raster it is being applied to. A single band mask_raster is broadcast across all bands of the raster being modified.
Returns: The resulting raster with updated mask.
Return type: Raster

set_null_value(value)[source]#

Sets or replaces the null value for the raster.

Parameters: value (scalar or None) – The new null value for the raster. If None, the resulting raster will have no null value, i.e. the null value is cleared.
Returns: The new resulting Raster.
Return type: Raster

property shape#

The shape of the underlying raster. Dim 0 is the band dimension.

The shape will always be of the form (B, Y, X) where B is the band dimension, Y is the y dimension, and X is the x dimension.

property size#: The number of grid cells across all bands.

std(*args, **kwargs)#

Reduce the raster to a single dask value by applying std across all bands.

All arguments are ignored.

sum(*args, **kwargs)#

Reduce the raster to a single dask value by applying sum across all bands.

All arguments are ignored.

to_dataset()[source]#: Returns the underlying xarray.Dataset.

to_null_mask()[source]#

Returns a boolean Raster with True at null values and False otherwise.

Returns: The resulting mask Raster. It is True where this raster contains null values and False everywhere else.
Return type: Raster

to_numpy()[source]#: Return the raw internal raster as a numpy array.

Note

This triggers computation and loads the raster data into memory.

to_points()[source]#

Convert the raster into a vector where each non-null cell is a point.

The resulting points are located at the center of each grid cell.

Returns: The result is a dask_geopandas GeoDataFrame with the following columns: value, band, row, col, geometry. The value is the cell value at the row and column in the raster. Each row has a unique integer in the index. This is true across data frame partitions.
Return type: dask_geopandas.GeoDataFrame

See also

to_polygons(neighbors=4)[source]#

Convert the raster to a vector of polygons.

Null cells are ignored. The resulting vector is randomly ordered.

Parameters: neighbors ({4, 8} int, optional) – This determines how many neighboring cells to consider when joining cells together to form polygons. Valid values are 4 and 8. 8 causes diagonal neighbors to be used. Default is 4.
Returns: A GeoDataFrame with columns: value, band, geometry. The geometry column contains polygons/multi-polygons.
Return type: dask_geopandas.GeoDataFrame

Notes

See also

to_quadrants()[source]#

Split the raster into quadrants

This returns the quadrants of the raster in the order northwest, northeast, southwest, southeast.

Returns: result – The returned result is a namedtuple with attributes: nw, ne, sw, and se. Unpacking or indexing the object provides the quadrants in the stated order.
Return type: RasterQuadrantsResult

to_vector(as_polygons=False, neighbors=4)[source]#

Convert the raster to a vector.

Parameters

as_polygons (bool, optional) – If True, the raster is converted to polygons/multi-polygon, each polyon/mult-polygon is made up of like-valued cells. Null cells are ignored. to_polygons() for more information. If False, the raster is converted to points. Each non-null cell is a point in the output. See to_points() for more information. Default is False.
neighbors ({4, 8} int, optional) – Used when as_polygons is True. This determines how many neighboring cells to consider when joining cells together to form polygons. Valid values are 4 and 8. 8 causes diagonal neighbors to be used. Default is 4.

Returns

Return type

dask_geopandas.GeoDataFrame

property values#: The raw internal raster as a numpy array.

Note

This triggers computation and loads the raster data into memory.

var(*args, **kwargs)#

Reduce the raster to a single dask value by applying var across all bands.

All arguments are ignored.

where(condition, other)[source]#

Filter elements from this raster according to condition.

Parameters

condition (str or Raster) – A boolean or int raster that indicates where elements in this raster should be preserved and where other should be used. If the condition is an int raster, it is coerced to bool using condition > 0. True cells pull values from this raster and False cells pull from other. str is treated as a path to a raster.
other (scalar, str or Raster, None) – A raster or value to use in locations where condition is False. str is treated as a path to a raster. If None, this is treated as a null value.

Returns

The resulting filtered Raster.

Return type

property x#: The x (horizontal) coordinate values.

property xdata#: The underlying xarray.DataArray (read only)

property xmask#: The null value mask as an xarray DataArray.

property xrs#

xy(row, col, offset='center')[source]#

Return the (x, y) coordinates of the pixel at (row, col).

Parameters

row (int, float, array-like) – row value(s) in the raster’s CRS
col (int, float, array-like) – row value(s) in the raster’s CRS
offset (str, optional) –
Determines if the returned coordinates are for the center or a corner. Default is ‘center’

’center’
The pixel center.

’ul’
The upper left corner.

’ur’
The upper right corner.

’ll’
The lower left corner.

’lr’
The lower right corner.

Returns

(x value(s), y value(s)). If the inputs where array-like, the output values will be arrays.

Return type

tuple

property y#: The y (vertical) coordinate values.

class raster_tools.Vector(geo, size=None)[source]#

Bases: object

A class representing vector data.

Take care to provide the actual number of features in the data when creating a new Vector.

add_objectid_column(name=None)[source]#

Add a column of unique ID values to the set of features.

Parameters: name (str, optional) – The name for the column. If not given, the ESRI OBJECTID convention is used. For example, if no name is given, ‘OBJECTID’ will be used. If ‘OBJECTID’ is already present, ‘OBJECTID_1’ is used, etc.
Returns: result – The updated vector with the new column of unique values.
Return type: Vector

property bounds#

(minx, miny, maxx, maxy).

If the vector is lazy, the output is a dask array.

Type: Return a bounds array or dask array

buffer(*args, **kwargs)[source]#

Apply the buffer operation to the vector geometries.

Parameters

*args (positional args) – Arguments to be passed on to GoePandas.
**kwargs (keyword args) – Keyword arguments to be passed onto GeoPandas.

Returns

The buffered vector.

Return type

calculate_spatial_partitions(show_progress=False)[source]#

Calculate the spatial bounds of the underlying data.

Parameters

show_progress (bool, optional) – Show a progressbar for the calculation. This operation can take a significant amount of time, so a progressbar may be helpful. Default is False.
note:: (..) – This causes partial computation to take place.

cast_field(name, dtype)[source]#

Cast a field to the specified dtype.

Parameters

name (str) – The field name to cast.
dtype (str, type, or numpy.dtype) – The dtype to cast to.

Returns

A new vector with the updated attribute table.

Return type

copy()[source]#: Copies the vector.

property crs#: The vector CRS.

property data#

eval()[source]#: Computes the built-up chain of operations on the underlying data.

property field_dtypes#: The field dtypes.

property field_names#: The field names.

property field_schema#: A mapping of the field names to dtypes.

property geometry#: The vector geometry series.

load()[source]#: Compute delayed operations and load the result into memory.

model_predict(model, fields, n_outputs=1, out_prefix='pred_')[source]#

Predict new columns using a model.

layer’s values are used as predictors for the model to produce new predictions. The resulting predictions are used to create a new vector with the results appended as new columns.

Parameters

layer (vector or path str) – Vector with attribute columns.
model (object) – The model used to estimate new values. It must have a predict method that takes an array-like object of shape (N, M), where N is the number of samples and M is the number of features/predictor variables. The predict method should return an (N, [n_outputs]) shape result. If only one variable is resurned, then the n_outputs dimension is optional.
fields (list of str) – The names of columns used in the model
n_outputs (int, optional) – The number of output variables from the model. Each output variable produced by the model is converted to a band in the output raster. The default is 1.
out_prefix (str, optional) – The prefix to use when naming the resulting column(s). The prefix will be combined with the 1-based number of the output variable. The Default is “pred_”.

Returns

The resulting vector with estimated values appended as a columns (pred_1, pred_2, pred_3 …).

Return type

save(path, **fiona_kwargs)[source]#

Save the vector data to a file.

By default, an ESRI shapefile is written.

Parameters

path (str) – Output location to save the vector data to.
**fiona_kwargs (keyword args) – Keyword arguments to pass on to fiona.open() such as layer='name', driver='GPKG', or mode='a'

Returns

Returns a new vector pointing to the saved location.

Return type

property shape#: The shape of the attribute table.

simplify(*args, **kwargs)[source]#

Simplify the vector geometries.

Parameters

*args (positional args) – Arguments to be passed on to GoePandas.
**kwargs (keyword args) – Keyword arguments to be passed onto GeoPandas.

Returns

The simplify vector.

Return type

property size#

The number of vectors contained. NaN is returned if the vector is lazy.

Use len(vector) to trigger computation of the length.

spatial_shuffle(show_progress=False)[source]#

Shuffle the features into spatially grouped partitions.

This sorts the features into partitions such that each partition contains features that are near to one another. This has the added benefit of computing the spatial extents of each partition.

Note

This causes partial computation to take place.

property table#: The vector attribute table.

property tasks#: The number of lazy operations left to be computed.

to_crs(crs)[source]#

Transform the vector coordinates to the specified crs.

Parameters: crs (str, pyproj.CRS) – The crs to transform the vector coordinates to. The value can be anything accepted by pyproj.CRS.from_user_input(), such as an EPSG string (eg “EPSG:4326”) or a WKT string.
Return type: The transformed vector(s).

to_dask()[source]#: Returns the underlying data as a dask_geopandas.GeoDataFrame.

to_dataframe()[source]#: Returns the underlying GeoDataFrame.

to_lazy(npartitions=None)[source]#

Converts to a lazy dask-backed Vector.

Parameters: npartitions (int) – The number of partitions to use.
Returns: A lazy copy of the vector.
Return type: Vector

Convert vector feature data to a raster.

To add a column of unique IDs for each feature, see raster_tools.vector.add_objectid_column() or raster_tools.vector.Vector.add_objectid_column().

Note

Parameters

like (Raster) – A raster to use for grid and CRS information. The resulting raster will be on the same grid as like.
field (str, optional) – The name of a field to use for cell values when rasterizing the vector features. If None or not specified, the underlying dataframe’s index is used. The default is to use the index.
overlap_resolve_method (str, optional) –
The method used to resolve overlaping features. Default is “last”. The available methods are:

’first’
Cells with overlapping features will receive the value from the feature that appears first in the feature table.

’last’
Cells with overlapping features will receive the value from the feature that appears last in the feature table.

’min’
Cells with overlap will receive the value from the feature with the smallest value.

’max’
Cells with overlap will receive the value from the feature with the largest value.
mask (bool, optional) – If True, the features are rasterized as a mask. Cells that do not touch a feature are masked out. Cells that touch the features are set to 1. If mask_invert is also True, this is inverted. If mask is False, the features are rasterized using field to retrieve values from the underlying dataframe. field is ignored, if this option is a used. Default is False.
mask_invert (bool, optional) – If True cells that are inside or touch a feature are masked out. If False, cells that do not touch a feature are masked out. Default is False.
null_value (scalar, optional) – The value to use in cells with no feature data, when not masking.
all_touched (bool, optional) – If True, grid cells that the vector touches will be burned in. If False, only cells with a center point inside of the vector perimeter will be burned in.
use_spatial_aware (bool, optional) – Force the use of spatial aware rasterization. If True and features is not already spatially indexed, a spatial index will be computed. Alternatively, if True and features’s CRS differs from like, a new spatial index in a common CRS will be computed. If features already has a spatial index and its CRS matches like, this argument is ignored. Default is False.
show_progress (bool, optional) – If use_spatial_aware is True, this flag causes a progress bar to be displayed for spatial indexing. Default is False.

Returns

The resulting single band raster of rasterized features. This raster will be on the same grid as like.

Return type

to_shapely()[source]#: Returns the vector data as a list of shapely geometries objects.

raster_tools.band_concat(rasters)[source]#

Join a sequence of rasters along the band dimension.

Parameters: rasters (sequence of Rasters and/or paths) – The rasters to concatenate. These can be a mix of Rasters and paths. All rasters must have the same shape in the x and y dimensions.
Returns: The resulting concatenated Raster.
Return type: Raster

raster_tools.constant_raster(raster_template, value=1, bands=1, copy_mask=False)[source]#

Create a Raster filled with a constant value like a template raster.

This is a convenience function that wraps full_like().

Parameters

raster_template (Raster, str) – Template raster used to define rows, columns, crs, resolution, etc
value (scalar, optional) – Value to fill result with. Default is 1.
bands (int, optional) – Number of bands desired for output. Default is 1.
copy_mask (bool) – If True, the template raster’s mask is copied to the result raster. If bands differs from raster_template, the first band’s mask is copied bands times.

Returns

The resulting raster of constant values.

Return type

raster_tools.count_layer_features(path, layer)[source]#

Count the number of features in a layer of a vector source file.

Parameters

path (str) – The path to a vector source file.
layer (str, int) – The layer to count features from. Can be the 0-based index or a string.

Returns

The number of features.

Return type

int

raster_tools.data_to_raster(data, mask=None, x=None, y=None, affine=None, crs=None, nv=None, burn=False)[source]#

Create a Raster from a data array.

Parameters

data (np.ndarray, dask.array.Array) – The data array.
mask (np.ndarray, dask.array.Array) – A boolean mask array. The default is to generate a mask from the data using nv.
x (list, np.ndarra, optional) – The x coordinate value. If x and y are not specified, affine is used to generate x and y coordinates.
y (list, np.ndarra, optional) – The y coordinate value. If x and y are not specified, affine is used to generate x and y coordinates.
affine (affine.Affine, optional) –
If None, the affine matrix is created using x and y. If affine is None and x and y are not specified, default affine matrix of:
```
| 1.0 0.0 0.0 |
| 0.0 1.0   N |
```
where N is the size of the y dim.
crs (int, str, rasterio.CRS, optional) – The CRS to use for the result. The default is no CRS.
nv (scalar, optional) – The nodata/null value to use. The default is no null value.
burn (bool, optional) – If True, mask is used to ‘burn’ the null value into the data array (e.g. np.where(mask, nv, data)). The default is False.

Returns

raster – The resulting Raster object.

Return type

raster_tools.data_to_raster_like(data, like, mask=None, nv=None, burn=False, match_chunks=True)[source]#

Create a Raster, based on a template Raster, from a data array.

The CRS and x/y information are pulled from xlike.

Parameters

data (np.ndarray, dask.array.Array) – The data array.
like (xarray.DataArray, Raster) – The template to pull geospatial information from. Can be a DataArray or Raster.
mask (np.ndarray, dask.array.Array) – A boolean mask array. The default is to generate a mask from the data using nv.
nv (scalar, optional) – The nodata/null value to use. The default is no null value.
burn (bool, optional) – If True, mask is used to ‘burn’ the null value into the data array (e.g. np.where(mask, nv, data)). The default is False.
match_chunks (bool, optional) – If True, the chunks of the output will match the chunks in xlike. The default is True.

Returns

raster – The resulting raster matching like.

Return type

raster_tools.data_to_xr_raster(data, x=None, y=None, affine=None, crs=None, nv=None)[source]#

Create a standard raster DataArray from a data array.

Parameters

data (np.ndarray, dask.array.Array) – The data array.
x (list, np.ndarra, optional) – The x coordinate value. If x and y are not specified, affine is used to generate x and y coordinates.
y (list, np.ndarra, optional) – The y coordinate value. If x and y are not specified, affine is used to generate x and y coordinates.
affine (affine.Affine, optional) –
If None, the affine matrix is created using x and y. If affine is None and x and y are not specified, default affine matrix of:
```
| 1.0 0.0 0.0 |
| 0.0 1.0   N |
```
where N is the size of the y dim.
crs (int, str, rasterio.CRS, optional) – The CRS to use for the result. The default is no CRS.
nv (scalar, optional) – The nodata/null value to use. The default is no null value.

Returns

raster – The resulting raster DataArray.

Return type

xarray.DataArray

raster_tools.data_to_xr_raster_ds(data, mask=None, x=None, y=None, affine=None, crs=None, nv=None, burn=False)[source]#

Create a standard raster Dataset from a data array.

Parameters

data (np.ndarray, dask.array.Array) – The data array.
mask (np.ndarray, dask.array.Array) – A boolean mask array. The default is to generate a mask from the data using nv.
x (list, np.ndarra, optional) – The x coordinate value. If x and y are not specified, affine is used to generate x and y coordinates.
y (list, np.ndarra, optional) – The y coordinate value. If x and y are not specified, affine is used to generate x and y coordinates.
affine (affine.Affine, optional) –
If None, the affine matrix is created using x and y. If affine is None and x and y are not specified, default affine matrix of:
```
| 1.0 0.0 0.0 |
| 0.0 1.0   N |
```
where N is the size of the y dim.
crs (int, str, rasterio.CRS, optional) – The CRS to use for the result. The default is no CRS.
nv (scalar, optional) – The nodata/null value to use. The default is no null value.
burn (bool, optional) – If True, mask is used to ‘burn’ the null value into the data array (e.g. np.where(mask, nv, data)). The default is False.

Returns

raster – Theresulting raster Dataset object.

Return type

xarray.Dataset

raster_tools.data_to_xr_raster_ds_like(data, xlike, mask=None, nv=None, burn=False, match_chunks=True)[source]#

Create a standard raster Dataset using a template raster DataArray.

The CRS and x/y information are pulled from xlike.

Parameters

data (np.ndarray, dask.array.Array) – The data array.
xlike (xarray.DataArray) – The template to pull geospatial information from.
mask (np.ndarray, dask.array.Array) – A boolean mask array. The default is to generate a mask from the data using nv.
nv (scalar, optional) – The nodata/null value to use. The default is no null value.
burn (bool, optional) – If True, mask is used to ‘burn’ the null value into the data array (e.g. np.where(mask, nv, data)). The default is False.
match_chunks (bool, optional) – If True, the chunks of the output will match the chunks in xlike. The default is True

Returns

raster – The resulting raster Dataset object matching xlike.

Return type

xarray.Dataset

raster_tools.data_to_xr_raster_like(data, xlike, nv=None, match_band_dim=False, match_chunks=True)[source]#

Create a standard raster DataArray based on a template DataArray.

The CRS and x/y information are pulled from xlike.

Parameters

data (np.ndarray, dask.array.Array) – The data array.
xlike (xarray.DataArray) – The template to pull geospatial information from.
nv (scalar, optional) – The nodata/null value to use. The default is no null value.
match_band_dim (bool, optional) – If data has only 1 band, this will stack data to match the number of bands in xlike. The default is to not match the number of bands.
match_chunks (bool, optional) – If True, the chunks of the output will match the chunks in xlike. The default is True.

Returns

raster – The resulting raster DataArray matcing xlike.

Return type

xarray.DataArray

raster_tools.dataarray_to_raster(xdata, xmask=None, crs=None)[source]#

Create a Raster from a DataArray object.

The null value is pulled from xdata using rioxarray.

Parameters

xdata (xarray.DataArray) – The object to make a Raster from.
xmask (xarray.DataArray, optional) – The matching mask to use with the xdata object when creating the raster Dataset. Must have boolean dtype. The default is to generate a mask from xdata based on the value returned by xdata.rio.nodata.
crs (int, str, rasterio.CRS, optional) – The CRS to use when creating the result. The default is to take the CRS from xdata, if present.

Returns

raster – The resulting Raster.

Return type

raster_tools.dataarray_to_xr_raster(xdata)[source]#

Transform a DataArray object into standard raster DataArray.

The CRS and null value are pulled from xdata using rioxarray.

Parameters: xdata (xarray.DataArray,) – The object to convert to a raster form.
Returns: raster – The resulting DataArray in standard raster format with dims: ("band", "y", "x") and encoded CRS and null value.
Return type: xarray.DataArray

raster_tools.dataarray_to_xr_raster_ds(xdata, xmask=None, crs=None)[source]#

Create a raster Dataset object from a DataArray object.

The null value is pulled from xdata using rioxarray.

Parameters

xdata (xarray.DataArray,) – The object to convert to a raster Dataset
xmask (xarray.DataArray[bool], optional) – The matching mask to use with the xdata object when creating the raster Dataset. Must have boolean dtype. The default is to generate a mask from xdata based on the value returned by xdata.rio.nodata.
crs (int, str, rasterio.CRS, optional) – The CRS to use when creating the result. The default is to take the CRS from xdata, if present.

Returns

raster – The resulting raster Dataset with two data variables: “raster” and “mask”.

Return type

xarray.Dataset

raster_tools.empty_like(raster_template, bands=1, dtype=None, copy_mask=False)[source]#

Create a Raster filled with uninitialized data like a template raster.

Parameters

raster_template (Raster, str) – Template raster used to define rows, columns, crs, resolution, etc
bands (int, optional) – Number of bands desired for output. Default is 1.
dtype (data-type, optional) – Overrides the result dtype.
copy_mask (bool) – If True, the template raster’s mask is copied to the result raster. If bands differs from raster_template, the first band’s mask is copied bands times.

Returns

The resulting raster of uninitialized data.

Return type

raster_tools.full_like(raster_template, value, bands=1, dtype=None, copy_mask=False)[source]#

Create a Raster filled with a constant value like a template raster.

Parameters

raster_template (Raster, str) – Template raster used to define rows, columns, crs, resolution, etc
value (scalar) – Value to fill result with.
bands (int, optional) – Number of bands desired for output. Default is 1.
dtype (data-type, optional) – Overrides the result dtype.
copy_mask (bool) – If True, the template raster’s mask is copied to the result raster. If bands differs from raster_template, the first band’s mask is copied bands times.

Returns

The resulting raster of constant values.

Return type

raster_tools.get_raster(src, strict=True, null_to_nan=False)[source]#

raster_tools.list_layers(path)[source]#: List the layers in a vector source file.

raster_tools.ones_like(raster_template, bands=1, dtype=None, copy_mask=False)[source]#

Create a Raster filled with ones like a template raster.

Parameters

raster_template (Raster, str) – Template raster used to define rows, columns, crs, resolution, etc
bands (int, optional) – Number of bands desired for output. Default is 1.
dtype (data-type, optional) – Overrides the result dtype.
copy_mask (bool) – If True, the template raster’s mask is copied to the result raster. If bands differs from raster_template, the first band’s mask is copied bands times.

Returns

The resulting raster of ones.

Return type

raster_tools.open_dataset(path, crs=None, ignore_extra_dim_errors=False, xarray_kwargs=None)[source]#

Open a netCDF or GRIB dataset.

Parameters

path (str) – THe path to the netCDF or GRIB dataset file.
crs (str, rasterio.crs.CRS, optional) – A coordinate reference system definition to attach to the dataset. This can be an EPSG, PROJ, or WKT string. It can also be a rasterio.crs.CRS object. netCDF/GRIB files do not always encode a CRS. This option allows a CRS to be supplied, if known ahead of time. It can also be used to override the CRS encoded in the file.
ignore_extra_dim_errors (bool, optional) – If True, ignore dataset variables that cannot be mapped to a raster. An error is raised, otherwise. netCDF/GRIB files allow N-dimensional. Rasters only comprehend 2 or 3 dimensional data so it is not always possible to map a variable to a raster. The default is False.
xarray_kwargs (dict, optional) – Keyword arguments to supply to xarray.open_dataset when opening the file.

Raises

raster_tools.io.AffineEncodingError – Raised if the affine matrix is improperly encoded.
ra –

Returns

dataset – A dict of Raster objects. The keys are the variable names in the dataset file and the values are the corresponding variable data as a raster.

Return type

dict of Raster

raster_tools.open_vectors(path, layers=None)[source]#

Open a vector source.

This can be any GDAL/OGR compatible source.

Parameters

path (str, Path) – The vector source path.
layers (list of int, int, list of str, str, or None, optional) – The layer(s) to read from the source. This can be a single layer int or string, a list of layer ints/strings, or None. If None, all layers are read in. If int(s) are given, they are treated as 0-based layer indices.

Returns

If only a single layer was specified or found, a single Vector object is returned. Otherwise, a list of Vector objects is returned.

Return type

Vector, list of Vector

raster_tools.random_raster(raster_template, distribution='normal', bands=1, params=(1, 0.5), copy_mask=False)[source]#

Creates a Raster of random values based on the desired distribution.

This function uses dask.array.random to generate data. The default is a normal distribution with mean of 1 and standard deviation of 0.5.

Parameters

raster_template (Raster, str) – A template raster used to define rows, columns, crs, resolution, etc.
distribution (str, optional) –
Random distribution type. Default is ‘normal’. See params parameter below for passing additional distribution parameters. Valid values are:

’binomial’
Binomial distribution. Uses two additional parameters: (n, p).

’normal’
Normal distribution. Uses two additional parameters: (mean, std). This is the default.

’poisson’
Poisson distribution. Uses one additional parameter.

’uniform’
Uniform distribution in the half-open interval [0, 1). Uses no additional.

’weibull’
Weibull distribution. Uses one additional parameter.
bands (int, optional) – Number of bands needed desired. Default is 1.
params (list of scalars, optional) – Additional parameters for generating the distribution. For example distribution=’normal’ and params=(1, 0.5) would result in a normal distribution with mean of 1 and standard deviation of 0.5. Default is (1, 0.5).
copy_mask (bool) – If True, the template raster’s mask is copied to the result raster. If bands differs from raster_template, the first band’s mask is copied bands times.

Returns

The resulting raster of random values pulled from the distribution.

Return type

raster_tools.reclassify(raster, remapping, unmapped_to_null=False)[source]#

Reclassify the input raster values based on a mapping.

Parameters

raster (str, Raster) – The input raster to reclassify. Can be a path string or Raster object.
remapping (str, dict) – Can be either a dict or a path string. If a dict is provided, the keys will be reclassified to the corresponding values. It is possible to map values to the null value by providing None in the mapping. If a path string, it is treated as an ASCII remap file where each line looks like a:b and a and b are scalars. b can also be “NoData”. This indicates that a will be mapped to the null value. The output values of the mapping can cause type promotion. If the input raster has integer data and one of the outputs in the mapping is a float, the result will be a float raster.
unmapped_to_null (bool, optional) – If True, values not included in the mapping are instead mapped to the null value. Default is False.

Returns

The remapped raster.

Return type

raster_tools.remap_range(raster, mapping, inclusivity='left')[source]#

Remaps values based on a mapping or list of mappings.

Mappings are applied all at once with earlier mappings taking precedence.

Parameters

raster (Raster or str) – Path string or Raster to perform remap on.
mapping (3-tuple of scalars or list of 3-tuples of scalars) – A tuple or list of tuples containing (min, max, new_value) scalars. The mappiing(s) map values between the min and max to the new_value. If new_value is None, the matching pixels will be marked as null. If mapping is a list and there are mappings that conflict or overlap, earlier mappings take precedence. inclusivity determines which sides of the range are inclusive and exclusive.
inclusivity (str, optional) –
Determines whether to be inclusive or exclusive on either end of the range. Default is ‘left’.

’left’ [min, max)
Left (min) side is inclusive and right (max) side is exclusive.

’right’ (min, max]
Left (min) side is exclusive and right (max) side is inclusive.

’both’ [min, max]
Both sides are inclusive.

’none’ (min, max)
Both sides are exclusive.

Returns

The resulting Raster.

Return type

raster_tools.reproject(raster, crs_or_geobox=None, resample_method='nearest', resolution=None)[source]#

Reproject to a new projection or resolution.

This is a lazy operation.

Parameters

raster (str, Raster) – The raster to reproject.
crs_or_geobox (int, str, CRS, GeoBox, optional) – The target grid to reproject the raster to. This can be a projection string, EPSG code string or integer, a CRS object, or a GeoBox object. resolution can also be specified to change the output raster’s resolution in the new CRS. If crs_or_geobox is not provided, resolution must be specified.
resample_method (str, optional) –
The data resampling method to use. Null pixels are ignored for all methods. Some methods require specific versions of GDAL. These are noted below. Valid methods are:

’nearest’
Nearest neighbor resampling. This is the default.

’bilinear’
Bilinear resmapling.

’cubic’
Cubic resmapling.

’cubic_spline’
Cubic spline resmapling.

’lanczos’
Lanczos windowed sinc resmapling.

’average’
Average resampling, computes the weighted average of all contributing pixels.

’mode’
Mode resampling, selects the value which appears most often.

’max’
Maximum resampling. (GDAL 2.0+)

’min’
Minimum resampling. (GDAL 2.0+)

’med’
Median resampling. (GDAL 2.0+)

’q1’
Q1, first quartile resampling. (GDAL 2.0+)

’q3’
Q3, third quartile resampling. (GDAL 2.0+)

’sum’
Sum, compute the weighted sum. (GDAL 3.1+)

’rms’
RMS, root mean square/quadratic mean. (GDAL 3.3+)
resolution (int, float, tuple of int or float, optional) – The desired resolution of the reprojected raster. If crs_or_geobox is unspecified, this is used to reproject to the new resolution while maintaining the same CRS. One of crs_or_geobox or resolution must be provided. Both can also be provided.

Returns

The reprojected raster on the new grid.

Return type

raster_tools.zeros_like(raster_template, bands=1, dtype=None, copy_mask=False)[source]#

Create a Raster filled with zeros like a template raster.

Parameters

raster_template (Raster, str) – Template raster used to define rows, columns, crs, resolution, etc
bands (int, optional) – Number of bands desired for output. Default is 1.
dtype (data-type, optional) – Overrides the result dtype.
copy_mask (bool) – If True, the template raster’s mask is copied to the result raster. If bands differs from raster_template, the first band’s mask is copied bands times.

Returns

The resulting raster of zreos.

Return type