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 be created using function idf_object() or from methods of a parent Idf object, using $object(), $objects_in_class() and equivalent.

Usage

idfobj <- model$object(which)
idfobj <- idf_object(model, which, class = NULL)
idfobj$version()
idfobj$id()
idfobj$name()
idfobj$class_name()
idfobj$group_name()
idfobj$definition()
idfobj$comment(comment, append = TRUE, width = 0L)
idfobj$value(which = NULL, all = FALSE, simplify = FALSE, unit = FALSE)
idfobj$value_possible(which = NULL, type = c("auto", "default", "choice", "range", "source"))
idfobj$FieldName
idfobj[[Field]]
idfobj$set(..., .defaults = TRUE)
idfobj$FieldName <- Value
idfobj[[Field]] <- Value
idfobj$value_relation(which = NULL, direction = c("all", "ref_to", "ref_by", "node"),
                      recursive = FALSE, depth = 1L)
idfobj$ref_to_object(which = NULL, class = NULL, recursive = FALSE, depth = 1L)
idfobj$ref_by_object(which = NULL, class = NULL, recursive = FALSE, depth = 1L)
idfobj$ref_to_node(which = NULL, class = NULL, recursive = FALSE, depth = 1L)
idfobj$has_ref_to(which = NULL, class = NULL)
idfobj$has_ref_by(which = NULL, class = NULL)
idfobj$has_ref_node(which = NULL, class = NULL)
idfobj$has_ref(which)
idfobj$validate(level = eplusr_option("validate_level"))
idfobj$is_valid(level = eplusr_option("validate_level"))
idfobj$to_table(all = FALSE, unit = TRUE, wide = FALSE, string_value = TRUE)
idfobj$to_string(comment = TRUE, leading = 4L, sep_at = 29L, all = FALSE)
idfobj$print(comment = TRUE, auto_sep = FALSE, brief = FALSE)
print(iddobj)

Basic Info

idfobj <- model$object(which)
idfobj <- idf_object(model, which, class = NULL)
idfobj$version()
idfobj$id()
idfobj$name()
idfobj$group_name()
idfobj$class_name()

$version() returns the version of parent Idf object in a numeric_version format.

$id() returns current IdfObject ID.

$name() returns current IdfObject name. If the class does not have name attribute, NA is returned.

$group_name() returns the group name of current IdfObject belongs to.

$class_name() returns the class name of current IdfObject belongs to.

Arguments:

  • model: An Idf object.

  • class: A single string of valid class name.

  • which: A valid object ID (an integer) or name (a string).

Definition

idfobj$definition()

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

Getting and Setting Comments

idfobj$comment(comment, append = TRUE, width = 0L)

$comment() returns current IdfObject comment if comment is not given, or modifies current IdfObject comment if comment is given.

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.

Get Field Values

idfobj$value(which = NULL, all = FALSE, simplify = FALSE, unit = FALSE)
idfobj$value_possible(which = NULL, type = c("auto", "default", "choice", "range", "source"))
idfobj$FieldName
idfobj[[Field]]

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

$possible_value() 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:

    idfobj$definition()$is_autosizable_field()
    idfobj$definition()$is_autocalculatable_field()
    
  • 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.

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.

  • FieldName: A single length character vector of one valid field name where all characters except letters and numbers are replaced by underscores.

  • Field: A single length character vector of one valid field name or a single length integer vector of one valid field index. Same as above, field names should be given in a style where all characters except letters and numbers are replaced by underscores.

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

Set Field Values

idfobj$set(..., .default = TRUE)
idfobj$FieldName <- Value
idfobj[[Field]] <- Value

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

Note:

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

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

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.

  • FieldName: A single length character vector of one valid field name where all characters except letters and numbers are replaced by underscores.

  • Field: A single length character vector of one valid field name or a single length integer vector of one valid field index. Same as above, field names should be given in a style where all characters except letters and numbers are replaced by underscores.

  • Value: A single length vector of value to set.

Field Value Relation

idfobj$value_relation(which = NULL, direction = c("all", "ref_to", "ref_by", "node"),
                      recursive = FALSE, depth = 1L)
idfobj$ref_to_object(which = NULL, class = NULL, recursive = FALSE, depth = 1L)
idfobj$ref_by_object(which = NULL, class = NULL, recursive = FALSE, depth = 1L)
idfobj$ref_to_node(which = NULL, class = NULL, recursive = FALSE, depth = 1L)
idfobj$has_ref_to(which = NULL, class = NULL)
idfobj$has_ref_by(which = NULL, class = NULL)
idfobj$has_ref_node(which = NULL, class = NULL)
idfobj$has_ref(which)

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 futher easily extracted using $ref_by_object() method.

Note that $value_relation() shows all fields specified, even some of them may do not have 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() 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() 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() 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() 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() 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() 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.

Arguments:

  • which: An integer vector of field indexes or a character vector of field names.

  • class: A character vector of class names.

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

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

  • depth: Only applicable when recursive is TRUE. This is a depth to when searching value relations recursively. If NULL, all recursive relations are returned. Default: 1.

Validation

idfobj$validate(level = eplusr_option("validate_level"))
idfobj$is_valid(level = eplusr_option("validate_level"))

$validate() checks if there are errors in values in current IdfObject under specified validation level and returns an IdfValidity object which contains data of invalid field values. Different validation result examples are shown below:

  • No error is found:

    v No error found.
    

    Above result shows that there is no error found after conducting all validation checks in specified validation 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 Reheat
    

Above validation results show that after all validation components performed under current validation level, 2 invalid field values are found. All of them are in 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 set those two fields to correct value by doing idf$set(..176 = list(Maximum Flow per Zone Floor Area During Reheat= "autosize",Maximum Flow Fraction During Reheat = "autosize" ))

$is_valid() returns TRUE if there is no error in current IdfObject object under specified validation level and FALSE otherwise.

Underneath, an IdfValidity object which $validate() returns is a list of 13 element. For details about the underlying structure of IdfValidity, please $validate() in Idf class.

Data Extraction

idfobj$to_table(string_value = TRUE, unit = TRUE, wide = FALSE, all = FALSE)
idfobj$to_string(comment = TRUE, leading = 4L, sep_at = 29L, all = FALSE)

$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. Field values.

$to_string() returns the text format of an IdfObject.

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: 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. Default: FALSE.

  • 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, values of all possible fields in current class the IdfObject belongs to are returned. Default: FALSE

Print

idfobj$print(comment = TRUE, auto_sep = FALSE)
print(idfobj)

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

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.

See also

Idf class

Examples

if (FALSE) { # read an IDF file idf <- read_idf(system.file("extdata/1ZoneUncontrolled.idf", package = "eplusr"), idd = use_idd(8.8, download = "auto")) # get the IdfObject of material named "C5 - 4 IN HW CONCRETE" mat <- idf$Material[["C5 - 4 IN HW CONCRETE"]] # get object ID mat$id() # get object name mat$name() # NA will be returned if the class does not have name attribute. For example, # "Version" class idf$Version$name() # get underlying IddObject of current class mat$definition() # get object comments mat$comment() # add new object comments mat$comment(c("This is a material named `WD01`", "This object has an ID of 47")) mat$comment() # append new comments mat$comment("This is an appended comment") mat$comment() # prepend new comments mat$comment("This is a prepended comment", append = FALSE) mat$comment() # wrap long comments mat$comment("This is a very long comment that is needed to be wrapped.", width = 30) mat$comment() # delete old comments and add new one mat$comment("This is the only comment", append = NULL) mat$comment() # delete all comments mat$comment(NULL) mat$comment() # 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(idf$Zone$`ZONE ONE`$value()) str(idf$Zone$`ZONE ONE`$value(all = TRUE)) # get field values using shortcuts mat$Roughness mat[["Specific_Heat"]] mat[c(1,2)] mat[c("Name", "Density")] # 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 # check validate mat$validate() mat$is_valid() # if we set density to a negative number 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() # get other objects that this object refereces mat$ref_to_object() # not referencing other objects mat$has_ref_to() # get other objects that reference this object mat$ref_by_object() # referenced by construction "FLOOR" names(mat$ref_by_object()) mat$has_ref_by() # check if having any referenced objects or is referenced by other objects mat$has_ref() # 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)) # 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) # 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) }