Source code for energy_data_retrieval.sources.nasa_power.client
"""Bounded NASA POWER AOD550 retrieval; no inferred aerosol wavelengths."""
from __future__ import annotations
from dataclasses import dataclass
from datetime import date
import numpy as np
import pandas as pd
from energy_data_retrieval.sources.open_meteo import Site
from energy_data_retrieval.transport import HTTPClient, RequestRecord, RetrievalError, object_value
NASA_POWER_HOSTS = frozenset({"power.larc.nasa.gov"})
REFERENCE_IDS = ("nasa_power_aerosols",)
[docs]
@dataclass(frozen=True, slots=True)
class AODChunk:
"""Daily dimensionless AOD550; source grid resolution is not point precision."""
site: Site
frame: pd.DataFrame
request: RequestRecord
source: str
[docs]
@dataclass(slots=True)
class NASAPowerClient:
http: HTTPClient
[docs]
def daily_aod(self, site: Site, start: date, end: date) -> AODChunk:
"""Fetch 1-366 UTC days of total AOD at 550 nm (unadjusted AOD_55).
NASA POWER serves CERES SYN1deg aerosol fields. Provider fill values
become NaN; missing dates, unknown units and negative observations fail.
This is a separate source from the thesis's ECMWF/CAMS aerosol product.
"""
if start < date(2001, 1, 1) or not 1 <= (end - start).days + 1 <= 366:
raise ValueError("Request 1-366 days from 2001 onward")
response = self.http.get_json(
"https://power.larc.nasa.gov/api/temporal/daily/point",
{
"parameters": "AOD_55",
"community": "RE",
"format": "JSON",
"latitude": str(site.latitude),
"longitude": str(site.longitude),
"start": start.strftime("%Y%m%d"),
"end": end.strftime("%Y%m%d"),
"time-standard": "UTC",
},
)
payload = object_value(response.value)
header = object_value(payload.get("header"))
units = object_value(object_value(payload.get("parameters")).get("AOD_55"))
if units.get("units") != "dimensionless" or header.get("time_standard") != "UTC":
raise RetrievalError("Unexpected NASA AOD units or time standard")
fill = header.get("fill_value")
if isinstance(fill, bool) or not isinstance(fill, (int, float)) or not np.isfinite(fill):
raise RetrievalError("NASA fill value is missing or invalid")
parameters = object_value(object_value(payload.get("properties")).get("parameter"))
raw = object_value(parameters.get("AOD_55"))
time = pd.date_range(start, end, freq="D", tz="UTC")
keys = time.strftime("%Y%m%d").tolist()
if set(raw) != set(keys):
raise RetrievalError("NASA AOD dates differ from the requested interval")
values = [raw[key] for key in keys]
if not all(v is None or (type(v) in (int, float)) for v in values):
raise RetrievalError("NASA AOD contains nonnumeric observations")
array = np.asarray(values, dtype=float)
array[array == fill] = np.nan
if np.isinf(array).any() or np.any(array < 0):
raise RetrievalError("NASA AOD contains invalid negative or infinite observations")
return AODChunk(
site,
pd.DataFrame({"timestamp": time, "aod550": array}),
response.record,
f"NASA POWER AOD_55; source products: {header.get('sources', [])}",
)