awherepy.grids

A module to create and work with aWhere grids.

awherepy.grids.create_grid(study_area_path, buffer_distance, cell_size=0.08)[source]

Creates an aWhere-sized grid (0.08 x 0.08 degree, 5 arc-minute x 5 arc-minute grid) fit to a polygon.

Parameters

  • study_area_path (str) – Path the polygon shapefile boundary.

  • buffer_distance (int or float) – Buffer size in degrees (WGS 84 CRS).

  • cell_size (int or float) – Grid size (x and y dimension) in degrees (WGS 84 CRS).

Returns

  • study_area_grid_4326 (geopandas GeoDataFrame) – Grid dataframe shaped to the polygon boundary.

  • study_area_4326 (geopandas GeoDataFrame) – Study area boundary projected to WGS 84, EPSG 4326.

Example

>>> # Import packages
>>> import os
>>> import awherepy.grids as awg
>>> # Define path to shapefile boundary
>>> vt_bound_path = os.path.join(
...     working_directory, 'shapefiles', 'vermont_state_boundary.shp')
>>> # Create aWhere grid
>>> vt_grid, vt_bound_4326 = awg.create_grid(
...     vt_bound_path, buffer_distance=0.12)
>>> # Plot aWhere grid
>>> vt_grid.plot(facecolor="none", edgecolor="#984ea3", linewidth=1.5)
awherepy.grids.export_grid(awhere_grid, output_path)[source]

Exports an aWhere grid to the specified file format.

Functionality currently supports writing to comma-separated values (.CSV), shapefile (.SHP), geojson (.GEOJSON), geopackage (.GPKG).

Parameters

  • awhere_grid (geopandas geodataframe) – Geodataframe containing a grid of aWhere-sized cells.

  • output_path (str) – Path to write the output file (including file name and extension).

Returns

output_message – Message indicating successful export (and path) or error.

Return type

str

Example

>>> # Import packages
>>> import os
>>> import awherepy.grids as awg
>>> # Define path to shapefile boundary
>>> vt_bound_path = os.path.join(
...     working_directory, 'shapefiles',
...     vermont_state_boundary.shp')
>>> # Create aWhere grid
>>> vt_grid, vt_bound_4326 = awg.create_grid(
...     vt_bound_path, buffer_distance=0.12)
>>> # Define export path
>>> # export_path = os.path.join(
...     working_directory, '03-processed-data',
...     'vt_grid.csv')
>>> # Export grid to CSV
>>> csv_export = awg.export_grid(vt_grid, export_path)
vt_grid.csv
awherepy.grids.extract_centroids(grid)[source]

Extracts the longitude and latitude centroids from a grid of polygons.

Parameters

grid (geopandas GeoDataFrame) – Grid dataframe with polygon geometry.

Returns

centroid_list – List containing (longitude, latitude) tuples.

Return type

list (of tuples)

Example

>>> # Extract centroids
>>> vt_grid_centroids = awg.extract_centroids(vt_grid)
>>> # Show number of centroids/grid cells
>>> len(vt_grid_centroids)
533
>>> # Show first centroid
>>> vt_grid_centroids[0]
(-73.43784136769847, 43.527012318617274)
awherepy.grids.plot_grid(awhere_grid, study_area, plot_title='aWhere Grid', data_source=None)[source]

Plots a administrative boundary with the mathching awhere grid.

Parameters

  • awhere_grid (geopandas geodataframe) – Geodataframe containing a grid of aWhere-sized cells.

  • study_area (geopandas geodataframe) – Geodataframe containing the study area boundary polygon.

  • plot_title (str) – Title for the plot. Default value is ‘aWhere Grid’.

Returns

fig: matplotlib.figure.Figure object

The figure object associated with the histogram.

ax: matplotlib.axes._subplots.AxesSubplot objects

The axes object associated with the histogram.

Return type

tuple

Example

>>> # Import packages
>>> import os
>>> import awherepy.grids as awg
>>> # Define path to shapefile boundary
>>> vt_bound_path = os.path.join(
...     working_directory, 'shapefiles', vermont_state_boundary.shp')
>>> # Create aWhere grid
>>> vt_grid, vt_bound_4326 = create_grid(
...     vt_bound_path, buffer_distance=0.12)
>>> # Plot grid and boundary
>>> fig, ax = plot_grid(vt_grid, vt_bound_4326)
awherepy.grids.rasterize(awhere_grid, raster_path, zonal_stats='count sum')[source]

Rasterizes values from a GeoTiff (or other georeferenced raster) to the aWhere grid (9x9 km).

Aggregates the sum by default.

Parameters

  • awhere_grid (geopandas geodataframe) – Geodataframe containing a grid of aWhere-sized cells, sized to fit a shapefile boundary.

  • raster_path (str) – Path to the data the will be rasterized.

  • zonal_stats (space-delimited str (optional)) – Zonal statistics to calculate. Default value is ‘count sum’.

Returns

awhere_grid_rasterized – Input geodataframe with the rasterized values and grid centroids added.

Return type

geopandas geodataframe

Example

>>> # Import packages
>>> import os
>>> import awherepy.grids as awg
>>> # Define path to shapefile boundary
>>> vt_bound_path = os.path.join(
...     working_directory, 'shapefiles',
...     vermont_state_boundary.shp')
>>> # Create aWhere grid for Vermont
>>> vt_grid, vt_bound_4326 = awg.create_grid(
...     vt_bound_path, buffer_distance=0.12)
>>> # Define path to Vermont 2020 population per pixel
>>> vt_pop_path = os.path.join(
...     working_directory, 'geotiffs',
...     'vt_ppp_2020.tif')
>>> # Rasterize pop data (100x100 m) to aWhere grid (9x9 km)
>>> vt_pop_rasterized = awg.rasterize(vt_grid, vt_pop_path)
>>> # Display single entry in resulting geodataframe
>>> vt_pop_rasterized.loc[1]
geometry    POLYGON ((-73.4778398510704 43.56701241643375,...
centroid         POINT (-73.43783985107041 43.60701241643375)
count                                                    2759
sum                                                   12.7015
Name: 1, dtype: object