IdfObject is an abstraction of a single object in an Idf. It provides
more detail methods to modify object values and comments. An IdfObject
object can also be created using function idf_object() or from methods of a
parent Idf object, using $object(), $objects_in_class() and equivalent.
Only one single list is allowed, e.g. idfobj$set(lst1) where lst1 <- list(field1 = value1) is allowed, but idfobj$set(lst1, lst2) is not.
You can delete a field by assigning NULL to it, e.g. iddobj$set(fld = NULL) means to delete the value of field fld. If .default is FALSE,
also fld is not a required field and the index of fld is larger than
the number minimum fields required for that class, it will be deleted.
Otherwise it will be left as blank. If .default is TRUE, that field
will be filled with default value if applicable and left as blank if not.
By default, trailing empty fields that are not required will be removed and
only minimum required fields are kept. You can keep the trailing empty
fields by setting .empty to TRUE.
New fields that currently do not exist in that object can also be set. They will be automatically added on the fly.
Field name matching is case-insensitive. For convenience,
underscore-style field names are also allowed, e.g. eNd_MoNtH is
equivalent to End Month.
If not all field names are given, positions of those values without field
names are determined after those values with names. E.g. in
model$set(Construction = list("out_layer", name = "name")), "out_layer"
will be treated as the value of field Outside Layer in Construction, as
value of field Name has been given as "name".
eplusr also provides custom S3 method of $<- and
[[<- which makes it more convenient to set a single field value of an
IdfObject. Basically, idfobj$FieldName <- value and idfobj[[Field]]
<- value is equivalent to idfobj$set(FieldName = value) and
idfobjset(Field = value).
Idf class
new()Create an IdfObject object
IdfObject$new(object, class = NULL, parent)objectAn integer specifying an object ID.
classAn integer specifying a class index.
parentAn Idf object specifying the parent object.
It is not recommended to directly use $new() method to create an
IdfObject object, instead considering to use idf_object,
Idf$object()
and other equivalent to create IdfObject objects. They provide
more user-friendly interfaces. $new() is a lower level API which is
mainly used inside methods in other classes.
\dontrun{
# example model shipped with eplusr from EnergyPlus v8.8
path_idf <- system.file("extdata/1ZoneUncontrolled.idf", package = "eplusr") # v8.8
idf <- read_idf(path_idf, use_idd(8.8, "auto"))
roof <- IdfObject$new(26, parent = idf)
# get the IdfObject of material named "C5 - 4 IN HW CONCRETE"
mat <- idf$Material[["C5 - 4 IN HW CONCRETE"]]
}
version()Get the version of parent Idf
$version() returns the version of parent Idf in a
base::numeric_version() format. This makes it easy to direction
compare versions of different IdfObjects, e.g. idfobj$version() > 8.6 or
idfobj1$version() > idfobj2$version().
A base::numeric_version() object.
id()Get the unique ID for current object
name()Get the name for current object.
In Idf, each object is assigned with a single string as the name
for it, if the class it belongs to has name attribute, e.g. class
RunPeriod, Material and etc. That name should be unique among all
objects in that class. EnergyPlus will fail with an error if
duplications are found among object names in a class.
$name() returns a single string of current object name. If
specified class does not have name attribute, NA is returned.
definition()Get the IddObject object for current class.
$definition() returns an IddObject of current class. IddObject
contains all data used for parsing and creating current IdfObject.
For details, please see IddObject class.
An IddObject object.
comment()Get and modify object comments
commentA character vector.
If missing, current comments are returned. If there is no
comment in current IdfObject, NULL is returned.
If NULL, all comments in current IdfObject is deleted.
If a character vector, it is inserted as comments depending on
the append value.
appendOnly applicable when commment is a character vector.
Default: FALSE.
If NULL, existing comments is deleted before adding comment.
If TRUE, comment will be appended to existing comments.
If FALSE, comment is prepended to existing currents.
widthA positive integer giving the target width for wrapping
inserted comment.
$comment() returns current IdfObject comments if comment is not
given, or modifies current IdfObject comments if comment is given.
If no comments found, NULL is returned.
If calling without any argument, a character vector or NULL
(if no comments) is return. Otherwise, the modified object itself.
\dontrun{
# get object comments
roof$comment()
# add new object comments
roof$comment(c("This is a material named `WD01`", "This object has an ID of 47"))
roof$comment()
# append new comments
roof$comment("This is an appended comment")
roof$comment()
# prepend new comments
roof$comment("This is a prepended comment", append = FALSE)
roof$comment()
# wrap long comments
roof$comment("This is a very long comment that is needed to be wrapped.", width = 30)
roof$comment()
# delete old comments and add new one
roof$comment("This is the only comment", append = NULL)
roof$comment()
# delete all comments
roof$comment(NULL)
roof$comment()
}
value()Get object field values.
whichAn integer vector of field indexes or a character vector of field names.
allIf TRUE, values of all possible fields in current class
the IdfObject belongs to are returned. Default: FALSE
simplifyIf TRUE, values of fields are converted into
characters and the converted character vector is returned.
unitIf TRUE, values of numeric fields are assigned with
units using units::set_units() if applicable. Default:
FALSE.
$value() takes an integer vector of valid field indexes or a
character vector of valid field names, and returns a named list
containing values of specified fields when simplify is FALSE and
a character vector when simplify is TRUE.
eplusr also provides custom S3 method of $ and [[ which make
it more convenient to get a single value of current IdfObject.
Basically, idfobj$FieldName and idfobj[[Field]] is
equivalent to idfobj$value(FieldName)[[1]] and
idfobj$value(Field)[[1]].
\dontrun{
# get all existing field values
str(mat$value())
# get values of field 1, 3, 5
str(mat$value(c(1, 3, 5)))
# get character format values instead of a named list
mat$value(c(1, 3, 5), simplify = TRUE)
# get values of all field even those that are not set
str(roof$value())
str(roof$value(all = TRUE))
# get field values using shortcuts
mat$Roughness
mat[["Specific_Heat"]]
mat[c(1,2)]
mat[c("Name", "Density")]
}
set()Modify object field values.
$set() takes new field value definitions in field = value format
or in a single list format, sets new values for fields specified, and
returns the modified IdfObject. Unlike $set() method in Idf
class, the special element .comment is not allowed. To modify
object comments, please use $comment().
\dontrun{
# set field values
mat$set(name = "new_name", Thickness = 0.02)
mat[c("Name", "Thickness")]
# When `default` argument is set to TRUE and input field values are empty, i.e.
# NULL, the field values will be reset to defaults.
mat[c("Thermal Absorptance", "Solar Absorptance")]
mat$set(visible_absorptance = NULL, Solar_Absorptance = NULL, .default = TRUE)
mat[c("Visible Absorptance", "Solar Absorptance")]
# set field values using shortcuts
mat$Name <- "another_name"
mat$Name
mat[["Thickness"]] <- 0.019
mat$Thickness
}
value_possible()Get possible object field values.
IdfObject$value_possible(
which = NULL,
type = c("auto", "default", "choice", "range", "source")
)whichAn integer vector of field indexes or a character vector of field names.
typeA character vector. What types of possible values should
be returned. Should be one of or a combination of "auto",
"default", "choice", "range" and "source". Default:
All of those.
$value_possible() takes an integer vector of valid field indexes or a character
vector of valid field names, and returns all possible values for specified
fields. For a specific field, there are 5 types of possible values:
auto: Whether the field can be filled with Autosize and
Autocalculate. This field attribute can also be retrieved using:
default: The default value. This value can also be retrieved using
idfobj$defintion()$field_default().
choice: The choices which the field can be set. This value can also be
retrieved using idfobj$definition()$field_choice().
range: The range which the field value should fall in. This range can
also be retrieved using idfobj$definition()$field_range().
source: All values from other objects that current field can refer to.
$value_possible() returns an IdfValuePossible object
which is a data.table with at most 15
columns:
class_id: index of class that current IdfObject belongs to
class_name: name of class that current IdfObject belongs to
object_id: ID of current IdfObject
object_name: name of current IdfObject
field_id: indexes (at Idd level) of object fields specified
field_index: indexes of object fields specified
field_name: names (without units) of object fields specified
value_id: value indexes (at Idf level) of object fields specified
value_chr: values (converted to characters) of object fields specified
value_num: values (converted to numbers in SI units) of object fields
specified.
auto: Exists only when "auto" is one of type. Character type.
Possible values are: "Autosize", "Autocalculate" and NA (if current
field is neither autosizable nor autocalculatable).
default: Exists only when "default" is one of type. List type. The
default value of current field. The value is converted into number if
corresponding field type yells so. Note that if current field is a numeric
field but the default value is "Autosize" or "Autocalculate", it is
left as it is, leaving the returned type being a string instead of a
number.
range: Exists only when "range" is one of type. List type. The range
that field value should fall in. Every range has four components: minimum
(lower limit), lower_incbounds (TRUE if the lower limit should be
included), maximum (upper limit), and upper_incbounds (TRUE if the
upper limit should be included). For fields of character type, empty lists
are returned. For fields of numeric types with no specified ranges,
minimum is set to -Inf, lower_incbounds is set to FALSE, upper is
set to Inf, and upper_incbounds is set to FALSE. The field range is
printed in number interval denotation.
source: Exists only when "source" is one of type. List type. Each
element is a character vector which includes all values from other objects
that current field can use as sources and refers to.
validate()Check possible object field value errors
IdfObject$validate(level = eplusr_option("validate_level"))levelOne of "none", "draft", "final" or a list of 10
elements with same format as custom_validate() output.
$validate() checks if there are errors in current IdfObject object
under specified validation level and returns an IdfValidity object.
$validate() is useful to help avoid some common errors before
running the model. By default, validation is performed when calling
all methods that modify objects, e.g.
$set()
and etc.
In total, there are 10 different validate checking components:
required_object: Check if required objects are missing in current
Idf.
unique_object: Check if there are multiple objects in one
unique-object class. An unique-object class means that there should
be at most only one object existing in that class.
unique_name: Check if all objects in each class have unique names.
extensible: Check if all fields in an extensible group have
values. An extensible group is a set of fields that should be
treated as a whole, such like the X, Y and Z vertices of a building
surfaces. An extensible group should be added or deleted together.
extensible component checks if there are some, but not all,
fields in an extensible group are empty.
required_field: Check if all required fields have values.
auto_field: Check if all fields filled with value "Autosize" and
"Autocalculate" are actual autosizable and autocalculatable
fields or not.
type: Check if all fields have value types complied with their
definitions, i.e. character, numeric and integer fields should be
filled with corresponding type of values.
choice: Check if all choice fields are filled with valid choice
values.
range: Check if all numeric fields have values within prescribed
ranges.
reference: Check if all fields whose values refer to other fields
are valid.
The level argument controls what checkings should be performed.
level here is just a list of 10 element which specify the toggle
status of each component. You can use helper custom_validate() to
get that list and pass it directly to level.
There are 3 predefined validate level that indicates different
combinations of checking components, i.e. none, draft and
final. Basically, none level just does not perform any
checkings; draft includes 5 components, i.e. auto_field, type,
unique_name, choice and range; and final level includes all
10 components. You can always get what components each level contains
using level_checks(). By default, the result from
eplusr_option("validate_level") is passed to level. If not set,
final level is used.
Underneath, an IdfValidity object which $validate() returns is a
list of 13 element as shown below. Each element or several elements
represents the results from a single validation checking component.
missing_object: Result of required_object checking.
duplicate_object: Result of unique_object checking.
conflict_name: Result of unique_name checking.
incomplete_extensible: Result of extensible checking.
missing_value: Result of required_field checking.
invalid_autosize: Result of auto_field checking for invalid
Autosize field values.
invalid_autocalculate: Result of auto_field checking for
invalid Autocalculate field values.
invalid_character: Result of type checking for invalid
character field values.
invalid_numeric: Result of type checking for invalid
numeric field values.
invalid_integer: Result of type checking for invalid
integer field values.
invalid_choice: Result of choice checking.
invalid_range: Result of range checking.
invalid_reference: Result of reference checking.
Except missing_object, which is a character vector of class names
that are missing, all other elements are
data.table with 9 columns containing data
of invalid field values:
object_id: IDs of objects that contain invalid values
object_name: names of objects that contain invalid values
class_id: indexes of classes that invalid objects belong to
class_name: names of classes that invalid objects belong to
field_id: indexes (at Idd level) of object fields that are invalid
field_index: indexes of object fields in corresponding that are invalid
field_name: names (without units) of object fields that are invalid
units: SI units of object fields that are invalid
ip_units: IP units of object fields that are invalid
type_enum: An integer vector indicates types of invalid fields
value_id: indexes (at Idf level) of object field values that are invalid
value_chr: values (converted to characters) of object fields that are
invalid
value_num: values (converted to numbers in SI units) of object fields
that are invalid
Knowing the internal structure of IdfValidity, it is easy to extract
invalid IdfObjects you interested in. For example, you can get all IDs of
objects that contain invalid value references using
model$validate()$invalid_reference$object_id. Then using
$set()
method to correct them.
Different validate result examples are shown below:
No error is found:
Above result shows that there is no error found after conducting all validate checks in specified validate level.
Errors are found:
x [2] Errors found during validation.
=========================================================================
-- [2] Invalid Autocalculate Field --------------------------------------
Fields below cannot be `autocalculate`:
Class: <AirTerminal:SingleDuct:VAV:Reheat>
\- Object [ID:176] <SPACE5-1 VAV Reheat>
+- 17: AUTOCALCULATE, !- Maximum Flow per Zone Floor Area During Reheat {m3/s-m2}
\- 18: AUTOCALCULATE; !- Maximum Flow Fraction During ReheatAbove result shows that after all validate components
performed under current validate level, 2 invalid field values
are found. All of them are in a object named SPACE5-1 VAV Reheat
with ID 176. They are invalid because those two fields do not
have an autocalculatable attribute but are given AUTOCALCULATE
value. Knowing this info, one simple way to fix the
error is to correct those two fields by doing:
is_valid()Check if there is any error in current object
IdfObject$is_valid(level = eplusr_option("validate_level"))levelOne of "none", "draft", "final" or a list of 10
elements with same format as custom_validate() output.
$is_valid() returns TRUE if there is no error in current IdfObject
object under specified validation level and FALSE otherwise.
$is_valid() checks if there are errors in current IdfObject object
under specified validation level and returns TRUE or FALSE
accordingly. For detailed description on validate checking, see
$validate()
documentation above.
\dontrun{
mat$is_valid()
mat$definition()$field_range("Density")
eplusr_option(validate_level = "none") # have to set validate to "none" to do so
mat$Density <- -1
eplusr_option(validate_level = "final") # change back to "final" validate level
mat$is_valid()
# check at predefined validate level
mat$is_valid("none")
mat$is_valid("draft")
mat$is_valid("final")
# custom validate checking components
mat$is_valid(custom_validate(auto_field = TRUE, choice = TRUE))
}
value_relation()Get value relations
whichAn integer vector of field indexes or a character vector of field names.
directionThe relation direction to extract. Should be either
"all", "ref_to" or "ref_by".
objectA character vector of object names or an integer vector
of object IDs used for searching relations. Default: NULL.
classA character vector of class names used for searching
relations. Default: NULL.
groupA character vector of group names used for searching
relations. Default: NULL.
depthIf > 0, the relation is searched recursively. A
simple example of recursive reference: one material named
mat is referred by a construction named const, and const
is also referred by a surface named surf. If NULL,
all possible recursive relations are returned. Default: 0.
keepIf TRUE, all input fields are returned regardless they
have any relations with other objects or not. If FALSE, only
fields in input that have relations with other objects are
returned. Default: FALSE.
class_refSpecify how to handle class-name-references. Class
name references refer to references in like field Component 1 Object Type in Branch objects. Their value refers to other
many class names of objects, instaed of referring to specific
field values. There are 3 options in total, i.e. "none",
"both" and "all", with "both" being the default.
* "none": just ignore class-name-references. It is a reasonable
option, as for most cases, class-name-references always come
along with field value references. Ignoring
class-name-references will not impact the most part of the
relation structure.
* "both": only include class-name-references if this object
also reference field values of the same one. For example, if the
value of field Component 1 Object Type is
Coil:Heating:Water, only the object that is referenced in the
next field Component 1 Name is treated as referenced by
Component 1 Object Type. This is the default option.
* "all": include all class-name-references. For example, if the
value of field Component 1 Object Type is
Coil:Heating:Water, all objects in Coil:Heating:Water will
be treated as referenced by that field. This is the most
aggressive option.
Many fields in Idd can be referred by others. For example, the
Outside Layer and other fields in Construction class refer to the
Name field in Material class and other material related classes.
Here it means that the Outside Layer field refers to the Name
field and the Name field is referred by the Outside Layer. In
EnergyPlus, there is also a special type of field called Node,
which together with Branch and BranchList define the topography
of the HVAC connections. A outlet node of a component can be referred
by another component as its inlet node, but can also exists
independently, such as zone air node.
$value_relation() provides a simple interface to get this kind of
relation. It takes field indexes or field names, together a relation
direction, and returns an IdfRelation object which contains data
presenting such relation described above. For instance, if
idfobj$value_relation("Name", "ref_by") gives results below:
-- Referred by Others ------------------------
\- 1: "WALL-1"; !- Name
^~~~~~~~~~~~~~~~~~~~~~~~~
\- Class: <BuildingSurface:Detailed>
\- Object [ID:3] <WALL-1PF>
\- 3: "WALL-1"; !- Construction NameThis means that the value "WALL-1" of field Name is referred by
field Construction Name in a surface named WALL-1PF. All those
objects can be further easily extracted using $ref_by_object()
method.
Note that $value_relation() shows all fields specified, even some of them
may do not have relation.
An IdfRelation object, which is a list of 3
data.table::data.table()s named ref_to, ref_by and node.
Each data.table::data.table() contains 24 columns.
ref_to_object()Extract multiple IdfObject objects referred by specified field values
IdfObject$ref_to_object(
which = NULL,
object = NULL,
class = NULL,
group = NULL,
depth = 0L,
class_ref = c("both", "none", "all")
)whichAn integer vector of field indexes or a character vector of field names.
objectA character vector of object names or an integer vector
of object IDs used for searching relations. Default: NULL.
classA character vector of class names used for searching
relations. Default: NULL.
groupA character vector of group names used for searching
relations. Default: NULL.
depthIf > 0, the relation is searched recursively. A
simple example of recursive reference: one material named
mat is referred by a construction named const, and const
is also referred by a surface named surf. If NULL,
all possible recursive relations are returned. Default: 0.
class_refSpecify how to handle class-name-references. Class
name references refer to references in like field Component 1 Object Type in Branch objects. Their value refers to other
many class names of objects, instaed of referring to specific
field values. There are 3 options in total, i.e. "none",
"both" and "all", with "both" being the default.
* "none": just ignore class-name-references. It is a reasonable
option, as for most cases, class-name-references always come
along with field value references. Ignoring
class-name-references will not impact the most part of the
relation structure.
* "both": only include class-name-references if this object
also reference field values of the same one. For example, if the
value of field Component 1 Object Type is
Coil:Heating:Water, only the object that is referenced in the
next field Component 1 Name is treated as referenced by
Component 1 Object Type. This is the default option.
* "all": include all class-name-references. For example, if the
value of field Component 1 Object Type is
Coil:Heating:Water, all objects in Coil:Heating:Water will
be treated as referenced by that field. This is the most
aggressive option.
For details on field value relations, see
$value_relation().
$ref_to_object() takes an integer vector of field indexes or a
character vector of field names, and returns a list of IdfObjects
that specified fields refer to.
ref_by_object()Extract multiple IdfObject objects referring to specified field values
IdfObject$ref_by_object(
which = NULL,
object = NULL,
class = NULL,
group = NULL,
depth = 0L,
class_ref = c("both", "none", "all")
)whichAn integer vector of field indexes or a character vector of field names.
objectA character vector of object names or an integer vector
of object IDs used for searching relations. Default: NULL.
classA character vector of class names used for searching
relations. Default: NULL.
groupA character vector of group names used for searching
relations. Default: NULL.
depthIf > 0, the relation is searched recursively. A
simple example of recursive reference: one material named
mat is referred by a construction named const, and const
is also referred by a surface named surf. If NULL,
all possible recursive relations are returned. Default: 0.
class_refSpecify how to handle class-name-references. Class
name references refer to references in like field Component 1 Object Type in Branch objects. Their value refers to other
many class names of objects, instaed of referring to specific
field values. There are 3 options in total, i.e. "none",
"both" and "all", with "both" being the default.
* "none": just ignore class-name-references. It is a reasonable
option, as for most cases, class-name-references always come
along with field value references. Ignoring
class-name-references will not impact the most part of the
relation structure.
* "both": only include class-name-references if this object
also reference field values of the same one. For example, if the
value of field Component 1 Object Type is
Coil:Heating:Water, only the object that is referenced in the
next field Component 1 Name is treated as referenced by
Component 1 Object Type. This is the default option.
* "all": include all class-name-references. For example, if the
value of field Component 1 Object Type is
Coil:Heating:Water, all objects in Coil:Heating:Water will
be treated as referenced by that field. This is the most
aggressive option.
For details on field value relations, see
$value_relation().
$ref_by_object() takes an integer vector of field indexes or a
character vector of field names, and returns a list of IdfObjects
that refer to specified fields.
ref_to_node()Extract multiple IdfObject objects referring to same nodes
whichAn integer vector of field indexes or a character vector of field names.
objectA character vector of object names or an integer vector
of object IDs used for searching relations. Default: NULL.
classA character vector of class names used for searching
relations. Default: NULL.
groupA character vector of group names used for searching
relations. Default: NULL.
depthIf > 0, the relation is searched recursively. A
simple example of recursive reference: one material named
mat is referred by a construction named const, and const
is also referred by a surface named surf. If NULL,
all possible recursive relations are returned. Default: 0.
For details on field value relations, see
$value_relation().
$ref_to_node() takes an integer vector of field indexes or a
character vector of field names, and returns a list of IdfObjects
whose nodes are referred by specified fields.
has_ref_to()Check if object field values refer to others
IdfObject$has_ref_to(
which = NULL,
object = NULL,
class = NULL,
group = NULL,
recursive = FALSE,
class_ref = c("both", "none", "all")
)whichAn integer vector of field indexes or a character vector of field names.
objectA character vector of object names or an integer vector
of object IDs used for searching relations. Default: NULL.
classA character vector of class names used for searching
relations. Default: NULL.
groupA character vector of group names used for searching
relations. Default: NULL.
recursiveIf TRUE, the relation is searched recursively. A
simple example of recursive reference: one material named
mat is referred by a construction named const, and const
is also referred by a surface named surf. Default: FALSE.
class_refSpecify how to handle class-name-references. Class
name references refer to references in like field Component 1 Object Type in Branch objects. Their value refers to other
many class names of objects, instaed of referring to specific
field values. There are 3 options in total, i.e. "none",
"both" and "all", with "both" being the default.
* "none": just ignore class-name-references. It is a reasonable
option, as for most cases, class-name-references always come
along with field value references. Ignoring
class-name-references will not impact the most part of the
relation structure.
* "both": only include class-name-references if this object
also reference field values of the same one. For example, if the
value of field Component 1 Object Type is
Coil:Heating:Water, only the object that is referenced in the
next field Component 1 Name is treated as referenced by
Component 1 Object Type. This is the default option.
* "all": include all class-name-references. For example, if the
value of field Component 1 Object Type is
Coil:Heating:Water, all objects in Coil:Heating:Water will
be treated as referenced by that field. This is the most
aggressive option.
For details on field value relations, see
$value_relation().
$has_ref_to() takes an integer vector of field indexes or a
character vector of field names, and returns a logical vector showing
whether specified fields refer to other object values or not.
has_ref_by()Check if object field values are referred by others
IdfObject$has_ref_by(
which = NULL,
object = NULL,
class = NULL,
group = NULL,
recursive = FALSE,
class_ref = c("both", "none", "all")
)whichAn integer vector of field indexes or a character vector of field names.
objectA character vector of object names or an integer vector
of object IDs used for searching relations. Default: NULL.
classA character vector of class names used for searching
relations. Default: NULL.
groupA character vector of group names used for searching
relations. Default: NULL.
recursiveIf TRUE, the relation is searched recursively. A
simple example of recursive reference: one material named
mat is referred by a construction named const, and const
is also referred by a surface named surf. Default: FALSE.
class_refSpecify how to handle class-name-references. Class
name references refer to references in like field Component 1 Object Type in Branch objects. Their value refers to other
many class names of objects, instaed of referring to specific
field values. There are 3 options in total, i.e. "none",
"both" and "all", with "both" being the default.
* "none": just ignore class-name-references. It is a reasonable
option, as for most cases, class-name-references always come
along with field value references. Ignoring
class-name-references will not impact the most part of the
relation structure.
* "both": only include class-name-references if this object
also reference field values of the same one. For example, if the
value of field Component 1 Object Type is
Coil:Heating:Water, only the object that is referenced in the
next field Component 1 Name is treated as referenced by
Component 1 Object Type. This is the default option.
* "all": include all class-name-references. For example, if the
value of field Component 1 Object Type is
Coil:Heating:Water, all objects in Coil:Heating:Water will
be treated as referenced by that field. This is the most
aggressive option.
For details on field value relations, see
$value_relation().
$has_ref_by() takes an integer vector of field indexes or a
character vector of field names, and returns a logical vector showing
whether there are other object values ref to specified fields.
has_ref_node()Check if object field values refer to other nodes
IdfObject$has_ref_node(
which = NULL,
object = NULL,
class = NULL,
group = NULL,
recursive = FALSE
)whichAn integer vector of field indexes or a character vector of field names.
objectA character vector of object names or an integer vector
of object IDs used for searching relations. Default: NULL.
classA character vector of class names used for searching
relations. Default: NULL.
groupA character vector of group names used for searching
relations. Default: NULL.
recursiveIf TRUE, the relation is searched recursively. A
simple example of recursive reference: one material named
mat is referred by a construction named const, and const
is also referred by a surface named surf. Default: FALSE.
For details on field value relations, see
$value_relation().
$has_ref_node() takes an integer vector of field indexes or a
character vector of field names, and returns a logical vector showing
whether specified fields refer to other objects' nodes.
has_ref()Check if object field values refer to or are referred by others
IdfObject$has_ref(
which = NULL,
object = NULL,
class = NULL,
group = NULL,
recursive = FALSE
)whichAn integer vector of field indexes or a character vector of field names.
objectA character vector of object names or an integer vector
of object IDs used for searching relations. Default: NULL.
classA character vector of class names used for searching
relations. Default: NULL.
groupA character vector of group names used for searching
relations. Default: NULL.
recursiveIf TRUE, the relation is searched recursively. A
simple example of recursive reference: one material named
mat is referred by a construction named const, and const
is also referred by a surface named surf. Default: FALSE.
For details on field value relations, see
$value_relation().
$has_ref() takes an integer vector of field indexes or a character
vector of field names, and returns a logical vector showing whether
there are other object values ref to specified field values or
specified field values refer to other object values or specified
field values refer to other objects' nodes.
to_table()Format IdfObject as a data.frame
IdfObject$to_table(
string_value = TRUE,
unit = TRUE,
wide = FALSE,
all = FALSE,
group_ext = c("none", "group", "index")
)string_valueIf TRUE, all field values are returned as
character. If FALSE, value column in returned
data.table is a list column with
each value stored as corresponding type. Note that if the
value of numeric field is set to "Autosize" or
"Autocalculate", it is left as it is, leaving the returned
type being a string instead of a number. Default: TRUE.
unitOnly applicable when string_value is FALSE. If
TRUE, values of numeric fields are assigned with units using
units::set_units() if applicable. Default: FALSE.
wideOnly applicable if target objects belong to a same class.
If TRUE, a wide table will be returned, i.e. first three
columns are always id, name and class, and then every
field in a separate column. Note that this requires all
objects specified must from the same class.
Default: FALSE.
allIf TRUE, all available fields defined in IDD for the
class that objects belong to will be returned. Default:
FALSE.
group_extShould be one of "none", "group" or "index".
If not "none", value column in returned
data.table::data.table() will be converted into a list.
If "group", values from extensible fields will be grouped by the
extensible group they belong to. For example, coordinate
values of each vertex in class BuildingSurface:Detailed will
be put into a list. If "index", values from extensible fields
will be grouped by the extensible field indice they belong to.
For example, coordinate values of all x coordinates will be
put into a list. If "none", nothing special will be done.
Default: "none".
$to_table() returns a data.table that
contains core data of current IdfObject. It has 6 columns:
id: Integer type. Object IDs.
name: Character type. Object names.
class: Character type. Current class name.
index: Integer type. Field indexes.
field: Character type. Field names.
value: Character type if string_value is TRUE or list type if
string_value is FALSE or group_ext is not "none". Field values.
Note that when group_ext is not "none", index and field
values will not match the original field indices and names. In this
case, index will only indicate the indices of sequences. For
field column, specifically:
When group_ext is "group", each field name in a extensible group
will be abbreviated using abbreviate() with minlength being
10L and all abbreviated names will be separated by | and
combined together. For example, field names in the extensible group
(Vertex 1 X-coordinate, Vertex 1 Y-coordinate, Vertex 1 Z-coordinate) in class BuildiBuildingSurface:Detailed will be
merged into one name Vrtx1X-crd|Vrtx1Y-crd|Vrtx1Z-crd.
When group_ext is "index", the extensible group indicator in field
names will be removed. Take the same example as above, the
resulting field names will be Vertex X-coordinate, Vertex Y-coordinate, and Vertex Z-coordinate.
A data.table with 6 columns (if
wide is FALSE) or at least 6 columns (if wide is TRUE).
\dontrun{
# get all object data in a data.table format without field units
str(mat$to_table(unit = FALSE))
# get all object data in a data.table format where all field values are put in a
# list column and field names without unit
str(mat$to_table(string_value = FALSE, unit = FALSE))
# get all object data in a data.table format, including tailing empty fields
str(idf$Zone$`ZONE ONE`$to_table(all = TRUE))
# get all object data in a data.table format where each field becomes a column
str(mat$to_table(wide = TRUE))
# group extensible by extensible group number
surf <- idf$BuildingSurface_Detailed[["Zn001:Roof001"]]
surf$to_table(group_ext = "group")
# group extensible by extensible group number and convert into a wide table
surf$to_table(group_ext = "group", wide = TRUE)
# group extensible by extensible field index
surf$to_table(group_ext = "index")
# group extensible by extensible field index and convert into a wide table
surf$to_table(group_ext = "index", wide = TRUE)
# when grouping extensible, 'string_value' and 'unit' still take effect
surf$to_table(group_ext = "index", wide = TRUE, string_value = FALSE, unit = TRUE)
}
to_string()Format current object as a character vector
commentIf FALSE, all comments will not be included.
Default: TRUE.
leadingLeading spaces added to each field. Default: 4L.
sep_atThe character width to separate value string and field
string. Default: 29L which is the same as IDF Editor.
allIf TRUE, all available fields defined in IDD for the
class that objects belong to will be returned. Default:
FALSE.
print()Print IdfObject object
commentIf FALSE, all comments are not included.
auto_sepIf TRUE, values and field names are separated at
the largest character length of values. Default: FALSE.
briefIf TRUE, only OBJECT part is printed. Default:
FALSE.
allIf TRUE, all fields defined in Idd are printed even
they do not exist in current object. Default: FALSE.
$print() prints the IdfObject. Basically, the print output can be
divided into 3 parts:
OBJECT: Class name, object id and name (if applicable).
COMMENTS: Object comments if exist.
VALUES: fields and values of current IdfObject. Required fields are marked
with start *. String values are quoted. Numeric values are printed as
they are. Blank string values are printed as <"Blank"> and blank number
values are printed as <Blank>.
## ------------------------------------------------
## Method `IdfObject$new`
## ------------------------------------------------
if (FALSE) { # \dontrun{
# example model shipped with eplusr from EnergyPlus v8.8
path_idf <- system.file("extdata/1ZoneUncontrolled.idf", package = "eplusr") # v8.8
idf <- read_idf(path_idf, use_idd(8.8, "auto"))
roof <- IdfObject$new(26, parent = idf)
# get the IdfObject of material named "C5 - 4 IN HW CONCRETE"
mat <- idf$Material[["C5 - 4 IN HW CONCRETE"]]
} # }
## ------------------------------------------------
## Method `IdfObject$version`
## ------------------------------------------------
if (FALSE) { # \dontrun{
# get version
roof$version()
} # }
## ------------------------------------------------
## Method `IdfObject$parent`
## ------------------------------------------------
if (FALSE) { # \dontrun{
roof$parent()
} # }
## ------------------------------------------------
## Method `IdfObject$id`
## ------------------------------------------------
if (FALSE) { # \dontrun{
roof$id()
} # }
## ------------------------------------------------
## Method `IdfObject$name`
## ------------------------------------------------
if (FALSE) { # \dontrun{
roof$name()
# NA will be returned if the class does not have name attribute. For example,
# "Version" class
idf$Version$name()
} # }
## ------------------------------------------------
## Method `IdfObject$group_name`
## ------------------------------------------------
if (FALSE) { # \dontrun{
roof$group_name()
} # }
## ------------------------------------------------
## Method `IdfObject$class_name`
## ------------------------------------------------
if (FALSE) { # \dontrun{
roof$class_name()
} # }
## ------------------------------------------------
## Method `IdfObject$definition`
## ------------------------------------------------
if (FALSE) { # \dontrun{
roof$definition()
} # }
## ------------------------------------------------
## Method `IdfObject$comment`
## ------------------------------------------------
if (FALSE) { # \dontrun{
# get object comments
roof$comment()
# add new object comments
roof$comment(c("This is a material named `WD01`", "This object has an ID of 47"))
roof$comment()
# append new comments
roof$comment("This is an appended comment")
roof$comment()
# prepend new comments
roof$comment("This is a prepended comment", append = FALSE)
roof$comment()
# wrap long comments
roof$comment("This is a very long comment that is needed to be wrapped.", width = 30)
roof$comment()
# delete old comments and add new one
roof$comment("This is the only comment", append = NULL)
roof$comment()
# delete all comments
roof$comment(NULL)
roof$comment()
} # }
## ------------------------------------------------
## Method `IdfObject$value`
## ------------------------------------------------
if (FALSE) { # \dontrun{
# get all existing field values
str(mat$value())
# get values of field 1, 3, 5
str(mat$value(c(1, 3, 5)))
# get character format values instead of a named list
mat$value(c(1, 3, 5), simplify = TRUE)
# get values of all field even those that are not set
str(roof$value())
str(roof$value(all = TRUE))
# get field values using shortcuts
mat$Roughness
mat[["Specific_Heat"]]
mat[c(1,2)]
mat[c("Name", "Density")]
} # }
## ------------------------------------------------
## Method `IdfObject$set`
## ------------------------------------------------
if (FALSE) { # \dontrun{
# set field values
mat$set(name = "new_name", Thickness = 0.02)
mat[c("Name", "Thickness")]
# When `default` argument is set to TRUE and input field values are empty, i.e.
# NULL, the field values will be reset to defaults.
mat[c("Thermal Absorptance", "Solar Absorptance")]
mat$set(visible_absorptance = NULL, Solar_Absorptance = NULL, .default = TRUE)
mat[c("Visible Absorptance", "Solar Absorptance")]
# set field values using shortcuts
mat$Name <- "another_name"
mat$Name
mat[["Thickness"]] <- 0.019
mat$Thickness
} # }
## ------------------------------------------------
## Method `IdfObject$value_possible`
## ------------------------------------------------
if (FALSE) { # \dontrun{
mat$value_possible()
} # }
## ------------------------------------------------
## Method `IdfObject$validate`
## ------------------------------------------------
if (FALSE) { # \dontrun{
mat$validate()
# check at predefined validate level
mat$validate("none")
mat$validate("draft")
mat$validate("final")
# custom validate checking components
mat$validate(custom_validate(auto_field = TRUE, choice = TRUE))
} # }
## ------------------------------------------------
## Method `IdfObject$is_valid`
## ------------------------------------------------
if (FALSE) { # \dontrun{
mat$is_valid()
mat$definition()$field_range("Density")
eplusr_option(validate_level = "none") # have to set validate to "none" to do so
mat$Density <- -1
eplusr_option(validate_level = "final") # change back to "final" validate level
mat$is_valid()
# check at predefined validate level
mat$is_valid("none")
mat$is_valid("draft")
mat$is_valid("final")
# custom validate checking components
mat$is_valid(custom_validate(auto_field = TRUE, choice = TRUE))
} # }
## ------------------------------------------------
## Method `IdfObject$value_relation`
## ------------------------------------------------
if (FALSE) { # \dontrun{
# check each layer's reference of a construction named FLOOR
roof$value_relation("zone name", "ref_to")
# check where is this construction being used
roof$value_relation("name", direction = "ref_by")
} # }
## ------------------------------------------------
## Method `IdfObject$ref_to_object`
## ------------------------------------------------
if (FALSE) { # \dontrun{
# get other objects that this object refereces
mat$ref_to_object() # not referencing other objects
} # }
## ------------------------------------------------
## Method `IdfObject$ref_by_object`
## ------------------------------------------------
if (FALSE) { # \dontrun{
# get other objects that reference this object
mat$ref_by_object() # referenced by construction "FLOOR"
} # }
## ------------------------------------------------
## Method `IdfObject$ref_to_node`
## ------------------------------------------------
if (FALSE) { # \dontrun{
if (is_avail_eplus(8.8)) {
path <- file.path(eplus_config(8.8)$dir, "ExampleFiles/5Zone_Transformer.idf")
idf_5z <- read_idf(path)
idf_5z$NodeList$OutsideAirInletNodes$ref_to_node()
}
} # }
## ------------------------------------------------
## Method `IdfObject$has_ref_to`
## ------------------------------------------------
if (FALSE) { # \dontrun{
mat$has_ref_to()
} # }
## ------------------------------------------------
## Method `IdfObject$has_ref_by`
## ------------------------------------------------
if (FALSE) { # \dontrun{
mat$has_ref_by()
} # }
## ------------------------------------------------
## Method `IdfObject$has_ref_node`
## ------------------------------------------------
if (FALSE) { # \dontrun{
mat$has_ref_node()
} # }
## ------------------------------------------------
## Method `IdfObject$has_ref`
## ------------------------------------------------
if (FALSE) { # \dontrun{
# check if having any referenced objects or is referenced by other objects
mat$has_ref()
} # }
## ------------------------------------------------
## Method `IdfObject$to_table`
## ------------------------------------------------
if (FALSE) { # \dontrun{
# get all object data in a data.table format without field units
str(mat$to_table(unit = FALSE))
# get all object data in a data.table format where all field values are put in a
# list column and field names without unit
str(mat$to_table(string_value = FALSE, unit = FALSE))
# get all object data in a data.table format, including tailing empty fields
str(idf$Zone$`ZONE ONE`$to_table(all = TRUE))
# get all object data in a data.table format where each field becomes a column
str(mat$to_table(wide = TRUE))
# group extensible by extensible group number
surf <- idf$BuildingSurface_Detailed[["Zn001:Roof001"]]
surf$to_table(group_ext = "group")
# group extensible by extensible group number and convert into a wide table
surf$to_table(group_ext = "group", wide = TRUE)
# group extensible by extensible field index
surf$to_table(group_ext = "index")
# group extensible by extensible field index and convert into a wide table
surf$to_table(group_ext = "index", wide = TRUE)
# when grouping extensible, 'string_value' and 'unit' still take effect
surf$to_table(group_ext = "index", wide = TRUE, string_value = FALSE, unit = TRUE)
} # }
## ------------------------------------------------
## Method `IdfObject$to_string`
## ------------------------------------------------
if (FALSE) { # \dontrun{
# get string format object
mat$to_string()
# get string format of object, and decrease the space between field values and
# field names
mat$to_string(sep_at = 15)
# get string format of object, and decrease the leading space of field values
mat$to_string(leading = 0)
} # }
## ------------------------------------------------
## Method `IdfObject$print`
## ------------------------------------------------
if (FALSE) { # \dontrun{
# print the object without comment
mat$print(comment = FALSE)
# print the object, and auto separate field values and field names at the
# largetst character length of field values
mat$print(auto_sep = TRUE)
} # }