API Docs

Class: WeatherData

PD. WeatherData

Stores and manages annual hourly weather data.

Annual hourly weather data is basically a series of large arrays, each containing 8760 (365x24) hourly data points. To standardise calculations, this class stores an array for each of the measurable weather data metrics found in the EnergyPlus Weather File (EPW) format.

new WeatherData( [config])

Creates a new annual hourly weather data store.

Parameters:
Name Type Argument Description
config object <optional>

An optional configuration object.
Properties of config:
Name Type Argument Description
stationName string <optional>

The name of the weather station.
stateOrRegion number <optional>

The state, province or region of the weather station.
country number <optional>

The country of the weather station.
WMO number <optional>

The World Meteorological Organization (WMO) station identifier.
latitude number <optional>

The terrestrial latitude of the weather station, in decimal degrees.
longitude number <optional>

The terrestrial longitude of the weather station, in decimal degrees.
timezone number <optional>

The local time zone at the weather station, in decimal hours.
northAngle number <optional>

The angle between north and the +Y axis, in decimal degrees.
elevation number <optional>

The average height of the station above sea level, in metres.
Author:
  • drajmarsh

Extends

Members

:string

WMO

The World Meteorological Organization (WMO) station identifier.

Type
  • string

annualHourly

Stores the available weather data as 24 hourly values for 365 days.

Each metric is stored as array with 365 entries, each containing an array of 24 hourly decimal data values.

Properties:
Name Type Description
tempDryBulb Array

Dry Bulb Temperature (°C)
tempDewPoint Array

Dew Point Temperature (°C).
relHumidity Array

Relative Humidity (%).
atmPressure Array

Atmospheric Pressure (Pa).
extRadHorizontal Array

Extraterrestrial Horizontal Radiation (Wh/m2).
extRadDirectBeam Array

Extraterrestrial Direct Normal Radiation (Wh/m2).
infraRedHorizontal Array

Horizontal Infrared Radiation from Sky (Wh/m2).
solarGlobalHorizontal Array

Global Horizontal Radiation (Wh/m2).
solarDirectBeam Array

Direct Normal Radiation (Wh/m2).
solarDiffuseHorizontal Array

Diffuse Horizontal Radiation (Wh/m2).
illumGlobalHorizontal Array

Global Horizontal Illuminance (Lux).
illumDirectBeam Array

Direct Normal Illuminance (Lux).
illumDiffuseHorizontal Array

Diffuse Horizontal Illuminance (Lux).
zenithLuminance Array

Zenith Luminance (cd/m2).
windDirection Array

Wind Direction (deg).
windSpeed Array

Wind Speed (m/s).
cloudCover Array

Total Cloud Cover (%).
cloudOpaque Array

Opaque Sky Cover (%).
visibility Array

Visibility (km).
ceilingHeight Array

Ceiling Height (m).
precipitableWater Array

Precipitable Water (mm).
aerosolOpticalDepth Array

Aerosol Optical Depth (thou).
snowDepth Array

Snow Depth (cm).
snowDaysSince Array

Days Since Last Snowfall (days).
albedo Array

Albedo (0-1).
precipitationDepth Array

Precipitation Depth (mm).
:string

country

The country of the weather station.

Type
  • string
:boolean

dayCount

Whether or not the data is for a leap year with 366 days.

Type
  • boolean
:number

elevation

The average height of the site above sea level, in metres.

Type
  • number
Inherited From:
Overrides:
:boolean

isLocation <readonly>

A flag identifying this object as a location.

Type
  • boolean
Inherited From:
Overrides:
:boolean

isWeatherData <readonly>

A flag identifying this object as a weather data store.

Type
  • boolean
:number

latitude

The terrestrial latitude of the current location, in decimal degrees.

Type
  • number
Inherited From:
Overrides:
:boolean

leapYear

Whether or not the data is for a leap year with 366 days.

Type
  • boolean
:number

longitude

The terrestrial longitude of the current location, in decimal degrees.

Type
  • number
Inherited From:
Overrides:
:number

northAngle

The angle between north and the +Y axis, in decimal degrees.

Type
  • number
Inherited From:
Overrides:
:string

stateOrRegion

The state, province or region of the weather station.

Type
  • string
:string

stationName

The name of the weather station.

Type
  • string
:number

timezone

The local time zone at the current location, in decimal hours.

Type
  • number
Inherited From:
Overrides:

Methods

calc30DayMeanOutdoorTemperature(day)

Calculates the ASHRAE mean monthly outdoor temperature for the given date.

This is the arithmetic average of the means of the daily minimum and daily maximum temperature for the preceding 30 days.

Parameters:
Name Type Description
day number

The numeric index of the day in the year (0 to 364).
Returns:

Returns the running mean outdoor temperature (degC).

Type
number

calcAverageTemperatureAtHour(from_day, to_day, hour)

Calculates the average temperature for the given hour over the date range.

Parameters:
Name Type Description
from_day number

The numeric index of the day in the year to start at (0 to 364/5).
to_day number

The numeric index of the day in the year to end at (0 to 364/5).
hour number

The hour of the day to calculate, in decimal hours (0 tp 24).
Returns:

Returns the calculated average outdoor temperature (degC).

Type
number

calcAverageTemperatureOverPeriod(day [, day_count])

Calculates a running mean outdoor temperature for the given date.

Parameters:
Name Type Argument Description
day number

The numeric index of the day in the year (0 to 364).
day_count number <optional>

An optional number of prior days to include in mean, defaults to 30.
Returns:

Returns the running mean outdoor temperature (degC).

Type
number

calcWindFrequencyData(range, angleBand, speedBand)

Computes wind speed/direction frequency data for the given date/time range.

This method calculates the frequency of wind speed and direction data for the given date/time range. The data is returned as an object with the following properties:

{
    windRose: [ [0.012, 0.026, ...], [0.002, 0.009, ...], ...],
    angleIncrementsInDegrees: 30.0, // computed `angleBand`.
    speedIncrementsInKmh: 10.0, // computed `speedBand`.
    totalHours: 8760,
    calmHours: 641,
    maxValue: 0.13
}

The windRose property is an array of arrays, with an array for each angular segment containing the fractional number of hours at each wind speed band, from lowest speed to highest speed. Any time wind speed is below 1 kilometer per hour, it is considered to be calm with no discernable direction so is added to the calmHours property.

You can give the wind speed band as an array of wind speed thresholds in kilometers per hour if you need irregular sized speed bands. If you pass an empty array, the speed bands will default to the Beaufort scale.

Parameters:
Name Type Description
range PD.DateTimeRange

The date/time range over which to calculate.
angleBand number

The preferred angle of each band in degrees, will be rounded to evenly divide into 360, defaults to 30deg (12 bands).
speedBand number | Array.<number>

The preferred wind speed of each band in kilometers per hour or an array of speed band threshold values, defaults to 10km/h bands. If you need knots, m/s or mph, convert the required value to km/h.
Returns:

Returns an object with totalHours and calmHours properties, as well as windRose with an array of angular bands, each with entries for hourly frequencies by speed band.

Type
object

closeTo(latitude, longitude [, timezone])

Determines if this location is sufficiently close to the given location to be considered effectively equal.

This method checks if the given latitude and longitude values are within 1e-6 degrees of this location, and that the timezone (if given) is within 1 minute of this location's timezone. A threshold of 1e-6 degrees represents a terrestrial distance of about 0.1 metre (4 inches) at sea level.

Parameters:
Name Type Argument Description
latitude number

The geographic latitude above the equator, in decimal degrees (-90 to 90).
longitude number

The geographic longitude west of the prime meridian, in decimal degrees (-180 to 180).
timezone number <optional>

The timezone in decimal hours (-12 to +13), ignored if not given.
Inherited From:
Overrides:
Returns:

Returns true if the given values are very close (within 1e-6 degrees).

Type
boolean

copy(from)

Copy the given location to this location.

Parameters:
Name Type Description
from PD.Location

Another location instance to copy from.
Inherited From:
Overrides:
Returns:

Returns this location instance to support method chaining.

Type
PD.Location

distanceTo(loc)

Estimates the terrestrial distance to the given location on the Earth's surface.

This uses the static PD.Location.terrestrialDistance method which is based on the haversine formula for calculating the great-circle distance between two given terrestrial locations. This is basically the shortest distance over the Earth’s surface 'as-the-crow-flies' between the two locations, ignoring any hills or valleys they may fly over.

Parameters:
Name Type Description
loc PD.Location

The target location.
Inherited From:
Overrides:
Returns:

Returns the computed distance 'as-the-crow-flies' over the Earth's surface, in metres.

Type
number

distanceToLatLng(latitude, longitude)

Estimates the terrestrial distance to the given location on the Earth's surface.

This uses the static PD.Location.terrestrialDistance method which is based on the haversine formula for calculating the great-circle distance between two given terrestrial locations. This is basically the shortest distance over the Earth’s surface 'as-the-crow-flies' between the two locations, ignoring any hills or valleys they may fly over.

Parameters:
Name Type Description
latitude number

The target geographic latitude above the equator, in decimal degrees (-90 to 90).
longitude number

The target geographic longitude west of the prime meridian, in decimal degrees (-180 to 180).
Inherited From:
Overrides:
Returns:

Returns the computed distance 'as-the-crow-flies' over the Earth's surface, in metres.

Type
number

fromJSON(data)

Extracts weather station and location information from the given object.

Parameters:
Name Type Description
data object

An object that might contain location information.
Properties of data:
Name Type Argument Description
stationName string <optional>

The name of the weather station.
stateOrRegion number <optional>

The state, province or region of the weather station.
country number <optional>

The country of the weather station.
WMO number <optional>

The World Meteorological Organization (WMO) station identifier.
latitude number <optional>

An optional terrestrial latitude of the current location, in decimal degrees.
longitude number <optional>

An optional terrestrial longitude of the current location, in decimal degrees.
timezone number <optional>

An optional local time zone at the current location, in decimal hours
northAngle number <optional>

An optional angle between north and the +Y axis, in decimal degrees.
elevation number <optional>

An optional average height of the site above sea level, in metres.
Inherited From:
Overrides:
Returns:

Returns true if any matching data was found, or false if nothing was copied.

getData(metric)

Returns the annual data array for the given metric.

You can use the PD.WEATHERDATA index values to specify the metric you require.

The returned array should contain 365/6 x 24hr data values ([day][hr]) and can be used directly with the PD.WeatherData#getSubHourlyValue and PD.WeatherData#getValue methods.

Parameters:
Name Type Description
metric PD.WEATHERDATA

The weather data metric index (0-25).
Returns:

Returns an array of 365/6 x 24hr data values ([day][hr]).

Type
Array.<Array.<number>>

getMetric(metric)

Returns data and metadata for the given metric.

You can use the PD.WEATHERDATA index values to specify the metric you require.

The returned object has the following properties:

NAME TYPE DESCRIPTION
data Array[] An array of 365/6 x 24hr data values ([day][hr]).
name string A human-readable name for the given metric.
shortName string An abbreviated but still readable name for the metric.
abbrev string A very short, typically 3 letter data type identifier.
units string A human-readable string with the metric units.
min number The minimum bounds of the data range for this metric.
max number The maximum bounds of the data range for this metric.
step number A recommended step increment value for this range.
Parameters:
Name Type Description
metric PD.WEATHERDATA

The weather data metric index (0-25).
Returns:

Returns a simple meta-data object.

Type
object
Example
let day = 90;
let hour = 12;
let metric = PD.WeatherData.getMetric(PD.WEATHERDATA.DRY_BULB);
let t = metric.data[day][hour];

getSubHourlyValue(data, day, hour)

Returns a data value interpolated between integer hourly values.

Parameters:
Name Type Description
data Array

An array with 365 24hr data values.
day number

The numeric index of the day in the year (0 to 364).
hour number

The decimal hour of the day (0.0 to 23.999).
Returns:

Returns the interpolated data sub-hourly value.

Type
number

getValue(data, day, hour)

Returns a data value at the given integer day/hour values.

Parameters:
Name Type Description
data Array

An array with 365 24hr data values.
day number

The numeric index of the day in the year (0 to 364).
hour number

The numeric indx of the hour in the day (0 to 23).
Returns:

Returns the hourly data value.

Type
number

parseEPW(text [, options])

Imports an EnergyPlus Weather File (EPW).

Parameters:
Name Type Argument Description
text string | FileReader

The textual contents of the EPW file.
options object <optional>

Optional configuration callbacks and conversion options.
Properties of options:
Name Type Argument Description
progressIncrement number <optional>

An optional fractional progress rate for callbacks.
callbackProgress function <optional>

An optional function to call after each progress increment.
callbackComplete function <optional>

An optional function to call when parsing is complete.
debug boolean <optional>

An optional flag to show parsing time in the console.
Throws:

Occurs if the EPW file is empty or invalid.

Type
TypeError
Returns:

Returns true if the EPW file contained recognizable data.

Type
boolean

parseWEA(text)

Imports a DAYSIM Solar Radiation Weather File (WEA).

Parameters:
Name Type Description
text string

The textual contents of the WEA file.
Throws:

Occurs if the WEA file is empty or invalid.

Type
TypeError
Returns:

Returns true if the WEA file contained recognizable data.

Type
boolean

set(latitude, longitude, timezone)

Sets the geographic location to calculate solar positions for.

Parameters:
Name Type Description
latitude number

The geographic latitude above the equator, in decimal degrees (-90 to 90).
longitude number

The geographic longitude west of the prime meridian, in decimal degrees (-180 to 180).
timezone number

The difference between local time at the location and UTC, in decimal hours (-13.0 to 13.0). The value should be positive for all time zone behind/east of UTC and negative for ahead/west.
Inherited From:
Overrides:
Returns:

Returns this solar calculator to support method chaining.

Type
PD.Location

setValuesFromArray(data, array)

Copies a flat annual hourly array to annual day/hour values.

Parameters:
Name Type Description
data Array

An array to receive the 365/366 24hr data values.
array Array

The flat data array, must contain at least 8760 values.
Throws:

Throws an error if either array is invalid or if flat array has less than a full year's worth of hourly data values (8760).

Type
Error
Returns:

Returns this weather object to support method chaining.

toJSON( [data])

Converts object instance to a simple POJO for conversion to JSON.

This method is used to copy, store and save the data for this object, so the returned object must have all the properties required be able to rebuild this instance in its entirety when passed to the class constructor.

Parameters:
Name Type Argument Description
data object <optional>

An optional parent object to append this data to.
Inherited From:
Overrides:
Returns:

Returns a Plain Old Javascript Object (POJO).

Type
object