API Reference

Submodules

gridfinder.gridfinder module

Implements Dijkstra’s algorithm on a cost-array 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) – Two-element 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) – Two-element 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’ on-grid point. Values of 0 imply that cell is part of an MV grid line.
Return type:

numpy array

gridfinder.post module

Post-processing 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.flip_arr_values(arr)[source]

Simple helper function used by accuracy()

gridfinder.post.raster_to_lines(guess_skel_in)[source]

Convert thinned raster to linestring geometry.

Parameters:guess_skel_in (path-like) – Output from thin().
Returns:guess_gdf – Converted to geometry.
Return type:GeoDataFrame
gridfinder.post.thin(guess_in)[source]

Use scikit-image skeletonize to ‘thin’ the guess raster.

Parameters:guess_in (path-like or 2D array) – Output from threshold().
Returns:
  • guess_skel (numpy array) – Thinned version.
  • affine (Affine) – Only if path-like supplied.
gridfinder.post.threshold(dists_in, cutoff=0.0)[source]

Convert distance array into binary array of connected locations.

Parameters:
  • dists_in (path-like 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.post.true_positives(guesses, truths)[source]

Calculate true positives, used by accuracy().

Parameters:
  • guesses (numpy array) – Output from model.
  • truths (numpy array) – Truth feature converted to array.
Returns:

tp – Ratio of true positives.
Return type:

float

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.filter_func(i, j)[source]

Function used in creating raster filter.

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 time-series 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 Fiona-readable 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