exactextract package

Submodules

exactextract.exact_extract module

exactextract.exact_extract.exact_extract(rast, vec, ops, *, weights=None, include_cols=None, include_geom=False, strategy: str = 'feature-sequential', max_cells_in_memory: int = 30000000, grid_compat_tol: float = 0.001, output: str = 'geojson', output_options: Mapping | None = None, progress=False)[source]

Calculate zonal statistics.

Parameters:

  • rast – One or a list of RasterSource object(s) or filename(s) that can be opened by GDAL/rasterio/xarray.

  • vec – A FeatureSource or filename that can be opened by GDAL/fiona

  • ops – A list of Operation objects, or strings that can be used to construct them (e.g., "mean", "quantile(q=0.33)"). Check out Available operations for more information.

  • weights – An optional RasterSource or filename for weights to be used in weighted operations.

  • include_cols – An optional list of columns from the input features to be included into the output.

  • include_geom – Flag indicating whether the geometry should be copied from the input features into the output.

  • strategy –

    Specifies the strategy to use when processing features. Detailed performance notes are available in Performance - Processing strategies. Must be set to one of:

    • "feature-sequential" (the default): iterate over the features in vec, read the corresponding pixels from rast/weights, and compute the summary operations. This offers predictable memory consumption but may be inefficient if the order of features in vec causes the same, relatively large raster blocks to be read and decompressed many times.

    • "raster-sequential": iterate over chunks of pixels in rast, identify the intersecting features from vec, and compute statistics. This performs better than strategy="feature-sequential" in some cases, but comes at a cost of higher memory usage.

  • max_cells_in_memory – Indicates the maximum number of raster cells that should be loaded into memory at a given time.

  • grid_compat_tol – require value and weight grids to align within grid_compat_tol times the smaller of the two grid resolutions

  • output –

    An OutputWriter or one of the following strings:

    • ”geojson” (the default): return a list of GeoJSON-like features

    • ”pandas”: return a pandas.DataFrame or geopandas.GeoDataFrame,

      depending on the value of include_geom

    • ”gdal”: write results to disk using GDAL/OGR as they are written. This

      option (with strategy="feature-sequential") avoids the need to maintain results for all features in memory at a single time, which may be significant for operations with large result sizes such as cell_id, values, etc.

  • output_options – an optional dictionary of options passed to the writer.JSONWriter, writer.PandasWriter, or writer.GDALWriter.

  • progress – if True, a progress bar will be displayed. Alternatively, a function may be provided that will be called with the completion fraction and a status message.

exactextract.feature module

class exactextract.feature.FeatureSource[source]

Bases: FeatureSource

Source from which polygon features can be read.

Several implementations are included in exactextract:

class exactextract.feature.GDALFeatureSource(src)[source]

Bases: FeatureSource

A FeatureSource using the GDAL/OGR Python interface to provide features.

__init__(src)[source]
Parameters:

src – one of the following - string or Path to a file/datasource that can be opened with GDAL/OGR - a gdal.Dataset - an ogr.DataSource - an ogr.Layer If the file has more than one layer, e.g., a GeoPackage, an ogr.Layer must be provided directly.

count(self: exactextract._exactextract.FeatureSource) → object[source]
srs_wkt(self: exactextract._exactextract.FeatureSource) → object[source]
class exactextract.feature.GeoPandasFeatureSource(src)[source]

Bases: FeatureSource

A FeatureSource using GeoPandas GeoDataFrame to provide features.

count(self: exactextract._exactextract.FeatureSource) → object[source]
srs_wkt(self: exactextract._exactextract.FeatureSource) → object[source]
class exactextract.feature.JSONFeatureSource(src, *, srs_wkt=None)[source]

Bases: FeatureSource

A FeatureSource providing GeoJSON-like features.

count(self: exactextract._exactextract.FeatureSource) → object[source]
srs_wkt(self: exactextract._exactextract.FeatureSource) → object[source]
class exactextract.feature.QGISFeatureSource(src)[source]

Bases: FeatureSource

FeatureSource providing features from a QGIS vector layer.

count(self: exactextract._exactextract.FeatureSource) → object[source]
srs_wkt(self: exactextract._exactextract.FeatureSource) → object[source]

exactextract.operation module

class exactextract.operation.Operation(stat_name: str, field_name: str, raster: RasterSource, weights: RasterSource | None = None, options: Mapping | None = None)[source]

Bases: Operation

Summarize of pixel values using a built-in function

Defines a summary operation to be performed on pixel values intersecting a geometry. May return a scalar (e.g., weighted_mean), or a vector (e.g., coverage).

__init__(stat_name: str, field_name: str, raster: RasterSource, weights: RasterSource | None = None, options: Mapping | None = None)[source]
Parameters:

  • stat_name – Name of the stat. Refer to docs for options.

  • field_name – Name of the result field that is assigned by this Operation.

  • raster – Raster to compute over.

  • weights – Weight raster to use. Defaults to None.

  • options – Arguments used to control the behavior of an Operation, e.g. options={"q": 0.667} with stat_name = "quantile"

class exactextract.operation.PythonOperation(function: Callable, field_name: str, raster: RasterSource, weights: RasterSource | None)[source]

Bases: PythonOperation

Summarize of pixel values using a Python function

Defines a summary operation to be performed on pixel values intersecting a geometry.

__init__(function: Callable, field_name: str, raster: RasterSource, weights: RasterSource | None)[source]
Parameters:

  • function – Function accepting either two arguments (if weights is None), or three arguments. The function will be called with arrays of equal length containing: - pixel values from raster (masked array) - cell coverage fractions - pixel values from weights (masked array)

  • field_name – Name of the result field that is assigned by this Operation.

  • raster – Raster to compute over.

  • weights – Weight raster to use. Defaults to None.

exactextract.processor module

class exactextract.processor.FeatureSequentialProcessor(ds: FeatureSource, writer: Writer, op_list: List[Operation], include_cols: List[Operation] | None = None)[source]

Bases: FeatureSequentialProcessor

Binding class around exactextract FeatureSequentialProcessor

__init__(ds: FeatureSource, writer: Writer, op_list: List[Operation], include_cols: List[Operation] | None = None)[source]
Parameters:

  • ds (FeatureSource) – Dataset to use

  • writer (Writer) – Writer to use

  • op_list – List of Operations to perform

  • include_cols – List of columns to copy from input features

class exactextract.processor.RasterSequentialProcessor(ds: FeatureSource, writer: Writer, op_list: List[Operation], include_cols: List[Operation] | None = None)[source]

Bases: RasterSequentialProcessor

Binding class around exactextract RasterSequentialProcessor

__init__(ds: FeatureSource, writer: Writer, op_list: List[Operation], include_cols: List[Operation] | None = None)[source]
Parameters:

  • ds (FeatureSource) – Dataset to use

  • writer (Writer) – Writer to use

  • op_list (List[Operation]) – List of operations

  • include_cols – List of columns to copy from input features

exactextract.raster module

class exactextract.raster.GDALRasterSource(ds, band_idx: int = 1, *, name=None)[source]

Bases: RasterSource

RasterSource backed by GDAL

__init__(ds, band_idx: int = 1, *, name=None)[source]
Parameters:

  • ds – A gdal.Dataset or path from which one can be opened

  • band_idx – 1-based numerical index of band to read

  • name – source name, to be used in generating field names for results

extent(self: exactextract._exactextract.RasterSource) → object[source]
nodata_value(self: exactextract._exactextract.RasterSource) → object[source]
read_window(self: exactextract._exactextract.RasterSource, arg0: int, arg1: int, arg2: int, arg3: int) → numpy.ndarray[source]
res(self: exactextract._exactextract.RasterSource) → object[source]
srs_wkt(self: exactextract._exactextract.RasterSource) → object[source]
class exactextract.raster.NumPyRasterSource(mat, xmin=None, ymin=None, xmax=None, ymax=None, *, nodata=None, name=None, srs_wkt=None)[source]

Bases: RasterSource

RasterSource backed by a NumPy array

__init__(mat, xmin=None, ymin=None, xmax=None, ymax=None, *, nodata=None, name=None, srs_wkt=None)[source]

Create a RasterSource that references a NumPy array.

If spatial extent arguments are not provided, the extent will be assumed to be from (0,0) to (nx,ny).

Parameters:

  • mat – a two-dimensional NumPy array. Masked arrays are supported.

  • xmin – x coordinate of left edge

  • ymin – y coordinate of bottom edge

  • xmax – x coordinate of right edge

  • ymax – y coordinate of top edge

  • nodata – Optional value used to indicate missing data.

  • name – source name, to be used in generating field names for results

  • srs_wkt – WKT string indicating the spatial reference system.

extent(self: exactextract._exactextract.RasterSource) → object[source]
nodata_value(self: exactextract._exactextract.RasterSource) → object[source]
read_window(self: exactextract._exactextract.RasterSource, arg0: int, arg1: int, arg2: int, arg3: int) → numpy.ndarray[source]
res(self: exactextract._exactextract.RasterSource) → object[source]
srs_wkt(self: exactextract._exactextract.RasterSource) → object[source]
class exactextract.raster.RasterSource[source]

Bases: RasterSource

Source from which raster data can be read.

A RasterSource provides the ability to read subsets of a single band of raster data. Several implementations are included in exactextract:

class exactextract.raster.RasterioRasterSource(ds, band_idx=1, *, name=None)[source]

Bases: RasterSource

RasterSource backed by rasterio

__init__(ds, band_idx=1, *, name=None)[source]
Parameters:

  • ds – A rasterio.DatasetReader or path from which one can be opened

  • band_idx – 1-based numerical index of band to read

  • name – source name, to be used in generating field names for results

extent(self: exactextract._exactextract.RasterSource) → object[source]
nodata_value(self: exactextract._exactextract.RasterSource) → object[source]
read_window(self: exactextract._exactextract.RasterSource, arg0: int, arg1: int, arg2: int, arg3: int) → numpy.ndarray[source]
res(self: exactextract._exactextract.RasterSource) → object[source]
srs_wkt(self: exactextract._exactextract.RasterSource) → object[source]
class exactextract.raster.XArrayRasterSource(ds, band_idx=1, *, name=None)[source]

Bases: RasterSource

RasterSource backed by xarray

The rio-xarray extension is used to retrieve metadata such as the array extent, resolution, and spatial reference system.

__init__(ds, band_idx=1, *, name=None)[source]
Parameters:

  • ds – An xarray DataArray or a path from which one can be read.

  • band_idx – 1-based numerical index of band to read

  • name – source name, to be used in generating field names for results

extent(self: exactextract._exactextract.RasterSource) → object[source]
nodata_value(self: exactextract._exactextract.RasterSource) → object[source]
read_window(self: exactextract._exactextract.RasterSource, arg0: int, arg1: int, arg2: int, arg3: int) → numpy.ndarray[source]
res(self: exactextract._exactextract.RasterSource) → object[source]
srs_wkt(self: exactextract._exactextract.RasterSource) → object[source]

exactextract.writer module

class exactextract.writer.GDALWriter(dataset=None, *, filename=None, driver=None, layer_name='', srs_wkt=None)[source]

Bases: Writer

Writes results using GDAL/OGR

__init__(dataset=None, *, filename=None, driver=None, layer_name='', srs_wkt=None)[source]
Parameters:

  • dataset – a gdal.Dataset or ogr.DataSource to which results should be created in a new layer

  • filename – file to write results to, if dataset is None

  • driver – driver to use when creating filename

  • layer_name – name of new layer to create in output dataset

  • srs_wkt – spatial reference system to assign to output dataset. No coordinate transformation will be performed.

add_column(self: exactextract._exactextract.Writer, arg0: str) → None[source]
add_operation(self: exactextract._exactextract.Writer, arg0: exactextract._exactextract.Operation) → None[source]
features()[source]
write(self: exactextract._exactextract.Writer, arg0: exactextract._exactextract.FeatureBase) → None[source]
class exactextract.writer.JSONWriter(*, array_type: str = 'numpy', map_fields: Mapping[str, Tuple[str]] | None = None)[source]

Bases: Writer

Creates GeoJSON-like features

__init__(*, array_type: str = 'numpy', map_fields: Mapping[str, Tuple[str]] | None = None)[source]
Parameters:

  • array_type – type that should be used to represent array outputs. either “numpy” (default), “list”, or “set”

  • map_fields – an optional dictionary of fields to be created by interpreting one field as keys and another as values, in the format { dst_field : (src_keys, src_vals) }. for example, the fields “values” and “frac” would be combined into a field called “frac_map” using map_fields = {"frac_map": ("values", "frac")}.

add_operation(self: exactextract._exactextract.Writer, arg0: exactextract._exactextract.Operation) → None[source]
features()[source]
write(self: exactextract._exactextract.Writer, arg0: exactextract._exactextract.FeatureBase) → None[source]
class exactextract.writer.PandasWriter(*, srs_wkt=None)[source]

Bases: Writer

Creates a (Geo)Pandas DataFrame

add_column(self: exactextract._exactextract.Writer, arg0: str) → None[source]
add_geometry(self: exactextract._exactextract.Writer) → None[source]
add_operation(self: exactextract._exactextract.Writer, arg0: exactextract._exactextract.Operation) → None[source]
features()[source]
write(self: exactextract._exactextract.Writer, arg0: exactextract._exactextract.FeatureBase) → None[source]
class exactextract.writer.QGISWriter(*, srs_wkt=None)[source]

Bases: Writer

Creates QGSVectorLayer

add_column(self: exactextract._exactextract.Writer, arg0: str) → None[source]
add_operation(self: exactextract._exactextract.Writer, arg0: exactextract._exactextract.Operation) → None[source]
features()[source]
write(self: exactextract._exactextract.Writer, arg0: exactextract._exactextract.FeatureBase) → None[source]
class exactextract.writer.Writer[source]

Bases: Writer

Writes the results of summary operations to a desired format

Module contents

Python bindings for exactextract