eplusr (version 0.9.4)

Epw: Read, and modify an EnergyPlus Weather File (EPW)

Description

Reading an EPW file starts with function read_epw(), which parses an EPW file and returns an Epw object. The parsing process is extremely inspired by OpenStudio utilities library with some simplifications.

Usage

epw <- read_epw(path)
epw$city
epw$city <- "city"
epw$state_province
epw$state_province <- "state_province"
epw$country
epw$country <- "country"
epw$data_source
epw$data_source <- "data_source"
epw$wmo_number
epw$wmo_number <- "wmo_number"
epw$latitude
epw$latitude <- "latitude"
epw$longitute
epw$longitute <- "longitute"
epw$time_zone
epw$time_zone <- "time_zone"
epw$elevation
epw$elevation <- "elevation"
epw$time_step
epw$time_step <- "time_step"
epw$start_day_of_week
epw$start_day_of_week <- "start_day_of_week"
epw$path()
epw$get_data(year = NULL, unit = FALSE, tz = Sys.timezone(), update = FALSE)
epw$set_data(data)
epw$save(path, overwrite = FALSE)
epw$clone(deep = FALSE)
epw$print()
print(epw)

Read

epw <- read_epw(path)

Arguments

• path: Path of an EnergyPlus EPW file.

Query and Modify Header

epw$city
epw$city <- "city"
epw$state_province
epw$state_province <- "state_province"
epw$country
epw$country <- "country"
epw$data_source
epw$data_source <- "data_source"
epw$wmo_number
epw$wmo_number <- "wmo_number"
epw$latitude
epw$latitude <- "latitude"
epw$longitute
epw$longitute <- "longitute"
epw$time_zone
epw$time_zone <- "time_zone"
epw$elevation
epw$elevation <- "elevation"
epw$time_step
epw$time_step <- "time_step"
epw$start_day_of_week
epw$start_day_of_week <- "start_day_of_week"

$city, $state_province, $country, $data_source, $wmo_number, $latitude, $longitute, $time_zone, $elevation, $time_step and $start_day_of_week are all active bindings, which means that you can get the value and also set new value to it.

NOTE: Please be super careful when trying to modify those data. Some of them must be consistent with weather data in order to make the weather file successfully parsed by EnergyPlus and eplusr.

Query and Modify Data

epw$path()
epw$get_data(year = NULL, unit = FALSE, tz = Sys.timezone(), update = FALSE)
epw$set_data(data)

$path() returns the path of EPW file. NULL if Epw is not created from local file.

$get_data() returns the core weather data in a data.table.

$set_data() replaces core weather data with input data. NOTE: This feature is experimental. There is no validation when replacing.

Arguments

• year: A integer to indicate the year value in the return datetime column. If NULL, which is the default, the year is left as it is in EPW file.

• tz: The time zone of Date and Time in datetime column. Default: value of Sys.timezone().

• unit: If TRUE, units are set to all numeric columns using units::set_units(). Default: FALSE.

• update: If TRUE, not only datetime column, but also year, month, day, hour and minute are also updated according to the input year value. Default: FALSE

• data: A data.frame which has all required columns.

Save

epw$save(path, overwrite = FALSE)

Arguments

• path: A path where to save the weather file. If NULL, the path of the weather file itself is used.

• overwrite: Whether to overwrite the file if it already exists. Default is FALSE.

Clone

epw$clone(deep = FALSE)

$clone() copies and returns the cloned Epw object. Because Epw uses R6Class under the hook which has "modify-in-place" semantics, epw_2 <- epw_1 does not copy epw_1 at all but only create a new binding to epw_1. Modify epw_1 will also affect epw_2 as well, as these two are exactly the same thing underneath. In order to create a complete cloned copy, please use $clone(deep = TRUE).

Arguments

• deep: Has to be TRUE if a complete cloned copy is desired.

Details

An EPW file can be divided into two parts, headers and weather data. The first eight lines of a standard EPW file are normally headers which contains data of location, design conditions, typical/extreme periods, ground temperatures, holidays/daylight savings, data periods and other comments. For now, eplusr only parses headers of location, holidays/daylight savings and data periods. All other headers are left as they were when parsing and saving. For details on the data structure of EPW file, please see "Chapter 2 - Weather Converter Program" in EnergyPlus "Auxiliary Programs" documentation. An online version can be found here.

There are about 35 variables in the core weather data. However, not all of them are used by EnergyPlus. Actually, despite of date and time columns, only 14 columns are used:

1. dry bulb temperature

2. dew point temperature

3. relative humidity

4. atmospheric pressure

5. horizontal infrared radiation intensity from sky

6. direct normal radiation

7. diffuse horizontal radiation

8. wind direction

9. wind speed

10. present weather observation

11. present weather codes

12. snow depth

13. liquid precipitation depth

14. liquid precipitation rate

NOTE: Even though Epw class provides methods to replace core weather data, it is still not recommended.

Examples

# NOT RUN {
# read an EPW file from EnergyPlus website
path_base <- "https://energyplus.net/weather-download"
path_region <- "north_and_central_america_wmo_region_4/USA/CA"
path_file <- "USA_CA_San.Francisco.Intl.AP.724940_TMY3/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw"
path_epw <- file.path(path_base, path_region, path_file)
epw <- read_epw(path_epw)

# read an EPW file distributed with EnergyPlus
if (is_avail_eplus(8.8)) {
    epw_path <- file.path(
        eplus_config(8.8)$dir,
        "WeatherData",
        "USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw"
    )
    epw <- read_epw(path_epw)
}

# get file path
epw$path()

# get basic info
epw$city
epw$state_province
epw$country
epw$data_source
epw$wmo_number
epw$latitude
epw$longitude
epw$time_zone
epw$elevation
epw$time_step
epw$start_day_of_week

# set basic info
# NOTE: Use with caution. May mess up your weather data
epw$city <- "Chongqing"
epw$city

epw$state_province <- "Chongqing"
epw$state_province

epw$country <- "China"
epw$country

epw$data_source <- "TMY"
epw$data_source

epw$wmo_number <- "724944"
epw$wmo_number

epw$latitude <- 20.0
epw$latitude

epw$longitude <- -120.0
epw$longitude

epw$time_zone <- 8
epw$time_zone

epw$elevation <- 100
epw$elevation

epw$time_step <- 2
epw$time_step

epw$start_day_of_week <- "Monday"
epw$start_day_of_week

# get weather data
str(epw$get_data())

# get weather data but change the year to 2018
# the year column is not changed by default, only the returned datetime column
str(epw$get_data(year = 2018)$datetime)
str(epw$get_data(year = 2018)$year)
# you can force to update the year column
str(epw$get_data(year = 2018, update = TRUE)$year)

# get weather data with units
str(epw$get_data(unit = TRUE))
# with units specified, you can easily perform unit conversion using units
# package
t_dry_bulb <- epw$get_data(unit = TRUE)$dry_bulb_temperature
units(t_dry_bulb) <- with(units::ud_units, "kelvin")
str(t_dry_bulb)

# change the time zone of datetime column in the returned weather data
attributes(epw$get_data()$datetime)
attributes(epw$get_data(tz = "America/Chicago")$datetime)

# change the weather data
# NOTE: This feature is experimental. There is no validation when replacing.
epw$set_data(epw$get_data())
# save the weather file
epw$save(file.path(tempdir(), "weather.epw"))
# }