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:
- 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:
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:
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:
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:
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: