GSODWeatherSource

class eemeter.weather.GSODWeatherSource(station, cache_url=None)

The GSODWeatherSource draws weather data from the NOAA Global Summary of the Day FTP site. It stores fetched data locally by default in a SQLite database at ~/eemeter/cache/weather_cache.db, unless you use set the EEMETER_WEATHER_CACHE_URL environment variable to another, SQLAlchemy compatible database URL:

Basic usage is as follows:

>>> from eemeter.weather import GSODWeatherSource
>>> ws = GSODWeatherSource("722880")  # or another 6-digit USAF station

This object can be used to fetch weather data as follows, using an daily frequency time-zone aware pandas DatetimeIndex covering any stretch of time.

>>> import pandas as pd
>>> import pytz
>>> index = pd.date_range('2015-01-01', periods=365,
...     freq='D', tz=pytz.UTC)
>>> ws.indexed_temperatures(index, "degF")
2015-01-01 00:00:00+00:00    43.6
2015-01-02 00:00:00+00:00    45.0
2015-01-03 00:00:00+00:00    47.3
                             ...
2015-12-29 00:00:00+00:00    48.0
2015-12-30 00:00:00+00:00    46.4
2015-12-31 00:00:00+00:00    47.6
Freq: D, dtype: float64
add_year(year, force_fetch=False)

Adds temperature data to internal pandas timeseries

Note

This method is called automatically internally to keep data updated in response to calls to .indexed_temperatures()

Parameters:
  • year ({int, string}) – The year for which data should be fetched, e.g. “2010”.
  • force_fetch (bool, default=False) – If True, forces the fetch; if False, checks to see if locally available before actually fetching.
add_year_range(start_year, end_year, force_fetch=False)

Adds temperature data to internal pandas timeseries across a range of years.

Note

This method is called automatically internally to keep data updated in response to calls to .indexed_temperatures()

Parameters:
  • start_year ({int, string}) – The earliest year for which data should be fetched, e.g. “2010”.
  • end_year ({int, string}) – The latest year for which data should be fetched, e.g. “2013”.
  • force_fetch (bool, default=False) – If True, forces the fetch; if false, checks to see if year has been added before actually fetching.
indexed_temperatures(index, unit, allow_mixed_frequency=False)

Return average temperatures over the given index.

Parameters:
  • index (pandas.DatetimeIndex) – Index over which to supply average temperatures. The index should be given as either an hourly (‘H’) or daily (‘D’) frequency.
  • unit (str, {"degF", "degC"}) – Target temperature unit for returned temperature series.
Returns:

temperatures – Average temperatures over series indexed by index.

Return type:

pandas.Series with DatetimeIndex

ISDWeatherSource

class eemeter.weather.ISDWeatherSource(station, cache_url=None)

The ISDWeatherSource draws weather data from the NOAA Integrated Surface Database (ISD) FTP site. It stores fetched hourly data locally by default in a SQLite database at ~/eemeter/cache/weather_cache.db, unless you use set the following environment variable to something different:

$ export EEMETER_WEATHER_CACHE_DIRECTORY=/path/to/custom/directory

Basic usage is as follows:

>>> from eemeter.weather import ISDWeatherSource
>>> ws = ISDWeatherSource("722880")  # or another 6-digit USAF station

This object can be used to fetch weather data as follows, using an hourly or daily frequency time-zone aware pandas DatetimeIndex covering any stretch of time.

>>> import pandas as pd
>>> import pytz
>>> daily_index = pd.date_range('2015-01-01', periods=365,
...     freq='D', tz=pytz.UTC)
>>> ws.indexed_temperatures(daily_index, "degF")
2015-01-01 00:00:00+00:00    43.550000
2015-01-02 00:00:00+00:00    45.042500
2015-01-03 00:00:00+00:00    47.307500
                               ...
2015-12-29 00:00:00+00:00    47.982500
2015-12-30 00:00:00+00:00    46.415000
2015-12-31 00:00:00+00:00    47.645000
Freq: D, dtype: float64
>>> hourly_index = pd.date_range('2015-01-01', periods=365*24,
...     freq='H', tz=pytz.UTC)
>>> ws.indexed_temperatures(hourly_index, "degF")
2015-01-01 00:00:00+00:00    51.98
2015-01-01 01:00:00+00:00    50.00
2015-01-01 02:00:00+00:00    48.02
                             ...
2015-12-31 21:00:00+00:00    62.06
2015-12-31 22:00:00+00:00    62.06
2015-12-31 23:00:00+00:00    62.06
Freq: H, dtype: float64
add_year(year, force_fetch=False)

Adds temperature data to internal pandas timeseries

Note

This method is called automatically internally to keep data updated in response to calls to .indexed_temperatures()

Parameters:
  • year ({int, string}) – The year for which data should be fetched, e.g. “2010”.
  • force_fetch (bool, default=False) – If True, forces the fetch; if False, checks to see if locally available before actually fetching.
add_year_range(start_year, end_year, force_fetch=False)

Adds temperature data to internal pandas timeseries across a range of years.

Note

This method is called automatically internally to keep data updated in response to calls to .indexed_temperatures()

Parameters:
  • start_year ({int, string}) – The earliest year for which data should be fetched, e.g. “2010”.
  • end_year ({int, string}) – The latest year for which data should be fetched, e.g. “2013”.
  • force_fetch (bool, default=False) – If True, forces the fetch; if false, checks to see if year has been added before actually fetching.
indexed_temperatures(index, unit, allow_mixed_frequency=False)

Return average temperatures over the given index.

Parameters:
  • index (pandas.DatetimeIndex) – Index over which to supply average temperatures. The index should be given as either an hourly (‘H’) or daily (‘D’) frequency.
  • unit (str, {"degF", "degC"}) – Target temperature unit for returned temperature series.
Returns:

temperatures – Average temperatures over series indexed by index.

Return type:

pandas.Series with DatetimeIndex

TMY3WeatherSource

class eemeter.weather.TMY3WeatherSource(station, cache_url=None, preload=True)

The TMY3WeatherSource draws weather data from the NREL’s Typical Meteorological Year 3 database. It stores fetched data locally by default in a SQLite database at ~/.eemeter/cache/weather_cache.db, unless you use set the EEMETER_WEATHER_CACHE_URL environment variable to another, SQLAlchemy compatible database URL:

Basic usage is as follows:

>>> from eemeter.weather import TMY3WeatherSource
>>> ws = TMY3WeatherSource("724830")  # or another 6-digit USAF station

This object can be used to fetch weather data as follows, using an daily frequency time-zone aware pandas DatetimeIndex covering any stretch of time.

>>> import pandas as pd
>>> import pytz
>>> daily_index = pd.date_range('2015-01-01', periods=365,
...     freq='D', tz=pytz.UTC)
>>> ws.indexed_temperatures(daily_index, "degF")
2015-01-01 00:00:00+00:00    38.6450
2015-01-02 00:00:00+00:00    40.4900
2015-01-03 00:00:00+00:00    43.9175
                              ...
2015-12-29 00:00:00+00:00    43.7750
2015-12-30 00:00:00+00:00    43.6250
2015-12-31 00:00:00+00:00    46.9250
Freq: D, dtype: float64
>>> hourly_index = pd.date_range('2015-01-01', periods=365*24,
...     freq='H', tz=pytz.UTC)
>>> ws.indexed_temperatures(hourly_index, "degF")
2015-01-01 00:00:00+00:00    51.80
2015-01-01 01:00:00+00:00    50.00
2015-01-01 02:00:00+00:00    50.00
                             ...
2015-12-31 21:00:00+00:00    53.60
2015-12-31 22:00:00+00:00    55.40
2015-12-31 23:00:00+00:00    55.40
Freq: H, dtype: float64
indexed_temperatures(index, unit)

Return average temperatures over the given index.

Parameters:
  • index (pandas.DatetimeIndex) – Index over which to supply average temperatures. The index should be given as either an hourly (‘H’) or daily (‘D’) frequency.
  • unit (str, {"degF", "degC"}) – Target temperature unit for returned temperature series.
Returns:

temperatures – Average temperatures over series indexed by index.

Return type:

pandas.Series with DatetimeIndex

Location

eemeter.weather.location.climate_zone_is_supported(climate_zone)

True if given Climate Zone is supported.

Parameters:climate_zone (str) – String representing a climate_zone.
Returns:supportedTrue if supported, otherwise False.
Return type:bool
eemeter.weather.location.climate_zone_to_tmy3_stations(climate_zone)

Return TMY3 weather stations falling within in the given climate zone.

Parameters:climate_zone (str) – String representing a climate zone.
Returns:stations – Strings representing TMY3 station ids.
Return type:list of str
eemeter.weather.location.climate_zone_to_usaf_stations(climate_zone)

Return USAF weather stations falling within in the given climate zone.

Parameters:climate_zone (str) – String representing a climate zone.
Returns:stations – Strings representing USAF station ids.
Return type:list of str
eemeter.weather.location.climate_zone_to_zipcodes(climate_zone)

Return ZIP codes with centroids in the given climate zone.

Parameters:climate_zone (str) – String representing a climate zone.
Returns:zipcodes – Strings representing USPS ZIP codes.
Return type:list of str
eemeter.weather.location.haversine(lat1, lng1, lat2, lng2)

Calculate the great circle distance between two points on the earth (specified in decimal degrees)

Parameters:
  • lat1 (float) – Latitude coordinate of first point.
  • lng1 (float) – Longitude coordinate of first point.
  • lat2 (float) – Latitude coordinate of second point.
  • lng2 (float) – Longitude coordinate of second point.
Returns:

distance – Kilometers between the two lat/lng coordinates.

Return type:

float

eemeter.weather.location.lat_lng_to_climate_zone(lat, lng)

Return the closest ZIP code using latitude and longitude coordinates.

Parameters:
  • lat (float) – Latitude coordinate.
  • lng (float) – Longitude coordinate.
Returns:

climate_zone – String representing a climate zone.

Return type:

str, None

eemeter.weather.location.lat_lng_to_tmy3_station(lat, lng)

Return the closest TMY3 station ID using latitude and longitude coordinates.

Parameters:
  • lat (float) – Latitude coordinate.
  • lng (float) – Longitude coordinate.
Returns:

station – String representing a TMY3 weather station ID or None, if none was found.

Return type:

str, None

eemeter.weather.location.lat_lng_to_usaf_station(lat, lng)

Return the closest USAF station ID using latitude and longitude coordinates.

Parameters:
  • lat (float) – Latitude coordinate.
  • lng (float) – Longitude coordinate.
Returns:

station – String representing a USAF weather station ID or None, if none was found.

Return type:

str, None

eemeter.weather.location.lat_lng_to_zipcode(lat, lng)

Return the closest ZIP code using latitude and longitude coordinates.

Parameters:
  • lat (float) – Latitude coordinate.
  • lng (float) – Longitude coordinate.
Returns:

zipcode – String representing a USPS ZIP code, or None, if none was found.

Return type:

str, None

eemeter.weather.location.tmy3_station_is_supported(station)

True if given TMY3 weather station is supported. USAF IDs.

Parameters:station (str) – 6-digit string representing a weather station.
Returns:supportedTrue if supported, otherwise False.
Return type:bool
eemeter.weather.location.tmy3_station_to_climate_zone(station)

Return the climate zone of the station.

Parameters:station (str) – String representing a USAF Weather station ID
Returns:climate_zone – String representing a climate zone.
Return type:str
eemeter.weather.location.tmy3_station_to_lat_lng(station)

Return the latitude and longitude coordinates of the given station.

Parameters:station (str) – String representing a TMY3 USAF Weather station ID
Returns:lat_lng – Latitude and longitude coordinates.
Return type:tuple of float
eemeter.weather.location.tmy3_station_to_zipcodes(station)

Return the zipcodes that map to this station.

Parameters:station (str) – String representing a USAF Weather station ID
Returns:zipcode – String representing a USPS ZIP code.
Return type:list of str
eemeter.weather.location.usaf_station_is_supported(station)

True if given USAF weather station is supported. USAF IDs.

Parameters:station (str) – 6-digit string representing a weather station.
Returns:supportedTrue if supported, otherwise False.
Return type:bool
eemeter.weather.location.usaf_station_to_climate_zone(station)

Return the climate zone of the station.

Parameters:station (str) – String representing a USAF Weather station ID
Returns:climate_zone – String representing a climate zone
Return type:str
eemeter.weather.location.usaf_station_to_lat_lng(station)

Return the latitude and longitude coordinates of the given USAF station.

Parameters:station (str) – String representing a USAF Weather station ID
Returns:lat_lng – Latitude and longitude coordinates.
Return type:tuple of float
eemeter.weather.location.usaf_station_to_zipcodes(station)

Return the zipcodes that map to this USAF station.

Parameters:station (str) – String representing a USAF Weather station ID
Returns:zipcodes – Strings representing a USPS ZIP code mapped to from this station.
Return type:list of str
eemeter.weather.location.zipcode_is_supported(zipcode)

True if given ZIP Code is supported. ZCTA only.

Parameters:zipcode (str) – 5-digit string representing a zipcode.
Returns:supportedTrue if supported, otherwise False.
Return type:bool
eemeter.weather.location.zipcode_to_climate_zone(zipcode)

Return the climate zone of the ZIP code (by latitude and longitude centroid of ZIP code).

Parameters:zipcode (str) – String representing a USPS ZIP code.
Returns:climate_zone – String representing a climate zone
Return type:str
eemeter.weather.location.zipcode_to_lat_lng(zipcode)

Return the latitude and longitude centroid of a particular ZIP code.

Parameters:zipcode (str) – String representing a USPS ZIP code.
Returns:lat_lng – Latitude and longitude coordinates.
Return type:tuple of float
eemeter.weather.location.zipcode_to_tmy3_station(zipcode)

Return the nearest TMY3 station (by latitude and longitude centroid) of the ZIP code.

Parameters:zipcode (str) – String representing a USPS ZIP code.
Returns:station – String representing a TMY3 Weather station (USAF ID).
Return type:str
eemeter.weather.location.zipcode_to_usaf_station(zipcode)

Return the nearest USAF station (by latitude and longitude centroid) of the ZIP code.

Parameters:zipcode (str) – String representing a USPS ZIP code.
Returns:station – String representing a USAF weather station ID
Return type:str