hongyuanjia/eplusr
A Toolkit for Using Whole Building Simulation Program 'EnergyPlus'

Package index
Search the hongyuanjia/eplusr package
Vignettes
Functions
1046
Source code
85
Man pages
82
Home
/
GitHub
/
hongyuanjia/eplusr
/
Epw: Read, and modify an EnergyPlus Weather File (EPW)

Epw: Read, and modify an EnergyPlus Weather File (EPW)
In hongyuanjia/eplusr: A Toolkit for Using Whole Building Simulation Program 'EnergyPlus'

EpwR 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:

  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

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

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:

  1. 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⁠.

  2. 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⁠.

  3. 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.

  4. A string giving ⁠number Weekday in Month⁠. For example, "2 Sunday in Jan" will be parsed and presented as ⁠2th Sunday in January⁠.

  5. 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)

hongyuanjia/eplusr documentation built on Feb. 14, 2024, 5:38 a.m.

Related to Epw in hongyuanjia/eplusr...

hongyuanjia/eplusr index
README.md

R Package Documentation

rdrr.io home R language documentation Run R code online

Browse R Packages

CRAN packages Bioconductor packages R-Forge packages GitHub packages

We want your feedback!

Note that we can't provide technical support on individual packages. You should contact the package authors for that.
GitHub issue tracker
ian@mutexlabs.com
Personal blog

 
Embedding an R snippet on your website

Add the following code to your website.

For more information on customizing the embed code, read Embedding Snippets.

Close