IddObject is an abstraction of a single object in an Idd object. It
provides more detail methods to query field properties. IddObject can only
be created from the parent Idd object, using $object(),
$object_in_group() and other equivalent. This is because that
initialization of an IddObject needs some shared data from parent Idd
object.
There are lots of properties for every class and field. For details on the
meaning of each property, please see the heading comments in the
Energy+.idd file in the EnergyPlus installation path.
Some classes have special format when saved in the IDFEditor with the special format option enabled. Those special format includes "singleLine", "vertices", "compactSchedule", "fluidProperties", "viewFactors" and "spectral". eplusr can handle all those format when parsing IDF files. However, when saved, all classes are formatted in standard way.
This number may change if the class is extensible and after
$add_extensible_group() or $del_extensible_group().
The type of each default value will be consistent with field
definition. However, for numeric fields with default values being
"autosize" or "autocalculate", the type of returned values will
be character.
All outputs are extracted from the LaTeX source file of "Input Output Reference" for EnergyPlus v9.5.0 and later. So empty result will always be returned for Idd version lower than v9.5.
It is possible that there are some mistakes introduced when extracting the output variables. Also, some outputs are only available if certain fields are set. Even they are listed in the results, it does not mean that the Idf can report all of them. It is strongly suggested to check the RDD and MDD file for correctness.
Idd Class
new()Create an IddObject object
IddObject$new(class, parent)Note that an IddObject can be created from the parent Idd object,
using $object(), idd_object and other equivalent.
version()Get the version of parent Idd
$version() returns the version of parent Idd in a
base::numeric_version() format. This makes it easy to direction
compare versions of different IddObjects, e.g. iddobj$version() > 8.6 or
iddobj1$version() > iddobj2$version().
A base::numeric_version() object.
group_index()Get the group index
$group_index() returns the group index of current IddObject. A
group index is just an integer indicating its appearance order in the
Idd.
class_index()Get the class index
$class_index() returns the class index of current IddObject. A
class index is just an integer indicating its appearance order in the
Idd.
class_format()Get the class format
min_fields()Get the minimum field number of current class
num_extensible()Get the field number of the extensible group in current class
$num_extensible() returns the field number of the extensible group
in current class.
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.
If there is no extensible group in current class, 0 is returned.
first_extensible_index()Get the minimum field number of current class
$first_extensible_index() returns the field index of first
extensible field in current class.
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.
If there is no extensible group in current class, 0 is returned.
extensible_group_num()Get the number of extensible groups in current class
$extensible_group_num() returns the number of extensible groups in
current class.
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.
If there is no extensible group in current class, 0 is returned.
add_extensible_group()Add extensible groups in current class
$add_extensible_groups() adds extensible groups in this class.
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.
An error will be issued if current class contains no extensible group.
\dontrun{
# field number before adding
surf$num_fields()
# extensible group number before adding
surf$extensible_group_num()
# add 2 more extensible groups
surf$add_extensible_group(2)
# field number after adding
surf$num_fields()
# extensible group number after adding
surf$extensible_group_num()
}
del_extensible_group()Delete extensible groups in current class
$del_extensible_groups() deletes extensible groups in this class.
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.
An error will be issued if current class contains no extensible group.
\dontrun{
# field number before deleting
surf$num_fields()
# extensible group number before deleting
surf$extensible_group_num()
# delete 2 more extensible groups
surf$del_extensible_group(2)
# field number after deleting
surf$num_fields()
# extensible group number after deleting
surf$extensible_group_num()
}
has_name()Check if current class has name attribute
is_required()Check if current class is required
is_unique()Check if current class is unique
is_extensible()Check if current class is extensible
field_name()Get field names
IddObject$field_name(
index = NULL,
unit = FALSE,
in_ip = eplusr_option("view_in_ip")
)indexAn integer vector of field indices. If NULL, names of
all fields in this class are returned. Default: NULL.
unitIf TRUE, the units of those fields are also returned.
Default: FALSE.
in_ipIf in_ip, corresponding imperial units are returned.
It only has effect when unit is TRUE. Default:
eplusr_option("view_in_ip").
field_index()Get field indices
nameA character vector of field names. Can be in
"lower-style", i.e. all spaces and dashes is replaced by
underscores. If NULL, indices of all fields in this class
are returned. Default: NULL.
field_type()Get field types
whichAn integer vector of field indices or a character vector
of field names in current class. If NULL, all fields in this
class are used. Default: NULL.
$field_type() returns a character vector of field types of
specified fields in current class. All possible values are:
"integer"
"real"
"alpha" (arbitrary string)
"choice" (alpha with specific list of choices)
"object-list" (link to a list of objects defined elsewhere)
"external-list" (uses a special list from an external source)
"node" (name used in connecting HVAC components).
field_note()Get field notes
whichAn integer vector of field indices or a character vector
of field names in current class. If NULL, all fields in this
class are used. Default: NULL.
field_unit()Get field units
IddObject$field_unit(which = NULL, in_ip = eplusr_option("view_in_ip"))whichAn integer vector of field indices or a character vector
of field names in current class. If NULL, all fields in this
class are used. Default: NULL.
in_ipIf in_ip, corresponding imperial units are returned.
Default: eplusr_option("view_in_ip").
field_default()Get field default value
IddObject$field_default(which = NULL, in_ip = eplusr_option("view_in_ip"))whichAn integer vector of field indices or a character vector
of field names in current class. If NULL, all fields in this
class are used. Default: NULL.
in_ipIf in_ip, values in corresponding imperial units are
returned. Default: eplusr_option("view_in_ip").
field_choice()Get choices of field values
whichAn integer vector of field indices or a character vector
of field names in current class. If NULL, all fields in this
class are used. Default: NULL.
field_range()Get field value ranges
whichAn integer vector of field indices or a character vector
of field names in current class. If NULL, all fields in this
class are used. Default: NULL.
$field_range() returns a list of value ranges of specified fields
in current class.
Every range has four components:
minimum: lower limit
lower_incbounds: TRUE if the lower limit should be included
maximum: upper limit
upper_incbounds: TRUE if the upper limit should be included
For fields of character type,
minimum and maximum are always set to NA
lower_incbounds and upper_incbounds are always set to FALSE
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
upper_incbounds is set to FALSE
The field range is printed in number interval denotation.
field_relation()Extract the relationship among fields
IddObject$field_relation(
which = NULL,
direction = c("all", "ref_by", "ref_to"),
class = NULL,
group = NULL,
depth = 0L,
keep = FALSE
)whichAn integer vector of field indices or a character vector
of field names in current class. If NULL, all fields in this
class are used. Default: NULL.
directionThe relation direction to extract. Should be one of
"all", "ref_to" or "ref_by".
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.
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.
$field_relation() provides a simple interface to get this kind of
relation. It takes a field specification and a relation
direction, and returns an IddRelation object which contains data
presenting such relation above.
$field_relation() returns a list of references for those fields
that have the object-list and/or reference and
reference-class-name attribute. Basically, it is a list of two
elements ref_to and ref_by. Underneath, ref_to and ref_by
are data.tables which contain source
field data and reference field data with custom printing method. For
instance, if iddobj$field_relation(c(1, 2), "ref_to") gives results
below:
-- Refer to Others ---------------------
+- Field: <1: Field 1>
| v~~~~~~~~~~~~~~~~~~
| \- Class: <Class 2>
| \- Field: <2: Field 2>
|
\- Field: <2: Field 2>This means that Field 2 in current class does not refer to any other fields.
But Field 1 in current class refers to Field 2 in class named Class 2.
field_possible()Get field possible values
whichAn integer vector of field indices or a character vector
of field names in current class. If NULL, all fields in this
class are used. Default: NULL.
$field_possible() returns all possible values for specified fields,
including auto-value (Autosize, Autocalculate, and NA if not
applicable), and results from $field_default(), $field_range(),
$field_choice(). Underneath, it returns a data.table with custom
printing method. For instance, if iddobj$field_possible(c(4, 2))
gives results below:
-- 4: Field 4 ----------
* Auto value: <NA>
* Default: <NA>
* Choice:
- "Key1"
- "Key2"
-- 2: Field 2 ----------
* Auto value: "Autosize"
* Default: 2
* Choice: <NA>This means that Field 4 in current class cannot be "autosized" or
"autocalculated", and it does not have any default value. Its value should be
a choice from "Key1" or "Key2". For Field 2 in current class, it has a
default value of 2 but can also be filled with value "Autosize".
A IddFieldPossible object which is a
data.table::data.table() with 9 columns.
is_valid_field_num()Check if input is a valid field number
$is_valid_field_num() returns TRUE if input num is acceptable
as a total number of fields in this class. Extensible property is
considered.
For instance, the total number of fields defined in IDD for class
BuildingSurfaces:Detailed is 390. However, 396 is still a valid
field number for this class as the number of field in the extensible
group is 3.
is_extensible_index()Check if input field index indicates an extensible field
is_valid_field_name()Check if input character is a valid field name
nameA character vector to test.
strictIf TRUE, only exact match is accepted. Default:
FALSE.
is_valid_field_index()Check if input integer is a valid field index
is_autosizable_field()Check if input field can be autosized
is_autocalculatable_field()Check if input field can be autocalculated
is_numeric_field()Check if input field value should be numeric
whichAn integer vector of field indices or a character vector
of field names in current class. If NULL, all fields in this
class are used. Default: NULL.
is_real_field()Check if input field value should be a real number
whichAn integer vector of field indices or a character vector
of field names in current class. If NULL, all fields in this
class are used. Default: NULL.
is_integer_field()Check if input field value should be an integer
is_required_field()Check if input field is required
has_ref()Check if input field can refer to or can be referred by other fields
whichAn integer vector of field indices or a character vector
of field names in current class. If NULL, all fields in this
class are used. 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.
has_ref_to()Check if input field can refer to other fields
whichAn integer vector of field indices or a character vector
of field names in current class. If NULL, all fields in this
class are used. 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.
has_ref_by()Check if input field can be referred by other fields
whichAn integer vector of field indices or a character vector
of field names in current class. If NULL, all fields in this
class are used. 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.
outputs()Get possible output variables for current class
$outputs() returns a data.table that
gives all possible outputs for current class.
The returned data.table has 6 columns:
*index: Integer. Index of each variable.
*class: Character. Name of current class.
reported_time_step: Character. Reported time step for the variables.
Possible value: Zone and HVAC.
report_type: Character. Report types. Possible value: Average,
Sum.
variable: Character. Report variable names.
units: Character. Units of reported values. NA if report values do not
have units.
A data.table with 6 columns.
to_table()Format an IddObject as a data.frame
allIf TRUE, all available fields defined in IDD for
specified class will be returned. If FALSE, only the minimum
field number is returned. Default: FALSE.
$to_table() returns a data.table that
contains basic data of current class.
The returned data.table has 3 columns:
class: Character type. Current class name.
index: Integer type. Field indexes.
field: Character type. Field names.
A data.table with 3 columns.
to_string()Format an IdfObject as a character vector
commentA character vector to be used as comments of returned string format object.
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
specified class will be returned. Default: FALSE.
print()Print IddObject object
$print() prints the IddObject object giving the information of
class name, class properties, field indices and field names.
$print() prints the IddObject. Basically, the print output can be
divided into 4 parts:
CLASS: IDD class name of current object in format <IddObject: CLASS>.
MEMO: brief description of the IDD class.
PROPERTY: properties of the IDD class, including name of group it
belongs to, whether it is an unique or required class and current
total fields. The fields may increase if the IDD class is
extensible, such as Branch, ZoneList and etc.
FIELDS: fields of current IDD class. Required fields are marked
with stars (*). If the class is extensible, only the first
extensible group will be printed and two ellipses will be shown at
the bottom. Fields in the extensible group will be marked with an
arrow down surrounded by angle brackets (<v>).
## ------------------------------------------------
## Method `IddObject$new`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf <- IddObject$new("BuildingSurface:Detailed", use_idd(8.8, download = "auto"))
} # }
## ------------------------------------------------
## Method `IddObject$version`
## ------------------------------------------------
if (FALSE) { # \dontrun{
# get version
surf$version()
} # }
## ------------------------------------------------
## Method `IddObject$parent`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf$parent()
} # }
## ------------------------------------------------
## Method `IddObject$group_name`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf$group_name()
} # }
## ------------------------------------------------
## Method `IddObject$group_index`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf$group_index()
} # }
## ------------------------------------------------
## Method `IddObject$class_name`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf$class_name()
} # }
## ------------------------------------------------
## Method `IddObject$class_index`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf$class_index()
} # }
## ------------------------------------------------
## Method `IddObject$class_format`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf$class_format()
} # }
## ------------------------------------------------
## Method `IddObject$min_fields`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf$min_fields()
} # }
## ------------------------------------------------
## Method `IddObject$num_fields`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf$num_fields()
} # }
## ------------------------------------------------
## Method `IddObject$memo`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf$memo()
} # }
## ------------------------------------------------
## Method `IddObject$num_extensible`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf$num_extensible()
} # }
## ------------------------------------------------
## Method `IddObject$first_extensible_index`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf$first_extensible_index()
} # }
## ------------------------------------------------
## Method `IddObject$extensible_group_num`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf$extensible_group_num()
} # }
## ------------------------------------------------
## Method `IddObject$add_extensible_group`
## ------------------------------------------------
if (FALSE) { # \dontrun{
# field number before adding
surf$num_fields()
# extensible group number before adding
surf$extensible_group_num()
# add 2 more extensible groups
surf$add_extensible_group(2)
# field number after adding
surf$num_fields()
# extensible group number after adding
surf$extensible_group_num()
} # }
## ------------------------------------------------
## Method `IddObject$del_extensible_group`
## ------------------------------------------------
if (FALSE) { # \dontrun{
# field number before deleting
surf$num_fields()
# extensible group number before deleting
surf$extensible_group_num()
# delete 2 more extensible groups
surf$del_extensible_group(2)
# field number after deleting
surf$num_fields()
# extensible group number after deleting
surf$extensible_group_num()
} # }
## ------------------------------------------------
## Method `IddObject$has_name`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf$has_name()
} # }
## ------------------------------------------------
## Method `IddObject$is_required`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf$is_required()
} # }
## ------------------------------------------------
## Method `IddObject$is_unique`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf$is_unique()
} # }
## ------------------------------------------------
## Method `IddObject$is_extensible`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf$is_extensible()
} # }
## ------------------------------------------------
## Method `IddObject$field_name`
## ------------------------------------------------
if (FALSE) { # \dontrun{
# get all field names
surf$field_name()
# get field units also
surf$field_name(unit = TRUE)
# get field units in IP
surf$field_name(unit = TRUE)
# change field name to lower-style
surf$field_name(unit = TRUE, in_ip = TRUE)
} # }
## ------------------------------------------------
## Method `IddObject$field_index`
## ------------------------------------------------
if (FALSE) { # \dontrun{
# get all field indices
surf$field_index()
# get field indices for specific fields
surf$field_index(c("number of vertices", "vertex 10 z-coordinate"))
} # }
## ------------------------------------------------
## Method `IddObject$field_type`
## ------------------------------------------------
if (FALSE) { # \dontrun{
# get all field types
surf$field_type()
# get field types for specific fields
surf$field_type(c("name", "zone name", "vertex 10 z-coordinate"))
} # }
## ------------------------------------------------
## Method `IddObject$field_note`
## ------------------------------------------------
if (FALSE) { # \dontrun{
# get all field notes
surf$field_note()
# get field types for specific fields
surf$field_note(c("name", "zone name", "vertex 10 z-coordinate"))
} # }
## ------------------------------------------------
## Method `IddObject$field_unit`
## ------------------------------------------------
if (FALSE) { # \dontrun{
# get all field units
surf$field_unit()
# get field units for specific fields
surf$field_unit(c("name", "zone name", "vertex 10 z-coordinate"))
} # }
## ------------------------------------------------
## Method `IddObject$field_default`
## ------------------------------------------------
if (FALSE) { # \dontrun{
# get all field default values
surf$field_default()
# get default values for specific fields
surf$field_default(c("name", "zone name", "vertex 10 z-coordinate"))
} # }
## ------------------------------------------------
## Method `IddObject$field_choice`
## ------------------------------------------------
if (FALSE) { # \dontrun{
# get all field value choices
surf$field_choice()
# get field value choices for specific fields
surf$field_choice(c("name", "sun exposure", "wind exposure"))
} # }
## ------------------------------------------------
## Method `IddObject$field_range`
## ------------------------------------------------
if (FALSE) { # \dontrun{
# get all field value ranges
surf$field_range()
# get value ranges for specific fields
surf$field_range(c("name", "number of vertices", "vertex 10 z-coordinate"))
} # }
## ------------------------------------------------
## Method `IddObject$field_relation`
## ------------------------------------------------
if (FALSE) { # \dontrun{
# get field relation for specific fields
surf$field_relation(c("name", "zone name", "vertex 10 z-coordinate"))
} # }
## ------------------------------------------------
## Method `IddObject$field_possible`
## ------------------------------------------------
if (FALSE) { # \dontrun{
# get field possible values for specific fields
surf$field_possible(6:10)
} # }
## ------------------------------------------------
## Method `IddObject$is_valid_field_num`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf$is_valid_field_num(c(10, 14, 100))
} # }
## ------------------------------------------------
## Method `IddObject$is_extensible_index`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf$is_extensible_index(c(10, 14, 100))
} # }
## ------------------------------------------------
## Method `IddObject$is_valid_field_name`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf$is_valid_field_name(c("name", "sun_exposure"))
# exact match
surf$is_valid_field_name(c("Name", "Sun_Exposure"), strict = TRUE)
} # }
## ------------------------------------------------
## Method `IddObject$is_valid_field_index`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf$is_valid_field_index(1:10)
} # }
## ------------------------------------------------
## Method `IddObject$is_autosizable_field`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf$is_autosizable_field()
surf$is_autosizable_field(c("name", "sun_exposure"))
} # }
## ------------------------------------------------
## Method `IddObject$is_autocalculatable_field`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf$is_autocalculatable_field()
surf$is_autocalculatable_field(c("name", "sun_exposure"))
} # }
## ------------------------------------------------
## Method `IddObject$is_numeric_field`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf$is_numeric_field()
surf$is_numeric_field(c("name", "sun_exposure"))
} # }
## ------------------------------------------------
## Method `IddObject$is_real_field`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf$is_real_field()
surf$is_real_field(c("name", "number of vertices"))
} # }
## ------------------------------------------------
## Method `IddObject$is_integer_field`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf$is_integer_field()
surf$is_integer_field(c("name", "number of vertices"))
} # }
## ------------------------------------------------
## Method `IddObject$is_required_field`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf$is_required_field()
surf$is_required_field(c("name", "number of vertices"))
} # }
## ------------------------------------------------
## Method `IddObject$has_ref`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf$has_ref()
surf$has_ref(c("name", "zone name"))
} # }
## ------------------------------------------------
## Method `IddObject$has_ref_to`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf$has_ref_to()
surf$has_ref_to(c("name", "zone name"))
} # }
## ------------------------------------------------
## Method `IddObject$has_ref_by`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf$has_ref_by()
surf$has_ref_by(c("name", "zone name"))
} # }
## ------------------------------------------------
## Method `IddObject$outputs`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf$outputs()
} # }
## ------------------------------------------------
## Method `IddObject$to_table`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf$to_table()
surf$to_table(TRUE)
} # }
## ------------------------------------------------
## Method `IddObject$to_string`
## ------------------------------------------------
if (FALSE) { # \dontrun{
# get text format of class BuildingSurface:Detailed
surf$to_string()
# tweak output formatting
surf$to_string(leading = 0, sep_at = 0)
# add comments
surf$to_string(c("This", "will", "be", "comments"))
} # }
## ------------------------------------------------
## Method `IddObject$print`
## ------------------------------------------------
if (FALSE) { # \dontrun{
surf
surf$print(brief = TRUE)
} # }