API Reference¶
Submodules¶
gridfinder.gridfinder module¶
Implements Dijkstra’s algorithm on a costarray to create an MST.
Functions:
 get_targets_costs
 estimate_mem_use
 optimise

gridfinder.gridfinder.
estimate_mem_use
(targets, costs)[source]¶ Estimate memory usage in GB, probably not very accurate.
Parameters:  targets (numpy array) – 2D array of targets.
 costs (numpy array) – 2D array of costs.
Returns: est_mem – Estimated memory requirement in GB.
Return type: float

gridfinder.gridfinder.
get_targets_costs
(targets_in, costs_in)[source]¶ Load the targets and costs arrays from the given file paths.
Parameters:  targets_in (str) – Path for targets raster.
 costs_in (str) – Path for costs raster.
Returns:  targets (numpy array) – 2D array of targets
 costs (numpy array) – 2D array of costs
 start (tuple) – Twoelement tuple with row, col of starting point.
 affine (affine.Affine) – Affine transformation for the rasters.

gridfinder.gridfinder.
optimise
(targets, costs, start, jupyter=False, animate=False, affine=None, animate_path=None, silent=False)[source]¶ Run the Dijkstra algorithm for the supplied arrays.
Parameters:  targets (numpy array) – 2D array of targets.
 costs (numpy array) – 2D array of costs.
 start (tuple) – Twoelement tuple with row, col of starting point.
 jupyter (boolean, optional (default False)) – Whether the code is being run from a Jupyter Notebook.
Returns: dist – 2D array with the distance (in cells) of each point from a ‘found’ ongrid point. Values of 0 imply that cell is part of an MV grid line.
Return type: numpy array
gridfinder.post module¶
Postprocessing for gridfinder package.
Functions:
 threshold
 thin
 raster_to_lines
 accuracy
 true_positives
 false_negatives
 flip_arr_values

gridfinder.post.
accuracy
(grid_in, guess_in, aoi_in, buffer_amount=0.01)[source]¶ Measure accuracy against a specified grid ‘truth’ file.
Parameters:  grid_in (str, Path) – Path to vector truth file.
 guess_in (str, Path) – Path to guess output from guess2geom.
 aoi_in (str, Path) – Path to AOI feature.
 buffer_amount (float, optional (default 0.01.)) – Leeway in decimal degrees in calculating equivalence. 0.01 DD equals approximately 1 mile at the equator.

gridfinder.post.
false_negatives
(guesses, truths)[source]¶ Calculate false negatives, used by accuracy().
Parameters:  guesses (numpy array) – Output from model.
 truths (numpy array) – Truth feature converted to array.
Returns: fn – Ratio of false negatives.
Return type: float

gridfinder.post.
raster_to_lines
(guess_skel_in)[source]¶ Convert thinned raster to linestring geometry.
Parameters: guess_skel_in (pathlike) – Output from thin(). Returns: guess_gdf – Converted to geometry. Return type: GeoDataFrame

gridfinder.post.
thin
(guess_in)[source]¶ Use scikitimage skeletonize to ‘thin’ the guess raster.
Parameters: guess_in (pathlike or 2D array) – Output from threshold(). Returns:  guess_skel (numpy array) – Thinned version.
 affine (Affine) – Only if pathlike supplied.

gridfinder.post.
threshold
(dists_in, cutoff=0.0)[source]¶ Convert distance array into binary array of connected locations.
Parameters:  dists_in (pathlike or numpy array) – 2D array output from gridfinder algorithm.
 cutoff (float, optional (default 0.5.)) – Cutoff value below which consider the cells to be grid.
Returns:  guess (numpy array) – Binary representation of input array.
 affine (affine.Affine) – Affine transformation for raster.
gridfinder.prepare module¶
Prepare input layers for gridfinder.
Functions:
 clip_rasters
 merge_rasters
 filter_func
 create_filter
 prepare_ntl
 drop_zero_pop
 prepare_roads

gridfinder.prepare.
clip_rasters
(folder_in, folder_out, aoi_in, debug=False)[source]¶ Read continental rasters one at a time, clip to AOI and save
Parameters:  folder_in (str, Path) – Path to directory containing rasters.
 folder_out (str, Path) – Path to directory to save clipped rasters.
 aoi_in (str, Path) – Path to an AOI file (readable by Fiona) to use for clipping.

gridfinder.prepare.
create_filter
()[source]¶ Create and return a numpy array filter to be applied to the raster.

gridfinder.prepare.
drop_zero_pop
(targets_in, pop_in, aoi)[source]¶ Drop electrified cells with no other evidence of human activity.
Parameters:  targets_in (str, Path) – Path to output from prepare_ntl()
 pop_in (str, Path) – Path to a population raster such as GHS or HRSL.
 aoi (str, Path or GeoDataFrame) – An AOI to use to clip the population raster.
Returns: targets – Array with zero population sites dropped.
Return type: numpy array

gridfinder.prepare.
merge_rasters
(folder, percentile=70)[source]¶ Merge a set of monthly rasters keeping the nth percentile value.
Used to remove transient features from timeseries data.
Parameters:  folder (str, Path) – Folder containing rasters to be merged.
 percentile (int, optional (default 70.)) – Percentile value to use when merging using np.nanpercentile. Lower values will result in lower values/brightness.
Returns:  raster_merged (numpy array) – The merged array.
 affine (affine.Affine) – The affine transformation for the merged raster.

gridfinder.prepare.
prepare_ntl
(ntl_in, aoi_in, ntl_filter=None, threshold=0.1, upsample_by=2)[source]¶ Convert the supplied NTL raster and output an array of electrified cells as targets for the algorithm.
Parameters:  ntl_in (str, Path) – Path to an NTL raster file.
 aoi_in (str, Path) – Path to a Fionareadable AOI file.
 ntl_filter (numpy array, optional (defaults to create_filter())) – The filter will be convolved over the raster.
 threshold (float, optional (default 0.1.)) – The threshold to apply after filtering, values above are considered electrified.
 upsample_by (int, optional (default 2.)) – The factor by which to upsample the input raster, applied to both axes (so a value of 2 results in a raster 4 times bigger). This is to allow the roads detail to be captured in higher resolution.
Returns:  ntl_thresh (numpy array) – Array of cells of value 0 (not electrified) or 1 (electrified).
 newaff (affine.Affine) – Affine raster transformation for the returned array.

gridfinder.prepare.
prepare_roads
(roads_in, aoi_in, ntl_in)[source]¶ Prepare a roads feature layer for use in algorithm.
Parameters:  roads_in (str, Path) – Path to a roads feature layer. This implementation is specific to OSM data and won’t assign proper weights to other data inputs.
 aoi_in (str, Path or GeoDataFrame) – AOI to clip roads.
 ntl_in (str, Path) – Path to a raster file, only used for correct shape and affine of roads raster.
Returns:  roads_raster (numpy array) – Roads as a raster array with the value being the cost of traversing.
 affine (affine.Affine) – Affine raster transformation for the new raster (same as ntl_in).
Module contents¶
gridfinder package contains the following modules:
 gridfinder.py : main implementation of Dijkstra’s algorithm
 prepare.py : transforming input data into the cost and targets arrays
 post.py : postprocess the algorithm output and check accuracy
 _util.py : helper functions used internally