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,latitudeandlongitude. Original columns and attributes are retained in a new frame;distance_kmand the one-basedrankare 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;limitmust 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