pvlib.iotools.read_epw

pvlib.iotools.read_epw(filename, coerce_year=None)

Read an EPW file in to a pandas dataframe.

Note that values contained in the metadata dictionary are unchanged from the EPW file.

EPW files are commonly used by building simulation professionals and are widely available on the web. For example via: https://energyplus.net/weather , http://climate.onebuilding.org or http://www.ladybug.tools/epwmap/

Parameters:

• filename (String) – Can be a relative file path, absolute file path, or url.
• coerce_year (None or int, default None) – If supplied, the year of the data will be set to this value. This can be a useful feature because EPW data is composed of data from different years. Warning: EPW files always have 365*24 = 8760 data rows; be careful with the use of leap years.

Returns:

• data (DataFrame) – A pandas dataframe with the columns described in the table below. For more detailed descriptions of each component, please consult the EnergyPlus Auxiliary Programs documentation [1]
• metadata (dict) – The site metadata available in the file.

See also

pvlib.iotools.parse_epw()

Notes

The returned structures have the following fields.

key	format	description
loc	String	default identifier, not used
city	String	site loccation
state-prov	String	state, province or region (if available)
country	String	site country code
data_type	String	type of original data source
WMO_code	String	WMO identifier
latitude	Float	site latitude
longitude	Float	site longitude
TZ	Float	UTC offset
altitude	Float	site elevation

EPWData field	description
index	A pandas datetime index. NOTE, times are set to local standard time (daylight savings is not included). Days run from 0-23h to comply with PVLIB’s convention.
year	Year, from original EPW file. Can be overwritten using coerce function.
month	Month, from original EPW file.
day	Day of the month, from original EPW file.
hour	Hour of the day from original EPW file. Note that EPW’s convention of 1-24h is not taken over in the index dataframe used in PVLIB.
minute	Minute, from original EPW file. Not used.
data_source_unct	Data source and uncertainty flags. See [1], chapter 2.13
temp_air	Dry bulb temperature at the time indicated, deg C
temp_dew	Dew-point temperature at the time indicated, deg C
relative_humidity	Relative humidity at the time indicated, percent
atmospheric_pressure	Station pressure at the time indicated, Pa
etr	Extraterrestrial horizontal radiation recv’d during 60 minutes prior to timestamp, Wh/m^2
etrn	Extraterrestrial normal radiation recv’d during 60 minutes prior to timestamp, Wh/m^2
ghi_infrared	Horizontal infrared radiation recv’d during 60 minutes prior to timestamp, Wh/m^2
ghi	Direct and diffuse horizontal radiation recv’d during 60 minutes prior to timestamp, Wh/m^2
dni	Amount of direct normal radiation (modeled) recv’d during 60 minutes prior to timestamp, Wh/m^2
dhi	Amount of diffuse horizontal radiation recv’d during 60 minutes prior to timestamp, Wh/m^2
global_hor_illum	Avg. total horizontal illuminance recv’d during the 60 minutes prior to timestamp, lx
direct_normal_illum	Avg. direct normal illuminance recv’d during the 60 minutes prior to timestamp, lx
diffuse_horizontal_illum	Avg. horizontal diffuse illuminance recv’d during the 60 minutes prior to timestamp, lx
zenith_luminance	Avg. luminance at the sky’s zenith during the 60 minutes prior to timestamp, cd/m^2
wind_direction	Wind direction at time indicated, degrees from north (360 = north; 0 = undefined,calm)
wind_speed	Wind speed at the time indicated, m/s
total_sky_cover	Amount of sky dome covered by clouds or obscuring phenomena at time stamp, tenths of sky
opaque_sky_cover	Amount of sky dome covered by clouds or obscuring phenomena that prevent observing the sky at time stamp, tenths of sky
visibility	Horizontal visibility at the time indicated, km
ceiling_height	Height of cloud base above local terrain (7777=unlimited), meter
present_weather_observation	Indicator for remaining fields: If 0, then the observed weather codes are taken from the following field. If 9, then missing weather is assumed.
present_weather_codes	Present weather code, see [1], chapter 2.9.1.28
precipitable_water	Total precipitable water contained in a column of unit cross section from earth to top of atmosphere, cm. Note that some old *_TMY3.epw files may have incorrect unit if it was retrieved from www.energyplus.net.
aerosol_optical_depth	The broadband aerosol optical depth per unit of air mass due to extinction by aerosol component of atmosphere, unitless
snow_depth	Snow depth in centimeters on the day indicated, (999 = missing data)
days_since_last_snowfall	Number of days since last snowfall (maximum value of 88, where 88 = 88 or greater days; 99 = missing data)
albedo	The ratio of reflected solar irradiance to global horizontal irradiance, unitless
liquid_precipitation_depth	The amount of liquid precipitation observed at indicated time for the period indicated in the liquid precipitation quantity field, millimeter
liquid_precipitation_quantity	The period of accumulation for the liquid precipitation depth field, hour

References

[1]	(1, 2) EnergyPlus documentation, Auxiliary Programs