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 bysite_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 nameca_climate_zone
: Califoria climate zone numberrough_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 availableis_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:
-
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 byeeweather.rank_stations
oreeweather.combine_ranked_stations
, specifically having at least an index withusaf_id
values and the columndistance_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: -
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_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_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_isd_daily_temp_data_cache_key
(year)[source]¶ Get key used to cache resampled daily ISD temperature data for the given year.
-
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.
-
load_cached_cz2010_hourly_temp_data
()[source]¶ Load all cached hourly TMY3 temperature data (the year is set to 1900)
-
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_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.
-
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.
-
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: 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.
ISDDataNotAvailableError
(usaf_id, year)[source]¶ Raised when ISD data is not available for a particular station and year.