Package 'eplusr'

Description

A rich toolkit of using the whole building simulation program 'EnergyPlus'(https://energyplus.net), which enables programmatic navigation, modification of 'EnergyPlus' models and makes it less painful to do parametric simulations and analysis.

Details

eplusr provides a rich toolkit of using EnergyPlus directly in R, which enables programmatic navigation, modification of EnergyPlus models and makes it less painful to do parametric simulations and analysis.

Features

• Download and install EnergyPlus in R

• Read, parse and modify EnergyPlus:

  • Input Data File (IDF)

  • Weather File (EPW)

  • Report Data Dictionary (RDD) & Meter Data Dictionary (MDD)

  • Error File (ERR)

• Modify multiple versions of IDFs and run corresponding EnergyPlus both in the background and in the front

• Rich-featured interfaces to query and modify IDFs

• Automatically handle referenced fields and validate input during modification

• Take fully advantage of most common used data structure for data science in R – data.frame

  • Extract model, weather data into data.frames

  • Modify multiple objects via data.frames input

  • Query output via SQL in Tidy format which is much better for data analysis and visualization

• Provide a simple yet extensible prototype of conducting parametric simulations and collect all results in one go

• A pure R-based version updater transition() which is much faster than VersionUpdater distributed with EnergyPlus

Author(s)

Hongyuan Jia

See Also

Useful links:

• https://hongyuanjia.github.io/eplusr/

• https://github.com/hongyuanjia/eplusr

• Report bugs at https://github.com/hongyuanjia/eplusr/issues

Description

Coerce an IddObject into an empty object of current class in a character vector format. It is formatted exactly the same as in IDF Editor.

Usage

## S3 method for class 'IddObject'
as.character(x, comment = NULL, leading = 4L, sep_at = 29L, all = FALSE, ...)

Arguments

Value

A character vector.

Examples

## Not run: 
as.character(use_idd(8.8, download = "auto")$Materal, leading = 0)

## End(Not run)

Description

Coerce an Idf object into a character vector.

Usage

## S3 method for class 'Idf'
as.character(
  x,
  comment = TRUE,
  header = TRUE,
  format = eplusr_option("save_format"),
  leading = 4L,
  sep_at = 29L,
  ...
)

Arguments

Value

A character vector.

Author(s)

Hongyuan Jia

Examples

## Not run: 
idf_path <- system.file("extdata/1ZoneUncontrolled.idf", package = "eplusr")
as.character(read_idf(idf_path, use_idd(8.8, "auto")), leading = 0)

## End(Not run)

Description

Coerce an IdfObject into a character vector in the same way as in IDF Editor.

Usage

## S3 method for class 'IdfObject'
as.character(x, comment = TRUE, leading = 4L, sep_at = 29L, all = FALSE, ...)

Arguments

Value

A character vector.

Examples

## Not run: 
idf <- read_idf(system.file("extdata/1ZoneUncontrolled.idf", package = "eplusr"),
    idd = use_idd("8.8", download = "auto"))

# get the IdfObject of material named "C5 - 4 IN HW CONCRETE"
mat <- idf$Material[["C5 - 4 IN HW CONCRETE"]]

as.character(mat, leading = 0, sep_at = 10)

## End(Not run)

Description

Clean working directory of an EnergyPlus simulation by deleting all input and output files of previous simulation.

Usage

clean_wd(path)

Arguments

Details

clean_wd() imitates the same process that EnergyPlus does whenever a new simulation is getting to start. It deletes all related output files that have the same name prefix as the input path. The input model itself and any weather file are not deleted. clean_wd() is called internally when running EnergyPlus models using run_idf() and run_multi().

Author(s)

Hongyuan Jia

Examples

## Not run: 
# run a test simulation
idf_path <- system.file("extdata/1ZoneUncontrolled.idf", package = "eplusr")
epw_path <- path_eplus_weather("8.8",
     "USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw"
)
dir <- file.path(tempdir(), "test")
run_idf(idf_path, epw_path, output_dir = dir, echo = FALSE)

list.files(dir)

# remove all output files
clean_wd(file.path(dir, basename(idf_path)))

list.files(dir)

## End(Not run)

Description

custom_validate() makes it easy to customize what validation components should be included during IDF object modifications using ⁠$dup()⁠, ⁠$add()⁠, ⁠$set()⁠ and other methods in Idf class.

Usage

custom_validate(
  required_object = FALSE,
  unique_object = FALSE,
  unique_name = FALSE,
  extensible = FALSE,
  required_field = FALSE,
  auto_field = FALSE,
  type = FALSE,
  choice = FALSE,
  range = FALSE,
  reference = FALSE
)

Arguments

Details

There are 10 different validation check components in total. Three predefined validation level are included, i.e. "none", "draft" and "final". To get what validation components those levels contain, see level_checks().

Value

A named list with 10 elements.

Examples

custom_validate(unique_object = TRUE)

# only check unique name during validation
eplusr_option(validate_level = custom_validate(unique_name = TRUE))

Description

download_weather() makes it easy to download EnergyPlus weather files (EPW) and design day files (DDY).

Usage

download_weather(
  pattern,
  filename = NULL,
  dir = ".",
  type = c("all", "epw", "ddy", "stat"),
  ask = TRUE,
  max_match = 3
)

Arguments

Value

A character vector containing paths of downloaded files.

Data sources

There are 2 data sources:

• EnergyPlus.net

• OneBuilding.org

EnergyPlus sources allow downloading EPW, STAT, and DDY files separately while OneBuilding sources can only download them all through a ZIP file.

Author(s)

Hongyuan Jia

Examples

## Not run: 
download_weather("los angeles.*tmy3", "LosAngeles", tempdir(), ask = FALSE)

## End(Not run)

Description

dt_to_load() takes a data.table, usually created from Idf$to_table() or IdfObject$to_table() with wide being TRUE, and format it into a data.table in acceptable format for ⁠$load()⁠ method in Idf class.

Usage

dt_to_load(dt, string_value = TRUE)

Arguments

Value

A data.table with 5 or 6 columns:

• id: Integer type. Used to distinguish each object definition.

• name: Character type. Only exists when input dt has a name column.

• class: Character type.

• index: Integer type. Field indices.

• field: Character type. Field names.

• value: Character or list type. The value of each field to be added.

Examples

## Not run: 
# read an example distributed with eplusr
path_idf <- system.file("extdata/1ZoneUncontrolled.idf", package = "eplusr")
idf <- read_idf(path_idf)

# extract all material object data and return it as a wide table
dt <- idf$to_table(class = "Material", wide = TRUE)

dt_to_load(dt)

## End(Not run)

Description

empty_idf() takes a valid IDD version and creates an empty Idf object that only contains a Version object.

Usage

empty_idf(ver = "latest")

Arguments

Value

An Idf object

Examples

## Not run: 
if (is_avail_idd(8.8)) empty_idf(8.8)

## End(Not run)

Description

eplus_sql() takes an EnergyPlus SQLite output file as input, and returns an EplusSQL object for collecting simulation outputs. For more details, please see EplusSql.

Usage

eplus_sql(sql)

Arguments

Value

An EplusSql object.

Author(s)

Hongyuan Jia

Examples

## Not run: 
if (is_avail_eplus(8.8)) {
    idf_name <- "1ZoneUncontrolled.idf"
    epw_name <-  "USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw"

    idf_path <- file.path(eplus_config(8.8)$dir, "ExampleFiles", idf_name)
    epw_path <- file.path(eplus_config(8.8)$dir, "WeatherData", epw_name)

    # copy to tempdir and run the model
    idf <- read_idf(idf_path)
    idf$run(epw_path, tempdir(), echo = FALSE)

    # create from local file
    sql <- eplus_sql(file.path(tempdir(), "1ZoneUncontrolled.sql"))
}

## End(Not run)

Description

EplusGroupJob class is a wrapper of run_multi() and provides an interface to group multiple EnergyPlus simulations together for running and collecting outputs.

group_job() takes IDFs and EPWs as input and returns a EplusGroupJob.

Usage

group_job(idfs, epws)

Arguments

Value

A EplusGroupJob object.

Methods

Public methods

• EplusGroupJob$new()

• EplusGroupJob$run()

• EplusGroupJob$kill()

• EplusGroupJob$status()

• EplusGroupJob$errors()

• EplusGroupJob$output_dir()

• EplusGroupJob$list_files()

• EplusGroupJob$locate_output()

• EplusGroupJob$list_table()

• EplusGroupJob$read_table()

• EplusGroupJob$read_rdd()

• EplusGroupJob$read_mdd()

• EplusGroupJob$report_data_dict()

• EplusGroupJob$report_data()

• EplusGroupJob$tabular_data()

• EplusGroupJob$print()

Method new()

Create an EplusGroupJob object

Usage

EplusGroupJob$new(idfs, epws)

Arguments

Returns

An EplusGroupJob object.

Examples

\dontrun{
if (is_avail_eplus(8.8)) {
    dir <- eplus_config(8.8)$dir
    path_idfs <- list.files(file.path(dir, "ExampleFiles"), "\\.idf",
        full.names = TRUE)[1:5]
    path_epws <- list.files(file.path(dir, "WeatherData"), "\\.epw",
        full.names = TRUE)[1:5]

    # create from local files
    group <- group_job(path_idfs, path_epws)

    # create from Idfs and Epws object
    group_job(lapply(path_idfs, read_idf), lapply(path_epws, read_epw))
}
}

Method run()

Run grouped simulations

Usage

EplusGroupJob$run(
  dir = NULL,
  wait = TRUE,
  force = FALSE,
  copy_external = FALSE,
  echo = wait,
  separate = TRUE,
  readvars = TRUE
)

Arguments

Details

⁠$run()⁠ runs all grouped simulations in parallel. The number of parallel EnergyPlus process can be controlled by eplusr_option("num_parallel"). If wait is FALSE, then the job will be run in the background. You can get updated job status by just printing the EplusGroupJob object.

Returns

The EplusGroupJob object itself, invisibly.

Examples

\dontrun{
# only run design day
group$run(NULL)

# do not show anything in the console
group$run(echo = FALSE)

# specify output directory
group$run(tempdir(), echo = FALSE)

# run in the background
group$run(wait = TRUE, echo = FALSE)
# see group job status
group$status()

# force to kill background group job before running the new one
group$run(force = TRUE, echo = FALSE)

# copy external files used in the model to simulation output directory
group$run(copy_external = TRUE, echo = FALSE)
}

Method kill()

Kill current running jobs

Usage

EplusGroupJob$kill()

Details

⁠$kill()⁠ kills all background EnergyPlus processes that are current running if possible. It only works when simulations run in non-waiting mode.

Returns

A single logical value of TRUE or FALSE, invisibly.

Examples

\dontrun{
group$kill()
}

Method status()

Get the group job status

Usage

EplusGroupJob$status()

Details

⁠$status()⁠ returns a named list of values indicates the status of the job:

• run_before: TRUE if the job has been run before. FALSE otherwise.

• alive: TRUE if the job is still running in the background. FALSE otherwise.

• terminated: TRUE if the job was terminated during last simulation. FALSE otherwise. NA if the job has not been run yet.

• successful: TRUE if all simulations ended successfully. FALSE if there is any simulation failed. NA if the job has not been run yet.

• changed_after: TRUE if the models has been modified since last simulation. FALSE otherwise.

• job_status: A data.table::data.table() contains meta data for each simulation job. For details, please see run_multi(). If the job has not been run before, a data.table::data.table() with 4 columns is returned:

  • index: The index of simulation

  • status: The status of simulation. As the simulation has not been run, status will always be "idle".

  • idf: The path of input IDF file.

  • epw: The path of input EPW file. If not provided, NA will be assigned.

Returns

A named list of 6 elements.

Examples

\dontrun{
group$status()
}

Method errors()

Read group simulation errors

Usage

EplusGroupJob$errors(which = NULL, info = FALSE)

Arguments

Details

$errors() returns a list of ErrFile objects which contain all contents of the simulation error files (.err). If info is FALSE, only warnings and errors are printed.

Returns

A list of ErrFile objects.

Examples

\dontrun{
group$errors()

# show all information
group$errors(info = TRUE)
}

Method output_dir()

Get simulation output directory

Usage

EplusGroupJob$output_dir(which = NULL)

Arguments

Details

⁠$output_dir()⁠ returns the output directory of simulation results.

Returns

A character vector.

Examples

\dontrun{
# get output directories of all simulations
group$output_dir()

# get output directories of specified simulations
group$output_dir(c(1, 4))
}

Method list_files()

List all output files in simulations

Usage

EplusGroupJob$list_files(which = NULL, simplify = FALSE, full = FALSE)

Arguments

Details

⁠$list_files()⁠ returns all input and output files for the grouped EnergyPlus simulations.

Description of all possible outputs from EnergyPlus can be found in EnergyPlus documentation "Output Details and Examples".

Below gives a brief summary on the meaning of elements in the returned list.

Returns

If simplify is TRUE, a list. Otherwise, a data.table of 3 columns:

• index: Integer type. Simulation indices.

• type: Character type. Input or output types. See table above for the meaning

• file: List type. File names if full is FALSE. Full file paths if full is TRUE

Examples

\dontrun{
# list all files in the output directory
group$list_files(simplify = TRUE)

# get a data.table that contains a full list of all possible inputs
# and outputs even though they may not exist for current simulation
group$list_files()

# return the full paths instead of just file names
group$locate_output(full = TRUE)
}

Method locate_output()

Get paths of output file

Usage

EplusGroupJob$locate_output(which = NULL, suffix = ".err", strict = TRUE)

Arguments

Details

⁠$locate_output()⁠ returns the path of a single output file of specified simulations.

Returns

A character vector.

Examples

\dontrun{
# get the file path of the error file
group$locate_output(c(1, 4), ".err", strict = FALSE)

# can detect if certain output file exists
group$locate_output(c(1, 4), ".expidf", strict = TRUE)
}

Method list_table()

List all table names in EnergyPlus SQL outputs

Usage

EplusGroupJob$list_table(which = NULL)

Arguments

Details

⁠$list_table()⁠ returns a list of character vectors that contain all available table and view names in the EnergyPlus SQLite files for group simulations. The list is named using IDF names.

Returns

A named list of character vectors.

Examples

\dontrun{
group$list_table(c(1, 4))
}

Method read_table()

Read the same table from EnergyPlus SQL outputs

Usage

EplusGroupJob$read_table(which = NULL, name)

Arguments

Details

⁠$read_table()⁠ takes a simulation index and a valid table name of those from $list_table() and returns that table data in a data.table::data.table() format. The two column will always be index and case which can be used to distinguish output from different simulations. index contains the indices of simulated models and case contains the model names without extensions.

Returns

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

Examples

\dontrun{
# read a specific table
group$read_table(c(1, 4), "Zones")
}

Method read_rdd()

Read Report Data Dictionary (RDD) files

Usage

EplusGroupJob$read_rdd(which = NULL)

Arguments

Details

⁠$read_rdd()⁠ return the core data of Report Data Dictionary (RDD) files. For details, please see read_rdd(). The two column will always be index and case which can be used to distinguish output from different simulations. index contains the indices of simulated models and case contains the model names without extensions.

Returns

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

Examples

\dontrun{
group$read_rdd(c(1, 4))
}

Method read_mdd()

Read Meter Data Dictionary (MDD) files

Usage

EplusGroupJob$read_mdd(which = NULL)

Arguments

Details

⁠$read_mdd()⁠ return the core data of Meter Data Dictionary (MDD) files. For details, please see read_mdd(). The two column will always be index and case which can be used to distinguish output from different simulations. index contains the indices of simulated models and case contains the model names without extensions.

Returns

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

Examples

\dontrun{
group$read_mdd(c(1, 4))
}

Method report_data_dict()

Read report data dictionary from EnergyPlus SQL outputs

Usage

EplusGroupJob$report_data_dict(which = NULL)

Arguments

Details

⁠$report_data_dict()⁠ returns a data.table::data.table() which contains all information about report data.

For details on the meaning of each columns, please see "2.20.2.1 ReportDataDictionary Table" in EnergyPlus "Output Details and Examples" documentation.

Returns

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

• index: The index of simulated model. This column can be used to distinguish output from different simulations

• case: The model name without extension. This column can be used to distinguish output from different simulations

• report_data_dictionary_index: The integer used to link the dictionary data to the variable data. Mainly useful when joining different tables

• is_meter: Whether report data is a meter data. Possible values: 0 and 1

• timestep_type: Type of data timestep. Possible values: Zone and ⁠HVAC System⁠

• key_value: Key name of the data

• name: Actual report data name

• reporting_frequency:

• schedule_name: Name of the the schedule that controls reporting frequency.

• units: The data units

Examples

\dontrun{
group$report_data_dict(c(1, 4))
}

Method report_data()

Read report data

Usage

EplusGroupJob$report_data(
  which = NULL,
  key_value = NULL,
  name = NULL,
  year = NULL,
  tz = "UTC",
  all = FALSE,
  wide = FALSE,
  period = NULL,
  month = NULL,
  day = NULL,
  hour = NULL,
  minute = NULL,
  interval = NULL,
  simulation_days = NULL,
  day_type = NULL,
  environment_name = NULL
)

Arguments

Details

⁠$report_data()⁠ extracts the report data in a data.table::data.table() using key values, variable names and other specifications.

⁠$report_data()⁠ can also directly take all or subset output from ⁠$report_data_dict()⁠ as input, and extract all data specified.

The returned column numbers varies depending on all argument.

• all is FALSE, the returned data.table::data.table() has 6 columns:

  • index: The index of simulated model. This column can be used to distinguish output from different simulations

  • case: The model name. This column can be used to distinguish output from different simulations

  • datetime: The date time of simulation result

  • key_value: Key name of the data

  • name: Actual report data name

  • units: The data units

  • value: The data value

• all is TRUE, besides columns described above, extra columns are also included:

  • month: The month of reported date time

  • day: The day of month of reported date time

  • hour: The hour of reported date time

  • minute: The minute of reported date time

  • dst: Daylight saving time indicator. Possible values: 0 and 1

  • interval: Length of reporting interval

  • simulation_days: Day of simulation

  • day_type: The type of day, e.g. Monday, Tuesday and etc.

  • environment_period_index: The indices of environment.

  • environment_name: A text string identifying the environment.

  • is_meter: Whether report data is a meter data. Possible values: 0 and 1

  • type: Nature of data type with respect to state. Possible values: Sum and Avg

  • index_group: The report group, e.g. Zone, System

  • timestep_type: Type of data timestep. Possible values: Zone and ⁠HVAC System⁠

  • reporting_frequency: The reporting frequency of the variable, e.g. ⁠HVAC System Timestep⁠, ⁠Zone Timestep⁠.

  • schedule_name: Name of the the schedule that controls reporting frequency.

With the datetime column, it is quite straightforward to apply time-series analysis on the simulation output. However, another painful thing is that every simulation run period has its own ⁠Day of Week for Start Day⁠. 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 RunPeriod objects.

eplusr provides a simple solution for this. By setting year to NULL, which is the default behavior, eplusr will calculate a year value (from year 2017 backwards) for each run period that compliances with the start day of week restriction.

It is worth noting that EnergyPlus uses 24-hour clock system where 24 is only used to denote midnight at the end of a calendar day. In EnergyPlus output, "00:24:00" with a time interval being 15 mins represents a time period from "00:23:45" to "00:24:00", and similarly "00:15:00" represents a time period from "00:24:00" to "00:15:00" of the next day. This means that if current day is Friday, day of week rule applied in schedule time period "00:23:45" to "00:24:00" (presented as "00:24:00" in the output) is also Friday, but not Saturday. However, if you try to get the day of week of time "00:24:00" in R, you will get Saturday, but not Friday. This introduces inconsistency and may cause problems when doing data analysis considering day of week value.

With wide equals TRUE, ⁠$report_data()⁠ will format the simulation output in the same way as standard EnergyPlus csv output file. Sometimes this can be useful as there may be existing tools/workflows that depend on this format. When both wide and all are TRUE, columns of runperiod environment names and date time components are also returned, including: ⁠environment_period_index", "environment_name⁠, simulation_days, datetime, month, day, hour, minute, day_type.

For convenience, input character arguments matching in ⁠$report_data()⁠ are case-insensitive.

Returns

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

Examples

\dontrun{
# read report data
group$report_data(c(1, 4))

# specify output variables using report data dictionary
dict <- group$report_data_dict(1)
group$report_data(c(1, 4), dict[units == "C"])

# specify output variables using 'key_value' and 'name'
group$report_data(c(1, 4), "environment", "site outdoor air drybulb temperature")

# explicitly specify year value and time zone
group$report_data(c(1, 4), dict[1], year = 2020, tz = "Etc/GMT+8")

# get all possible columns
group$report_data(c(1, 4), dict[1], all = TRUE)

# return in a format that is similar as EnergyPlus CSV output
group$report_data(c(1, 4), dict[1], wide = TRUE)

# return in a format that is similar as EnergyPlus CSV output with
# extra columns
group$report_data(c(1, 4), dict[1], wide = TRUE, all = TRUE)

# only get data at the working hour on the first Monday
group$report_data(c(1, 4), dict[1], hour = 8:18, day_type = "monday", simulation_days = 1:7)
}

Method tabular_data()

Read tabular data

Usage

EplusGroupJob$tabular_data(
  which = NULL,
  report_name = NULL,
  report_for = NULL,
  table_name = NULL,
  column_name = NULL,
  row_name = NULL,
  wide = FALSE,
  string_value = !wide
)

Arguments

Details

⁠$tabular_data()⁠ extracts the tabular data in a data.table::data.table() using report, table, column and row name specifications. The returned data.table::data.table() has 9 columns:

• index: The index of simulated model. This column can be used to distinguish output from different simulations

• case: The model name. This column can be used to distinguish output from different simulations

• index: Tabular data index

• report_name: The name of the report that the record belongs to

• report_for: The For text that is associated with the record

• table_name: The name of the table that the record belongs to

• column_name: The name of the column that the record belongs to

• row_name: The name of the row that the record belongs to

• units: The units of the record

• value: The value of the record in string format by default

For convenience, input character arguments matching in ⁠$tabular_data()⁠ are case-insensitive.

Returns

A data.table::data.table() with 9 columns (when wide is FALSE) or a named list of data.table::data.table()s where the names are the combination of report_name, report_for and table_name.

Examples

\dontrun{
# read all tabular data
group$tabular_data(c(1, 4))

# explicitly specify data you want
str(group$tabular_data(c(1, 4),
    report_name = "AnnualBuildingUtilityPerformanceSummary",
    table_name = "Site and Source Energy",
    column_name = "Total Energy",
    row_name = "Total Site Energy"
))

# get tabular data in wide format and coerce numeric values
str(group$tabular_data(c(1, 4),
    report_name = "AnnualBuildingUtilityPerformanceSummary",
    table_name = "Site and Source Energy",
    column_name = "Total Energy",
    row_name = "Total Site Energy",
    wide = TRUE, string_value = FALSE
))
}

Method print()

Print EplusGroupJob object

Usage

EplusGroupJob$print()

Details

⁠$print()⁠ shows the core information of this EplusGroupJob, including the path of IDFs and EPWs and also the simulation job status.

⁠$print()⁠ is quite useful to get the simulation status, especially when wait is FALSE in ⁠$run()⁠. The job status will be updated and printed whenever ⁠$print()⁠ is called.

Returns

The EplusGroupJob object itself, invisibly.

Examples

\dontrun{
group$print()
}

Author(s)

Hongyuan Jia

See Also

eplus_job() for creating an EnergyPlus single simulation job.

Examples

## ------------------------------------------------
## Method `EplusGroupJob$new`
## ------------------------------------------------

## Not run: 
if (is_avail_eplus(8.8)) {
    dir <- eplus_config(8.8)$dir
    path_idfs <- list.files(file.path(dir, "ExampleFiles"), "\\.idf",
        full.names = TRUE)[1:5]
    path_epws <- list.files(file.path(dir, "WeatherData"), "\\.epw",
        full.names = TRUE)[1:5]

    # create from local files
    group <- group_job(path_idfs, path_epws)

    # create from Idfs and Epws object
    group_job(lapply(path_idfs, read_idf), lapply(path_epws, read_epw))
}

## End(Not run)


## ------------------------------------------------
## Method `EplusGroupJob$run`
## ------------------------------------------------

## Not run: 
# only run design day
group$run(NULL)

# do not show anything in the console
group$run(echo = FALSE)

# specify output directory
group$run(tempdir(), echo = FALSE)

# run in the background
group$run(wait = TRUE, echo = FALSE)
# see group job status
group$status()

# force to kill background group job before running the new one
group$run(force = TRUE, echo = FALSE)

# copy external files used in the model to simulation output directory
group$run(copy_external = TRUE, echo = FALSE)

## End(Not run)


## ------------------------------------------------
## Method `EplusGroupJob$kill`
## ------------------------------------------------

## Not run: 
group$kill()

## End(Not run)


## ------------------------------------------------
## Method `EplusGroupJob$status`
## ------------------------------------------------

## Not run: 
group$status()

## End(Not run)


## ------------------------------------------------
## Method `EplusGroupJob$errors`
## ------------------------------------------------

## Not run: 
group$errors()

# show all information
group$errors(info = TRUE)

## End(Not run)


## ------------------------------------------------
## Method `EplusGroupJob$output_dir`
## ------------------------------------------------

## Not run: 
# get output directories of all simulations
group$output_dir()

# get output directories of specified simulations
group$output_dir(c(1, 4))

## End(Not run)


## ------------------------------------------------
## Method `EplusGroupJob$list_files`
## ------------------------------------------------

## Not run: 
# list all files in the output directory
group$list_files(simplify = TRUE)

# get a data.table that contains a full list of all possible inputs
# and outputs even though they may not exist for current simulation
group$list_files()

# return the full paths instead of just file names
group$locate_output(full = TRUE)

## End(Not run)


## ------------------------------------------------
## Method `EplusGroupJob$locate_output`
## ------------------------------------------------

## Not run: 
# get the file path of the error file
group$locate_output(c(1, 4), ".err", strict = FALSE)

# can detect if certain output file exists
group$locate_output(c(1, 4), ".expidf", strict = TRUE)

## End(Not run)


## ------------------------------------------------
## Method `EplusGroupJob$list_table`
## ------------------------------------------------

## Not run: 
group$list_table(c(1, 4))

## End(Not run)


## ------------------------------------------------
## Method `EplusGroupJob$read_table`
## ------------------------------------------------

## Not run: 
# read a specific table
group$read_table(c(1, 4), "Zones")

## End(Not run)


## ------------------------------------------------
## Method `EplusGroupJob$read_rdd`
## ------------------------------------------------

## Not run: 
group$read_rdd(c(1, 4))

## End(Not run)


## ------------------------------------------------
## Method `EplusGroupJob$read_mdd`
## ------------------------------------------------

## Not run: 
group$read_mdd(c(1, 4))

## End(Not run)


## ------------------------------------------------
## Method `EplusGroupJob$report_data_dict`
## ------------------------------------------------

## Not run: 
group$report_data_dict(c(1, 4))

## End(Not run)


## ------------------------------------------------
## Method `EplusGroupJob$report_data`
## ------------------------------------------------

## Not run: 
# read report data
group$report_data(c(1, 4))

# specify output variables using report data dictionary
dict <- group$report_data_dict(1)
group$report_data(c(1, 4), dict[units == "C"])

# specify output variables using 'key_value' and 'name'
group$report_data(c(1, 4), "environment", "site outdoor air drybulb temperature")

# explicitly specify year value and time zone
group$report_data(c(1, 4), dict[1], year = 2020, tz = "Etc/GMT+8")

# get all possible columns
group$report_data(c(1, 4), dict[1], all = TRUE)

# return in a format that is similar as EnergyPlus CSV output
group$report_data(c(1, 4), dict[1], wide = TRUE)

# return in a format that is similar as EnergyPlus CSV output with
# extra columns
group$report_data(c(1, 4), dict[1], wide = TRUE, all = TRUE)

# only get data at the working hour on the first Monday
group$report_data(c(1, 4), dict[1], hour = 8:18, day_type = "monday", simulation_days = 1:7)

## End(Not run)


## ------------------------------------------------
## Method `EplusGroupJob$tabular_data`
## ------------------------------------------------

## Not run: 
# read all tabular data
group$tabular_data(c(1, 4))

# explicitly specify data you want
str(group$tabular_data(c(1, 4),
    report_name = "AnnualBuildingUtilityPerformanceSummary",
    table_name = "Site and Source Energy",
    column_name = "Total Energy",
    row_name = "Total Site Energy"
))

# get tabular data in wide format and coerce numeric values
str(group$tabular_data(c(1, 4),
    report_name = "AnnualBuildingUtilityPerformanceSummary",
    table_name = "Site and Source Energy",
    column_name = "Total Energy",
    row_name = "Total Site Energy",
    wide = TRUE, string_value = FALSE
))

## End(Not run)


## ------------------------------------------------
## Method `EplusGroupJob$print`
## ------------------------------------------------

## Not run: 
group$print()

## End(Not run)

Description

EplusJob class wraps the EnergyPlus command line interface and provides methods to extract simulation outputs.

eplus_job() takes an IDF and EPW as input, and returns an EplusJob object for running EnergyPlus simulation and collecting outputs.

Usage

eplus_job(idf, epw)

Arguments

Details

eplusr uses the EnergyPlus SQL output for extracting simulation outputs.

EplusJob has provide some wrappers that do SQL query to get report data results, i.e. results from Output:Variable and ⁠Output:Meter*⁠. But for Output:Table results, you have to be familiar with the structure of the EnergyPlus SQL results, especially for table "TabularDataWithStrings". For details, please see "2.20 eplusout.sql", especially "2.20.4.4 TabularData Table" in EnergyPlus "Output Details and Examples" documentation. An object in Output:SQLite with ⁠Option Type⁠ value of SimpleAndTabular will be automatically created if it does not exists, to ensure that the output collection functionality works successfully.

In order to make sure .rdd (Report Data Dictionary) and .mdd (Meter Data Dictionary) files are created during simulation, an object in Output:VariableDictionary class with ⁠Key Field⁠ value being IDF will be automatically created if it does not exists.

Value

An EplusJob object.

Methods

Public methods

• EplusJob$new()

• EplusJob$version()

• EplusJob$path()

• EplusJob$run()

• EplusJob$kill()

• EplusJob$status()

• EplusJob$errors()

• EplusJob$output_dir()

• EplusJob$list_files()

• EplusJob$locate_output()

• EplusJob$read_rdd()

• EplusJob$read_mdd()

• EplusJob$list_table()

• EplusJob$read_table()

• EplusJob$report_data_dict()

• EplusJob$report_data()

• EplusJob$tabular_data()

• EplusJob$print()

Method new()

Create an EplusJob object

Usage

EplusJob$new(idf, epw)

Arguments

Returns

An EplusJob object.

Examples

\dontrun{
if (is_avail_eplus("8.8")) {
    name_idf <- "1ZoneUncontrolled.idf"
    name_epw <-  "USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw"

    path_idf <- path_eplus_example("8.8", name_idf)
    path_epw <- path_eplus_weather("8.8", name_epw)

    # create from local files
    job <- eplus_job(path_idf, path_epw)

    # create from an Idf and an Epw object
    job <- eplus_job(read_idf(path_idf), read_epw(path_epw))
}
}

Method version()

Get the version of IDF in current job

Usage

EplusJob$version()

Details

⁠$version()⁠ returns the version of IDF that current EplusJob uses.

Returns

A base::numeric_version() object.

Examples

\dontrun{
job$version()
}

Method path()

Get the paths of file that current EpwSql uses

Usage

EplusJob$path(type = c("all", "idf", "epw"))

Arguments

Details

⁠$path()⁠ returns the path of IDF or EPW of current job.

Returns

A character vector.

Examples

\dontrun{
job$path()
job$path("idf")
job$path("epw")
}

Method run()

Run simulation

Usage

EplusJob$run(
  epw,
  dir = NULL,
  wait = TRUE,
  force = FALSE,
  echo = wait,
  copy_external = FALSE,
  readvars = TRUE
)

Arguments

Details

⁠$run()⁠ runs the simulation using input IDF and EPW file. If wait is FALSE, the job is run in the background. You can get updated job status by just printing the EplusJob object.

Parameter epw can be used to reset the EPW file to use for simulation. If not given, the epw input used when creating this EplusJob object will be used.

Returns

The EplusJob object itself, invisibly.

Examples

\dontrun{
# only run design day
job$run(NULL)

# specify output directory
job$run(dir = tempdir())

# run in the background
job$run(wait = TRUE)
# see job status
job$status()

# force to kill background job before running the new one
job$run(force = TRUE)

# do not show anything in the console
job$run(echo = FALSE)

# copy external files used in the model to simulation output directory
job$run(copy_external = TRUE)

# run simulation without generating CSV files from ESO output
job$run(epw, dir = tempdir(), readvars = FALSE)
}

Method kill()

Kill current running job

Usage

EplusJob$kill()

Details

⁠$kill()⁠ kills the background EnergyPlus process if possible. It only works when simulation runs in non-waiting mode.

Returns

A single logical value of TRUE or FALSE, invisibly.

Examples

\dontrun{
job$kill()
}

Method status()

Get the job status

Usage

EplusJob$status()

Details

⁠$status()⁠ returns a named list of values that indicates the status of the job:

• run_before: TRUE if the job has been run before. FALSE otherwise.

• alive: TRUE if the simulation is still running in the background. FALSE otherwise.

• terminated: TRUE if the simulation was terminated during last simulation. FALSE otherwise. NA if the job has not been run yet.

• successful: TRUE if last simulation ended successfully. FALSE otherwise. NA if the job has not been run yet.

• changed_after: TRUE if the IDF file has been changed since last simulation. FALSE otherwise. NA if the job has not been run yet.

Returns

A named list of 5 elements.

Examples

\dontrun{
job$status()
}

Method errors()

Read simulation errors

Usage

EplusJob$errors(info = FALSE)

Arguments

Details

$errors() returns an ErrFile object which contains all contents of the simulation error file (.err). If info is FALSE, only warnings and errors are printed.

Returns

An ErrFile object.

Examples

\dontrun{
job$errors()

# show all information
job$errors(info = TRUE)
}

Method output_dir()

Get simulation output directory

Usage

EplusJob$output_dir(open = FALSE)

Arguments

Details

⁠$output_dir()⁠ returns the output directory of simulation results.

Examples

\dontrun{
job$output_dir()

# Below will open output directory
# job$output_dir(open = TRUE)
}

Method list_files()

List all output files in current simulation

Usage

EplusJob$list_files(simplify = FALSE, full = FALSE)

Arguments

Details

⁠$list_files()⁠ returns all input and output files for current EnergyPlus simulation.

Description of all possible outputs from EnergyPlus can be found in EnergyPlus documentation "Output Details and Examples".

Below gives a brief summary on the meaning of elements in the returned list.

Returns

If FALSE, a character vector. Otherwise, a named list.

Examples

\dontrun{
# list all files in the output directory
job$list_files(simplify = TRUE)

# get a full list of all possible inputs and outputs even though they
# may not exist for current simulation
job$list_files()

# return the full paths instead of just file names
job$locate_output(full = TRUE)
}

Method locate_output()

Get path of output file

Usage

EplusJob$locate_output(suffix = ".err", strict = TRUE)

Arguments

Details

⁠$locate_output()⁠ returns the path of a single output file specified by file suffix.

Examples

\dontrun{
# get the file path of the error file
job$locate_output(".err", strict = FALSE)

# can use to detect if certain output file exists
job$locate_output(".expidf", strict = TRUE)
}

Method read_rdd()

Read Report Data Dictionary (RDD) file

Usage

EplusJob$read_rdd()

Details

⁠$read_rdd()⁠ return the core data of Report Data Dictionary (RDD) file. For details, please see read_rdd().

Returns

An RddFile object.

Examples

\dontrun{
job$read_rdd()
}

Method read_mdd()

Read Report Data Dictionary (RDD) file

Usage

EplusJob$read_mdd()

Details

⁠$read_mdd()⁠ return the core data of Meter Data Dictionary (MDD) file. For details, please see read_mdd().

Returns

An MddFile object.

Examples

\dontrun{
job$read_mdd()
}

Method list_table()

List all table names in EnergyPlus SQL output

Usage

EplusJob$list_table()

Details

⁠$list_table()⁠ returns all available table and view names in the EnergyPlus SQLite file.

Returns

A character vector

Examples

\dontrun{
job$list_table()
}

Method read_table()

Read a single table from EnergyPlus SQL output

Usage

EplusJob$read_table(name)

Arguments

Details

⁠$read_table()⁠ takes a valid table name of those from $list_table() and returns that table data in a data.table::data.table() format.

Returns

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

Examples

\dontrun{
# read a specific table
job$read_table("Zones")
}

Method report_data_dict()

Read report data dictionary from EnergyPlus SQL output

Usage

EplusJob$report_data_dict()

Details

⁠$report_data_dict()⁠ returns a data.table::data.table() which contains all information about report data.

For details on the meaning of each columns, please see "2.20.2.1 ReportDataDictionary Table" in EnergyPlus "Output Details and Examples" documentation.

Returns

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

• report_data_dictionary_index: The integer used to link the dictionary data to the variable data. Mainly useful when joining different tables

• is_meter: Whether report data is a meter data. Possible values: 0 and 1

• timestep_type: Type of data timestep. Possible values: Zone and ⁠HVAC System⁠

• key_value: Key name of the data

• name: Actual report data name

• reporting_frequency: Data reporting frequency

• schedule_name: Name the the schedule that controls reporting frequency.

• units: The data units

Examples

\dontrun{
job$report_data_dict()
}

Method report_data()

Read report data

Usage

EplusJob$report_data(
  key_value = NULL,
  name = NULL,
  year = NULL,
  tz = "UTC",
  case = "auto",
  all = FALSE,
  wide = FALSE,
  period = NULL,
  month = NULL,
  day = NULL,
  hour = NULL,
  minute = NULL,
  interval = NULL,
  simulation_days = NULL,
  day_type = NULL,
  environment_name = NULL
)

Arguments

Details

⁠$report_data()⁠ extracts the report data in a data.table::data.table() using key values, variable names and other specifications.

⁠$report_data()⁠ can also directly take all or subset output from ⁠$report_data_dict()⁠ as input, and extract all data specified.

The returned column numbers varies depending on all argument.

• all is FALSE, the returned data.table::data.table() has 6 columns:

  • case: Simulation case specified using case argument

  • datetime: The date time of simulation result

  • key_value: Key name of the data

  • name: Actual report data name

  • units: The data units

  • value: The data value

• all is TRUE, besides columns described above, extra columns are also included:

  • month: The month of reported date time

  • day: The day of month of reported date time

  • hour: The hour of reported date time

  • minute: The minute of reported date time

  • dst: Daylight saving time indicator. Possible values: 0 and 1

  • interval: Length of reporting interval

  • simulation_days: Day of simulation

  • day_type: The type of day, e.g. Monday, Tuesday and etc.

  • environment_period_index: The indices of environment.

  • environment_name: A text string identifying the environment.

  • is_meter: Whether report data is a meter data. Possible values: 0 and 1

  • type: Nature of data type with respect to state. Possible values: Sum and Avg

  • index_group: The report group, e.g. Zone, System

  • timestep_type: Type of data timestep. Possible values: Zone and ⁠HVAC System⁠

  • reporting_frequency: The reporting frequency of the variable, e.g. ⁠HVAC System Timestep⁠, ⁠Zone Timestep⁠.

  • schedule_name: Name of the the schedule that controls reporting frequency.

With the datetime column, it is quite straightforward to apply time-series analysis on the simulation output. However, another painful thing is that every simulation run period has its own ⁠Day of Week for Start Day⁠. 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 RunPeriod objects.

eplusr provides a simple solution for this. By setting year to NULL, which is the default behavior, eplusr will calculate a year value (from year 2017 backwards) for each run period that compliances with the start day of week restriction.

It is worth noting that EnergyPlus uses 24-hour clock system where 24 is only used to denote midnight at the end of a calendar day. In EnergyPlus output, "00:24:00" with a time interval being 15 mins represents a time period from "00:23:45" to "00:24:00", and similarly "00:15:00" represents a time period from "00:24:00" to "00:15:00" of the next day. This means that if current day is Friday, day of week rule applied in schedule time period "00:23:45" to "00:24:00" (presented as "00:24:00" in the output) is also Friday, but not Saturday. However, if you try to get the day of week of time "00:24:00" in R, you will get Saturday, but not Friday. This introduces inconsistency and may cause problems when doing data analysis considering day of week value.

With wide equals TRUE, ⁠$report_data()⁠ will format the simulation output in the same way as standard EnergyPlus csv output file. Sometimes this can be useful as there may be existing tools/workflows that depend on this format. When both wide and all are TRUE, columns of runperiod environment names and date time components are also returned, including: ⁠environment_period_index", "environment_name⁠, simulation_days, datetime, month, day, hour, minute, day_type.

For convenience, input character arguments matching in ⁠$report_data()⁠ are case-insensitive.

Returns

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

Examples

\dontrun{
# read all report data
job$report_data()

# specify output variables using report data dictionary
dict <- job$report_data_dict()
job$report_data(dict[units == "C"])

# specify output variables using 'key_value' and 'name'
job$report_data("environment", "site outdoor air drybulb temperature")

# explicitly specify year value and time zone
job$report_data(dict[1], year = 2020, tz = "Etc/GMT+8")

# explicitly specify case name
job$report_data(dict[1], case = "example")

# get all possible columns
job$report_data(dict[1], all = TRUE)

# return in a format that is similar as EnergyPlus CSV output
job$report_data(dict[1], wide = TRUE)

# return in a format that is similar as EnergyPlus CSV output with
# extra columns
job$report_data(dict[1], wide = TRUE, all = TRUE)

# only get data at the working hour on the first Monday
job$report_data(dict[1], hour = 8:18, day_type = "monday", simulation_days = 1:7)

# only get specified run period data
job$read_table("EnvironmentPeriods") # possible environment name
job$report_data(dict[1], environment_name = "San Francisco Intl Ap CA USA TMY3 WMO#=724940")
# can also be done using 'environment_period_index' column
job$report_data(dict[1], all = TRUE)[environment_period_index == 3L]
}

Method tabular_data()

Read tabular data

Usage

EplusJob$tabular_data(
  report_name = NULL,
  report_for = NULL,
  table_name = NULL,
  column_name = NULL,
  row_name = NULL,
  wide = FALSE,
  string_value = !wide
)

Arguments

Details

⁠$tabular_data()⁠ extracts the tabular data in a data.table::data.table() using report, table, column and row name specifications. The returned data.table::data.table() has 9 columns:

• case: Simulation case specified using case argument

• index: Tabular data index

• report_name: The name of the report that the record belongs to

• report_for: The For text that is associated with the record

• table_name: The name of the table that the record belongs to

• column_name: The name of the column that the record belongs to

• row_name: The name of the row that the record belongs to

• units: The units of the record

• value: The value of the record in string format by default

For convenience, input character arguments matching in ⁠$tabular_data()⁠ are case-insensitive.

Returns

A data.table::data.table() with 8 columns (when wide is FALSE) or a named list of data.table::data.table()s where the names are the combination of report_name, report_for and table_name.

Examples

\dontrun{
# read all tabular data
job$tabular_data()

# explicitly specify data you want
str(job$tabular_data(
    report_name = "AnnualBuildingUtilityPerformanceSummary",
    table_name = "Site and Source Energy",
    column_name = "Total Energy",
    row_name = "Total Site Energy"
))

# get tabular data in wide format and coerce numeric values
str(job$tabular_data(
    report_name = "AnnualBuildingUtilityPerformanceSummary",
    table_name = "Site and Source Energy",
    column_name = "Total Energy",
    row_name = "Total Site Energy",
    wide = TRUE, string_value = FALSE
))
}

Method print()

Print EplusSql object

Usage

EplusJob$print()

Details

⁠$print()⁠ shows the core information of this EplusJob object, including the path of model and weather, the version and path of EnergyPlus used to run simulations, and the simulation job status.

⁠$print()⁠ is quite useful to get the simulation status, especially when wait is FALSE in ⁠$run()⁠. The job status will be updated and printed whenever ⁠$print()⁠ is called.

Returns

The EplusSql object itself, invisibly.

Examples

\dontrun{
job$print()
}

Author(s)

Hongyuan Jia

See Also

ParametricJob class for EnergyPlus parametric simulations.

param_job() for creating an EnergyPlus parametric job.

Examples

## ------------------------------------------------
## Method `EplusJob$new`
## ------------------------------------------------

## Not run: 
if (is_avail_eplus("8.8")) {
    name_idf <- "1ZoneUncontrolled.idf"
    name_epw <-  "USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw"

    path_idf <- path_eplus_example("8.8", name_idf)
    path_epw <- path_eplus_weather("8.8", name_epw)

    # create from local files
    job <- eplus_job(path_idf, path_epw)

    # create from an Idf and an Epw object
    job <- eplus_job(read_idf(path_idf), read_epw(path_epw))
}

## End(Not run)

## ------------------------------------------------
## Method `EplusJob$version`
## ------------------------------------------------

## Not run: 
job$version()

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$path`
## ------------------------------------------------

## Not run: 
job$path()
job$path("idf")
job$path("epw")

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$run`
## ------------------------------------------------

## Not run: 
# only run design day
job$run(NULL)

# specify output directory
job$run(dir = tempdir())

# run in the background
job$run(wait = TRUE)
# see job status
job$status()

# force to kill background job before running the new one
job$run(force = TRUE)

# do not show anything in the console
job$run(echo = FALSE)

# copy external files used in the model to simulation output directory
job$run(copy_external = TRUE)

# run simulation without generating CSV files from ESO output
job$run(epw, dir = tempdir(), readvars = FALSE)

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$kill`
## ------------------------------------------------

## Not run: 
job$kill()

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$status`
## ------------------------------------------------

## Not run: 
job$status()

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$errors`
## ------------------------------------------------

## Not run: 
job$errors()

# show all information
job$errors(info = TRUE)

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$output_dir`
## ------------------------------------------------

## Not run: 
job$output_dir()

# Below will open output directory
# job$output_dir(open = TRUE)

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$list_files`
## ------------------------------------------------

## Not run: 
# list all files in the output directory
job$list_files(simplify = TRUE)

# get a full list of all possible inputs and outputs even though they
# may not exist for current simulation
job$list_files()

# return the full paths instead of just file names
job$locate_output(full = TRUE)

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$locate_output`
## ------------------------------------------------

## Not run: 
# get the file path of the error file
job$locate_output(".err", strict = FALSE)

# can use to detect if certain output file exists
job$locate_output(".expidf", strict = TRUE)

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$read_rdd`
## ------------------------------------------------

## Not run: 
job$read_rdd()

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$read_mdd`
## ------------------------------------------------

## Not run: 
job$read_mdd()

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$list_table`
## ------------------------------------------------

## Not run: 
job$list_table()

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$read_table`
## ------------------------------------------------

## Not run: 
# read a specific table
job$read_table("Zones")

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$report_data_dict`
## ------------------------------------------------

## Not run: 
job$report_data_dict()

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$report_data`
## ------------------------------------------------

## Not run: 
# read all report data
job$report_data()

# specify output variables using report data dictionary
dict <- job$report_data_dict()
job$report_data(dict[units == "C"])

# specify output variables using 'key_value' and 'name'
job$report_data("environment", "site outdoor air drybulb temperature")

# explicitly specify year value and time zone
job$report_data(dict[1], year = 2020, tz = "Etc/GMT+8")

# explicitly specify case name
job$report_data(dict[1], case = "example")

# get all possible columns
job$report_data(dict[1], all = TRUE)

# return in a format that is similar as EnergyPlus CSV output
job$report_data(dict[1], wide = TRUE)

# return in a format that is similar as EnergyPlus CSV output with
# extra columns
job$report_data(dict[1], wide = TRUE, all = TRUE)

# only get data at the working hour on the first Monday
job$report_data(dict[1], hour = 8:18, day_type = "monday", simulation_days = 1:7)

# only get specified run period data
job$read_table("EnvironmentPeriods") # possible environment name
job$report_data(dict[1], environment_name = "San Francisco Intl Ap CA USA TMY3 WMO#=724940")
# can also be done using 'environment_period_index' column
job$report_data(dict[1], all = TRUE)[environment_period_index == 3L]

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$tabular_data`
## ------------------------------------------------

## Not run: 
# read all tabular data
job$tabular_data()

# explicitly specify data you want
str(job$tabular_data(
    report_name = "AnnualBuildingUtilityPerformanceSummary",
    table_name = "Site and Source Energy",
    column_name = "Total Energy",
    row_name = "Total Site Energy"
))

# get tabular data in wide format and coerce numeric values
str(job$tabular_data(
    report_name = "AnnualBuildingUtilityPerformanceSummary",
    table_name = "Site and Source Energy",
    column_name = "Total Energy",
    row_name = "Total Site Energy",
    wide = TRUE, string_value = FALSE
))

## End(Not run)


## ------------------------------------------------
## Method `EplusJob$print`
## ------------------------------------------------

## Not run: 
job$print()

## End(Not run)

Description

Get and set eplusr options which affect the way in which eplusr computes and displays its results.

Usage

eplusr_option(...)

Arguments

Details

• validate_level: The strictness level of validation during field value modification and model error checking. Possible value: "none", "draft" and "final" or a custom validation level using custom_validate(). Default: "final". For what validation components each level contains, see level_checks().

• view_in_ip: Whether models should be presented in IP units. Default: FALSE. It is not recommended to set this option to TRUE as currently IP-units support in eplusr is not fully tested.

• save_format: The default format to use when saving Idf objects to .idf files. Possible values: "asis", "sorted", "new_top" and "new_bot". The later three have the same effect as ⁠Save Options⁠ settings "Sorted", "Original with New at Top" and "Original with New at Bottom" in IDF Editor, respectively. For "asis", the saving format will be set according to the header of IDF file. If no header found, "sorted" is used. Default: "asis".

• num_parallel: Maximum number of parallel simulations to run. Default: parallel::detectCores().

• verbose_info: Whether to show information messages. Default: TRUE.

• autocomplete: Deprecated. Whether to turn on autocompletion on class and field names. Now autocompletion is enabled all the time.

Value

If called directly, a named list of input option values. If input is a single option name, a length-one vector whose type is determined by that option. If input is new option values, a named list of newly set option values.

Author(s)

Hongyuan Jia

Examples

# list all current options
eplusr_option() # a named list

# get a specific option value
eplusr_option("verbose_info")

# set options
eplusr_option(verbose_info = TRUE, view_in_ip = FALSE)

Description

EplusSql class wraps SQL queries that can retrieve simulation outputs using EnergyPlus SQLite output file.

Details

SQLite output is an optional output format for EnergyPlus. It will be created if there is an object in class Output:SQLite. If the value of field Option in class Output:SQLite is set to "SimpleAndTabular", then database tables related to the tabular reports will be also included.

There are more than 30 tables in the SQLite output file which contains all of the data found in EnergyPlus's tabular output files, standard variable and meter output files, plus a number of reports that are found in the eplusout.eio output file. The full description for SQLite outputs can be found in the EnergyPlus "Output Details and Examples" documentation. Note that all column names of tables returned have been tidied, i.e. "KeyValue" becomes "key_value", "IsMeter" becomes "is_meter" and etc.

EplusSql class makes it possible to directly retrieve simulation results without creating an EplusJob object. EplusJob can only get simulation outputs after the job was successfully run before.

However, it should be noted that, unlike EplusJob, there is no checking on whether the simulation is terminated or completed unsuccessfully or, the parent Idf has been changed since last simulation. This means that you may encounter some problems when retrieve data from an unsuccessful simulation. It is suggested to carefully go through the .err file using read_err() to make sure the output data in the SQLite is correct and reliable.

Methods

Public methods

• EplusSql$new()

• EplusSql$path()

• EplusSql$path_idf()

• EplusSql$list_table()

• EplusSql$read_table()

• EplusSql$report_data_dict()

• EplusSql$report_data()

• EplusSql$tabular_data()

• EplusSql$print()

Method new()

Create an EplusSql object

Usage

EplusSql$new(sql)

Arguments

Returns

An EplusSql object.

Examples

\dontrun{
if (is_avail_eplus("8.8")) {
    idf_name <- "1ZoneUncontrolled.idf"
    epw_name <-  "USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw"

    idf_path <- path_eplus_example("8.8", idf_name)
    epw_path <- path_eplus_weather("8.8", epw_name)

    # copy to tempdir and run the model
    idf <- read_idf(idf_path)
    idf$run(epw_path, tempdir(), echo = FALSE)

    # create from local file
    sql <- eplus_sql(file.path(tempdir(), "1ZoneUncontrolled.sql"))
}
}

Method path()

Get the file path of current EpwSql object

Usage

EplusSql$path()

Details

⁠$path()⁠ returns the path of EnergyPlus SQLite file.

Returns

A single string.

Examples

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

Method path_idf()

Get the path of corresponding IDF file

Usage

EplusSql$path_idf()

Details

⁠$path_idf()⁠ returns the IDF file path with same name as the SQLite file in the same folder. NULL is returned if no corresponding IDF is found.

Returns

NULL or a single string.

Examples

\dontrun{
# get path
sql$path_idf()
}

Method list_table()

List all table names in current EnergyPlus SQL output

Usage

EplusSql$list_table()

Details

⁠$list_table()⁠ returns all available table and view names in the EnergyPlus SQLite file.

Returns

A character vector

Examples

\dontrun{
sql$list_table()
}

Method read_table()

Read a single table from current EnergyPlus SQL output

Usage

EplusSql$read_table(name)

Arguments

Details

⁠$read_table()⁠ takes a valid table name of those from $list_table() and returns that table data in a data.table::data.table() format.

Returns

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

Examples

\dontrun{
# read a specific table
sql$read_table("Zones")
}

Method report_data_dict()

Read report data dictionary from current EnergyPlus SQL output

Usage

EplusSql$report_data_dict()

Details

⁠$report_data_dict()⁠ returns a data.table::data.table() which contains all information about report data.

For details on the meaning of each columns, please see "2.20.2.1 ReportDataDictionary Table" in EnergyPlus "Output Details and Examples" documentation.

Returns

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

• report_data_dictionary_index: The integer used to link the dictionary data to the variable data. Mainly useful when joining different tables

• is_meter: Whether report data is a meter data. Possible values: 0 and 1

• timestep_type: Type of data timestep. Possible values: Zone and ⁠HVAC System⁠

• key_value: Key name of the data

• name: Actual report data name

• reporting_frequency:

• schedule_name: Name of the the schedule that controls reporting frequency.

• units: The data units

Examples

\dontrun{
sql$report_data_dict()
}

Method report_data()

Read report data

Usage

EplusSql$report_data(
  key_value = NULL,
  name = NULL,
  year = NULL,
  tz = "UTC",
  case = "auto",
  all = FALSE,
  wide = FALSE,
  period = NULL,
  month = NULL,
  day = NULL,
  hour = NULL,
  minute = NULL,
  interval = NULL,
  simulation_days = NULL,
  day_type = NULL,
  environment_name = NULL
)

Arguments

Details

⁠$report_data()⁠ extracts the report data in a data.table::data.table() using key values, variable names and other specifications.

⁠$report_data()⁠ can also directly take all or subset output from ⁠$report_data_dict()⁠ as input, and extract all data specified.

The returned column numbers varies depending on all argument.

• all is FALSE, the returned data.table::data.table() has 6 columns:

  • case: Simulation case specified using case argument

  • datetime: The date time of simulation result

  • key_value: Key name of the data

  • name: Actual report data name

  • units: The data units

  • value: The data value

• all is TRUE, besides columns described above, extra columns are also included:

  • month: The month of reported date time

  • day: The day of month of reported date time

  • hour: The hour of reported date time

  • minute: The minute of reported date time

  • dst: Daylight saving time indicator. Possible values: 0 and 1

  • interval: Length of reporting interval

  • simulation_days: Day of simulation

  • day_type: The type of day, e.g. Monday, Tuesday and etc.

  • environment_period_index: The indices of environment.

  • environment_name: A text string identifying the environment.

  • is_meter: Whether report data is a meter data. Possible values: 0 and 1

  • type: Nature of data type with respect to state. Possible values: Sum and Avg

  • index_group: The report group, e.g. Zone, System

  • timestep_type: Type of data timestep. Possible values: Zone and ⁠HVAC System⁠

  • reporting_frequency: The reporting frequency of the variable, e.g. ⁠HVAC System Timestep⁠, ⁠Zone Timestep⁠.

  • schedule_name: Name of the the schedule that controls reporting frequency.

With the datetime column, it is quite straightforward to apply time-series analysis on the simulation output. However, another painful thing is that every simulation run period has its own ⁠Day of Week for Start Day⁠. 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 RunPeriod objects.

eplusr provides a simple solution for this. By setting year to NULL, which is the default behavior, eplusr will calculate a year value (from year 2017 backwards) for each run period that compliances with the start day of week restriction.

It is worth noting that EnergyPlus uses 24-hour clock system where 24 is only used to denote midnight at the end of a calendar day. In EnergyPlus output, "00:24:00" with a time interval being 15 mins represents a time period from "00:23:45" to "00:24:00", and similarly "00:15:00" represents a time period from "00:24:00" to "00:15:00" of the next day. This means that if current day is Friday, day of week rule applied in schedule time period "00:23:45" to "00:24:00" (presented as "00:24:00" in the output) is also Friday, but not Saturday. However, if you try to get the day of week of time "00:24:00" in R, you will get Saturday, but not Friday. This introduces inconsistency and may cause problems when doing data analysis considering day of week value.

With wide equals TRUE, ⁠$report_data()⁠ will format the simulation output in the same way as standard EnergyPlus csv output file. Sometimes this can be useful as there may be existing tools/workflows that depend on this format. When both wide and all are TRUE, columns of runperiod environment names and date time components are also returned, including: ⁠environment_period_index", "environment_name⁠, simulation_days, datetime, month, day, hour, minute, day_type.

For convenience, input character arguments matching in ⁠$report_data()⁠ are case-insensitive.

Returns

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

Examples

\dontrun{
# read all report data
sql$report_data()

# specify output variables using report data dictionary
dict <- sql$report_data_dict()
sql$report_data(dict[units == "C"])

# specify output variables using 'key_value' and 'name'
sql$report_data("environment", "site outdoor air drybulb temperature")

# explicitly specify year value and time zone
sql$report_data(dict[1], year = 2020, tz = "Etc/GMT+8")

# explicitly specify case name
sql$report_data(dict[1], case = "example")

# get all possible columns
sql$report_data(dict[1], all = TRUE)

# return in a format that is similar as EnergyPlus CSV output
sql$report_data(dict[1], wide = TRUE)

# return in a format that is similar as EnergyPlus CSV output with
# extra columns
sql$report_data(dict[1], wide = TRUE, all = TRUE)

# only get data at the working hour on the first Monday
sql$report_data(dict[1], hour = 8:18, day_type = "monday", simulation_days = 1:7)

# only get specified run period data
sql$read_table("EnvironmentPeriods") # possible environment name
sql$report_data(dict[1], environment_name = "San Francisco Intl Ap CA USA TMY3 WMO#=724940")
# can also be done using 'environment_period_index' column
sql$report_data(dict[1], all = TRUE)[environment_period_index == 3L]
}

Method tabular_data()

Read tabular data

Usage

EplusSql$tabular_data(
  report_name = NULL,
  report_for = NULL,
  table_name = NULL,
  column_name = NULL,
  row_name = NULL,
  case = "auto",
  wide = FALSE,
  string_value = !wide
)

Arguments

Details

⁠$tabular_data()⁠ extracts the tabular data in a data.table::data.table() using report, table, column and row name specifications. The returned data.table::data.table() has 9 columns:

• case: Simulation case specified using case argument

• index: Tabular data index

• report_name: The name of the report that the record belongs to

• report_for: The For text that is associated with the record

• table_name: The name of the table that the record belongs to

• column_name: The name of the column that the record belongs to

• row_name: The name of the row that the record belongs to

• units: The units of the record

• value: The value of the record in string format by default.

For convenience, input character arguments matching in ⁠$tabular_data()⁠ are case-insensitive.

Returns

A data.table::data.table() with 9 columns (when wide is FALSE) or a named list of data.table::data.table()s where the names are the combination of report_name, report_for and table_name.

Examples

\dontrun{
# read all tabular data
sql$tabular_data()

# explicitly specify data you want
str(sql$tabular_data(
    report_name = "AnnualBuildingUtilityPerformanceSummary",
    table_name = "Site and Source Energy",
    column_name = "Total Energy",
    row_name = "Total Site Energy"
))

# get tabular data in wide format and coerce numeric values
str(sql$tabular_data(
    report_name = "AnnualBuildingUtilityPerformanceSummary",
    table_name = "Site and Source Energy",
    column_name = "Total Energy",
    row_name = "Total Site Energy",
    wide = TRUE, string_value = FALSE
))
}

Method print()

Print EplusSql object

Usage

EplusSql$print()

Details

⁠$print()⁠ shows the core information of this EplusSql object, including the path of the EnergyPlus SQLite file, last modified time of the SQLite file and the path of the IDF file with the same name in the same folder.

Returns

The EplusSql object itself, invisibly.

Examples

\dontrun{
sql$print()
}

Author(s)

Hongyuan Jia

Examples

## ------------------------------------------------
## Method `EplusSql$new`
## ------------------------------------------------

## Not run: 
if (is_avail_eplus("8.8")) {
    idf_name <- "1ZoneUncontrolled.idf"
    epw_name <-  "USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw"

    idf_path <- path_eplus_example("8.8", idf_name)
    epw_path <- path_eplus_weather("8.8", epw_name)

    # copy to tempdir and run the model
    idf <- read_idf(idf_path)
    idf$run(epw_path, tempdir(), echo = FALSE)

    # create from local file
    sql <- eplus_sql(file.path(tempdir(), "1ZoneUncontrolled.sql"))
}

## End(Not run)


## ------------------------------------------------
## Method `EplusSql$path`
## ------------------------------------------------

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

## End(Not run)


## ------------------------------------------------
## Method `EplusSql$path_idf`
## ------------------------------------------------

## Not run: 
# get path
sql$path_idf()

## End(Not run)


## ------------------------------------------------
## Method `EplusSql$list_table`
## ------------------------------------------------

## Not run: 
sql$list_table()

## End(Not run)


## ------------------------------------------------
## Method `EplusSql$read_table`
## ------------------------------------------------

## Not run: 
# read a specific table
sql$read_table("Zones")

## End(Not run)


## ------------------------------------------------
## Method `EplusSql$report_data_dict`
## ------------------------------------------------

## Not run: 
sql$report_data_dict()

## End(Not run)


## ------------------------------------------------
## Method `EplusSql$report_data`
## ------------------------------------------------

## Not run: 
# read all report data
sql$report_data()

# specify output variables using report data dictionary
dict <- sql$report_data_dict()
sql$report_data(dict[units == "C"])

# specify output variables using 'key_value' and 'name'
sql$report_data("environment", "site outdoor air drybulb temperature")

# explicitly specify year value and time zone
sql$report_data(dict[1], year = 2020, tz = "Etc/GMT+8")

# explicitly specify case name
sql$report_data(dict[1], case = "example")

# get all possible columns
sql$report_data(dict[1], all = TRUE)

# return in a format that is similar as EnergyPlus CSV output
sql$report_data(dict[1], wide = TRUE)

# return in a format that is similar as EnergyPlus CSV output with
# extra columns
sql$report_data(dict[1], wide = TRUE, all = TRUE)

# only get data at the working hour on the first Monday
sql$report_data(dict[1], hour = 8:18, day_type = "monday", simulation_days = 1:7)

# only get specified run period data
sql$read_table("EnvironmentPeriods") # possible environment name
sql$report_data(dict[1], environment_name = "San Francisco Intl Ap CA USA TMY3 WMO#=724940")
# can also be done using 'environment_period_index' column
sql$report_data(dict[1], all = TRUE)[environment_period_index == 3L]

## End(Not run)


## ------------------------------------------------
## Method `EplusSql$tabular_data`
## ------------------------------------------------

## Not run: 
# read all tabular data
sql$tabular_data()

# explicitly specify data you want
str(sql$tabular_data(
    report_name = "AnnualBuildingUtilityPerformanceSummary",
    table_name = "Site and Source Energy",
    column_name = "Total Energy",
    row_name = "Total Site Energy"
))

# get tabular data in wide format and coerce numeric values
str(sql$tabular_data(
    report_name = "AnnualBuildingUtilityPerformanceSummary",
    table_name = "Site and Source Energy",
    column_name = "Total Energy",
    row_name = "Total Site Energy",
    wide = TRUE, string_value = FALSE
))

## End(Not run)


## ------------------------------------------------
## Method `EplusSql$print`
## ------------------------------------------------

## Not run: 
sql$print()

## End(Not run)

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

• 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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)

Description

Format an Idd into a string.

Usage

## S3 method for class 'Idd'
format(x, ...)

Arguments

Value

A single length character vector.

Examples

## Not run: 
format(use_idd(8.8, download = "auto"))

## End(Not run)

Description

Format an IddObject into a string. It is formatted the same way as IddObject$print(brief = TRUE) but with a suffix of current IDD version.

Usage

## S3 method for class 'IddObject'
format(x, ver = TRUE, ...)

Arguments

Value

A single length character vector.

Examples

## Not run: 
format(use_idd(8.8, download = "auto")$Material)

## End(Not run)

Description

Format an Idf object.

Usage

## S3 method for class 'Idf'
format(
  x,
  comment = TRUE,
  header = TRUE,
  format = eplusr_option("save_format"),
  leading = 4L,
  sep_at = 29L,
  ...
)

Arguments

Value

A single length string.

Author(s)

Hongyuan Jia

Examples

## Not run: 
idf_path <- system.file("extdata/1ZoneUncontrolled.idf", package = "eplusr")
cat(format(read_idf(idf_path, use_idd(8.8, "auto")), leading = 0))

## End(Not run)

Description

Format an IddObject into a character vector in the same way as in IDF Editor.

Usage

## S3 method for class 'IdfObject'
format(x, comment = TRUE, leading = 4L, sep_at = 29L, all = FALSE, ...)

Arguments