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

Epw {eplusr}

R Documentation

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 basically the same as [EnergyPlus/WeatherManager.cc] in EnergyPlus, with some simplifications.

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. Epw class provides methods to directly extract those data. 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 13 columns are used:

dry bulb temperature
dew point temperature
relative humidity
atmospheric pressure
horizontal infrared radiation intensity from sky
direct normal radiation
diffuse horizontal radiation
wind direction
wind speed
present weather observation
present weather codes
snow depth
liquid precipitation depth

Note the hour column in the core weather data corresponds to the period from (Hour-1)th to (Hour)th. For instance, if the number of interval per hour is 1, hour of 1 on a certain day corresponds to the period between 00:00:01 to 01:00:00, Hour of 2 corresponds to the period between 01:00:01 to 02:00:00, and etc. Currently, in EnergyPlus the minute column is not used to determine currently sub-hour time. For instance, if the number of interval per hour is 2, there is no difference between two rows with following time columns (a) Hour 1, Minute 0; Hour 1, Minute 30 and (b) Hour 1, Minute 30; Hour 1, Minute 60. Only the number of rows count. When EnergyPlus reads the EPW file, both (a) and (b) represent the same time period: 00:00:00 - 00:30:00 and 00:30:00 - 01:00:00. Missing data on the weather file used can be summarized in the eplusout.err file, if DisplayWeatherMissingDataWarnings is turned on in Output:Diagnostics object. In EnergyPlus, missing data is shown only for fields that EnergyPlus will use. EnergyPlus will fill some missing data automatically during simulation. Likewise out of range values are counted for each occurrence and summarized. However, note that the out of range values will not be changed by EnergyPlus and could affect your simulation.

Epw class provides methods to easily extract and inspect those abnormal (missing and out of range) weather data and also to know what kind of actions that EnergyPlus will perform on those data.

EnergyPlus energy model calibration often uses actual measured weather data. In order to streamline the error-prone process of creating custom EPW file, Epw provides methods to direction add, replace the core weather data.

Methods

Public methods

Epw$new()
Epw$path()
Epw$definition()
Epw$location()
Epw$design_condition()
Epw$typical_extreme_period()
Epw$ground_temperature()
Epw$holiday()
Epw$comment1()
Epw$comment2()
Epw$num_period()
Epw$interval()
Epw$period()
Epw$missing_code()
Epw$initial_missing_value()
Epw$range_exist()
Epw$range_valid()
Epw$fill_action()
Epw$data()
Epw$abnormal_data()
Epw$redundant_data()
Epw$make_na()
Epw$fill_abnormal()
Epw$add_unit()
Epw$drop_unit()
Epw$purge()
Epw$add()
Epw$set()
Epw$del()
Epw$is_unsaved()
Epw$save()
Epw$print()
Epw$clone()

Method `new()`

Create an Epw object

Usage

Epw$new(path, encoding = "unknown")

Arguments

path: Either a path, a connection, or literal data (either a single string or a raw vector) to an EnergyPlus Weather File (EPW). If a file path, that file usually has a extension .epw.
encoding: The file encoding of input IDD. Should be one of "unknown", ⁠"Latin-1" and ⁠"UTF-8"⁠. The default is ⁠"unknown"' which means that the file is encoded in the native encoding.

Details

It takes an EnergyPlus Weather File (EPW) as input and returns an Epw object.

Returns

An Epw object.

Examples

\dontrun{
# 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)) {
    path_epw <- file.path(
        eplus_config(8.8)$dir,
        "WeatherData",
        "USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw"
    )
    epw <- read_epw(path_epw)
}
}

Method `path()`

Get the file path of current Epw

Usage

Epw$path()

Details

⁠$path()⁠ returns the full path of current Epw or NULL if the Epw object is created using a character vector and not saved locally.

Returns

NULL or a single string.

Examples

\dontrun{
# get path
epw$path()
}

Method `definition()`

Get the IddObject object for specified EPW class.

Usage

Epw$definition(class)

Arguments

class: A single string.

Details

⁠$definition()⁠ returns an IddObject of given EPW class. IddObject contains all data used for parsing that EPW class.

Currently, all supported EPW classes are:

LOCATION
⁠DESIGN CONDITIONS⁠
⁠TYPICAL/EXTREME PERIODS⁠
⁠GROUND TEMPERATURES⁠
⁠HOLIDAYS/DAYLIGHT SAVINGS⁠
⁠COMMENTS 1⁠
⁠COMMENTS 2⁠
⁠DATA PERIODS⁠
⁠WEATHER DATA⁠

Examples

\dontrun{
# get path
epw$definition("LOCATION")
}

Method `location()`

Get and modify LOCATION header

Usage

Epw$location(
  city,
  state_province,
  country,
  data_source,
  wmo_number,
  latitude,
  longitude,
  time_zone,
  elevation
)

Arguments

city: A string of city name recorded in the LOCATION header.
state_province: A string of state or province name recorded in the LOCATION header.
country: A string of country name recorded in the LOCATION header.
data_source: A string of data source recorded in the LOCATION header.
wmo_number: A string of WMO (World Meteorological Organization) number recorded in the LOCATION header.
latitude: A number of latitude recorded in the LOCATION header. North latitude is positive and south latitude is negative. Should in range ⁠[-90, +90]⁠.
longitude: A number of longitude recorded in the LOCATION header. East longitude is positive and west longitude is negative. Should in range ⁠[-180, +180]⁠.
time_zone: A number of time zone recorded in the LOCATION header. Usually presented as the offset hours from UTC time. Should in range ⁠[-12, +14]⁠.
elevation: A number of elevation recorded in the LOCATION header. Should in range ⁠[-1000, 9999.9)⁠.

Details

⁠$location()⁠ takes new values for LOCATION header fields and returns the parsed values of LOCATION header in a list format. If no input is given, current LOCATION header value is returned.

Returns

A named list of 9 elements.

Examples

\dontrun{
epw$location()

# modify location data
epw$location(city = "MyCity")
}

Method `design_condition()`

Get DESIGN CONDITION header

Usage

Epw$design_condition()

Details

⁠$design_condition()⁠ returns the parsed values of ⁠DESIGN CONDITION⁠ header in a list format with 4 elements:

source: A string of source field
heating: A list, usually of length 16, of the heading design conditions
cooling: A list, usually of length 32, of the cooling design conditions
extremes: A list, usually of length 16, of the extreme design conditions

For the meaning of each element, please see ASHRAE Handbook of Fundamentals.

Returns

A named list of 4 elements.

Examples

\dontrun{
epw$design_condition()
}

Method `typical_extreme_period()`

Get TYPICAL/EXTREME header

Usage

Epw$typical_extreme_period()

Details

⁠$typical_extreme_period()⁠ returns the parsed values of ⁠TYPICAL/EXTREME PERIOD⁠ header in a data.table format with 6 columns:

index: Integer type. The index of typical or extreme period record
name: Character type. The name of typical or extreme period record
type: Character type. The type of period. Possible value: typical and extreme
start_day: Date type with customized formatting. The start day of the period
start_day: Date type with customized formatting. The end day of the period

Returns

A data.table::data.table() with 6 columns.

Examples

\dontrun{
epw$typical_extreme_period()
}

Method `ground_temperature()`

Get GROUND TEMPERATURE header

Usage

Epw$ground_temperature()

Details

⁠$ground_temperature()⁠ returns the parsed values of ⁠GROUND TEMPERATURE⁠ header in a data.table format with 17 columns:

index: Integer type. The index of ground temperature record
depth: Numeric type. The depth of the ground temperature is measured
soil_conductivity: Numeric type. The soil conductivity at measured depth
soil_density: Numeric type. The soil density at measured depth
⁠soil_specific heat⁠: Numeric type. The soil specific heat at measured depth
January to December: Numeric type. The measured group temperature for each month.

Returns

A data.table::data.table() with 17 columns.

Examples

\dontrun{
epw$ground_temperature()
}

Method `holiday()`

Get and modify HOLIDAYS/DAYLIGHT SAVINGS header

Usage

Epw$holiday(leapyear, dst, holiday)

Arguments

leapyear

Either TRUE or FALSE.

dst

A length 2 EPW date specifications identifying the start and end of daylight saving time. For example, c(3.10, 10.3).

holiday

a list or a data.frame containing two elements (columns) name and day where name are the holiday names and day are valid EPW date specifications. For example:

list(name = c("New Year's Day", "Christmas Day"), day = c("1.1", "25 Dec"))

Details

⁠$holiday()⁠ takes new value for leap year indicator, daylight saving time and holiday specifications, set these new values and returns the parsed values of ⁠HOLIDAYS/DAYLIGHT SAVINGS⁠ header. If no input is given, current values of ⁠HOLIDAYS/DAYLIGHT SAVINGS⁠ header is returned. It returns a list of 3 elements:

leapyear: A single logical vector. TRUE means that the weather data contains leap year data
dst: A Date vector contains the start and end day of daylight saving time
holiday: A data.table contains 2 columns. If no holiday specified, an empty data.table
- name: Name of the holiday
- day: Date of the holiday

Validation process below is performed when changing the leapyear indicator:

If current record of leapyear is TRUE, but new input is FALSE, the modification is only conducted when all data periods do not cover Feb 29.
If current record of leapyear is FALSE, but new input is TRUE, the modification is only conducted when TMY data periods do not across Feb, e.g. [01/02, 02/28], [03/01, 12/31]; for AMY data, it is always OK.

The date specifications in dst and holiday should follow the rules of "Table 2.14: Weather File Date File Interpretation" in "AuxiliaryPrograms" documentation. eplusr is able to handle all those kinds of formats automatically. Basically, 5 formats are allowed:

A single integer is interpreted as the Julian day of year. For example, 1, 2, 3 and 4 will be parsed and presented as ⁠1st day⁠, ⁠2nd day⁠, ⁠3rd day⁠ and ⁠4th day⁠.
A single number is interpreted as Month.Day. For example, 1.2 and 5.6 will be parsed and presented as ⁠Jan 02⁠ and ⁠May 06⁠.
A string giving MonthName / DayNumber, DayNumber / MonthName, and MonthNumber / DayNumber. A year number can be also included. For example, "Jan/1", "05/Dec", "7/8", "02/10/2019", and "2019/04/05" will be parsed and presented as ⁠Jan 02⁠, ⁠Dec 06⁠, ⁠Jul 8⁠, 2019-02-10 and 2019-04-15.
A string giving ⁠number Weekday in Month⁠. For example, "2 Sunday in Jan" will be parsed and presented as ⁠2th Sunday in January⁠.
A string giving ⁠Last Weekday in Month⁠. For example, "last Sunday in Dec" will be parsed and presented as ⁠Last Sunday in December⁠.

For convenience, besides all the formats described above, dst and days in holiday also accept standard Dates input. They will be treated as the same way as No.3 format described above.

Returns

A named list of 3 elements.

Examples

\dontrun{
epw$holiday()

# add daylight saving time
epw$holiday(dst = c(3.10, 11.3))
}

Method `comment1()`

Get and modify COMMENT1 header

Usage

Epw$comment1(comment)

Arguments

comment: A string of new comments.

Details

⁠$comment1()⁠ takes a single string of new comments and replaces the old comment with input one. If NULL is given, the comment is removed. Empty string or a string that contains only spaces will be treated as NULL. If no input is given, current comment is returned. If no comments exist, NULL is returned.

Returns

A single string.

Examples

\dontrun{
epw$comment1()

epw$comment1("Comment1")
}

Method `comment2()`

Get and modify COMMENT2 header

Usage

Epw$comment2(comment)

Arguments

comment: A string of new comments.

Details

⁠$comment2()⁠ takes a single string of new comments and replaces the old comment with input one. If NULL is given, the comment is removed. Empty string or a string that contains only spaces will be treated as NULL. If no input is given, current comment is returned. If no comments exist, NULL is returned.

Returns

A single string.

Examples

\dontrun{
epw$comment2()

epw$comment2("Comment2")
}

Method `num_period()`

Get number of data periods in DATA PERIODS header

Usage

Epw$num_period()

Details

⁠$num_period()⁠ returns a single positive integer of how many data periods current Epw contains.

Returns

A single integer.

Examples

\dontrun{
epw$num_period()
}

Method `interval()`

Get the time interval in DATA PERIODS header

Usage

Epw$interval()

Details

⁠$interval()⁠ returns a single positive integer of how many records of weather data exist in one hour.

Returns

A single integer.

Examples

\dontrun{
epw$interval()
}

Method `period()`

Get and modify data period meta data in DATA PERIODS header

Usage

Epw$period(period, name, start_day_of_week)

Arguments

period: A positive integer vector identifying the data period indexes.
name: A character vector used as new names for specified data periods. Should have the same length as index.
start_day_of_week: A character vector or an integer vector used as the new start days of week of specified data periods. Should have the same length as index.

Details

⁠$period()⁠ takes a data period index, a new period name and start day of week specification, and uses that input to replace the data period's name and start day of week. If no input is given, data periods in current Epw is returned.

Returns

A data.table with 5 columns:

index: Integer type. The index of data period.
name: Character type. The name of data period.
start_day_of_week: Character type. The start day of week of data period.
start_day: Date (EpwDate) type. The start day of data period.
end_day: Date (EpwDate) type. The end day of data period.

Examples

\dontrun{
# modify data period name
epw$period(1, name = "test")

# change start day of week
epw$period(1, start_day_of_week = 3)
}

Method `missing_code()`

Get missing code for weather data variables

Usage

Epw$missing_code()

Details

⁠$missing_code()⁠ returns a list of 29 elements containing the value used as missing value identifier for all weather data.

Returns

A named list of 29 elements.

Examples

\dontrun{
epw$missing_code()
}

Method `initial_missing_value()`

Get initial value for missing data of weather data variables

Usage

Epw$initial_missing_value()

Details

⁠$initial_missing_value()⁠ returns a list of 16 elements containing the initial value used to replace missing values for corresponding weather data.

Returns

A named list of 16 elements.

Examples

\dontrun{
epw$initial_missing_value()
}

Method `range_exist()`

Get value ranges for existing values of weather data variables

Usage

Epw$range_exist()

Details

⁠$range_exist()⁠ returns a list of 28 elements containing the range each numeric weather data should fall in. Any values out of this range are treated as missing.

Returns

A named list of 28 elements.

Examples

\dontrun{
epw$range_exist()
}

Method `range_valid()`

Get value ranges for valid values of weather data variables

Usage

Epw$range_valid()

Details

⁠$range_valid()⁠ returns a list of 28 elements containing the range each numeric weather data should fall in. Any values out of this range are treated as invalid.

Returns

A named list of 28 elements.

Examples

\dontrun{
epw$range_valid()
}

Method `fill_action()`

Get fill actions for abnormal values of weather data variables

Usage

Epw$fill_action(type = c("missing", "out_of_range"))

Arguments

type: What abnormal type of actions to return. Should be one of "missing" and "out_of_range". Default: "missing".

Details

⁠$fill_action()⁠ returns a list containing actions that EnergyPlus will perform when certain abnormal data found for corresponding weather data. There are 3 types of actions in total:

do_nothing: All abnormal values are left as they are.
use_zero: All abnormal values are reset to zeros.
use_previous: The first abnormal values of variables will be set to the initial missing values. All after are set to previous valid one.

Returns

A named list.

Examples

\dontrun{
epw$fill_action("missing")

epw$fill_action("out_of_range")
}

Method `data()`

Get weather data

Usage

Epw$data(
  period = 1L,
  start_year = NULL,
  align_wday = TRUE,
  tz = "UTC",
  update = FALSE,
  line = FALSE
)

Arguments

period: A single positive integer identifying the data period index. Data periods information can be obtained using $period() described above.
start_year: A positive integer identifying the year of first date time in specified data period. If NULL, the values in the year column are used as years of datetime column. Default: NULL.
align_wday: Only applicable when start_year is NULL. If TRUE, a year value is automatically calculated for specified data period that compliance with the start day of week value specified in ⁠DATA PERIODS⁠ header.
tz: A valid time zone to be assigned to the datetime column. All valid time zone names can be obtained using OlsonNames(). Default:"UTC".
update: If TRUE, the year column are updated according to the newly created datetime column using start_year. If FALSE, original year data in the Epw object is kept. Default: FALSE.
line: If TRUE, a column named line is prepended indicating the line numbers where data occur in the actual EPW file. Default: FALSE.

Details

⁠$data()⁠ returns weather data of specific data period.

Usually, EPW file downloaded from EnergyPlus website contains TMY weather data. As years of weather data is not consecutive, it may be more convenient to align the year values to be consecutive, which will makes it possible to direct analyze and plot weather data. The start_year argument in ⁠$data()⁠ method can help to achieve this. However, randomly setting the year may result in a date time series that does not have the same start day of week as specified in the ⁠DATA PERIODS⁠ header. eplusr provides a simple solution for this. By setting year to NULL and align_wday to TRUE, eplusr will calculate a year value (from current year backwards) for each data period that compliance with the start day of week restriction.

Note that if current data period contains AMY data and start_year is given, a warning is given because the actual year values will be overwritten by input start_year. An error is given if:

Using input start_year introduces invalid date time. This may happen when weather data contains leap year but input start_year is not a leap year.
Applying specified time zone specified using tz introduces invalid date time.

Returns

A data.table::data.table() of 36 columns.

Examples

\dontrun{
# get weather data
str(epw$data())

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

# change the time zone of datetime column in the returned weather data
attributes(epw$data()$datetime)
attributes(epw$data(tz = "Etc/GMT+8")$datetime)
}

Method `abnormal_data()`

Get abnormal weather data

Usage

Epw$abnormal_data(
  period = 1L,
  cols = NULL,
  keep_all = TRUE,
  type = c("both", "missing", "out_of_range")
)

Arguments

period: A single positive integer identifying the data period index. Data periods information can be obtained using $period() described above.
cols: A character vector identifying what data columns, i.e. all columns except datetime, year, month, day, hour minute, and character columns, to search abnormal values. If NULL, all data columns are used. Default: NULL.
keep_all: If TRUE, all columns are returned. If FALSE, only line, datetime, year, month, day, hour and minute, together with columns specified in cols are returned. Default: TRUE
type: What abnormal type of data to return. Should be one of "all", "missing" and "out_of_range". Default: "all".

Details

⁠$abnormal_data()⁠ returns abnormal data of specific data period. Basically, there are 2 types of abnormal data in Epw, i.e. missing values and out-of-range values. Sometimes, it may be useful to extract and inspect those data especially when inserting measured weather data. ⁠$abnormal_data()⁠ does this.

In the returned data.table::data.table(), a column named line is created indicating the line numbers where abnormal data occur in the actual EPW file.

Returns

A data.table::data.table().

Examples

\dontrun{
epw$abnormal_data()

# only check if there are any abnormal values in air temperature and
# liquid precipitation rate
epw$abnormal_data(cols = c("dry_bulb_temperature", "liquid_precip_rate"))

# save as above, but only return date time columns plus those 2 columns
epw$abnormal_data(cols = c("dry_bulb_temperature", "liquid_precip_rate"),
    keep_all = FALSE
)

# same as above, but only check for missing values
epw$abnormal_data(cols = c("dry_bulb_temperature", "liquid_precip_rate"),
    type = "missing"
)

# same as above, but only check for out-of-range values
epw$abnormal_data(cols = c("dry_bulb_temperature", "liquid_precip_rate"),
    type = "out_of_range"
)
}

Method `redundant_data()`

Get redundant weather data

Usage

Epw$redundant_data()

Details

⁠$redundant_data()⁠ returns weather data in Epw object that do not belong to any data period. This data can be further removed using $purge()' method described below.

In the returned data.table::data.table(), a column named line is created indicating the line numbers where redundant data occur in the actual EPW file.

Returns

A data.table::data.table() of 37 columns.

Examples

\dontrun{
epw$redundant_data()
}

Method `make_na()`

Convert abnormal data into NAs

Usage

Epw$make_na(missing = FALSE, out_of_range = FALSE)

Arguments

missing: If TRUE, missing values are included. Default: FALSE.
out_of_range: If TRUE, out-of-range values are included. Default: FALSE.

Details

⁠$make_na()⁠ converts specified abnormal data into NAs in specified data period. This makes it easier to find abnormal data directly using is.na() instead of using $missing_code()

⁠$make_na()⁠ and $fill_abnormal() are reversible, i.e. ⁠$make_na()⁠ can be used to counteract the effects introduced by $make_na(), and vise a versa.

Note that ⁠$make_na⁠ modify the weather data in-place, meaning that the returned data from $data() and $abnormal_data() may be different after calling ⁠$make_na()⁠.

Returns

The modified Epw object itself, invisibly.

Examples

\dontrun{
# turn all missing values into NAs
summary(epw$data()$liquid_precip_rate)
epw$make_na(missing = TRUE)
summary(epw$data()$liquid_precip_rate)
}

Method `fill_abnormal()`

Fill abnormal data using prescribed pattern

Usage

Epw$fill_abnormal(missing = FALSE, out_of_range = FALSE, special = FALSE)

Arguments

missing: If TRUE, missing values are included. Default: FALSE.
out_of_range: If TRUE, out-of-range values are included. Default: FALSE.
special: If TRUE, abnormal data are filled using corresponding actions listed $fill_action(). If FALSE, all abnormal data are fill with missing code described in $missing_code().

Details

⁠$fill_abnormal()⁠ fills specified abnormal data using corresponding actions listed in $fill_action(). For what kinds of actions to be performed, please see $fill_action(). method described above. Note that only if special is TRUE, special actions listed in ⁠$fill_action()⁠ is performed. If special is FALSE, all abnormal data, including both missing values and out-of-range values, are filled with corresponding missing codes.

$make_na() and ⁠$fill_abnormal()⁠ are reversible, i.e. $make_na() can be used to counteract the effects introduced by ⁠$fill_abnormal()⁠, and vise a versa.

Note that ⁠$fill_abnormal⁠ modify the weather data in-place, meaning that the returned data from $data() and $abnormal_data() may be different after calling ⁠$fill_abnormal()⁠.

Returns

The modified Epw object itself, invisibly.

Examples

\dontrun{
# turn all missing values into NAs
summary(epw$data()$liquid_precip_rate)
epw$fill_abnormal(missing = TRUE)
summary(epw$data()$liquid_precip_rate)
}

Method `add_unit()`

Add units to weather data variables

Usage

Epw$add_unit()

Details

⁠$add_unit()⁠ assigns units to numeric weather data using units::set_units() if applicable.

⁠$add_unit()⁠ and $drop_unit() are reversible, i.e. ⁠$add_unit()⁠ can be used to counteract the effects introduced by $drop_unit(), and vise a versa.

Note that ⁠$add_unit⁠ modify the weather data in-place, meaning that the returned data from $data() and $abnormal_data() may be different after calling ⁠$add_unit()⁠.

Returns

The modified Epw object itself, invisibly.

Examples

\dontrun{
# get weather data with units
epw$add_unit()
head(epw$data())

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

head(t_dry_bulb)
}

Method `drop_unit()`

Remove units in weather data variables

Usage

Epw$drop_unit()

Details

⁠$drop_unit()⁠ removes all units of numeric weather data.

$add_unit() and ⁠$drop_unit()⁠ are reversible, i.e. $add_unit() can be used to counteract the effects introduced by ⁠$drop_unit()⁠, and vise a versa.

Note that ⁠$add_unit⁠ modify the weather data in-place, meaning that the returned data from $data() and $abnormal_data() may be different after calling ⁠$add_unit()⁠.

Returns

The modified Epw object itself, invisibly.

Examples

\dontrun{
epw$drop_unit()
epw$data()
}

Method `purge()`

Delete redundant weather data observations

Usage

Epw$purge()

Details

⁠$purge()⁠ deletes weather data in Epw object that do not belong to any data period.

Returns

The modified Epw object itself, invisibly.

Examples

\dontrun{
epw$purge()
}

Method `add()`

Add a data period

Usage

Epw$add(
  data,
  realyear = FALSE,
  name = NULL,
  start_day_of_week = NULL,
  after = 0L
)

Arguments

data: A data.table::data.table() of new weather data to add or set. Validation is performed according to rules described above.
realyear: Whether input data is AMY data. Default: FALSE.
name: A new string used as name of added or set data period. Should not be the same as existing data period names. If NULL, it is generated automatically in format Data, Data_1 and etc., based on existing data period names. Default: NULL
start_day_of_week: A single integer or character specifying start day of week of input data period. If NULL, Sunday is used for TMY data and the actual start day of week is used for AMY data. Default: NULL.
after: A single integer identifying the index of data period where input new data period to be inserted after. IF 0, input new data period will be the first data period. Default: 0.

Details

⁠$add()⁠ adds a new data period into current Epw object at specified position.

The validity of input data is checked before adding according to rules following:

Column datetime exists and has type of POSIXct. Note that time zone of input date time will be reset to UTC.
It assumes that input data is already sorted, i.e. no further sorting is made during validation. This is because when input data is TMY data, there is no way to properly sort input data rows only using datetime column.
Number of data records per hour should be consistent across input data.
Input number of data records per hour should be the same as existing data periods.
The date time of input data should not overlap with existing data periods.
Input data should have all 29 weather data columns with correct types. The year, month, day, and minute column are not compulsory. They will be created according to values in the datetime column. Existing values will be overwritten.

Returns

The modified Epw object itself, invisibly.

Examples

\dontrun{
# will fail since date time in input data has already been covered by
# existing data period
try(epw$add(epw$data()), silent = TRUE)
}

Method `set()`

Replace a data period

Usage

Epw$set(
  data,
  realyear = FALSE,
  name = NULL,
  start_day_of_week = NULL,
  period = 1L
)

Arguments

data: A data.table::data.table() of new weather data to add or set. Validation is performed according to rules described above.
realyear: Whether input data is AMY data. Default: FALSE.
name: A new string used as name of added or set data period. Should not be the same as existing data period names. If NULL, it is generated automatically in format Data, Data_1 and etc., based on existing data period names. Default: NULL
start_day_of_week: A single integer or character specifying start day of week of input data period. If NULL, Sunday is used for TMY data and the actual start day of week is used for AMY data. Default: NULL.
period: A single integer identifying the index of data period to set.

Details

⁠$set()⁠ replaces existing data period using input new weather data.

The validity of input data is checked before replacing according to rules following:

Column datetime exists and has type of POSIXct. Note that time zone of input date time will be reset to UTC.
It assumes that input data is already sorted, i.e. no further sorting is made during validation. This is because when input data is TMY data, there is no way to properly sort input data rows only using datetime column.
Number of data records per hour should be consistent across input data.
Input number of data records per hour should be the same as existing data periods.
The date time of input data should not overlap with existing data periods.
Input data should have all 29 weather data columns with right types. The year, month, day, and minute column are not compulsory. They will be created according to values in the datetime column. Existing values will be overwritten.

Returns

The modified Epw object itself, invisibly.

Examples

\dontrun{
# change the weather data
epw$set(epw$data())
}

Method `del()`

Delete a data period

Usage

Epw$del(period)

Arguments

period: A single integer identifying the index of data period to set.

Details

⁠$del()⁠ removes a specified data period. Note that an error will be given if current Epw only contains one data period.

Returns

The modified Epw object itself, invisibly.

Method `is_unsaved()`

Check if there are unsaved changes in current Epw

Usage

Epw$is_unsaved()

Details

⁠$is_unsaved()⁠ returns TRUE if there are modifications on the Epw object since it was read or since last time it was saved, and returns FALSE otherwise.

Returns

A single logical value of TRUE or FALSE.

Examples

\dontrun{
epw$is_unsaved()
}

Method `save()`

Save Epw object as an EPW file

Usage

Epw$save(path = NULL, overwrite = FALSE, purge = FALSE, format_digit = TRUE)

Arguments

path: A path where to save the weather file. If NULL, the path of the weather file itself is used. Default: NULL.
overwrite: Whether to overwrite the file if it already exists. Default is FALSE.
purge: Whether to remove redundant data when saving. Default: FALSE.
format_digit: Whether to remove trailing digits in weather data. Default: TRUE.

Details

⁠$save()⁠ saves current Epw to an EPW file. Note that if missing values and out-of-range values are converted to NAs using $make_na(), they will be filled with corresponding missing codes during saving.

Returns

A length-one character vector, invisibly.

Examples

\dontrun{
# save the weather file
epw$save(file.path(tempdir(), "weather.epw"), overwrite = TRUE)
}

Method `print()`

Print Idf object

Usage

Epw$print()

Details

⁠$print()⁠ prints the Epw object, including location, elevation, data source, WMO station, leap year indicator, interval and data periods.

Returns

The Epw object itself, invisibly.

Examples

\dontrun{
epw$print()
}

Method `clone()`

The objects of this class are cloneable with this method.

Usage

Epw$clone(deep = TRUE)

Arguments

deep: Whether to make a deep clone.

Author(s)

Hongyuan Jia

Examples


## ------------------------------------------------
## Method `Epw$new`
## ------------------------------------------------

## 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)) {
    path_epw <- file.path(
        eplus_config(8.8)$dir,
        "WeatherData",
        "USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw"
    )
    epw <- read_epw(path_epw)
}

## End(Not run)


## ------------------------------------------------
## Method `Epw$path`
## ------------------------------------------------

## Not run: 
# get path
epw$path()

## End(Not run)


## ------------------------------------------------
## Method `Epw$definition`
## ------------------------------------------------

## Not run: 
# get path
epw$definition("LOCATION")

## End(Not run)


## ------------------------------------------------
## Method `Epw$location`
## ------------------------------------------------

## Not run: 
epw$location()

# modify location data
epw$location(city = "MyCity")

## End(Not run)


## ------------------------------------------------
## Method `Epw$design_condition`
## ------------------------------------------------

## Not run: 
epw$design_condition()

## End(Not run)


## ------------------------------------------------
## Method `Epw$typical_extreme_period`
## ------------------------------------------------

## Not run: 
epw$typical_extreme_period()

## End(Not run)


## ------------------------------------------------
## Method `Epw$ground_temperature`
## ------------------------------------------------

## Not run: 
epw$ground_temperature()

## End(Not run)


## ------------------------------------------------
## Method `Epw$holiday`
## ------------------------------------------------

## Not run: 
epw$holiday()

# add daylight saving time
epw$holiday(dst = c(3.10, 11.3))

## End(Not run)


## ------------------------------------------------
## Method `Epw$comment1`
## ------------------------------------------------

## Not run: 
epw$comment1()

epw$comment1("Comment1")

## End(Not run)


## ------------------------------------------------
## Method `Epw$comment2`
## ------------------------------------------------

## Not run: 
epw$comment2()

epw$comment2("Comment2")

## End(Not run)


## ------------------------------------------------
## Method `Epw$num_period`
## ------------------------------------------------

## Not run: 
epw$num_period()

## End(Not run)


## ------------------------------------------------
## Method `Epw$interval`
## ------------------------------------------------

## Not run: 
epw$interval()

## End(Not run)


## ------------------------------------------------
## Method `Epw$period`
## ------------------------------------------------

## Not run: 
# modify data period name
epw$period(1, name = "test")

# change start day of week
epw$period(1, start_day_of_week = 3)

## End(Not run)


## ------------------------------------------------
## Method `Epw$missing_code`
## ------------------------------------------------

## Not run: 
epw$missing_code()

## End(Not run)


## ------------------------------------------------
## Method `Epw$initial_missing_value`
## ------------------------------------------------

## Not run: 
epw$initial_missing_value()

## End(Not run)


## ------------------------------------------------
## Method `Epw$range_exist`
## ------------------------------------------------

## Not run: 
epw$range_exist()

## End(Not run)


## ------------------------------------------------
## Method `Epw$range_valid`
## ------------------------------------------------

## Not run: 
epw$range_valid()

## End(Not run)


## ------------------------------------------------
## Method `Epw$fill_action`
## ------------------------------------------------

## Not run: 
epw$fill_action("missing")

epw$fill_action("out_of_range")

## End(Not run)


## ------------------------------------------------
## Method `Epw$data`
## ------------------------------------------------

## Not run: 
# get weather data
str(epw$data())

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

# change the time zone of datetime column in the returned weather data
attributes(epw$data()$datetime)
attributes(epw$data(tz = "Etc/GMT+8")$datetime)

## End(Not run)


## ------------------------------------------------
## Method `Epw$abnormal_data`
## ------------------------------------------------

## Not run: 
epw$abnormal_data()

# only check if there are any abnormal values in air temperature and
# liquid precipitation rate
epw$abnormal_data(cols = c("dry_bulb_temperature", "liquid_precip_rate"))

# save as above, but only return date time columns plus those 2 columns
epw$abnormal_data(cols = c("dry_bulb_temperature", "liquid_precip_rate"),
    keep_all = FALSE
)

# same as above, but only check for missing values
epw$abnormal_data(cols = c("dry_bulb_temperature", "liquid_precip_rate"),
    type = "missing"
)

# same as above, but only check for out-of-range values
epw$abnormal_data(cols = c("dry_bulb_temperature", "liquid_precip_rate"),
    type = "out_of_range"
)

## End(Not run)


## ------------------------------------------------
## Method `Epw$redundant_data`
## ------------------------------------------------

## Not run: 
epw$redundant_data()

## End(Not run)


## ------------------------------------------------
## Method `Epw$make_na`
## ------------------------------------------------

## Not run: 
# turn all missing values into NAs
summary(epw$data()$liquid_precip_rate)
epw$make_na(missing = TRUE)
summary(epw$data()$liquid_precip_rate)

## End(Not run)


## ------------------------------------------------
## Method `Epw$fill_abnormal`
## ------------------------------------------------

## Not run: 
# turn all missing values into NAs
summary(epw$data()$liquid_precip_rate)
epw$fill_abnormal(missing = TRUE)
summary(epw$data()$liquid_precip_rate)

## End(Not run)


## ------------------------------------------------
## Method `Epw$add_unit`
## ------------------------------------------------

## Not run: 
# get weather data with units
epw$add_unit()
head(epw$data())

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

head(t_dry_bulb)

## End(Not run)


## ------------------------------------------------
## Method `Epw$drop_unit`
## ------------------------------------------------

## Not run: 
epw$drop_unit()
epw$data()

## End(Not run)


## ------------------------------------------------
## Method `Epw$purge`
## ------------------------------------------------

## Not run: 
epw$purge()

## End(Not run)


## ------------------------------------------------
## Method `Epw$add`
## ------------------------------------------------

## Not run: 
# will fail since date time in input data has already been covered by
# existing data period
try(epw$add(epw$data()), silent = TRUE)

## End(Not run)


## ------------------------------------------------
## Method `Epw$set`
## ------------------------------------------------

## Not run: 
# change the weather data
epw$set(epw$data())

## End(Not run)


## ------------------------------------------------
## Method `Epw$is_unsaved`
## ------------------------------------------------

## Not run: 
epw$is_unsaved()

## End(Not run)


## ------------------------------------------------
## Method `Epw$save`
## ------------------------------------------------

## Not run: 
# save the weather file
epw$save(file.path(tempdir(), "weather.epw"), overwrite = TRUE)

## End(Not run)


## ------------------------------------------------
## Method `Epw$print`
## ------------------------------------------------

## Not run: 
epw$print()

## End(Not run)

[Package eplusr version 0.16.2 Index]

Read, and modify an EnergyPlus Weather File (EPW)

Description

Details

Methods

Public methods

Method new()

Usage

Arguments

Details

Returns

Examples

Method path()

Usage

Details

Returns

Examples

Method definition()

Usage

Arguments

Details

Examples

Method location()

Usage

Arguments

Details

Returns

Examples

Method design_condition()

Usage

Details

Returns

Examples

Method typical_extreme_period()

Usage

Details

Returns

Examples

Method ground_temperature()

Usage

Details

Returns

Examples

Method holiday()

Usage

Arguments

Details

Returns

Examples

Method comment1()

Usage

Arguments

Details

Returns

Examples

Method comment2()

Usage

Arguments

Details

Returns

Examples

Method num_period()

Usage

Details

Returns

Examples

Method interval()

Usage

Details

Returns

Examples

Method period()

Usage

Arguments

Details

Returns

Examples

Method missing_code()

Usage

Details

Returns

Method `new()`

Method `path()`

Method `definition()`

Method `location()`

Method `design_condition()`

Method `typical_extreme_period()`

Method `ground_temperature()`

Method `holiday()`

Method `comment1()`

Method `comment2()`

Method `num_period()`

Method `interval()`

Method `period()`

Method `missing_code()`

Method `initial_missing_value()`

Method `range_exist()`

Method `range_valid()`

Method `fill_action()`

Method `data()`

Method `abnormal_data()`

Method `redundant_data()`

Method `make_na()`

Method `fill_abnormal()`

Method `add_unit()`

Method `drop_unit()`

Method `purge()`

Method `add()`