tobler.util

Package Contents

Functions

h3fy	Generate a hexgrid geodataframe that covers the face of a source geodataframe.
circumradius	Find the circumradius of an h3 hexagon at given resolution.
dot_density	Draw a sample of points inside each polygon/multipolygon row of a geodataframe, where sample size is one or more columns on the dataframe, optionally scaled by a constant. For example to create a proportional dot density map, pass a polygon geodataframe storing total population counts for mutually-exclusive groups.

API

tobler.util.h3fy(source, resolution=6, clip=False, buffer=False, return_geoms=True)

Generate a hexgrid geodataframe that covers the face of a source geodataframe.

Parameters

source : geopandas.GeoDataFrame GeoDataFrame to transform into a hexagonal grid resolution : int, optional (default is 6) resolution of output h3 hexgrid. See https://h3geo.org/docs/core-library/restable for more information clip : bool, optional (default is False) if True, hexagons are clipped by the boundary of the source gdf. Otherwise, heaxgons along the boundary will be left intact. buffer : bool, optional (default is False) if True, force hexagons to completely fill the interior of the source area. if False, (h3 default) may result in empty areas within the source area. return_geoms: bool, optional (default is True) whether to generate hexagon geometries as a geodataframe or simply return hex ids as a pandas.Series

Returns

pandas.Series or geopandas.GeoDataFrame if return_geoms is True, a geopandas.GeoDataFrame whose rows comprise a hexagonal h3 grid (indexed on h3 hex id). if return_geoms is False, a pandas.Series of h3 hexagon ids

tobler.util.circumradius(resolution)

Find the circumradius of an h3 hexagon at given resolution.

Parameters

resolution : int h3 grid resolution

Returns

circumradius : float circumradius in meters

tobler.util.dot_density(gdf, columns, scale=1.0, method='uniform', rng=None, method_kwargs=None)

Draw a sample of points inside each polygon/multipolygon row of a geodataframe, where sample size is one or more columns on the dataframe, optionally scaled by a constant. For example to create a proportional dot density map, pass a polygon geodataframe storing total population counts for mutually-exclusive groups.

Parameters

gdf : gpd.GeoDataFrame a geodataframe with columns of numeric data, a selection of which will be used to simulate a point-process within each geometry. The data in each column defines the number of points to simulate in each geometry columns : list-like, a list or array of columns in the dataframe holding the desired size of the set of points in each category. For example this would hold a set of mutually-exclusive racial groups, or employment industries, etc. industries scale : float, optional scalar coefficient used to increase or decrease the number of simulated points in each geometry. For example a number less than 1 is used to create a proportional dot-density map; a stochastic realization of the population in each polygon would use 1, resulting in the same number of points generated as the numeric value in the dataframe. By default 1 method : str, optional name of the distribution used to simulate point locations. The default is “uniform”, in which every location within a polygon has an equal chance of being chosen. Alternatively, other methods are implemented in the pointpats package, including {‘normal’, ‘cluster_normal’, ‘poisson’, ‘cluster_poisson’} rng : {None, int, array_like[ints], SeedSequence, BitGenerator, Generator}, optional A random generator or seed to initialize the numpy BitGenerator. If None, then fresh, unpredictable entropy will be pulled from the OS. method_kwargs : dict, optional additional keyword arguments passed to the pointpats.random generator.

Returns

GeoDataFrame a geodataframe with simulated points in the geometry column, with each row/point holding the index of its containing polygon, and the column to which the point belongs.

Raises

ValueError raises an error if the specified categories are not columns in the geodataframe ValueError raises an error of the categories argument is not list-like