energy_data_retrieval.sources.noaa.client#

Bounded NOAA GHCNh station-year acquisition with native metadata and QC.

The current GHCNh product replaces the discontinued ISD updates. Its documented native PSV files preserve timestamps, station identity and per-variable quality, measurement, report and source codes. Units are already physical values in these files; applying legacy ISD integer scaling would be incorrect.

energy_data_retrieval.sources.noaa.client.normalize_stations(text, *, country_code=None, bbox=None, maximum_stations=100000)[source]#

Filter the official catalogue without inferring availability or nearest sites.

country_code uses the catalogue’s ISO_CODE column. The distinct FIPS prefix in GHCN station IDs is retained as country_fips (CL vs CI for Chile). The station list does not establish period or variable coverage.

Parameters:
  • text (str)

  • country_code (str | None)

  • bbox (tuple[float, float, float, float] | None)

  • maximum_stations (int)

Return type:

DataFrame

energy_data_retrieval.sources.noaa.client.normalize_observations(text, station_id, start, end, *, maximum_rows=600000)[source]#

Keep native UTC observations and raw per-variable provenance/QC columns.

Source values, including flagged observations and reported zeros, are retained. Blank values become null only in the added numeric columns. No quality flag is treated as a universal pass: meanings depend on the variable and source.

Parameters:
  • text (str)

  • station_id (str)

  • start (date)

  • end (date)

  • maximum_rows (int)

Return type:

DataFrame

class energy_data_retrieval.sources.noaa.client.NOAAStations(frame: 'pd.DataFrame', request: 'RequestRecord')[source]#

Bases: object

Parameters:
frame: DataFrame#
request: RequestRecord#
class energy_data_retrieval.sources.noaa.client.NOAAObservations(station_id: 'str', start: 'date', end: 'date', frame: 'pd.DataFrame', requests: 'tuple[RequestRecord, ...]', source_text: 'str')[source]#

Bases: object

Parameters:
  • station_id (str)

  • start (date)

  • end (date)

  • frame (DataFrame)

  • requests (tuple[RequestRecord, ...])

  • source_text (str)

station_id: str#
start: date#
end: date#
frame: DataFrame#
requests: tuple[RequestRecord, ...]#
source_text: str#
energy_data_retrieval.sources.noaa.client.save_observations(result, output)[source]#

Persist selected observations with the complete native source and its hash.

Parameters:
Return type:

Artifact

class energy_data_retrieval.sources.noaa.client.NOAAClient(http, maximum_rows=600000, maximum_stations=100000, maximum_years=100)[source]#

Bases: object

Explicit station retrieval using current NOAA GHCNh public HTTPS exports.

Parameters:
  • http (HTTPClient)

  • maximum_rows (int)

  • maximum_stations (int)

  • maximum_years (int)

http: HTTPClient#
maximum_rows: int#
maximum_stations: int#
maximum_years: int#
stations(*, country_code=None, bbox=None)[source]#
Parameters:
  • country_code (str | None)

  • bbox (tuple[float, float, float, float] | None)

Return type:

NOAAStations

observations(station_id, start, end)[source]#
Parameters:
  • station_id (str)

  • start (date)

  • end (date)

Return type:

NOAAObservations

iter_observations(station_id, start, end)[source]#

Yield one station-year at a time; no all-years dataset is collected.

Parameters:
  • station_id (str)

  • start (date)

  • end (date)

Return type:

Iterator[NOAAObservations]

retrieve(station_id, start, end, output)[source]#

Reuse only verified Parquet/source pairs before any provider access.

Parameters:
  • station_id (str)

  • start (date)

  • end (date)

  • output (Path)

Return type:

Artifact