IdfObject {eplusr}R Documentation

Create and Modify an EnergyPlus Object

Description

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.

Methods

Public methods


Method new()

Create an IdfObject object

Usage
IdfObject$new(object, class = NULL, parent)
Arguments
object

An integer specifying an object ID.

class

An integer specifying a class index.

parent

An Idf object specifying the parent object.

Details

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.

Returns

An IdfObject object.

Examples
\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 version()

Get the version of parent Idf

Usage
IdfObject$version()
Details

⁠$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().

Returns

A base::numeric_version() object.

Examples
\dontrun{
# get version
roof$version()
}


Method parent()

Get parent Idf

Usage
IdfObject$parent()
Details

⁠$parent()⁠ returns parent Idf object.

Returns

A Idf object.

Examples
\dontrun{
roof$parent()
}


Method id()

Get the unique ID for current object

Usage
IdfObject$id()
Details

In Idf, each object is assigned with an integer as an universally unique identifier (UUID) in the context of current Idf. UUID is not reused even if the object associated is deleted.

⁠$id()⁠ returns an integer of current object unique ID.

Returns

A single integer.

Examples
\dontrun{
roof$id()
}


Method name()

Get the name for current object.

Usage
IdfObject$name()
Details

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.

Returns

A single string.

Examples
\dontrun{
roof$name()

# NA will be returned if the class does not have name attribute. For example,
# "Version" class
idf$Version$name()
}


Method group_name()

Get name of group for current object.

Usage
IdfObject$group_name()
Details

⁠$group_name()⁠ returns a single string of group name current IdfObject belongs to.

Returns

A single string.

Examples
\dontrun{
roof$group_name()
}


Method class_name()

Get name of class for current object.

Usage
IdfObject$class_name()
Details

⁠$class_name()⁠ returns a single string of class name current IdfObject belongs to.

Returns

A single string.

Examples
\dontrun{
roof$class_name()
}


Method definition()

Get the IddObject object for current class.

Usage
IdfObject$definition()
Details

⁠$definition()⁠ returns an IddObject of current class. IddObject contains all data used for parsing and creating current IdfObject. For details, please see IddObject class.

Returns

An IddObject object.

Examples
\dontrun{
roof$definition()
}


Method comment()

Get and modify object comments

Usage
IdfObject$comment(comment, append = TRUE, width = 0L)
Arguments
comment

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

append

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

width

A positive integer giving the target width for wrapping inserted comment.

Details

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

Returns

If calling without any argument, a character vector or NULL (if no comments) is return. Otherwise, the modified object itself.

Examples
\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 value()

Get object field values.

Usage
IdfObject$value(which = NULL, all = FALSE, simplify = FALSE, unit = FALSE)
Arguments
which

An integer vector of field indexes or a character vector of field names.

all

If TRUE, values of all possible fields in current class the IdfObject belongs to are returned. Default: FALSE

simplify

If TRUE, values of fields are converted into characters and the converted character vector is returned.

unit

If TRUE, values of numeric fields are assigned with units using units::set_units() if applicable. Default: FALSE.

Details

⁠$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]].

Returns

A named list.

Examples
\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 set()

Modify object field values.

Usage
IdfObject$set(..., .default = TRUE, .empty = FALSE)
Arguments
...

New field value definitions in field = value format or a single list in format:

list(field1 = value1, field2 = value2)
.default

If TRUE, default values are used for those blank fields if possible. Default: TRUE.

.empty

If TRUE, trailing empty fields are kept. Default: FALSE.

Details

⁠$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()⁠.

Examples
\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 value_possible()

Get possible object field values.

Usage
IdfObject$value_possible(
  which = NULL,
  type = c("auto", "default", "choice", "range", "source")
)
Arguments
which

An integer vector of field indexes or a character vector of field names.

type

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

Details

⁠$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:

Returns

⁠$value_possible()⁠ returns an IdfValuePossible object which is a data.table with at most 15 columns:

Examples
\dontrun{
mat$value_possible()
}


Method validate()

Check possible object field value errors

Usage
IdfObject$validate(level = eplusr_option("validate_level"))
Arguments
level

One of "none", "draft", "final" or a list of 10 elements with same format as custom_validate() output.

Details

⁠$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:

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.

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:

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:

Returns

An IdfValidity object.

Examples
\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 is_valid()

Check if there is any error in current object

Usage
IdfObject$is_valid(level = eplusr_option("validate_level"))
Arguments
level

One of "none", "draft", "final" or a list of 10 elements with same format as custom_validate() output.

Details

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

Returns

A single logical value of TRUE or FALSE.

Examples
\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 value_relation()

Get value relations

Usage
IdfObject$value_relation(
  which = NULL,
  direction = c("all", "ref_to", "ref_by", "node"),
  object = NULL,
  class = NULL,
  group = NULL,
  depth = 0L,
  keep = FALSE,
  class_ref = c("both", "none", "all")
)
Arguments
which

An integer vector of field indexes or a character vector of field names.

direction

The relation direction to extract. Should be either "all", "ref_to" or "ref_by".

object

A character vector of object names or an integer vector of object IDs used for searching relations. Default: NULL.

class

A character vector of class names used for searching relations. Default: NULL.

group

A character vector of group names used for searching relations. Default: NULL.

depth

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

keep

If 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_ref

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

Details

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 Name

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

Returns

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.

Examples
\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 ref_to_object()

Extract multiple IdfObject objects referred by specified field values

Usage
IdfObject$ref_to_object(
  which = NULL,
  object = NULL,
  class = NULL,
  group = NULL,
  depth = 0L,
  class_ref = c("both", "none", "all")
)
Arguments
which

An integer vector of field indexes or a character vector of field names.

object

A character vector of object names or an integer vector of object IDs used for searching relations. Default: NULL.

class

A character vector of class names used for searching relations. Default: NULL.

group

A character vector of group names used for searching relations. Default: NULL.

depth

If > 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_ref

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

Details

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.

Returns

A named list of IdfObject objects.

Examples
\dontrun{
# get other objects that this object refereces
mat$ref_to_object() # not referencing other objects
}


Method ref_by_object()

Extract multiple IdfObject objects referring to specified field values

Usage
IdfObject$ref_by_object(
  which = NULL,
  object = NULL,
  class = NULL,
  group = NULL,
  depth = 0L,
  class_ref = c("both", "none", "all")
)
Arguments
which

An integer vector of field indexes or a character vector of field names.

object

A character vector of object names or an integer vector of object IDs used for searching relations. Default: NULL.

class

A character vector of class names used for searching relations. Default: NULL.

group

A character vector of group names used for searching relations. Default: NULL.

depth

If > 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_ref

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

Details

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.

Returns

A named list of IdfObject objects.

Examples
\dontrun{
# get other objects that reference this object
mat$ref_by_object() # referenced by construction "FLOOR"
}


Method ref_to_node()

Extract multiple IdfObject objects referring to same nodes

Usage
IdfObject$ref_to_node(
  which = NULL,
  object = NULL,
  class = NULL,
  group = NULL,
  depth = 0L
)
Arguments
which

An integer vector of field indexes or a character vector of field names.

object

A character vector of object names or an integer vector of object IDs used for searching relations. Default: NULL.

class

A character vector of class names used for searching relations. Default: NULL.

group

A character vector of group names used for searching relations. Default: NULL.

depth

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

Details

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.

Returns

A named list of IdfObject objects.

Examples
\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 has_ref_to()

Check if object field values refer to others

Usage
IdfObject$has_ref_to(
  which = NULL,
  object = NULL,
  class = NULL,
  group = NULL,
  recursive = FALSE,
  class_ref = c("both", "none", "all")
)
Arguments
which

An integer vector of field indexes or a character vector of field names.

object

A character vector of object names or an integer vector of object IDs used for searching relations. Default: NULL.

class

A character vector of class names used for searching relations. Default: NULL.

group

A character vector of group names used for searching relations. Default: NULL.

recursive

If 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_ref

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

Details

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.

Returns

A logical vector with the same length as specified field.

Examples
\dontrun{
mat$has_ref_to()
}


Method has_ref_by()

Check if object field values are referred by others

Usage
IdfObject$has_ref_by(
  which = NULL,
  object = NULL,
  class = NULL,
  group = NULL,
  recursive = FALSE,
  class_ref = c("both", "none", "all")
)
Arguments
which

An integer vector of field indexes or a character vector of field names.

object

A character vector of object names or an integer vector of object IDs used for searching relations. Default: NULL.

class

A character vector of class names used for searching relations. Default: NULL.

group

A character vector of group names used for searching relations. Default: NULL.

recursive

If 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_ref

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

Details

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.

Returns

A logical vector with the same length as specified field.

Examples
\dontrun{
mat$has_ref_by()
}


Method has_ref_node()

Check if object field values refer to other nodes

Usage
IdfObject$has_ref_node(
  which = NULL,
  object = NULL,
  class = NULL,
  group = NULL,
  recursive = FALSE
)
Arguments
which

An integer vector of field indexes or a character vector of field names.

object

A character vector of object names or an integer vector of object IDs used for searching relations. Default: NULL.

class

A character vector of class names used for searching relations. Default: NULL.

group

A character vector of group names used for searching relations. Default: NULL.

recursive

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

Details

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.

Returns

A logical vector with the same length as specified field.

Examples
\dontrun{
mat$has_ref_node()
}


Method has_ref()

Check if object field values refer to or are referred by others

Usage
IdfObject$has_ref(
  which = NULL,
  object = NULL,
  class = NULL,
  group = NULL,
  recursive = FALSE
)
Arguments
which

An integer vector of field indexes or a character vector of field names.

object

A character vector of object names or an integer vector of object IDs used for searching relations. Default: NULL.

class

A character vector of class names used for searching relations. Default: NULL.

group

A character vector of group names used for searching relations. Default: NULL.

recursive

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

Details

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.

Returns

A logical vector with the same length as specified field.

Examples
\dontrun{
# check if having any referenced objects or is referenced by other objects
mat$has_ref()
}


Method to_table()

Format IdfObject as a data.frame

Usage
IdfObject$to_table(
  string_value = TRUE,
  unit = TRUE,
  wide = FALSE,
  all = FALSE,
  group_ext = c("none", "group", "index")
)
Arguments
string_value

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

unit

Only applicable when string_value is FALSE. If TRUE, values of numeric fields are assigned with units using units::set_units() if applicable. Default: FALSE.

wide

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

all

If TRUE, all available fields defined in IDD for the class that objects belong to will be returned. Default: FALSE.

group_ext

Should 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".

Details

⁠$to_table()⁠ returns a data.table that contains core data of current IdfObject. It has 6 columns:

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:

Returns

A data.table with 6 columns (if wide is FALSE) or at least 6 columns (if wide is TRUE).

Examples
\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 to_string()

Format current object as a character vector

Usage
IdfObject$to_string(comment = TRUE, leading = 4L, sep_at = 29L, all = FALSE)
Arguments
comment

If FALSE, all comments will not be included. Default: TRUE.

leading

Leading spaces added to each field. Default: 4L.

sep_at

The character width to separate value string and field string. Default: 29L which is the same as IDF Editor.

all

If TRUE, all available fields defined in IDD for the class that objects belong to will be returned. Default: FALSE.

Details

⁠$to_string()⁠ returns the text format of current object.

Returns

A character vector.

Examples
\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 print()

Print IdfObject object

Usage
IdfObject$print(comment = TRUE, auto_sep = TRUE, brief = FALSE, all = FALSE)
Arguments
comment

If FALSE, all comments are not included.

auto_sep

If TRUE, values and field names are separated at the largest character length of values. Default: FALSE.

brief

If TRUE, only OBJECT part is printed. Default: FALSE.

all

If TRUE, all fields defined in Idd are printed even they do not exist in current object. Default: FALSE.

Details

⁠$print()⁠ prints the IdfObject. Basically, the print output can be divided into 3 parts:

Returns

The IdfObject itself, invisibly.

Examples
\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)
}


Method clone()

The objects of this class are cloneable with this method.

Usage
IdfObject$clone(deep = FALSE)
Arguments
deep

Whether to make a deep clone.

Note

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

Author(s)

Hongyuan Jia

See Also

Idf class

Examples


## ------------------------------------------------
## Method `IdfObject$new`
## ------------------------------------------------

## Not run: 
# 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"]]

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$version`
## ------------------------------------------------

## Not run: 
# get version
roof$version()

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$parent`
## ------------------------------------------------

## Not run: 
roof$parent()

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$id`
## ------------------------------------------------

## Not run: 
roof$id()

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$name`
## ------------------------------------------------

## Not run: 
roof$name()

# NA will be returned if the class does not have name attribute. For example,
# "Version" class
idf$Version$name()

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$group_name`
## ------------------------------------------------

## Not run: 
roof$group_name()

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$class_name`
## ------------------------------------------------

## Not run: 
roof$class_name()

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$definition`
## ------------------------------------------------

## Not run: 
roof$definition()

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$comment`
## ------------------------------------------------

## Not run: 
# 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()

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$value`
## ------------------------------------------------

## Not run: 
# 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")]

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$set`
## ------------------------------------------------

## Not run: 
# 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

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$value_possible`
## ------------------------------------------------

## Not run: 
mat$value_possible()

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$validate`
## ------------------------------------------------

## Not run: 
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))

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$is_valid`
## ------------------------------------------------

## Not run: 
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))

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$value_relation`
## ------------------------------------------------

## Not run: 
# 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")

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$ref_to_object`
## ------------------------------------------------

## Not run: 
# get other objects that this object refereces
mat$ref_to_object() # not referencing other objects

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$ref_by_object`
## ------------------------------------------------

## Not run: 
# get other objects that reference this object
mat$ref_by_object() # referenced by construction "FLOOR"

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$ref_to_node`
## ------------------------------------------------

## Not run: 
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()
}

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$has_ref_to`
## ------------------------------------------------

## Not run: 
mat$has_ref_to()

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$has_ref_by`
## ------------------------------------------------

## Not run: 
mat$has_ref_by()

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$has_ref_node`
## ------------------------------------------------

## Not run: 
mat$has_ref_node()

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$has_ref`
## ------------------------------------------------

## Not run: 
# check if having any referenced objects or is referenced by other objects
mat$has_ref()

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$to_table`
## ------------------------------------------------

## Not run: 
# 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)

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$to_string`
## ------------------------------------------------

## Not run: 
# 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)

## End(Not run)


## ------------------------------------------------
## Method `IdfObject$print`
## ------------------------------------------------

## Not run: 
# 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)

## End(Not run)


[Package eplusr version 0.15.1 Index]