SensitivityJob: Conduct Sensitivity Analysis for An EnergyPlus Model
In ideas-lab-nus/epluspar: Conduct Parametric Analysis on 'EnergyPlus' Models
SensitivityJob R Documentation
Conduct Sensitivity Analysis for An EnergyPlus Model
Description
sensi_job() takes an IDF and EPW as input and returns a SensitivityJob,
which provides a prototype of conducting sensitivity analysis of EnergyPlus
simulations using Morris method.
Details
SensitivityJob inherits from eplusr::ParametricJob class, which means
that all methods provided by eplusr::ParametricJob class are also available
for SensitivityJob class.
The basic workflow is basically:
Adding parameters for sensitivity analysis using
$param()
or
$apply_measure().
Check parameter sampled values and generated parametric models using
$samples()
and
$models(),
respectively.
Run EnergyPlus simulations in parallel using
$run(),
Gather EnergyPlus simulated data using
$report_data() or
$tabular_data().
Evaluate parameter sensitivity using
$evaluate().
Super classes
eplusr::EplusGroupJob -> eplusr::ParametricJob -> SensitivityJob
Methods
Public methods
-
-
-
-
-
Inherited methods
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Method param()
Set parameters for sensitivity analysis
Usage
SensitivityJob$param(
...,
.names = NULL,
.r = 12L,
.grid_jump = 4L,
.scale = TRUE
)
Arguments
...Lists of paramter definitions. Please see above on the
syntax.
.namesA character vector of the parameter names. If NULL,
the parameter will be named in format theta + number, where
number is the index of parameter. Default: NULL.
.rAn positive integer specifying the number of elementary
effect computed per factor. For details, see
sensitivity::morris. Default: 12.
.grid_jumpAn integer or a vector of integers specifying the
number of levels that are increased/decreased for computing
the elementary effects. Default: 1L. For details, see
sensitivity::morris.
.scaleIf TRUE, the input design of experiments is scaled
after building the design and before computing the elementary
effects so that all factors vary within the range [0,1].
Default: TRUE. For details, see sensitivity::morris.
Details
$param() takes parameter definitions in list format, which is
similar to $set() in eplusr::Idf class except that each field is
not assigned with a single value, but a numeric vector of length 3,
indicating the minimum value, maximum value and number of levels of
each parameter.
Similar like the way of modifying object field values in
eplusr::Idf$set(), there are 3 different ways of
defining a parameter in epluspar:
-
object = list(field = c(min, max, levels)): Where object is a
valid object ID or name. Note object ID should be denoted with two
periods .., e.g. ..10 indicates the object with ID 10, It
will set that specific field in that object as one parameter.
-
.(object, object) := list(field = c(min, max, levels)): Simimar
like above, but note the use of .() in the left hand side. You
can put multiple object ID or names in .(). It will set the field
of all specified objects as one parameter.
-
class := list(field = c(min, max, levels)): Note the use of :=
instead of =. The main difference is that, unlike =, the left
hand side of := should be a valid class name in current
eplusr::Idf. It will set that field of all objects in specified
class as one parameter.
For example, the code block below defines 3 parameters:
Field Fan Total Efficiency in object named Supply Fan 1 in class
Fan:VariableVolume class, with minimum, maximum and number of levels
being 0.1, 1.0 and 5, respectively.
Field Thickness in all objects in class Material, with minimum, maximum
and number of levels being 0.01, 1.0 and 5, respectively.
Field Conductivity in all objects in class Material, with minimum,
maximum and number of levels being 0.1, 0.6 and 10, respectively.
sensi$param(
`Supply Fan 1` = list(Fan_Total_Efficiency = c(min = 0.1, max = 1.0, levels = 5)),
Material := list(Thickness = c(0.01, 1, 5), Conductivity = c(0.1, 0.6, 10))
)
Returns
The modified SensitivityJob object itself.
Examples
\dontrun{
sensi$param(
`Supply Fan 1` = list(Fan_Total_Efficiency = c(min = 0.1, max = 1.0, levels = 5)),
Material := list(Thickness = c(0.01, 1, 5), Conductivity = c(0.1, 0.6, 10))
)
}
Method apply_measure()
Set parameters for sensitivity analysis using function
Usage
SensitivityJob$apply_measure(
measure,
...,
.r = 12L,
.grid_jump = 4L,
.scale = TRUE
)
Arguments
measureA function that takes an eplusr::Idf and other
arguments as input and returns an eplusr::Idf object as
output.
...Arguments except first Idf argument that are passed
to that measure.
.rAn positive integer specifying the number of elementary
effect computed per factor. For details, see
sensitivity::morris.
.grid_jumpAn integer or a vector of integers specifying the
number of levels that are increased/decreased for computing
the elementary effects. For details, see
sensitivity::morris.
.scaleIf TRUE, the input design of experiments is scaled
after building the design and before computing the elementary
effects so that all factors vary within the range [0,1].
Default: TRUE. For details, see sensitivity::morris.
Details
$apply_measure() works in a similar way as the $apply_measure in
eplusr::ParametricJob class, with only exception that each argument
supplied in ... should be a numeric vector of length 3, indicating
the minimum, maximum and number of levels of each parameter.
Basically $apply_measure() allows to apply a measure to an
eplusr::Idf. A measure here is just a function that takes an
eplusr::Idf object and other arguments as input, and returns a
modified eplusr::Idf object as output.
The names of function parameter will be used as the names of
sensitivity parameter. For example, the equivalent version of
specifying parameters described in
$param()
using $apply_measure() can be:
# set sensitivity parameters using $apply_measure()
# (a) first define a "measure"
measure <- function (idf, efficiency, thickness, conducitivy) {
idf$set(
`Supply Fan 1` = list(Fan_Total_Efficiency = efficiency),
Material := list(Thickness = thickness, Conductivity = conducivity)
)
idf
}
# (b) then apply that measure with parameter space definitions as
# function arguments
sensi$apply_measure(measure,
efficiency = c(min = 0.1, max = 1.0, levels = 5),
thickness = c(0.01, 1, 5), conductivity = c(0.1, 0.6, 10)
)
Returns
The modified SensitivityJob object itself.
Examples
\dontrun{
# set sensitivity parameters using $apply_measure()
# (a) first define a "measure"
measure <- function (idf, efficiency, thickness, conducitivy) {
idf$set(
`Supply Fan 1` = list(Fan_Total_Efficiency = efficiency),
Material := list(Thickness = thickness, Conductivity = conducivity)
)
idf
}
# (b) then apply that measure with parameter space definitions as
# function arguments
sensi$apply_measure(measure,
efficiency = c(min = 0.1, max = 1.0, levels = 5),
thickness = c(0.01, 1, 5), conductivity = c(0.1, 0.6, 10)
)
}
Method samples()
Get sampled parameter values
Usage
SensitivityJob$samples()
Details
$samples() returns a data.table::data.table() which contains the
sampled value for each parameter using Morris
method. The returned data.table has 1 + n columns, where n is the
parameter number, while 1 indicates an extra column named case
giving the index of each sample.
Returns
A data.table::data.table().
Examples
\dontrun{
sensi$samples()
}
Method evaluate()
Evaluate sensitivity
Usage
SensitivityJob$evaluate(results)
Arguments
resultsA numeric vector. Usually the output of parametric
simulations extracted using
$report_data() or
$tabular_data().
Details
$evaluate() takes a numeric vector with the same length as total
sample number and returns the a sensitivity::morris() object. The
statistics of interest (mu, mu* and sigma) are stored as an attribute
named data and can be retrieved using atrr(sensi$evaluate(), "data").
Returns
a sensitivity::morris() object with an extra data
attribute.
Examples
\dontrun{
# run parametric simulations
sensi$run(wait = TRUE)
# status now includes a data.table with detailed information on each simulation
sensi$status()
# print simulation errors
sensi$errors()
# extract a target simulation output value for each case to evaluate the
# sensitivity results
eng <- sen$tabular_data(table_name = "site and source energy",
column_name = "energy per total building area",
row_name = "total site energy")[, as.numeric(value)]
(result <- sensi$evaluate(eng))
# extract sensivitity data
attr(result, "data")
# plot
plot(result)
}
Method print()
Print SensitivityJob object
Usage
SensitivityJob$print()
Details
$print() shows the core information of this SensitivityJob,
including the path of IDFs and EPWs and also the simulation job
status.
$print() is quite useful to get the simulation status, especially
when wait is FALSE in $run(). The job status will be updated
and printed whenever $print() is called.
Returns
The SensitivityJob object itself, invisibly.
Examples
\dontrun{
sen$print()
}
Author(s)
Hongyuan Jia
Examples
## ------------------------------------------------
## Method `SensitivityJob$param`
## ------------------------------------------------
## Not run:
sensi$param(
`Supply Fan 1` = list(Fan_Total_Efficiency = c(min = 0.1, max = 1.0, levels = 5)),
Material := list(Thickness = c(0.01, 1, 5), Conductivity = c(0.1, 0.6, 10))
)
## End(Not run)
## ------------------------------------------------
## Method `SensitivityJob$apply_measure`
## ------------------------------------------------
## Not run:
# set sensitivity parameters using $apply_measure()
# (a) first define a "measure"
measure <- function (idf, efficiency, thickness, conducitivy) {
idf$set(
`Supply Fan 1` = list(Fan_Total_Efficiency = efficiency),
Material := list(Thickness = thickness, Conductivity = conducivity)
)
idf
}
# (b) then apply that measure with parameter space definitions as
# function arguments
sensi$apply_measure(measure,
efficiency = c(min = 0.1, max = 1.0, levels = 5),
thickness = c(0.01, 1, 5), conductivity = c(0.1, 0.6, 10)
)
## End(Not run)
## ------------------------------------------------
## Method `SensitivityJob$samples`
## ------------------------------------------------
## Not run:
sensi$samples()
## End(Not run)
## ------------------------------------------------
## Method `SensitivityJob$evaluate`
## ------------------------------------------------
## Not run:
# run parametric simulations
sensi$run(wait = TRUE)
# status now includes a data.table with detailed information on each simulation
sensi$status()
# print simulation errors
sensi$errors()
# extract a target simulation output value for each case to evaluate the
# sensitivity results
eng <- sen$tabular_data(table_name = "site and source energy",
column_name = "energy per total building area",
row_name = "total site energy")[, as.numeric(value)]
(result <- sensi$evaluate(eng))
# extract sensivitity data
attr(result, "data")
# plot
plot(result)
## End(Not run)
## ------------------------------------------------
## Method `SensitivityJob$print`
## ------------------------------------------------
## Not run:
sen$print()
## End(Not run)
ideas-lab-nus/epluspar documentation built on March 23, 2024, 11:51 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| SensitivityJob | R Documentation |
Conduct Sensitivity Analysis for An EnergyPlus Model
Description
sensi_job() takes an IDF and EPW as input and returns a SensitivityJob,
which provides a prototype of conducting sensitivity analysis of EnergyPlus
simulations using Morris method.
Details
SensitivityJob inherits from eplusr::ParametricJob class, which means
that all methods provided by eplusr::ParametricJob class are also available
for SensitivityJob class.
The basic workflow is basically:
Adding parameters for sensitivity analysis using
$param()or$apply_measure().Check parameter sampled values and generated parametric models using
$samples()and$models(), respectively.Run EnergyPlus simulations in parallel using
$run(),Gather EnergyPlus simulated data using $report_data() or $tabular_data().
Evaluate parameter sensitivity using
$evaluate().
Super classes
eplusr::EplusGroupJob -> eplusr::ParametricJob -> SensitivityJob
Methods
Public methods
Inherited methods
Method param()
Set parameters for sensitivity analysis
Usage
SensitivityJob$param( ..., .names = NULL, .r = 12L, .grid_jump = 4L, .scale = TRUE )
Arguments
...Lists of paramter definitions. Please see above on the syntax.
.namesA character vector of the parameter names. If
NULL, the parameter will be named in formattheta + number, wherenumberis the index of parameter. Default:NULL..rAn positive integer specifying the number of elementary effect computed per factor. For details, see sensitivity::morris. Default:
12..grid_jumpAn integer or a vector of integers specifying the number of levels that are increased/decreased for computing the elementary effects. Default:
1L. For details, see sensitivity::morris..scaleIf
TRUE, the input design of experiments is scaled after building the design and before computing the elementary effects so that all factors vary within the range [0,1]. Default:TRUE. For details, see sensitivity::morris.
Details
$param() takes parameter definitions in list format, which is
similar to $set() in eplusr::Idf class except that each field is
not assigned with a single value, but a numeric vector of length 3,
indicating the minimum value, maximum value and number of levels of
each parameter.
Similar like the way of modifying object field values in eplusr::Idf$set(), there are 3 different ways of defining a parameter in epluspar:
-
object = list(field = c(min, max, levels)): Whereobjectis a valid object ID or name. Note object ID should be denoted with two periods.., e.g...10indicates the object with ID10, It will set that specific field in that object as one parameter. -
.(object, object) := list(field = c(min, max, levels)): Simimar like above, but note the use of.()in the left hand side. You can put multiple object ID or names in.(). It will set the field of all specified objects as one parameter. -
class := list(field = c(min, max, levels)): Note the use of:=instead of=. The main difference is that, unlike=, the left hand side of:=should be a valid class name in current eplusr::Idf. It will set that field of all objects in specified class as one parameter.
For example, the code block below defines 3 parameters:
Field
Fan Total Efficiencyin object namedSupply Fan 1in classFan:VariableVolumeclass, with minimum, maximum and number of levels being 0.1, 1.0 and 5, respectively.Field
Thicknessin all objects in classMaterial, with minimum, maximum and number of levels being 0.01, 1.0 and 5, respectively.Field
Conductivityin all objects in classMaterial, with minimum, maximum and number of levels being 0.1, 0.6 and 10, respectively.
sensi$param(
`Supply Fan 1` = list(Fan_Total_Efficiency = c(min = 0.1, max = 1.0, levels = 5)),
Material := list(Thickness = c(0.01, 1, 5), Conductivity = c(0.1, 0.6, 10))
)
Returns
The modified SensitivityJob object itself.
Examples
\dontrun{
sensi$param(
`Supply Fan 1` = list(Fan_Total_Efficiency = c(min = 0.1, max = 1.0, levels = 5)),
Material := list(Thickness = c(0.01, 1, 5), Conductivity = c(0.1, 0.6, 10))
)
}
Method apply_measure()
Set parameters for sensitivity analysis using function
Usage
SensitivityJob$apply_measure( measure, ..., .r = 12L, .grid_jump = 4L, .scale = TRUE )
Arguments
measureA function that takes an eplusr::Idf and other arguments as input and returns an eplusr::Idf object as output.
...Arguments except first
Idfargument that are passed to thatmeasure..rAn positive integer specifying the number of elementary effect computed per factor. For details, see sensitivity::morris.
.grid_jumpAn integer or a vector of integers specifying the number of levels that are increased/decreased for computing the elementary effects. For details, see sensitivity::morris.
.scaleIf
TRUE, the input design of experiments is scaled after building the design and before computing the elementary effects so that all factors vary within the range [0,1]. Default:TRUE. For details, see sensitivity::morris.
Details
$apply_measure() works in a similar way as the $apply_measure in
eplusr::ParametricJob class, with only exception that each argument
supplied in ... should be a numeric vector of length 3, indicating
the minimum, maximum and number of levels of each parameter.
Basically $apply_measure() allows to apply a measure to an
eplusr::Idf. A measure here is just a function that takes an
eplusr::Idf object and other arguments as input, and returns a
modified eplusr::Idf object as output.
The names of function parameter will be used as the names of
sensitivity parameter. For example, the equivalent version of
specifying parameters described in
$param()
using $apply_measure() can be:
# set sensitivity parameters using $apply_measure()
# (a) first define a "measure"
measure <- function (idf, efficiency, thickness, conducitivy) {
idf$set(
`Supply Fan 1` = list(Fan_Total_Efficiency = efficiency),
Material := list(Thickness = thickness, Conductivity = conducivity)
)
idf
}
# (b) then apply that measure with parameter space definitions as
# function arguments
sensi$apply_measure(measure,
efficiency = c(min = 0.1, max = 1.0, levels = 5),
thickness = c(0.01, 1, 5), conductivity = c(0.1, 0.6, 10)
)
Returns
The modified SensitivityJob object itself.
Examples
\dontrun{
# set sensitivity parameters using $apply_measure()
# (a) first define a "measure"
measure <- function (idf, efficiency, thickness, conducitivy) {
idf$set(
`Supply Fan 1` = list(Fan_Total_Efficiency = efficiency),
Material := list(Thickness = thickness, Conductivity = conducivity)
)
idf
}
# (b) then apply that measure with parameter space definitions as
# function arguments
sensi$apply_measure(measure,
efficiency = c(min = 0.1, max = 1.0, levels = 5),
thickness = c(0.01, 1, 5), conductivity = c(0.1, 0.6, 10)
)
}
Method samples()
Get sampled parameter values
Usage
SensitivityJob$samples()
Details
$samples() returns a data.table::data.table() which contains the
sampled value for each parameter using Morris
method. The returned data.table has 1 + n columns, where n is the
parameter number, while 1 indicates an extra column named case
giving the index of each sample.
Returns
A data.table::data.table().
Examples
\dontrun{
sensi$samples()
}
Method evaluate()
Evaluate sensitivity
Usage
SensitivityJob$evaluate(results)
Arguments
resultsA numeric vector. Usually the output of parametric simulations extracted using $report_data() or $tabular_data().
Details
$evaluate() takes a numeric vector with the same length as total
sample number and returns the a sensitivity::morris() object. The
statistics of interest (mu, mu* and sigma) are stored as an attribute
named data and can be retrieved using atrr(sensi$evaluate(), "data").
Returns
a sensitivity::morris() object with an extra data
attribute.
Examples
\dontrun{
# run parametric simulations
sensi$run(wait = TRUE)
# status now includes a data.table with detailed information on each simulation
sensi$status()
# print simulation errors
sensi$errors()
# extract a target simulation output value for each case to evaluate the
# sensitivity results
eng <- sen$tabular_data(table_name = "site and source energy",
column_name = "energy per total building area",
row_name = "total site energy")[, as.numeric(value)]
(result <- sensi$evaluate(eng))
# extract sensivitity data
attr(result, "data")
# plot
plot(result)
}
Method print()
Print SensitivityJob object
Usage
SensitivityJob$print()
Details
$print() shows the core information of this SensitivityJob,
including the path of IDFs and EPWs and also the simulation job
status.
$print() is quite useful to get the simulation status, especially
when wait is FALSE in $run(). The job status will be updated
and printed whenever $print() is called.
Returns
The SensitivityJob object itself, invisibly.
Examples
\dontrun{
sen$print()
}
Author(s)
Hongyuan Jia
Examples
## ------------------------------------------------
## Method `SensitivityJob$param`
## ------------------------------------------------
## Not run:
sensi$param(
`Supply Fan 1` = list(Fan_Total_Efficiency = c(min = 0.1, max = 1.0, levels = 5)),
Material := list(Thickness = c(0.01, 1, 5), Conductivity = c(0.1, 0.6, 10))
)
## End(Not run)
## ------------------------------------------------
## Method `SensitivityJob$apply_measure`
## ------------------------------------------------
## Not run:
# set sensitivity parameters using $apply_measure()
# (a) first define a "measure"
measure <- function (idf, efficiency, thickness, conducitivy) {
idf$set(
`Supply Fan 1` = list(Fan_Total_Efficiency = efficiency),
Material := list(Thickness = thickness, Conductivity = conducivity)
)
idf
}
# (b) then apply that measure with parameter space definitions as
# function arguments
sensi$apply_measure(measure,
efficiency = c(min = 0.1, max = 1.0, levels = 5),
thickness = c(0.01, 1, 5), conductivity = c(0.1, 0.6, 10)
)
## End(Not run)
## ------------------------------------------------
## Method `SensitivityJob$samples`
## ------------------------------------------------
## Not run:
sensi$samples()
## End(Not run)
## ------------------------------------------------
## Method `SensitivityJob$evaluate`
## ------------------------------------------------
## Not run:
# run parametric simulations
sensi$run(wait = TRUE)
# status now includes a data.table with detailed information on each simulation
sensi$status()
# print simulation errors
sensi$errors()
# extract a target simulation output value for each case to evaluate the
# sensitivity results
eng <- sen$tabular_data(table_name = "site and source energy",
column_name = "energy per total building area",
row_name = "total site energy")[, as.numeric(value)]
(result <- sensi$evaluate(eng))
# extract sensivitity data
attr(result, "data")
# plot
plot(result)
## End(Not run)
## ------------------------------------------------
## Method `SensitivityJob$print`
## ------------------------------------------------
## Not run:
sen$print()
## End(Not run)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.