urclib.urc_common

Misc functions and classes used in URC calculations.

Module Contents

Classes

RasterGroup

Container for storing Rasters which share the same dimensions and geotransformations.

Functions

list_featureclass_names(ds, wildcard[, first_char, ...])

Function that creates a list of all unique REE-Coal components in an ESRI GDB Feature Dataset, for use in use in

list_featureclasses(ds, wildcard)

Function that creates a list of all unique REE-Coal components in an ESRI GDB Feature Dataset, for use in use in

find_unique_components(gdb_ds, prefix)

Find the collections to be used in subsequent steps.

rasterize_components(src_rasters, gdb_ds, component_data)

Convert specified vector layers into raster datasets.

gen_domain_hitmaps(src_rasters)

Generate hitmaps for each domain component.

gen_domain_index_rasters(src_rasters, as_distance[, ...])

Generate unique rasters for each domain component.

find_domain_component_rasters(dom_dist_rasters, ...[, ...])

Find Domain/index overlap for individual components.

combine_domdist_rasters(found, domkey, comp_name, ...)

Combine individual domain indices rasters into new raster.

norm_multrasters(implicits, explicits[, cache_dir])

Normalize and multiply rasters; match using input raster names.

norm_lg_rasters(in_rasters[, cache_dir])

Normalize LG rasters.

raster_copy(id, in_ds[, drvr_name, prefix, suffix, opts])

Create a copy of a Raster

raster_distance(id, in_ds[, drvr_name, prefix, ...])

Compute distances for values in raster.

normalize_raster(in_rast[, flip])

Normalize the values in a Raster.

mult_band_data(data1, data2, id, nd1, nd2, geotrans, ...)

Multiply two bands of raster datat together.

build_pandas_dataframe(index_rasters, data_rasters[, ...])

Convert a RasterGroup to a pandas DataFrame.

dataframe_to_rastergroup(df, index_raster[, cols, gdtype])

Convert a pandas DataFrame into a series of rasters.
class urclib.urc_common.RasterGroup(**kwargs)

Bases: object

Container for storing Rasters which share the same dimensions and geotransformations.

Keyword Arguments:

kwargs – Any provide named arguments are expected to have a gdal.Dataset as a value, and the key will be reused as the reference id.

property raster_names

Alphabetically sorted list of raster ids/names.

Type:

list

property extents

The shared real-world extents in (x-min,x-max,y-min,y-max) order.

Type:

tuple

property geotransform

The shared geotransformation matrix for all included rasters.

Type:

tuple

property spatialref

The spatial reference used by the internal test raster, or None if group is empty.

Type:

osr.SpatialReference

property raster_x_size

The width (in pixels) of all included rasters.

Type:

int

property raster_y_size

The height (in pixels) of all included rasters.

Type:

int

property empty_raster_names

Rasters in group which contain only nodata.

Type:

list

__contains__(item)
__repr__()

Return repr(self).

__getitem__(item)
__setitem__(key, value)
__delitem__(key)
__len__()
items()

Equivalent to dict.items.

Returns:

A key,value generator.

Return type:

dict_items

values()

Equivalent to dict.values.

Returns:

A value generator.

Return type:

dict_values

keys()

Equivalent to dict.keys.

Returns:

A value generator.

Return type:

dict_keys

add(id, path_or_ds)

Add a new raster to the dataset.

Parameters:

  • id (str) – The dlg_label to apply to the raster dataset.

  • path_or_ds (str or gdal.Dataset) – Either a path to a raster, or a loaded raster Dataset.

Raises:

  • KeyError – If a raster with the value id already exists in the group.

  • ValueError – If there are existing rasters in the collection and the new raster does not match the dimensions or geotransformation of the existing rasters.

generate_hitmap(keys=None)

Generate a map of presence/absence of data for each raster in group.

Parameters:

keys (list,optional) – A list of rasters to include in hitmap generation. If None, include all rasters.

Returns:

A list of keys of the rasters included in the analysis, in the order of their inclusion in the

hitmap, followed by a 3d array representing the hitmap of all included rasters. Dimensions are (raster,y,x).

Return type:

tuple

generate_nodata_mask()

Generate a noData mask for the combination of all included rasters.

Returns:

2D array of an included raster dimension, denoting which cells are valid (1) or nodata (0).

Return type:

numpy.ndarray

copy_rasters(driver, path, suffix='', opts=None)

Copy all the rasters in this group using the provided information.

Parameters:

  • driver (str or gdal.Driver) – Either the name of the driver to use for copying, or the Driver object itself.

  • path (str) – Path to parent directory to write out each raster; acts as label with drivers that don’t require paths (such as “MEM”).

  • suffix (str,optional) – The tail to apply to the filepath; typically this is a file extension. Can be omitted.

  • opts (list,optional) – Optional list of strings to pass to the file driver during file creation.

Returns:

List of newly created gdal.Datasets. This return value can be ignored if just concerned with

performing a write-only operation.

Return type:

list

update(other)

Add content from another RasterGroup. This effectively calls add() on all contents of other.

Parameters:

other (RasterGroup) – The other raster to extract values from.

Raises:

ValueError – If other is not of type RasterGroup.

clip_with_raster(clip_raster)

Clip all rasters in group using another raster.

Parameters:

clip_raster (gdal.Dataset) – The raster to use in clipping operation.

calc_max_values(prefix=None, out_nodata=-9999)

Find the max value for each pixel location across all rasters.

Parameters:

  • prefix (str,optional) – Only include rasters whose keys begin with this. If None (default), include all rasters in calculation.

  • out_nodata (int) – The value to use to represent nodata.

Returns:

A 2d array of max values, with nodata values marked with the value provided by outNoData.

Return type:

numpy.ndarray

_check_consistancy(ds)

…

_get_test_raster()

Retrieve a raster to use for testing for conformance.

Returns:

raster to use for testing, or None if RasterGroup is empty.

Return type:

gdal.Dataset

urclib.urc_common.list_featureclass_names(ds, wildcard, first_char=0, last_char=sys.maxsize)
Function that creates a list of all unique REE-Coal components in an ESRI GDB Feature Dataset, for use in use in

calculating PE score from DA and DS databases.

Parameters:

  • ds (osgeo.gdal.Dataset) – The dataset to query.

  • wildcard (str) – Criteria used to limit the results returned.

  • first_char (int,optional) – Index of first character to include in the filename. Defaults to 0.

  • last_char (int,optional) – Index of last character to include in the filename. Defaults to position of last character in string.

Returns:

sorted, non-repeating iterable sequence of layer names based on the WildCard criteria

Return type:

list

urclib.urc_common.list_featureclasses(ds, wildcard)
Function that creates a list of all unique REE-Coal components in an ESRI GDB Feature Dataset, for use in use in

calculating PE score from DA and DS databases.

Parameters:

  • ds (osgeo.gdal.Dataset) – The dataset to query.

  • wildcard (str) – Criteria used to limit the results returned.

Returns:

sorted, non-repeating iterable sequence of Layers based on the WildCard criteria

Return type:

list

urclib.urc_common.find_unique_components(gdb_ds, prefix)

Find the collections to be used in subsequent steps.

Parameters:

  • gdb_ds (osgeo.gdal.Dataset) – Dataset containing features to parse. Expected to originate from a file geodatabase (.gdb) file.

  • prefix (str) – The prefix used to filter returned layers.

Returns:

key is layer name, value is list of layers.

Return type:

dict

urclib.urc_common.rasterize_components(src_rasters, gdb_ds, component_data, cache_dir=None, mask=None)

Convert specified vector layers into raster datasets.

Parameters:

  • src_rasters (RasterGroup) – The RasterGroup container to use as frame of reference for conversion.

  • gdb_ds (gdal.Dataset) – Source of vector layers to convert.

  • component_data (dict) – Id and vector components to Raster.

  • cache_dir (str,optional) – If present, save generated rasters to the specified folder.

  • mask (numpy.ndarray,optional) – If present, apply mask to newly created rasters.

Returns:

collection of newly rasterized components.

Return type:

RasterGroup

urclib.urc_common.gen_domain_hitmaps(src_rasters)

Generate hitmaps for each domain component.

Parameters:

src_rasters (RasterGroup) – The index rasters to use for generating the hitmaps.

Returns:

Collection of index hitmaps for ld, ud, and sd domains, along with which values were hit.

Return type:

dict

urclib.urc_common.gen_domain_index_rasters(src_rasters, as_distance, cache_dir=None, mask=None)

Generate unique rasters for each domain component.

Parameters:

  • src_rasters (RasterGroup) – The rasters to use for domain index generation.

  • as_distance (bool) – If true, creates domain as a distance from index raster; otherwise, creates presence/absence raster.

  • cache_dir (str,optional) – If present, save generated rasters to the specified folder.

  • mask (numpy.ndarray,optional) – If present, apply mask to newly created rasters.

Returns:

RasterGroup of newly created rasters, and the associated list of hit values.

Return type:

tuple

urclib.urc_common.find_domain_component_rasters(dom_dist_rasters, hit_maps, test_rasters, cache_dir=None)

Find Domain/index overlap for individual components.

Parameters:

  • dom_dist_rasters (RasterGroup) – Rasters containing domain distances.

  • hit_maps (dict) – key is name of raster in test_rasters, value is numpy.ndarray as hit map for associated index.

  • test_rasters (RasterGroup) – The domain indices rasters to use for domain expansion.

  • cache_dir (str,optional) – If present, save generated rasters to the specified folder.

Returns:

The newly created domain-component distance rasters.

Return type:

RasterGroup

urclib.urc_common.combine_domdist_rasters(found, domkey, comp_name, domdist_rasters, combo_rasters, prefix='', suffix='', drvr_name='mem', opts=None)

Combine individual domain indices rasters into new raster.

Parameters:

  • found (set) – Collection of domain indices triggered in hitmap.

  • domkey (str) – The domain key (ie ‘ld’,’ud’,or ‘sd’).

  • comp_name (str) – Label or path to apply to newly created raster

  • domdist_rasters (RasterGroup) – Collection of domain distance rasters.

  • combo_rasters (RasterGroup) – The collection to add the newly generated raster to.

  • prefix (str,optional) – Prefix to apply to comp_name for gdal.Dataset dlg_label; this could be a path to a directory if raster is being saved to disk.

  • suffix (str,optional) – Suffix to apply to comp_name for gdal.Dataset dlg_label; this could be the file extension if raster is being saved to disk.

  • drvr_name (str,optional) – Name of driver to use to create new raster; defaults to “MEM”.

  • opts (list,optional) – String flags to forward to GDAL drivers, if any.

urclib.urc_common.norm_multrasters(implicits, explicits, cache_dir=None)

Normalize and multiply rasters; match using input raster names.

Parameters:

  • implicits (RasterGroup) – Rasters containing implicit data.

  • explicits (RasterGroup) – Rasters containing explicit data.

  • cache_dir (str,optional) – If present, save generated rasters to the specified folder.

Returns:

The products of normalization and multiplication.

Return type:

RasterGroup

urclib.urc_common.norm_lg_rasters(in_rasters, cache_dir=None)

Normalize LG rasters.

Parameters:

  • in_rasters (RasterGroup) – The rasters to be transformed.

  • cache_dir (str,optional) – A directory to write the normalized rasters to. If None, keep rasters in memory only.

Returns:

The normalized contents of in_rasters.

Return type:

RasterGroup

urclib.urc_common.raster_copy(id, in_ds, drvr_name='mem', prefix='', suffix='', opts=None)

Create a copy of a Raster

Parameters:

  • id (str) – The id of the new index raster.

  • in_ds (gdal.Dataset) – The raster dataset to copy.

  • drvr_name (str,optional) – Name of driver to use to create new raster; defaults to “MEM”.

  • prefix (str,optional) – Prefix to apply to comp_name for gdal.Dataset dlg_label; this could be a path to a directory if raster is being saved to disk.

  • suffix (str,optional) – Suffix to apply to comp_name for gdal.Dataset dlg_label; this could be the file extension if raster is being saved to disk.

  • opts (list,optional) – Optional list of strings to pass to the file driver during file creation.

Returns:

The copy of the dataset.

Return type:

gdal.Dataset

urclib.urc_common.raster_distance(id, in_ds, drvr_name='mem', prefix='', suffix='', mask=None, dist_thresh=None, gdtype=gdal.GDT_Float32, opts=None)

Compute distances for values in raster.

Parameters:

  • id (str) – The id for the newly created Raster.

  • in_ds (gdal.Dataset) – The Raster to calculate distances for.

  • drvr_name (str,optional) – Name of driver to use to create new raster; defaults to “MEM”.

  • prefix (str,optional) – Prefix to apply to comp_name for gdal.Dataset dlg_label; this could be a path to a directory if raster is being saved to disk.

  • suffix (str,optional) – Suffix to apply to comp_name for gdal.Dataset dlg_label; this could be the file extension if raster is being saved to disk.

  • mask (numpy.ndarray,optional) – No-data mask to apply to generated distance raster.

  • dist_thresh (Numeric,optional) – Optional threshold to apply to distance calculation.

  • gdtype (int,optional) – Flag indicating the data type for the raster; default is “gdal.GDT_Float32”.

  • opts (list,optional) – Optional list of strings to pass to the file driver during file creation.

Returns:

The newly generated distance Raster.

Return type:

gdal.Dataset

urclib.urc_common.normalize_raster(in_rast, flip=True)

Normalize the values in a Raster.

Parameters:

  • in_rast (gdal.Dataset) – The Raster to normalize.

  • flip (bool,optional) – If True (the default), invert the normalized values; transform every value n to 1-n.

Returns:

Returns a numpy.ndarray that represents the normalized raster data, and the value representing no-data.

Return type:

tuple

urclib.urc_common.mult_band_data(data1, data2, id, nd1, nd2, geotrans, spatref, drvr_name='mem', opts=None)

Multiply two bands of raster datat together.

Parameters:

  • data1 (numpy.ndarray) – The first raster band to multiply.

  • data2 (numpy.ndarray) – The second raster band to multiply.

  • id (str) – The id to apply to the new raster.

  • nd1 (float) – The no-data value for the first raster band.

  • nd2 (float) – The no-data value for the second raster band.

  • geotrans (tuple) – Matrix of float values describing geographic transformation.

  • spatref (osr.SpatialReference) – The Spatial Reference System to provide for the new Raster.

  • drvr_name (str,optional) – Name of driver to use to create new raster; defaults to “MEM”.

  • opts (list,optional) – Optional list of strings to pass to the file driver during file creation.

Returns:

The raster representing the product of the two raster bands.

Return type:

ds.Dataset

urclib.urc_common.build_pandas_dataframe(index_rasters, data_rasters, index_id='lg', index_df_name='LG_index')

Convert a RasterGroup to a pandas DataFrame.

Parameters:

  • index_rasters (RasterGroup) – RasterGroup which contains the index layer specified by index_id.

  • data_rasters (RasterGroup) – The data to convert into a pandas DataFrame.

  • index_id (str,optional) – The index_raster to use to map data to rows; defaults to ‘lg’.

  • index_df_name (str,optional) – The name of the index column in the DataFrame; defaults to ‘LG_index’.

Returns:

The newly created dataframe.

Return type:

pandas.DataFrame

urclib.urc_common.dataframe_to_rastergroup(df, index_raster, cols=None, gdtype=gdal.GDT_Float32)

Convert a pandas DataFrame into a series of rasters.

Parameters:

  • df (pandas.DataFrame) – The DataFrame containing the columns to convert.

  • index_raster (gdal.Dataset or str) – The raster (or path to raster) to use as the indexing reference, and as a template to generated rasters.

  • cols (list,optional) – A list of columns to rasterize. If None (the default), rasterize all columns.

  • gdtype (int,optional) – Flag indicating the data type for the raster; default is “gdal.GDT_Float32”.

Returns:

The newly generated Rasters.

Return type:

RasterGroup