API Docs

Ranking

eeweather.rank_stations(site_latitude, site_longitude, site_state=None, site_elevation=None, match_iecc_climate_zone=False, match_iecc_moisture_regime=False, match_ba_climate_zone=False, match_ca_climate_zone=False, match_state=False, minimum_quality=None, minimum_tmy3_class=None, max_distance_meters=None, max_difference_elevation_meters=None, is_tmy3=None, is_cz2010=None)[source]

Get a ranked, filtered set of candidate weather stations and metadata for a particular site.

Parameters:
  • site_latitude (float) – Latitude of target site for which to find candidate weather stations.
  • site_longitude (float) – Longitude of target site for which to find candidate weather stations.
  • site_state (str, 2 letter abbreviation) – US state of target site, used optionally to filter potential candidate weather stations. Ignored unless match_state=True.
  • site_elevation (float) – Elevation of target site in meters, used optionally to filter potential candidate weather stations. Ignored unless max_difference_elevation_meters is set.
  • match_iecc_climate_zone (bool) – If True, filter candidate weather stations to those matching the IECC climate zone of the target site.
  • match_iecc_moisture_regime (bool) – If True, filter candidate weather stations to those matching the IECC moisture regime of the target site.
  • match_ca_climate_zone (bool) – If True, filter candidate weather stations to those matching the CA climate zone of the target site.
  • match_ba_climate_zone (bool) – If True, filter candidate weather stations to those matching the Building America climate zone of the target site.
  • match_state (bool) – If True, filter candidate weather stations to those matching the US state of the target site, as specified by site_state=True.
  • minimum_quality (str, 'high', 'medium', 'low') – If given, filter candidate weather stations to those meeting or exceeding the given quality, as summarized by the frequency and availability of observations in the NOAA Integrated Surface Database.
  • minimum_tmy3_class (str, 'I', 'II', 'III') – If given, filter candidate weather stations to those meeting or exceeding the given class, as reported in the NREL TMY3 metadata.
  • max_distance_meters (float) – If given, filter candidate weather stations to those within the max_distance_meters of the target site location.
  • max_difference_elevation_meters (float) – If given, filter candidate weather stations to those with elevations within max_difference_elevation_meters of the target site elevation.
  • is_tmy3 (bool) – If given, filter candidate weather stations to those for which TMY3 normal year temperature data is available.
  • is_cz2010 (bool) – If given, filter candidate weather stations to those for which CZ2010 normal year temperature data is available.
Returns:

ranked_filtered_candidates – Index is usaf_id. Each row contains a potential weather station match and metadata. Contains the following columns:

  • rank: Rank of weather station match for the target site.
  • distance_meters: Distance from target site to weather station site.
  • latitude: Latitude of weather station site.
  • longitude: Longitude of weather station site.
  • iecc_climate_zone: IECC Climate Zone ID (1-8)
  • iecc_moisture_regime: IECC Moisture Regime ID (A-C)
  • ba_climate_zone: Building America climate zone name
  • ca_climate_zone: Califoria climate zone number
  • rough_quality: Approximate measure of frequency of ISD observations data at weather station.
  • elevation: Elevation of weather station site, if available.
  • state: US state of weather station site, if applicable.
  • tmy3_class: Weather station class as reported by NREL TMY3, if available
  • is_tmy3: Weather station has associated TMY3 data.
  • is_cz2010: Weather station has associated CZ2010 data.
  • difference_elevation_meters: Absolute difference in meters between target site elevation and weather station elevation, if available.

Return type:

pandas.DataFrame

eeweather.combine_ranked_stations(rankings)[source]

Combine pandas.DataFrame s of candidate weather stations to form a hybrid ranking dataframe.

Parameters:rankings (list of pandas.DataFrame) – Dataframes of ranked weather station candidates and metadata. All ranking dataframes should have the same columns and must be sorted by rank.
Returns:ranked_filtered_candidates – Dataframe has a rank column and the same columns given in the source dataframes.
Return type:pandas.DataFrame
eeweather.select_station(candidates, coverage_range=None, min_fraction_coverage=0.9, distance_warnings=(50000, 200000), rank=1, fetch_from_web=True)[source]

Select a station from a list of candidates that meets given data quality criteria.

Parameters:candidates (pandas.DataFrame) – A dataframe of the form given by eeweather.rank_stations or eeweather.combine_ranked_stations, specifically having at least an index with usaf_id values and the column distance_meters.
Returns:isd_station, warnings – A qualified weather station. None if no station meets criteria.
Return type:tuple of (eeweather.ISDStation, list of str)

ISDStation objects

class eeweather.ISDStation(usaf_id, load_metadata=True)[source]

A representation of an Integrated Surface Database weather station.

Contains data about a particular ISD station, as well as methods to pull data for this station.

Parameters:
  • usaf_id (str) – ISD station USAF ID
  • load_metatdata (bool, optional) – Whether or not to auto-load metadata for this station
usaf_id

ISD station USAF ID

Type:str
iecc_climate_zone

IECC Climate Zone

Type:str
iecc_moisture_regime

IECC Moisture Regime

Type:str
ba_climate_zone

Building America Climate Zone

Type:str
ca_climate_zone

California Building Climate Zone

Type:str
elevation

elevation of station

Type:float
latitude

latitude of station

Type:float
longitude

longitude of station

Type:float
coords

lat/long coordinates of station

Type:tuple of (float, float)
name

name of the station

Type:str
quality

“high”, “medium”, “low”

Type:str
wban_ids

list of WBAN IDs, or “99999” which have been used to identify the station.

Type:list of str
recent_wban_id = None

WBAN ID most recently used to identify the station.

climate_zones = {}

dict of all climate zones.

cached_gsod_daily_temp_data_is_expired(year)[source]

Return True if cache of resampled daily GSOD temperature data has expired or does not exist for the given year.

cached_isd_daily_temp_data_is_expired(year)[source]

Return True if cache of resampled daily ISD temperature data has expired or does not exist for the given year.

cached_isd_hourly_temp_data_is_expired(year)[source]

Return True if cache of resampled hourly ISD temperature data has expired or does not exist for the given year.

deserialize_cz2010_hourly_temp_data(data)[source]

Deserialize JSON representation of hourly CZ2010 into pandas time series.

deserialize_gsod_daily_temp_data(data)[source]

Deserialize JSON representation of resampled daily GSOD into pandas time series.

deserialize_isd_daily_temp_data(data)[source]

Deserialize JSON representation of resampled daily ISD into pandas time series.

deserialize_isd_hourly_temp_data(data)[source]

Deserialize JSON representation of resampled hourly ISD into pandas time series.

deserialize_tmy3_hourly_temp_data(data)[source]

Deserialize JSON representation of hourly TMY3 into pandas time series.

destroy_cached_cz2010_hourly_temp_data()[source]

Remove cached hourly CZ2010 temperature data to cache.

destroy_cached_gsod_daily_temp_data(year)[source]

Remove cached resampled daily GSOD temperature data to cache for given year.

destroy_cached_isd_daily_temp_data(year)[source]

Remove cached resampled daily ISD temperature data to cache for given year.

destroy_cached_isd_hourly_temp_data(year)[source]

Remove cached resampled hourly ISD temperature data to cache for given year.

destroy_cached_tmy3_hourly_temp_data()[source]

Remove cached hourly TMY3 temperature data to cache.

fetch_cz2010_hourly_temp_data()[source]

Pull hourly CZ2010 temperature hourly time series from URL.

fetch_gsod_daily_temp_data(year)[source]

Pull raw GSOD temperature data for the given year directly from FTP and resample to daily time series.

fetch_gsod_raw_temp_data(year)[source]

Pull raw GSOD data for the given year directly from FTP.

fetch_isd_daily_temp_data(year)[source]

Pull raw ISD temperature data for the given year directly from FTP and resample to daily time series.

fetch_isd_hourly_temp_data(year)[source]

Pull raw ISD temperature data for the given year directly from FTP and resample to hourly time series.

fetch_isd_raw_temp_data(year)[source]

Pull raw ISD data for the given year directly from FTP.

fetch_tmy3_hourly_temp_data()[source]

Pull hourly TMY3 temperature hourly time series directly from NREL.

get_cz2010_hourly_temp_data_cache_key()[source]

Get key used to cache CZ2010 weather-normalized temperature data.

get_gsod_daily_temp_data_cache_key(year)[source]

Get key used to cache resampled daily GSOD temperature data for the given year.

get_gsod_filenames(year=None, with_host=False)[source]

Get filenames of raw GSOD station data.

get_isd_daily_temp_data_cache_key(year)[source]

Get key used to cache resampled daily ISD temperature data for the given year.

get_isd_file_metadata()[source]

Get raw file metadata for the station.

get_isd_filenames(year=None, with_host=False)[source]

Get filenames of raw ISD station data.

get_isd_hourly_temp_data_cache_key(year)[source]

Get key used to cache resampled hourly ISD temperature data for the given year.

get_tmy3_hourly_temp_data_cache_key()[source]

Get key used to cache TMY3 weather-normalized temperature data.

json()[source]

Return a JSON-serializeable object containing station metadata.

load_cached_cz2010_hourly_temp_data()[source]

Load all cached hourly TMY3 temperature data (the year is set to 1900)

load_cached_gsod_daily_temp_data()[source]

Load all cached resampled daily GSOD temperature data.

load_cached_isd_daily_temp_data()[source]

Load all cached resampled daily ISD temperature data.

load_cached_isd_hourly_temp_data()[source]

Load all cached resampled hourly ISD temperature data.

load_cached_tmy3_hourly_temp_data()[source]

Load all cached hourly TMY3 temperature data (the year is set to 1900)

load_cz2010_hourly_temp_data(start, end, read_from_cache=True, write_to_cache=True, fetch_from_web=True)[source]

Load hourly CZ2010 temperature data from start date to end date (inclusive).

This is the primary convenience method for loading hourly CZ2010 temperature data.

Parameters:
  • start (datetime.datetime) – The earliest date from which to load data.
  • end (datetime.datetime) – The latest date until which to load data.
  • read_from_cache (bool) – Whether or not to load data from cache.
  • write_to_cache (bool) – Whether or not to write newly loaded data to cache.
  • fetch_from_web (bool) – Whether or not to fetch data from ftp.
load_cz2010_hourly_temp_data_cached_proxy(fetch_from_web=True)[source]

Load hourly CZ2010 temperature data from cache, or if it is expired or hadn’t been cached, fetch from URL.

load_gsod_daily_temp_data(start, end, read_from_cache=True, write_to_cache=True, fetch_from_web=True)[source]

Load resampled daily GSOD temperature data from start date to end date (inclusive).

This is the primary convenience method for loading resampled daily GSOD temperature data.

Parameters:
  • start (datetime.datetime) – The earliest date from which to load data.
  • end (datetime.datetime) – The latest date until which to load data.
  • read_from_cache (bool) – Whether or not to load data from cache.
  • write_to_cache (bool) – Whether or not to write newly loaded data to cache.
  • fetch_from_web (bool) – Whether or not to fetch data from ftp.
load_gsod_daily_temp_data_cached_proxy(year, fetch_from_web=True)[source]

Load resampled daily GSOD temperature data from cache, or if it is expired or hadn’t been cached, fetch from FTP for given year.

load_isd_daily_temp_data(start, end, read_from_cache=True, write_to_cache=True, fetch_from_web=True)[source]

Load resampled daily ISD temperature data from start date to end date (inclusive).

This is the primary convenience method for loading resampled daily ISD temperature data.

Parameters:
  • start (datetime.datetime) – The earliest date from which to load data.
  • end (datetime.datetime) – The latest date until which to load data.
  • read_from_cache (bool) – Whether or not to load data from cache.
  • fetch_from_web (bool) – Whether or not to fetch data from ftp.
  • write_to_cache (bool) – Whether or not to write newly loaded data to cache.
load_isd_daily_temp_data_cached_proxy(year, fetch_from_web=True)[source]

Load resampled daily ISD temperature data from cache, or if it is expired or hadn’t been cached, fetch from FTP for given year.

load_isd_hourly_temp_data(start, end, read_from_cache=True, write_to_cache=True, fetch_from_web=True, error_on_missing_years=True)[source]

Load resampled hourly ISD temperature data from start date to end date (inclusive).

This is the primary convenience method for loading resampled hourly ISD temperature data.

Parameters:
  • start (datetime.datetime) – The earliest date from which to load data.
  • end (datetime.datetime) – The latest date until which to load data.
  • read_from_cache (bool) – Whether or not to load data from cache.
  • fetch_from_web (bool) – Whether or not to fetch data from ftp.
  • write_to_cache (bool) – Whether or not to write newly loaded data to cache.
load_isd_hourly_temp_data_cached_proxy(year, fetch_from_web=True)[source]

Load resampled hourly ISD temperature data from cache, or if it is expired or hadn’t been cached, fetch from FTP for given year.

load_tmy3_hourly_temp_data(start, end, read_from_cache=True, write_to_cache=True, fetch_from_web=True)[source]

Load hourly TMY3 temperature data from start date to end date (inclusive).

This is the primary convenience method for loading hourly TMY3 temperature data.

Parameters:
  • start (datetime.datetime) – The earliest date from which to load data.
  • end (datetime.datetime) – The latest date until which to load data.
  • read_from_cache (bool) – Whether or not to load data from cache.
  • write_to_cache (bool) – Whether or not to write newly loaded data to cache.
  • fetch_from_web (bool) – Whether or not to fetch data from ftp.
load_tmy3_hourly_temp_data_cached_proxy(fetch_from_web=True)[source]

Load hourly TMY3 temperature data from cache, or if it is expired or hadn’t been cached, fetch from NREL.

read_cz2010_hourly_temp_data_from_cache()[source]

Get cached version of hourly TMY3 temperature data.

read_gsod_daily_temp_data_from_cache(year)[source]

Get cached version of resampled daily GSOD temperature data for given year.

read_isd_daily_temp_data_from_cache(year)[source]

Get cached version of resampled daily ISD temperature data for given year.

read_isd_hourly_temp_data_from_cache(year)[source]

Get cached version of resampled hourly ISD temperature data for given year.

read_tmy3_hourly_temp_data_from_cache()[source]

Get cached version of hourly TMY3 temperature data.

serialize_cz2010_hourly_temp_data(ts)[source]

Serialize hourly CZ2010 pandas time series as JSON for caching.

serialize_gsod_daily_temp_data(ts)[source]

Serialize resampled daily GSOD pandas time series as JSON for caching.

serialize_isd_daily_temp_data(ts)[source]

Serialize resampled daily ISD pandas time series as JSON for caching.

serialize_isd_hourly_temp_data(ts)[source]

Serialize resampled hourly ISD pandas time series as JSON for caching.

serialize_tmy3_hourly_temp_data(ts)[source]

Serialize hourly TMY3 pandas time series as JSON for caching.

validate_cz2010_hourly_temp_data_cache()[source]

Check if CZ2010 data exists in cache.

validate_gsod_daily_temp_data_cache(year)[source]

Delete cached resampled daily GSOD temperature data if it has expired for the given year.

validate_isd_daily_temp_data_cache(year)[source]

Delete cached resampled daily ISD temperature data if it has expired for the given year.

validate_isd_hourly_temp_data_cache(year)[source]

Delete cached resampled hourly ISD temperature data if it has expired for the given year.

validate_tmy3_hourly_temp_data_cache()[source]

Check if TMY3 data exists in cache.

write_cz2010_hourly_temp_data_to_cache(ts)[source]

Write hourly CZ2010 temperature data to cache for given year.

write_gsod_daily_temp_data_to_cache(year, ts)[source]

Write resampled daily GSOD temperature data to cache for given year.

write_isd_daily_temp_data_to_cache(year, ts)[source]

Write resampled daily ISD temperature data to cache for given year.

write_isd_hourly_temp_data_to_cache(year, ts)[source]

Write resampled hourly ISD temperature data to cache for given year.

write_tmy3_hourly_temp_data_to_cache(ts)[source]

Write hourly TMY3 temperature data to cache for given year.

Summaries

eeweather.summaries.get_zcta_ids(state=None)[source]

Get ids of all supported ZCTAs, optionally by state.

Parameters:state (str, optional) – Select zipcodes only from this state or territory, given as 2-letter abbreviation (e.g., 'CA', 'PR').
Returns:results – List of all supported selected ZCTA IDs.
Return type:list of str
eeweather.summaries.get_isd_station_usaf_ids(state=None)[source]

Get USAF IDs of all supported ISD stations, optionally by state.

Parameters:state (str, optional) – Select ISD station USAF IDs only from this state or territory, given as 2-letter abbreviation (e.g., 'CA', 'PR').
Returns:results – List of all supported selected ISD station USAF IDs.
Return type:list of str

Geography

eeweather.geo.get_lat_long_climate_zones(latitude, longitude)[source]

Get climate zones that contain lat/long coordinates.

Parameters:
  • latitude (float) – Latitude of point.
  • longitude (float) – Longitude of point.
Returns:

climate_zones – Region ids for each climate zone type.

Return type:

dict of str

eeweather.geo.get_zcta_metadata(zcta)[source]

Get metadata about a ZIP Code Tabulation Area (ZCTA).

Parameters:zcta (str) – ID of ZIP Code Tabulation Area
Returns:metadata – Dict of data about the ZCTA, including lat/long coordinates.
Return type:dict
eeweather.geo.zcta_to_lat_long(zcta)[source]

Get location of ZCTA centroid

Retrieves latitude and longitude of centroid of ZCTA to use for matching with weather station.

Parameters:zcta (str) – ID of the target ZCTA.
Returns:
  • latitude (float) – Latitude of centroid of ZCTA.
  • longitude (float) – Target Longitude of centroid of ZCTA.

Database

eeweather.database.build_metadata_db(zcta_geometry=False, iecc_climate_zone_geometry=True, iecc_moisture_regime_geometry=True, ba_climate_zone_geometry=True, ca_climate_zone_geometry=True)[source]

Build database of metadata from primary sources.

Downloads primary sources, clears existing DB, and rebuilds from scratch.

Parameters:
  • zcta_geometry (bool, optional) – Whether or not to include ZCTA geometry in database.
  • iecc_climate_zone_geometry (bool, optional) – Whether or not to include IECC Climate Zone geometry in database.
  • iecc_moisture_regime_geometry (bool, optional) – Whether or not to include IECC Moisture Regime geometry in database.
  • ba_climate_zone_geometry (bool, optional) – Whether or not to include Building America Climate Zone geometry in database.
  • ca_climate_zone_geometry (bool, optional) – Whether or not to include California Building Climate Zone Area geometry in database.

Exceptions

exception eeweather.EEWeatherError[source]

Base class for exceptions in the eeweather package.

exception eeweather.ISDDataNotAvailableError(usaf_id, year)[source]

Raised when ISD data is not available for a particular station and year.

usaf_id

the USAF ID for which ISD data does not exist.

Type:str
year

the year for which ISD data does not exist.

Type:int
message

a message describing the error

Type:str
exception eeweather.UnrecognizedZCTAError(value)[source]

Raised when an unrecognized ZCTA is encountered.

value

the value which is not a valid ZCTA

Type:str
message

a message describing the error

Type:str
exception eeweather.UnrecognizedUSAFIDError(value)[source]

Raised when an unrecognized USAF station id is encountered.

value

the value which is not a valid USAF ID

Type:str
message

a message describing the error

Type:str

Validators

eeweather.validation.valid_zcta_or_raise(zcta)[source]

Check if ZCTA is valid and raise eeweather.UnrecognizedZCTAError if not.

eeweather.validation.valid_usaf_id_or_raise(usaf_id)[source]

Check if USAF ID is valid and raise eeweather.UnrecognizedUSAFIDError if not.

Visualization

eeweather.plot_station_mapping(target_latitude, target_longitude, isd_station, distance_meters, target_label='target')[source]

Plots this mapping on a map.

eeweather.plot_station_mappings(mapping_results)[source]

Plot a list of mapping results on a map.

Requires matplotlib and cartopy.

Parameters:mapping_results (list of MappingResult objects) – Mapping results to plot