reVX.setbacks.base.AbstractBaseSetbacks

class AbstractBaseSetbacks(excl_fpath, regulations, features, hsds=False, weights_calculation_upscale_factor=None)

Bases: AbstractBaseExclusionsMerger

Base class for Setbacks Calculators

Parameters:

• excl_fpath (str) – Path to .h5 file containing exclusion layers, will also be the location of any new setback layers

• regulations (~reVX.setbacks.regulations.SetbackRegulations) – A SetbackRegulations object used to extract setback distances.

• features (str) – Path to file containing features to compute exclusions from.

• hsds (bool, optional) – Boolean flag to use h5pyd to handle .h5 ‘files’ hosted on AWS behind HSDS. By default False.

• weights_calculation_upscale_factor (int, optional) – If this value is an int > 1, the output will be a layer with inclusion weight values instead of exclusion booleans. For example, a cell that was previously excluded with a a boolean mask (value of 1) may instead be converted to an inclusion weight value of 0.75, meaning that 75% of the area corresponding to that point should be included (i.e. the exclusion feature only intersected a small portion - 25% - of the cell). This percentage inclusion value is calculated by upscaling the output array using this input value, rasterizing the exclusion features onto it, and counting the number of resulting sub-cells excluded by the feature. For example, setting the value to 3 would split each output cell into nine sub-cells - 3 divisions in each dimension. After the feature is rasterized on this high-resolution sub-grid, the area of the non-excluded sub-cells is totaled and divided by the area of the original cell to obtain the final inclusion percentage. Therefore, a larger upscale factor results in more accurate percentage values. If None (or a value <= 1), this process is skipped and the output is a boolean exclusion mask. By default None.

Methods

compute_all_local_exclusions([max_workers])	Compute local exclusions for all counties either.
compute_exclusions([out_layer, out_tiff, ...])	Compute exclusions for all states either in serial or parallel.
compute_generic_exclusions([max_workers])	Compute generic setbacks.
compute_local_exclusions(regulation_value, ...)	Compute local features setbacks.
pre_process_regulations()	Reduce regulations to state corresponding to features.
run(excl_fpath, features_path, out_fn, ...)	Compute exclusions and write them to a geotiff.

Attributes

BUFFER_TYPE	Key in BUFFERS pointing to buffer to use.
FEATURE_FILTER_TYPE	Key in FEATURE_FILTERS pointing to feature filter to use.
FEATURE_SUBTYPES_TO_EXCLUDE	Feature subtype names to exclude from regulations file.
FEATURE_TYPES	Feature type names using in the regulations file.
NUM_FEATURES_PER_WORKER	Number of features each worker processes at one time.
description	Description to be added to excl H5.
exclusion_merge_func	Function to merge overlapping exclusion layers.
no_exclusions_array	Array representing no exclusions.
profile	Geotiff profile.
regulations_table	Regulations table.

property description

Description to be added to excl H5.

Type:

str

property no_exclusions_array

Array representing no exclusions.

Type:

np.array

property exclusion_merge_func

Function to merge overlapping exclusion layers.

Type:

callable

pre_process_regulations()

Reduce regulations to state corresponding to features.

static compute_local_exclusions(regulation_value, county, *args)

Compute local features setbacks.

This method will compute the setbacks using a county-specific regulations file that specifies either a static setback or a multiplier value that will be used along with the base setback distance to compute the setback.

Parameters:

• regulation_value (float | int) – Setback distance in meters.

• county (geopandas.GeoDataFrame) – Regulations for a single county.

• features_ids (iterable of ints) – List of tuple (or other iterable) of integer values corresponding to the ID of the features in the GeoPackage to load and compute exclusions for. Note that these ID values are the internal SQL table ID’s stored with the features, NOT the index of the features when loaded using geopandas.read_file().

• features_fp (path-like) – Path to the GeoPackage file containing the features to be loaded and used for the exclusion calculation.

• col (str) – Namer of the primary key column in the main SQL table of the GeoPackage. This should be the name of the column under which the features_ids can be found.

• crs (str) – String representation of the Coordinate Reference System of the output exclusions array.

• features_filter_type (str) – Key from the FEATURE_FILTERS dictionary that points to the feature filter function to use. This feature filter function filters the loaded features such that they are localized to the county bounds.

• buffer_type (str) – Key from the BUFFERS dictionary that points to the feature buffer function to use.

• rasterizer (Rasterizer) – Instance of Rasterizer class used to rasterize the buffered county features.

Returns:

• setbacks (ndarray) – Raster array of setbacks

• slices (2-tuple of slice) – X and Y slice objects defining where in the original array the exclusion data should go.

compute_generic_exclusions(max_workers=None)

Compute generic setbacks.

This method will compute the setbacks using a generic setback of base_setback_dist * multiplier.

Parameters:

max_workers (int, optional) – Number of workers to use for exclusions computation, if 1 run in serial, if > 1 run in parallel with that many workers, if None run in parallel on all available cores. By default None.

Returns:

setbacks (ndarray) – Raster array of setbacks

abstract property FEATURE_TYPES

Feature type names using in the regulations file.

Type:

set

abstract property FEATURE_SUBTYPES_TO_EXCLUDE

Feature subtype names to exclude from regulations file.

Type:

set

abstract property BUFFER_TYPE

Key in BUFFERS pointing to buffer to use.

Type:

str

abstract property FEATURE_FILTER_TYPE

Key in FEATURE_FILTERS pointing to feature filter to use.

Type:

str

abstract property NUM_FEATURES_PER_WORKER

Number of features each worker processes at one time.

Type:

int

compute_all_local_exclusions(max_workers=None)

Compute local exclusions for all counties either.

Parameters:

max_workers (int, optional) – Number of workers to use for exclusions computation, if 1 run in serial, if > 1 run in parallel with that many workers, if None run in parallel on all available cores. By default None.

Returns:

exclusions (ndarray) – Raster array of exclusions.

compute_exclusions(out_layer=None, out_tiff=None, replace=False, max_workers=None)

Compute exclusions for all states either in serial or parallel. Existing exclusions are computed if a regulations file was supplied during class initialization, otherwise generic exclusions are computed.

Parameters:

• out_layer (str, optional) – Name to save rasterized exclusions under in .h5 file. If None, exclusions will not be written to the .h5 file. By default None.

• out_tiff (str, optional) – Path to save geotiff containing rasterized exclusions. If None, exclusions will not be written to a geotiff file. By default None.

• replace (bool, optional) – Flag to replace geotiff if it already exists. By default False.

• max_workers (int, optional) – Number of workers to use for exclusion computation, if 1 run in serial, if > 1 run in parallel with that many workers, if None, run in parallel on all available cores. By default None.

Returns:

exclusions (ndarray) – Raster array of exclusions

property profile

Geotiff profile.

Type:

dict

property regulations_table

Regulations table.

Returns:

geopandas.GeoDataFrame | None

classmethod run(excl_fpath, features_path, out_fn, regulations, max_workers=None, replace=False, out_layers=None, hsds=False, **kwargs)

Compute exclusions and write them to a geotiff. If a regulations file is given, compute local exclusions, otherwise compute generic exclusions. If both are provided, generic and local exclusions are merged such that the local exclusions override the generic ones.

Parameters:

• excl_fpath (str) – Path to .h5 file containing exclusion layers, will also be the location of any new exclusion layers.

• features_path (str) – Path to file or directory feature shape files. This path can contain any pattern that can be used in the glob function. For example, /path/to/features/[A]* would match with all the features in the directory /path/to/features/ that start with “A”. This input can also be a directory, but that directory must ONLY contain feature files. If your feature files are mixed with other files or directories, use something like /path/to/features/*.geojson.

• out_fn (str) – Path to output geotiff where exclusion data should be stored.

• regulations (~reVX.utilities.AbstractBaseRegulations subclass) – A regulations object used to extract exclusion regulation distances.

• max_workers (int, optional) – Number of workers to use for exclusion computation, if 1 run in serial, if > 1 run in parallel with that many workers, if None, run in parallel on all available cores. By default None.

• replace (bool, optional) – Flag to replace geotiff if it already exists. By default False.

• out_layers (dict, optional) – Dictionary mapping feature file names (with extension) to names of layers under which exclusions should be saved in the excl_fpath .h5 file. If None or empty dictionary, no layers are saved to the h5 file. By default None.

• hsds (bool, optional) – Boolean flag to use h5pyd to handle .h5 ‘files’ hosted on AWS behind HSDS. By default False.

• **kwargs – Keyword args to exclusions calculator class.