Generation Functions

Generation functions create distributions of points or cells for spatial analysis.

Points

Fibonacci Lattice

tatc.generation.generate_points_fibonacci_lattice(distance: float | None = None, elevation: float = 0, mask: Polygon | MultiPolygon | None = None, *, count: int | None = None, rotate: bool = False, seed: int | Generator | None = None) → GeoDataFrame[source]

Generates geodetic points following a Fibonacci lattice, of points about a distance apart, or of a count of points.

See: Gonzalez (2010). “Measurement of areas on a sphere using Fibonacci and latitude-longitude lattices”, Mathematical Geosciences 42(49). doi: 10.1007/s11004-009-9257-x

Note: this implementation differs slightly from Gonzalez. Gonzalez requires an odd number of points. This implementation allows any number of points. In agreement with Gonzalez, no points are placed at poles.

A lattice in a random orientation (rotate, drawn from seed) is a stratified sample of the sphere (randomized quasi-Monte Carlo). Each point is distributed uniformly by surface area, as are those of generate_points_random, but the points cover the sphere evenly rather than clustering by chance, so that statistics of samples of points (such as the share of points sampled sufficiently, over the replicates of a trade study) vary less between samples of the same size (with about 1.5 to 4 times less variance for the shares of points that constellations sample):

points = generate_points_fibonacci_lattice(count=100, rotate=True, seed=7)

With a mask, a lattice of a count of points covers the sphere with about count points inside the mask (from the mask’s share of the sphere’s area), and the number of points inside varies slightly with the orientation of a rotated lattice.

Parameters:
  • distance (float | None) – The typical surface distance (meters) between points, or None for a count of points.

  • elevation (float) – The elevation (meters) above the datum in the WGS 84 coordinate system.

  • mask (shapely.geometry.Polygon | shapely.geometry.MultiPolygon | None) – An optional mask to constrain points using WGS84 (EPSG:4326) geodetic coordinates in a Polygon or MultiPolygon.

  • count (int | None) – The number of points (about, with a mask), in place of a distance.

  • rotate (bool) – Whether to rotate the lattice into a random orientation, uniform over the rotations of the sphere.

  • seed (int | numpy.random.Generator | None) – An optional seed (or generator) of the random orientation.

Returns:

the data frame of generated points, each

identified by the hash of its geometry (point_id, see tatc.utils.geometry.hash_geometry)

Return type:

geopandas.GeoDataFrame

Raises:

ValueError – if neither or both of distance and count are given, count is negative, a seed is given without rotate, or the mask is not valid.

Equally Spaced

tatc.generation.generate_points_uniform_spacing(distance: float, elevation: float = 0, mask: Polygon | MultiPolygon | None = None) → GeoDataFrame[source]

Generates geodetic points at the centroid of regular equally spaced grid cells.

See: Putman and Lin (2007). “Finite-volume transport on various cubed-sphere grids”, Journal of Computational Physics, 227(1). doi: 10.1016/j.jcp.2007.07.022

Parameters:
  • distance (float) – The typical surface distance (meters) between points.

  • elevation (float) – The elevation (meters) above the datum in the WGS 84 coordinate system.

  • mask (shapely.geometry.Polygon | shapely.geometry.MultiPolygon | None) – An optional mask to constrain points using WGS84 (EPSG:4326) geodetic coordinates in a Polygon or MultiPolygon.

Returns:

the data frame of generated points, each

identified by the hash of its geometry (point_id, see tatc.utils.geometry.hash_geometry)

Return type:

geopandas.GeoDataFrame

Equal Angular Distance

tatc.generation.generate_points_uniform_angular_distance(theta_longitude: float, theta_latitude: float, elevation: float = 0, mask: Polygon | MultiPolygon | None = None) → GeoDataFrame[source]

Generates geodetic cells following regular equally spaced grid.

See: Putman and Lin (2007). “Finite-volume transport on various cubed-sphere grids”, Journal of Computational Physics, 227(1). doi: 10.1016/j.jcp.2007.07.022

Parameters:
  • theta_longitude (float) – The angular difference in longitude (degrees) between points.

  • theta_latitude (float) – The angular difference in latitude (degrees) between points.

  • elevation (float) – The elevation (meters) above the datum in the WGS 84 coordinate system.

  • mask (shapely.geometry.Polygon | shapely.geometry.MultiPolygon | None) – An optional mask to constrain points using WGS84 (EPSG:4326) geodetic coordinates in a Polygon or MultiPolygon.

Returns:

the data frame of generated points, each

identified by the hash of its geometry (point_id, see tatc.utils.geometry.hash_geometry)

Return type:

geopandas.GeoDataFrame

Random

tatc.generation.generate_points_random(count: int, elevation: float = 0, mask: Polygon | MultiPolygon | None = None, weights: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, weights_bounds: tuple[float, float, float, float] = (-180, -90, 180, 90), density: bool = False, seed: int | Generator | None = None) → GeoDataFrame[source]

Generates geodetic points at random, optionally weighted by a raster (for example, of population). Without weights, points are distributed uniformly by surface area (assuming a sphere). With weights, a raster cell is chosen with probability proportional to its weight (or, for density, its weight times its area) and a point is placed uniformly by area within it. Points outside the mask are discarded and redrawn, so the distribution within the mask is unchanged.

Weights can be read from a GeoTIFF with tatc.preprocess.read_raster_weights.

Parameters:
  • count (int) – The number of points to generate.

  • elevation (float) – The elevation (meters) above the datum in the WGS 84 coordinate system.

  • mask (shapely.geometry.Polygon | shapely.geometry.MultiPolygon | None) – An optional mask to constrain points using WGS84 (EPSG:4326) geodetic coordinates in a Polygon or MultiPolygon.

  • weights (numpy.typing.ArrayLike | None) – An optional two-dimensional raster of non-negative weights in WGS84 (EPSG:4326) geodetic coordinates, with rows from north to south and columns from west to east (as in a GeoTIFF). Not-a-number values have zero weight.

  • weights_bounds (tuple[float, float, float, float]) – The bounds (west, south, east, north) of the weights raster in degrees.

  • density (bool) – True, if weights are per unit area (for example, people per square kilometer) rather than totals per cell (for example, people).

  • seed (int | numpy.random.Generator | None) – An optional seed (or generator) for reproducible random numbers.

Returns:

the data frame of generated points, each

identified by the hash of its geometry (point_id, see tatc.utils.geometry.hash_geometry)

Return type:

geopandas.GeoDataFrame

Weights for random points can be read from a GeoTIFF raster with tatc.preprocess.read_raster_weights() (requires the optional preprocess dependencies, pip install tatc[preprocess]).

Rotated Lattice

Cells

Equally Spaced

tatc.generation.generate_cells_uniform_spacing(distance: float, elevation: float = 0, mask: Polygon | MultiPolygon | None = None, strips: str | None = None) → GeoDataFrame[source]

Generates geodetic polygons over a regular equally spaced grid.

See: Putman and Lin (2007). “Finite-volume transport on various cubed-sphere grids”, Journal of Computational Physics, 227(1). doi: 10.1016/j.jcp.2007.07.022

Parameters:
  • distance (float) – The typical surface distance (meters) between points.

  • elevation (float) – The elevation (meters) above the datum in the WGS 84 coordinate system.

  • mask (shapely.geometry.Polygon | shapely.geometry.MultiPolygon | None) – An optional mask to constrain cells using WGS84 (EPSG:4326) geodetic coordinates in a Polygon or MultiPolygon.

  • strips (str | None) – Option to generate strip-cells along latitude (“lat”), longitude (“lon”), or none (None).

Returns:

the data frame of generated cells, each

identified by the hash of its geometry (cell_id, see tatc.utils.geometry.hash_geometry)

Return type:

geopandas.GeoDataFrame

Equal Angular Spacing

tatc.generation.generate_cells_uniform_angular_spacing(theta_longitude: float, theta_latitude: float, elevation: float = 0, mask: Polygon | MultiPolygon | None = None, strips: str | None = None) → GeoDataFrame[source]

Generates geodetic polygons over a regular equally spaced grid.

See: Putman and Lin (2007). “Finite-volume transport on various cubed-sphere grids”, Journal of Computational Physics, 227(1). doi: 10.1016/j.jcp.2007.07.022

Parameters:
  • theta_longitude (float) – The angular difference in longitude (degrees) between cell centroids.

  • theta_latitude (float) – The angular difference in latitude (degrees) between cell centroids.

  • elevation (float) – The elevation (meters) above the datum in the WGS 84 coordinate system.

  • mask (shapely.geometry.Polygon | shapely.geometry.MultiPolygon | None) – An optional mask to constrain cells using WGS84 (EPSG:4326) geodetic coordinates in a Polygon or MultiPolygon.

  • strips (str | None) – Option to generate strip-cells along latitude (“lat”), longitude (“lon”), or none (None).

Returns:

the data frame of generated cells, each

identified by the hash of its geometry (cell_id, see tatc.utils.geometry.hash_geometry)

Return type:

geopandas.GeoDataFrame