Metrics

Spatial metrics of turbine layouts. See Spatial metrics for definitions and examples.

n_turbines(obj)	Number of turbines in the layout, from a Farm or an (N, 2) array.
nearest_neighbor_distances(obj)	Nearest-neighbor distance in meters per turbine, shape (N,).
nearest_neighbor_mean(obj)	Mean nearest-neighbor distance in meters between turbine positions.
nearest_neighbor_variation(obj)	Coefficient of variation of the nearest-neighbor distances.
hull_area(obj)	Convex-hull area in square meters of the positions, ignoring any boundary.
region_area(obj[, boundary])	Study-region area in square meters, from the boundary or else the hull.
density(obj[, boundary])	Turbines per square meter over the study region.
clark_evans(obj[, boundary])	Clark-Evans ratio R of the mean nearest-neighbor distance to its CSR value.
aspect_ratio(obj)	Square root of the largest over the smallest position covariance eigenvalue.
bounding_box_diagonal(obj)	Diagonal length in meters of the axis-aligned bounding box of the positions.
ripley_k(obj, radii[, boundary])	Ripley's K(r) in square meters at the given radii in meters.
ripley_l(obj, radii[, boundary])	Ripley's L(r) = sqrt(K(r) / pi) in meters, shape (len(radii),).
quadrat_window(obj[, boundary, ...])	Study-region polygon and hexagon side length for the quadrat test.
hexagon_vertices(center_x, center_y, side_length)	Closed vertex ring (7, 2) of a flat-top hexagon centered at the point.
hexagon_centers(polygon, side_length)	Centers (M, 2) of a flat-top hexagon lattice inside polygon.
quadrat_counts(obj, centers)	Point count per hexagon, shape (len(centers),), by nearest cell center.
quadrat_p_value(obj[, boundary, ...])	Chi-square CSR p-value from hexagonal quadrat counts.
summary(obj[, metrics])	Ordered name -> value dict of scalar metrics for a farm or array.
SCALAR_METRICS	Registry mapping public scalar metric names to their implementations.
DEFAULT_SUMMARY_METRICS	Metric names included by default in summary().

Spatial metrics for generated wind-farm layouts.

Each metric accepts a Farm or an (N, 2) array of turbine positions, N zero included, and a metric undefined for so few turbines is nan. Area-based metrics use Farm.boundary when available and fall back to the convex hull of the turbines. Pass an explicit boundary, a Boundary or a Shapely polygon, to override, or boundary=False to force the hull fallback.

oowl.metrics.DEFAULT_SUMMARY_METRICS = ('n_turbines', 'nearest_neighbor_mean', 'nearest_neighbor_variation', 'density', 'region_area')

Metric names included by default in summary().

oowl.metrics.SCALAR_METRICS = {'aspect_ratio': <function aspect_ratio>, 'bounding_box_diagonal': <function bounding_box_diagonal>, 'clark_evans': <function clark_evans>, 'density': <function density>, 'hull_area': <function hull_area>, 'n_turbines': <function n_turbines>, 'nearest_neighbor_mean': <function nearest_neighbor_mean>, 'nearest_neighbor_variation': <function nearest_neighbor_variation>, 'quadrat_p_value': <function quadrat_p_value>, 'region_area': <function region_area>}

Registry mapping public scalar metric names to their implementations.

Each entry takes a single Farm or (N, 2) array, and boundary-aware metrics resolve the Farm’s boundary automatically. Ripley’s K and L take radii, so they are not scalar and are not included.

oowl.metrics.aspect_ratio(obj)

Square root of the largest over the smallest position covariance eigenvalue.

This is the ratio of the spreads along the principal axes, 1 for an isotropic layout and large for an elongated one. nan for a single turbine or a degenerate spread, such as a straight row.

Parameters:

obj (object)

Return type:

float

oowl.metrics.bounding_box_diagonal(obj)

Diagonal length in meters of the axis-aligned bounding box of the positions.

nan for a layout without turbines.

Parameters:

obj (object)

Return type:

float

oowl.metrics.clark_evans(obj, boundary=None)

Clark-Evans ratio R of the mean nearest-neighbor distance to its CSR value.

Under complete spatial randomness (CSR) the expected mean is 0.5 * sqrt(A / N) with A the study-region area. R > 1 indicates regularity, R < 1 clustering and R ~ 1 CSR. nan when the area is not positive or there are no turbines.

See Clark and Evans (1954), Ecology 35(4), https://doi.org/10.2307/1931034.

Parameters:

• obj (object)

• boundary (object)

Return type:

float

oowl.metrics.density(obj, boundary=None)

Turbines per square meter over the study region.

Parameters:

• obj (object)

• boundary (object)

Return type:

float

oowl.metrics.hexagon_centers(polygon, side_length)

Centers (M, 2) of a flat-top hexagon lattice inside polygon.

The cells tessellate, so nearest-center assignment equals hexagon membership. Raises TypeError for a polygon that is no Shapely geometry, and ValueError for a side_length that is not finite and positive or that would lay out more than ten million hexagons over the polygon’s box.

Parameters:

• polygon (BaseGeometry)

• side_length (float)

Return type:

ndarray

oowl.metrics.hexagon_vertices(center_x, center_y, side_length)

Closed vertex ring (7, 2) of a flat-top hexagon centered at the point.

Parameters:

• center_x (float)

• center_y (float)

• side_length (float)

Return type:

ndarray

oowl.metrics.hull_area(obj)

Convex-hull area in square meters of the positions, ignoring any boundary.

nan when the hull encloses no area.

Parameters:

obj (object)

Return type:

float

oowl.metrics.n_turbines(obj)

Number of turbines in the layout, from a Farm or an (N, 2) array.

Parameters:

obj (object)

Return type:

int

oowl.metrics.nearest_neighbor_distances(obj)

Nearest-neighbor distance in meters per turbine, shape (N,).

nan for a single turbine, which has no neighbor.

Parameters:

obj (object)

Return type:

ndarray

oowl.metrics.nearest_neighbor_mean(obj)

Mean nearest-neighbor distance in meters between turbine positions.

nan for fewer than two turbines.

Parameters:

obj (object)

Return type:

float

oowl.metrics.nearest_neighbor_variation(obj)

Coefficient of variation of the nearest-neighbor distances.

Near 0 for a regular layout, larger for irregular or clustered ones. nan when the mean distance is zero or undefined.

Parameters:

obj (object)

Return type:

float

oowl.metrics.quadrat_counts(obj, centers)

Point count per hexagon, shape (len(centers),), by nearest cell center.

Parameters:

• obj (object)

• centers (ndarray)

Return type:

ndarray

oowl.metrics.quadrat_p_value(obj, boundary=None, hexagon_fraction=0.15, buffer_factor=1.0)

Chi-square CSR p-value from hexagonal quadrat counts.

Cells come from quadrat_window() and hexagon_centers(). Each cell’s expected count is proportional to its area inside the study region, and cells with no such area are dropped.

A low value rejects complete spatial randomness, as under clustering. A high value only fails to reject it and is not evidence of regularity. nan when fewer than two usable cells remain or no turbine lies in them.

Parameters:

• obj (object)

• boundary (object)

• hexagon_fraction (float)

• buffer_factor (float)

Return type:

float

oowl.metrics.quadrat_window(obj, boundary=None, hexagon_fraction=0.15, buffer_factor=1.0)

Study-region polygon and hexagon side length for the quadrat test.

The hexagon side length is hexagon_fraction * sqrt(region area) in meters, so the grid depends on the region and not on turbine count. The region is buffered outward by buffer_factor side lengths so the lattice covers every turbine. hexagon_fraction must be finite and > 0, and buffer_factor finite and >= 0. Returns (polygon, side_length). A region without area, such as the hull of collinear turbines, gives a nan or zero side length and is not buffered.

Parameters:

• obj (object)

• boundary (object)

• hexagon_fraction (float)

• buffer_factor (float)

Return type:

tuple[BaseGeometry, float]

oowl.metrics.region_area(obj, boundary=None)

Study-region area in square meters, from the boundary or else the hull.

Parameters:

• obj (object)

• boundary (object)

Return type:

float

oowl.metrics.ripley_k(obj, radii, boundary=None)

Ripley’s K(r) in square meters at the given radii in meters.

K(r) = A / N^2 * sum_{i != j} 1[d_ij <= r] with A the study-region area. No edge correction is applied, so with the bounding box of the positions as boundary it matches pointpats.distance_statistics.k. radii must be one-dimensional. Returns shape (len(radii),), all nan for fewer than two turbines.

See Ripley (1977), Journal of the Royal Statistical Society B 39(2), https://doi.org/10.1111/j.2517-6161.1977.tb01615.x.

Parameters:

• obj (object)

• radii (Sequence[float] | ndarray)

• boundary (object)

Return type:

ndarray

oowl.metrics.ripley_l(obj, radii, boundary=None)

Ripley’s L(r) = sqrt(K(r) / pi) in meters, shape (len(radii),).

L(r) - r > 0 indicates clustering and < 0 regularity.

See https://doi.org/10.1111/j.2517-6161.1977.tb01615.x.

Parameters:

• obj (object)

• radii (Sequence[float] | ndarray)

• boundary (object)

Return type:

ndarray

oowl.metrics.summary(obj, metrics=None)

Ordered name -> value dict of scalar metrics for a farm or array.

metrics names entries of SCALAR_METRICS, defaulting to DEFAULT_SUMMARY_METRICS. A string instead of a collection of names, or a name that is not a string, raises TypeError. Unknown names raise ValueError.

Parameters:

• obj (object)

• metrics (Iterable[str] | None)

Return type:

dict[str, float]