IdfSchedule {eplusr}

Create an IdfScheduleCompact object.

Description

schedule_compact() takes a parent Idf object, a name for Schedule:Compact object, and returns a corresponding IdfScheduleCompact object.

IdfScheduleCompact is an abstraction of a single Schedule:Compact object in an Idf. It provides more detailed methods to add, modify and extract schedule values.

Usage

schedule_compact(parent, name, new = FALSE)

Arguments

parent

An Idf object.

name

A valid name (a string) for a Schedule:Compact object.

new

If TRUE, a new empty IdfScheduleCompact is created. Default: FALSE.

Details

If new is TRUE, an empty IdfScheduleCompact is created, with all field values being empty. The empty IdfScheduleCompact is directly added into the parent Idf object. It is recommended to use ⁠$validate()⁠ method in IdfScheduleCompact to see what kinds of further modifications are needed for those empty fields and use ⁠$set()⁠ and ⁠$update()⁠ method to set field values.

Value

An IdfScheduleCompact object.

Super classes

eplusr::IdfObject -> eplusr::IdfSchedule -> IdfScheduleCompact

Methods

Public methods

• IdfScheduleCompact$new()

• IdfScheduleCompact$type_limits()

• IdfScheduleCompact$set()

• IdfScheduleCompact$update()

• IdfScheduleCompact$validate()

• IdfScheduleCompact$is_valid()

• IdfScheduleCompact$extract()

• IdfScheduleCompact$clone()

Inherited methods

• eplusr::IdfObject$class_name()
• eplusr::IdfObject$comment()
• eplusr::IdfObject$definition()
• eplusr::IdfObject$group_name()
• eplusr::IdfObject$has_ref()
• eplusr::IdfObject$has_ref_by()
• eplusr::IdfObject$has_ref_node()
• eplusr::IdfObject$has_ref_to()
• eplusr::IdfObject$id()
• eplusr::IdfObject$name()
• eplusr::IdfObject$parent()
• eplusr::IdfObject$print()
• eplusr::IdfObject$ref_by_object()
• eplusr::IdfObject$ref_to_node()
• eplusr::IdfObject$ref_to_object()
• eplusr::IdfObject$to_string()
• eplusr::IdfObject$to_table()
• eplusr::IdfObject$value()
• eplusr::IdfObject$value_possible()
• eplusr::IdfObject$value_relation()
• eplusr::IdfObject$version()

Method new()

Create an IdfScheduleCompact object

Usage

IdfScheduleCompact$new(object, parent, new = FALSE)

Arguments

object

An integer specifying an object ID.

parent

An Idf object specifying the parent object.

new

If TRUE, an empty IdfScheduleCompact will be created. Default: FALSE

Returns

An IdfScheduleCompact object.

Examples

\dontrun{
model <- read_idf(system.file("extdata/1ZoneUncontrolled.idf", package = "eplusr"))

# create an empty 'Schedule:Compact'
schedule_compact(model, "sch", TRUE)

# get an existing 'Schedule:Compact'
sch <- schedule_compact(model, "sch")
}

Method type_limits()

Get or set the schedule type limits

Usage

IdfScheduleCompact$type_limits(name)

Arguments

name

A string specifying the name of an ScheduleTypeLimits object in current Idf. If missing, value of last time will be used.

Returns

A list of 2 elements:

• name: The name of the ScheduleTypeLimits object

• range: The range of current schedule values

Method set()

Set schedule values

Usage

IdfScheduleCompact$set(..., .check_range = TRUE)

Arguments

...

Schedule day types and value specifications in lists.

• Group day types inside c(...) at the LHS of ⁠:=⁠

• Put actual schedule values inside list(...) at the RHS of ⁠:=⁠

• Each schedule value should be named a time. Time can be given in either ..H or "HH:MM".

.check_range

If TRUE, schedule values will be checked based on ⁠$type_limits()⁠. Default: TRUE.

Details

Please note that all schedules will be applied for all days in a year. For detailed modifications, please check ⁠$update()⁠ method which accepts data.frame input.

Returns

The modified IdfScheduleCompact object.

Examples

\dontrun{
sch$set(c("weekday", "summerdesignday") := list(
    ..6 = 0.2, "8:00" = 0.5,
    ..12 = 0.95, "13:30" = 0.6, ..14 = 0.8,
    ..18 = 0.95, ..19 = 0.2, ..24 = 0),
    allotherday = list(..24 = 0)
)
}

Method update()

Update schedule values using data.frame

Usage

IdfScheduleCompact$update(data, check_range = TRUE, compact = FALSE)

Arguments

data

A data.frame of at least 4 columns:

• year_day: Used for the ⁠Through:⁠ fields. Can be in one of the following formats:

  • character: Day specifications in either mm/dd or mm-dd where mm is the month in 1:12 or in character and dd is the day in month in 1:31

  • Date: The year component will be ignored and only the month and day component will be used

  • integer: Julian day, e.g. 360, 365 and etc

• id (Optional): Integer type. Used to group together different day types with same schedule values. Grouped day types will be compacted in a single ⁠For:⁠ field, e.g. ⁠For: Weekdays SummaryDesignDay⁠. Grouped day types should have the same schedule values. Otherwise an error will be issued.

• daytype: Character type. Used for the ⁠For:⁠ fields. All possible values are listed below. Case-insensitive matching is used. Different day types can be grouped using the id column mentioned above or put together directly in a single string separate by comma (⁠,⁠), e.g. "weekend, holiday"

  • "AllDay(s)"

  • "Weekday(s)", and also "Monday", "Tuesday", "Wednesday", "Thursday" and "Friday"

  • "Weekend(s)", and also "Saturday" and "Sunday"

  • "SummaryDesignDay" and "WinterDesignDay"

  • "Holiday"

  • "CustomDay1" and "CustomDay2"

  • "AllOtherDay(s)"

• time: Used for the ⁠Until:⁠ fields. Can be in one of the following formats:

  • character: Time specifications in HH:MM where HH is the hour in 0:24 and MM is the minute in 0:60

  • integer: Time differences from 00:00:00 in minutes, e.g. seq(60, 60 * 24, by = 60)

  • hms: hms objects constructed using hms::hms() or equivalents, e.g. hms::hms(minutes = 30, hours = 1), and hms::as_hms("1:30:00")

  • difftime: difftime objects constructed using as.difftime() or equivalents, e.g. as.difftime(1:24, units = "hours")

  • ITime: ITime objects constructed using data.table::as.ITime(), e.g. as.ITime("01:30:00")

• value: Numeric type. Used for the actual schedule values

check_range

If TRUE, schedule values will be checked based on ⁠$type_limits()⁠. Default: TRUE.

compact

If TRUE, same schedule values from different day types will be compacted together. Also, time periods that have the same schedule values will also be compacted. Note that only "Holiday", "CustomDay1" and "CustomDay2" will be compacted into "AllOtherDays". For example, if the daytype column contains only "Weekdays", "SummerDesignDay" and "AllOtherDays", "AllOtherDays" will be expanded to "Weekends", "WinterDesignDay" and "AllOtherDays". Default: FALSE.

Returns

The modified IdfScheduleCompact object.

Examples

\dontrun{
sch$update(sch$extract())

val1 <- data.table::data.table(
    year_day = "12/31",
    daytype = "weekday,summerdesignday",
    time = c("6:00", "8:00", "12:00", "13:30", "14:00", "18:00", "19:00", "24:00"),
    value = c(0.2,    0.5,    0.95,    0.6,     0.8,     0.95,    0.2,     0.0)
)
val2 <- data.table::data.table(
    year_day = "12/31", daytype = "allotherday",
    time = "24:00", value = 0.0
)
val <- data.table::rbindlist(list(val1, val2))
sch$update(val)
}

Method validate()

Check possible object field value errors

Usage

IdfScheduleCompact$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 IdfScheduleCompact object under specified validation level and returns an IdfValidity object. Schedule value ranges will be checked if current validate level contains range checking (if corresponding ScheduleTypeLimits ⁠Numeric Type⁠ is Continuous) or choice checking (if corresponding ScheduleTypeLimits ⁠Numeric Type⁠ is Discrete).

For detailed description on validate checking, see IdfObject$validate() documentation above.

Returns

An IdfValidity object.

Examples

\dontrun{
sch$validate()

# check at predefined validate level
sch$validate("none")
sch$validate("draft")
sch$validate("final")
}

Method is_valid()

Check if there is any error in current object

Usage

IdfScheduleCompact$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 IdfScheduleCompact object under specified validation level. Schedule value ranges will be checked if current validate level contains range checking (if corresponding ScheduleTypeLimits ⁠Numeric Type⁠ is Continuous) or choice checking (if corresponding ScheduleTypeLimits ⁠Numeric Type⁠ is Discrete).

⁠$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 IdfObject$validate() documentation above.

Returns

A single logical value of TRUE or FALSE.

Examples

\dontrun{
sch$is_valid()
}

Method extract()

Extract schedule values

Usage

IdfScheduleCompact$extract(daytype = NULL, timestep = NULL)

Arguments

daytype

Should be one of:

• NULL: Do nothing Grouped day types will be concatenated with a comma, e.g. ⁠Weekdays,SummerDesignDay⁠. This is the default behavior.

• TRUE or "expand": All compacted day types will be expanded.

• FALSE or "compact": Same schedule values from different day types will be compacted together.

• A character vector specifying the grouped day types, e.g. c("weekday", "summerdesignday"). All other days except specified ones will be classified into day type AllOtherDays, if possible. If not possible, those day types will still be extracted separately.

timestep

The time step of schedule values, e.g. "10 mins" and "1 hour". Valid units include sec(s), min(s), and hour(s). If NULL, the original time specifications will be kept. If "auto", the time periods with the same schedule values will be compacted. Default: NULL.

Returns

NULL if current schedule is empty. Otherwise, a data.table::data.table() of 5 columns:

• year_day: Character type. Used for the ⁠Through:⁠ fields. Day specifications in mm/dd format

• id: Integer type. The group index of day types

• daytype: Character type. Used for the ⁠For:⁠ fields. All possible values are:

  • "AllDay"

  • "Weekday", and also "Monday", "Tuesday", "Wednesday", "Thursday" and "Friday"

  • "Weekend", and also "Saturday" and "Sunday"

  • "SummaryDesignDay" and "WinterDesignDay"

  • "Holiday"

  • "CustomDay1" and "CustomDay2"

  • "AllOtherDay"

• time: hms vector. Used for the ⁠Until:⁠ fields. It is handy for plotting since hms object is directly supported by the scale system of ggplot2 package

• value: Numeric type. Actual schedule values

Examples

\dontrun{
sch$extract()
sch$extract("expand")
sch$extract(timestep = "30 mins")
}

Method clone()

The objects of this class are cloneable with this method.

Usage

IdfScheduleCompact$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Author(s)

Hongyuan Jia

See Also

Idf class

Examples

## ------------------------------------------------
## Method `IdfScheduleCompact$new`
## ------------------------------------------------

## Not run: 
model <- read_idf(system.file("extdata/1ZoneUncontrolled.idf", package = "eplusr"))

# create an empty 'Schedule:Compact'
schedule_compact(model, "sch", TRUE)

# get an existing 'Schedule:Compact'
sch <- schedule_compact(model, "sch")

## End(Not run)

## ------------------------------------------------
## Method `IdfScheduleCompact$set`
## ------------------------------------------------

## Not run: 
sch$set(c("weekday", "summerdesignday") := list(
    ..6 = 0.2, "8:00" = 0.5,
    ..12 = 0.95, "13:30" = 0.6, ..14 = 0.8,
    ..18 = 0.95, ..19 = 0.2, ..24 = 0),
    allotherday = list(..24 = 0)
)

## End(Not run)

## ------------------------------------------------
## Method `IdfScheduleCompact$update`
## ------------------------------------------------

## Not run: 
sch$update(sch$extract())

val1 <- data.table::data.table(
    year_day = "12/31",
    daytype = "weekday,summerdesignday",
    time = c("6:00", "8:00", "12:00", "13:30", "14:00", "18:00", "19:00", "24:00"),
    value = c(0.2,    0.5,    0.95,    0.6,     0.8,     0.95,    0.2,     0.0)
)
val2 <- data.table::data.table(
    year_day = "12/31", daytype = "allotherday",
    time = "24:00", value = 0.0
)
val <- data.table::rbindlist(list(val1, val2))
sch$update(val)

## End(Not run)

## ------------------------------------------------
## Method `IdfScheduleCompact$validate`
## ------------------------------------------------

## Not run: 
sch$validate()

# check at predefined validate level
sch$validate("none")
sch$validate("draft")
sch$validate("final")

## End(Not run)

## ------------------------------------------------
## Method `IdfScheduleCompact$is_valid`
## ------------------------------------------------

## Not run: 
sch$is_valid()

## End(Not run)


## ------------------------------------------------
## Method `IdfScheduleCompact$extract`
## ------------------------------------------------

## Not run: 
sch$extract()
sch$extract("expand")
sch$extract(timestep = "30 mins")

## End(Not run)