energy_data_retrieval.spatial#

Geographic station discovery with explicit spherical-distance assumptions.

energy_data_retrieval.spatial.haversine_distance_km(latitude, longitude, station_latitudes, station_longitudes)[source]#

Return vectorized great-circle distances from one location, in kilometres.

Coordinates are decimal degrees. Both station arrays must be finite, equally sized one-dimensional vectors, with latitude in [-90, 90] and longitude in [-180, 180]. The fixed mean-radius sphere has radius 6371.0088 km; distances are spherical approximations and do not account for elevation or terrain. Longitude wraps across the antimeridian. Longitude at either pole does not change that pole’s physical location.

Parameters:
  • latitude (float)

  • longitude (float)

  • station_latitudes (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str])

  • station_longitudes (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str])

Return type:

FloatArray

energy_data_retrieval.spatial.nearby_stations(stations, latitude, longitude, *, radius_km=100.0, limit=20)[source]#

Rank station candidates inside an inclusive geographic search radius.

Required columns are station_id, latitude and longitude. Original columns and attributes are retained in a new frame; distance_km and the one-based rank are added. Existing columns with either name are rejected to prevent overwriting source fields. Query coordinates must be finite.

Unavailable, nonnumeric, nonfinite or out-of-range catalogue coordinates are excluded. Their count, the query and the sphere assumption are recorded in result.attrs["spatial_search"]. The radius must be positive and no larger than half the sphere’s circumference; limit must be an integer in [1, 100000]. Results sort by distance, then source, station ID and original row order for deterministic ties. No station records are deduplicated.

Proximity alone establishes neither data availability nor suitability as a site’s weather reference. Provider coverage, quality and local terrain need separate assessment.

Parameters:
  • stations (DataFrame)

  • latitude (float)

  • longitude (float)

  • radius_km (float)

  • limit (int)

Return type:

DataFrame