pvlib.iotools.read_tmy3#

pvlib.iotools.read_tmy3(filename, coerce_year=None, map_variables=None, recolumn=None, encoding=None)[source]#

Read a TMY3 file into a pandas dataframe.

Note that values contained in the metadata dictionary are unchanged from the TMY3 file (i.e. units are retained). In the case of any discrepancies between this documentation and the TMY3 User’s Manual [1], the TMY3 User’s Manual takes precedence.

The TMY3 files were updated in Jan. 2015. This function requires the use of the updated files.

Parameters:
  • filename (str) – A relative file path or absolute file path.

  • coerce_year (int, optional) – If supplied, the year of the index will be set to coerce_year, except for the last index value which will be set to the next year so that the index increases monotonically.

  • map_variables (bool, optional) – When True, renames columns of the DataFrame to pvlib variable names where applicable. See variable VARIABLE_MAP.

  • recolumn (bool (deprecated, use map_variables instead)) – If True, apply standard names to TMY3 columns. Typically this results in stripping the units from the column name. Cannot be used in combination with map_variables.

  • encoding (str, optional) – Encoding of the file. For files that contain non-UTF8 characters it may be necessary to specify an alternative encoding, e.g., for SolarAnywhere TMY3 files the encoding should be ‘iso-8859-1’. Users may also consider using the ‘utf-8-sig’ encoding.

Returns:

  • Tuple of the form (data, metadata).

  • data (DataFrame) – A pandas dataframe with the columns described in the table below. For more detailed descriptions of each component, please consult the TMY3 User’s Manual [1], especially tables 1-1 through 1-6.

  • metadata (dict) – The site metadata available in the file.

Notes

The returned structures have the following fields.

key

format

description

altitude

Float

site elevation

latitude

Float

site latitudeitude

longitude

Float

site longitudeitude

Name

String

site name

State

String

state

TZ

Float

UTC offset

USAF

Int

USAF identifier

field

description

† denotes variables that are mapped when `map_variables` is True

Index

A pandas datetime index. NOTE, the index is timezone aware, and times are set to local standard time (daylight savings is not included)

ghi_extra†

Extraterrestrial horizontal radiation recv’d during 60 minutes prior to timestamp, Wh/m^2

dni_extra†

Extraterrestrial normal 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

GHI source

See [1], Table 1-4

GHI uncert (%)

Uncertainty based on random and bias error estimates see [2]

dni†

Amount of direct normal radiation (modeled) recv’d during 60 mintues prior to timestamp, Wh/m^2

DNI source

See [1], Table 1-4

DNI uncert (%)

Uncertainty based on random and bias error estimates see [2]

dhi†

Amount of diffuse horizontal radiation recv’d during 60 minutes prior to timestamp, Wh/m^2

DHI source

See [1], Table 1-4

DHI uncert (%)

Uncertainty based on random and bias error estimates see [2]

GH illum (lx)

Avg. total horizontal illuminance recv’d during the 60 minutes prior to timestamp, lx

GH illum source

See [1], Table 1-4

GH illum uncert (%)

Uncertainty based on random and bias error estimates see [2]

DN illum (lx)

Avg. direct normal illuminance recv’d during the 60 minutes prior to timestamp, lx

DN illum source

See [1], Table 1-4

DN illum uncert (%)

Uncertainty based on random and bias error estimates see [2]

DH illum (lx)

Avg. horizontal diffuse illuminance recv’d during the 60 minutes prior to timestamp, lx

DH illum source

See [1], Table 1-4

DH illum uncert (%)

Uncertainty based on random and bias error estimates see [2]

Zenith lum (cd/m^2)

Avg. luminance at the sky’s zenith during the 60 minutes prior to timestamp, cd/m^2

Zenith lum source

See [1], Table 1-4

Zenith lum uncert (%)

Uncertainty based on random and bias error estimates see [1] section 2.10

TotCld (tenths)

Amount of sky dome covered by clouds or obscuring phenonema at time stamp, tenths of sky

TotCld source

See [1], Table 1-5

TotCld uncert (code)

See [1], Table 1-6

OpqCld (tenths)

Amount of sky dome covered by clouds or obscuring phenonema that prevent observing the sky at time stamp, tenths of sky

OpqCld source

See [1], Table 1-5

OpqCld uncert (code)

See [1], Table 1-6

temp_air†

Dry bulb temperature at the time indicated, deg C

Dry-bulb source

See [1], Table 1-5

Dry-bulb uncert (code)

See [1], Table 1-6

temp_dew†

Dew-point temperature at the time indicated, deg C

Dew-point source

See [1], Table 1-5

Dew-point uncert (code)

See [1], Table 1-6

relative_humidity†

Relatitudeive humidity at the time indicated, percent

RHum source

See [1], Table 1-5

RHum uncert (code)

See [1], Table 1-6

pressure†

Station pressure at the time indicated, 1 mbar

Pressure source

See [1], Table 1-5

Pressure uncert (code)

See [1], Table 1-6

wind_direction†

Wind direction at time indicated, degrees from north (360 = north; 0 = undefined,calm)

Wdir source

See [1], Table 1-5

Wdir uncert (code)

See [1], Table 1-6

wind_speed†

Wind speed at the time indicated, meter/second

Wspd source

See [1], Table 1-5

Wspd uncert (code)

See [1], Table 1-6

Hvis (m)

Distance to discernable remote objects at time indicated (7777=unlimited), meter

Hvis source

See [1], Table 1-5

Hvis uncert (coe)

See [1], Table 1-6

CeilHgt (m)

Height of cloud base above local terrain (7777=unlimited), meter

CeilHgt source

See [1], Table 1-5

CeilHgt uncert (code)

See [1], Table 1-6

precipitable_water†

Total precipitable water contained in a column of unit cross section from earth to top of atmosphere, cm

Pwat source

See [1], Table 1-5

Pwat uncert (code)

See [1], Table 1-6

AOD

The broadband aerosol optical depth per unit of air mass due to extinction by aerosol component of atmosphere, unitless

AOD source

See [1], Table 1-5

AOD uncert (code)

See [1], Table 1-6

albedo†

The ratio of reflected solar irradiance to global horizontal irradiance, unitless

Alb source

See [1], Table 1-5

Alb uncert (code)

See [1], Table 1-6

Lprecip depth (mm)

The amount of liquid precipitation observed at indicated time for the period indicated in the liquid precipitation quantity field, millimeter

Lprecip quantity (hr)

The period of accumulatitudeion for the liquid precipitation depth field, hour

Lprecip source

See [1], Table 1-5

Lprecip uncert (code)

See [1], Table 1-6

PresWth (METAR code)

Present weather code, see [2].

PresWth source

Present weather code source, see [2].

PresWth uncert (code)

Present weather code uncertainty, see [2].

Midnight representation

The function is able to handle midnight represented as 24:00 (NREL TMY3 format, see [1]) and as 00:00 (SolarAnywhere TMY3 format, see [3]).

Warning

TMY3 irradiance data corresponds to the previous hour, so the first index is 1AM, corresponding to the irradiance from midnight to 1AM, and the last index is midnight of the next year. For example, if the last index in the TMY3 file was 1988-12-31 24:00:00 this becomes 1989-01-01 00:00:00 after calling read_tmy3().

Warning

When coercing the year, the last index in the dataframe will become midnight of the next year. For example, if the last index in the TMY3 was 1988-12-31 24:00:00, and year is coerced to 1990 then this becomes 1991-01-01 00:00:00.

References

Examples using pvlib.iotools.read_tmy3#

Simulating PV system DC output using the ADR module efficiency model

Simulating PV system DC output using the ADR module efficiency model

Calculating daily diffuse PAR using Spitter’s relationship

Calculating daily diffuse PAR using Spitter's relationship

Temperature modeling for floating PV

Temperature modeling for floating PV

Diffuse Fraction Estimation

Diffuse Fraction Estimation

Reverse transposition using one year of hourly data

Reverse transposition using one year of hourly data

Seasonal Tilt

Seasonal Tilt

Use different Perez coefficients with the ModelChain

Use different Perez coefficients with the ModelChain

Modeling Transposition Gain

Modeling Transposition Gain

Kimber Soiling Model

Kimber Soiling Model

Spectral Mismatch Estimation

Spectral Mismatch Estimation