tobler.dasymetric.masked_dot_density

tobler.dasymetric.masked_dot_density(source_df, raster, pixel_values, scale=1, method='uniform', columns=None, rng=None, method_kwargs=None, nodata=255, n_jobs=-1)

Simulate a point pattern process within each source polygon while using raster data to mask out uninhabited areas of the each geometry.

Parameters:

source_dfgeopandas.GeoDataFrame

source data to be converted to another geometric representation.

rasterstr

path to raster file that contains ancillary data

pixel_valueslist of ints

list of pixel values that should be considered part of the mask. For example if using data from NLCD Land Cover Database <https://www.mrlc.gov/data>, a common input might be [21,22,23,24], which match the “developed” land types in that dataset

scaleint, 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

methodstr, 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

columnslist-like, optional

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

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_kwargsdict, optional

additional keyword arguments passed to the pointpats.random generator.

nodataint

value in raster that indicates null or missing values. Default is 255

n_jobsint

[Optional. Default=-1] Number of processes to run in parallel to generate the area allocation. If -1, this is set to the number of CPUs available.

Returns:

GeoDataFrame

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