{"id":16703693,"url":"https://github.com/hongyuanjia/epluspar","last_synced_at":"2026-03-13T19:02:50.684Z","repository":{"id":87185646,"uuid":"183550151","full_name":"hongyuanjia/epluspar","owner":"hongyuanjia","description":"Conduct parametric analysis on EnergyPlus models in R","archived":false,"fork":false,"pushed_at":"2025-11-26T13:42:41.000Z","size":1839,"stargazers_count":9,"open_issues_count":12,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-11-28T15:01:44.193Z","etag":null,"topics":["bayesian-calibration","energyplus","parametric","r","sensitivity-analysis"],"latest_commit_sha":null,"homepage":"https://hongyuanjia.github.io/epluspar","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hongyuanjia.png","metadata":{"files":{"readme":"README.Rmd","changelog":"NEWS.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-04-26T03:26:55.000Z","updated_at":"2024-07-25T10:50:28.000Z","dependencies_parsed_at":"2023-09-24T03:30:23.374Z","dependency_job_id":"ec6c4426-29db-44a0-97ac-bf9993ec1c18","html_url":"https://github.com/hongyuanjia/epluspar","commit_stats":{"total_commits":106,"total_committers":3,"mean_commits":"35.333333333333336","dds":"0.037735849056603765","last_synced_commit":"508c5bd74f2f2b7dc92fe9eab97ace9b3d89fb43"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hongyuanjia/epluspar","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hongyuanjia%2Fepluspar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hongyuanjia%2Fepluspar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hongyuanjia%2Fepluspar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hongyuanjia%2Fepluspar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hongyuanjia","download_url":"https://codeload.github.com/hongyuanjia/epluspar/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hongyuanjia%2Fepluspar/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30472986,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-13T17:15:31.527Z","status":"ssl_error","status_checked_at":"2026-03-13T17:15:22.394Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bayesian-calibration","energyplus","parametric","r","sensitivity-analysis"],"created_at":"2024-10-12T19:09:10.302Z","updated_at":"2026-03-13T19:02:50.664Z","avatar_url":"https://github.com/hongyuanjia.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\noutput:\n  github_document\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n```{r setup, include = FALSE}\nlibrary(epluspar)\nlibrary(knitr)\n\n# the default output hook\nhook_output = knitr::knit_hooks$get('output')\nknitr::knit_hooks$set(output = function(x, options) {\n  if (!is.null(n \u003c- options$out.lines)) {\n    x \u003c- unlist(strsplit(x, '\\n', fixed = TRUE))\n    if (length(x) \u003e n) {\n      # truncate the output\n      x \u003c- c(head(x, n), '....', '')\n    } else {\n      x \u003c- c(x, \"\")\n    }\n    x \u003c- paste(x, collapse = '\\n') # paste first n lines together\n  }\n  hook_output(x, options)\n})\n\nknitr::opts_knit$set(root.dir = tempdir())\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"README-\",\n  out.lines = 20\n)\n\n# Make sure the date is shown in English format not Chinese.\ninvisible(Sys.setlocale(category = \"LC_TIME\", locale = \"en_US.UTF-8\"))\n```\n\n# epluspar\nConduct sensitivity analysis and Bayesian calibration of EnergyPlus models.\n\n[![Travis-CI Build Status](https://api.travis-ci.com/ideas-lab-nus/epluspar.svg?token=1LqeFok1d6q5niBF8Hqr\u0026branch=master)](https://travis-ci.com/ideas-lab-nus/epluspar)\n[![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/epluspar)](https://cran.r-project.org/package=epluspar)\n\n## Installation\n\nCurrently, epluspar is not on CRAN. You can install the development version from\nGitHub.\n\n```{r gh-installation, eval = FALSE}\ninstall.packages(\"epluspar\", repos = \"https://hongyuanjia.r-universe.dev\")\n```\n\n\u003c!-- TOC GFM --\u003e\n\n* [Sensitivity Analysis](#sensitivity-analysis)\n    * [Basic workflow](#basic-workflow)\n    * [Examples](#examples)\n* [Bayesian Calibration](#bayesian-calibration)\n    * [Basic workflow](#basic-workflow-1)\n    * [Examples](#examples-1)\n        * [Get RDD and MDD](#get-rdd-and-mdd)\n        * [Setting Input and Output Variables](#setting-input-and-output-variables)\n        * [Adding Parameters to Calibrate](#adding-parameters-to-calibrate)\n        * [Getting Sample Values and Parametric Models](#getting-sample-values-and-parametric-models)\n        * [Run simulations and gather data](#run-simulations-and-gather-data)\n        * [Specify Measured Data](#specify-measured-data)\n        * [Specify Input Data for Stan](#specify-input-data-for-stan)\n        * [Get Stan file](#get-stan-file)\n        * [Run Bayesian Calibration Using Stan](#run-bayesian-calibration-using-stan)\n\n\u003c!-- /TOC --\u003e\n\n## Sensitivity Analysis\n\n### Basic workflow\n\nThe basic workflow is basically:\n\n1. Adding parameters for sensitivity analysis using `$param()` or\n   `$apply_measure()`.\n1. Check parameter sampled values and generated parametric models using\n   `$samples()` and `$models()` respectively.\n1. Run EnergyPlus simulations in parallel using `$run()`.\n1. Gather EnergyPlus simulated data using `$report_data()` or `$tabular_data()`.\n1. Evaluate parameter sensitivity using `$evaluate()`.\n\n### Examples\n\nCreate a `SensitivityJob` object:\n\n```{r}\n# use an example file from EnergyPlus v8.8 for demonstration here\npath_idf \u003c- file.path(eplusr::eplus_config(8.8)$dir, \"ExampleFiles\", \"5Zone_Transformer.idf\")\npath_epw \u003c- file.path(eplusr::eplus_config(8.8)$dir, \"WeatherData\", \"USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw\")\n\n# create a `SensitivityJob` class which inheris from eplusr::ParametricJob class\nsen \u003c- sensi_job(path_idf, path_epw)\n```\n\nSet sensitivity parameters using `$param()` or `$apply_measure()`.\n\n* Using `$param()`\n\n```{r, eval = FALSE}\n# set parameter using similar syntax to `Idf$set()` in eplusr\nsen$param(\n    # For adding a single object field as parameter\n    # Syntax: Object = list(Field = c(Min, Max, Levels))\n    `Supply Fan 1` = list(Fan_Total_Efficiency = c(0.1, 1.0, 5)),\n\n    # For adding a class field as parameter\n    Material := list(\n        Thickness = c(min = 0.01, max = 0.08, levels = 5),\n        Conductivity = c(min = 0.01, max = 0.6, levels = 6)\n    ),\n\n    # use `.names` to give names to each parameter\n    .names = c(\"efficiency\", \"thickness\", \"conductivity\"),\n\n    # See `r` and `grid_jump` in `sensitivity::morris`\n    .r = 8, .grid_jump = 1\n)\n```\n\n* Using `$apply_measure()`\n\n```{r}\n# first define a \"measure\"\nmy_actions \u003c- function (idf, efficiency, thickness, conducitivy) {\n    idf$set(\n        `Supply Fan 1` = list(Fan_Total_Efficiency = efficiency),\n        Material := list(Thickness = thickness, Conductivity = conducitivy)\n    )\n\n    idf\n}\n\n# then apply that measure with parameter space definitions as function arguments\nsen$apply_measure(my_actions,\n    efficiency = c(0.1, 1.0, 5),\n    thickness = c(0.01, 0.08, 5),\n    conducitivy = c(0.1, 0.6, 6),\n    .r = 8, .grid_jump = 1\n)\n```\n\nGet samples\n\n```{r}\nsen$samples()\n```\n\nRun simulations and calculate statistic indicators\n\n```{r}\n# run simulations in temporary directory\nsen$run(dir = tempdir(), echo = FALSE)\n\n# extract output\n# here is just am example\neng \u003c- sen$tabular_data(table_name = \"site and source energy\",\n    column_name = \"energy per total building area\",\n    row_name = \"total site energy\")[, as.numeric(value)]\n\n# calculate sensitivity\n(result \u003c- sen$evaluate(eng))\n\n# extract data\nattr(result, \"data\")\n```\n\nPlot\n\n```{r get-started, fig.path = \"man/figures/\"}\n# plot\nplot(result)\n```\n\n## Bayesian Calibration\n\n### Basic workflow\n\n1. Setting input and output variables using `$input()` and `$output()`\n   respectively.\n   Input variables should be variables listed in RDD while output variables\n   should be variables listed in RDD and MDD.\n1. Adding parameters to calibrate using `$param()` or `$apply_measure()`.\n1. Check parameter sampled values and generated parametric models using\n   `$samples()` and `$models()` respectively.\n1. Run EnergyPlus simulations in parallel using `$eplus_run()`.\n1. Gather simulated data of input and output parameters using `$data_sim()`.\n1. Specify field measured data of input and output parameters using\n   `$data_field()`.\n1.  Specify field measured data of input and output parameters using `$data_field()`.\n1. Specify input data for Stan for Bayesian calibration using `$data_bc()`.\n1. Run bayesian calibration and get predictions using stan using `$stan_run()`.\n\n### Examples\n\nCreate a `BayesCalibJob` object:\n\n```{r}\n# use an example file from EnergyPlus v8.8 for demonstration here\npath_idf \u003c- file.path(eplusr::eplus_config(8.8)$dir, \"ExampleFiles\", \"RefBldgLargeOfficeNew2004_Chicago.idf\")\npath_epw \u003c- file.path(eplusr::eplus_config(8.8)$dir, \"WeatherData\", \"USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw\")\n\n# create a `SensitivityJob` class which inherits from eplusr::ParametricJob class\nbc \u003c- bayes_job(path_idf, path_epw)\n```\n\n#### Get RDD and MDD\n\n`$read_rdd()` and `$read_mdd()` can be used to get RDD and MDD for current seed\nmodel.\n\n```{r}\n(rdd \u003c- bc$read_rdd())\n(mdd \u003c- bc$read_mdd())\n```\n\n#### Setting Input and Output Variables\n\nInput variables and output variables can be set by using `$input()` and\n`$output()`, respectively. For `$input()`, only variables listed in RDD are\nsupported. For `$output()`, variables listed in RDD and MDD are both supported.\n\nBy default, they are all empty and `$input()`, `$output()` will return `NULL`.\n\n```{r}\nbc$input()\nbc$output()\nbc$models()\n```\n\nYou can specify input and output parameters using `RddFile`, `MddFile` and\ndata.frames.\n\n```{r}\n# using RDD and MDD\nbc$input(rdd[1:3])\nbc$output(mdd[1])\n\n# using data.frame\nbc$input(eplusr::rdd_to_load(rdd[1:3]))\nbc$output(eplusr::mdd_to_load(mdd[1]))\n```\n\nYou can set `append` to `NULL` to remove all existing input and output\nparameters.\n\n```{r}\nbc$input(append = NULL)\nbc$output(append = NULL)\n```\n\nYou can also directly specify variable names:\n\n```{r}\nbc$input(\"CoolSys1 Chiller 1\", paste(\"chiller evaporator\", c(\"inlet temperature\", \"outlet temperature\", \"mass flow rate\")), \"hourly\")\nbc$output(\"CoolSys1 Chiller 1\", \"chiller electric power\", \"hourly\")\n```\n\nNote that variable cannot be set as both an input and output variable.\n\n```{r, error = TRUE}\nbc$output(\"CoolSys1 Chiller 1\", name = \"chiller evaporator inlet temperature\", reporting_frequency = \"hourly\")\n```\n\nAlso, note that input and output variables should have the same reporting\nfrequency.\n\n```{r, error = TRUE}\nbc$output(mdd[1], reporting_frequency = \"daily\")\n```\n\nFor `$output()`, both variables in RDD and MDD are supported. However, for\n`$input()`, only variables in RDD are allowed.\n\n#### Adding Parameters to Calibrate\n\nSimilarly like `SensitivityJob`, parameters can be added using either `$param()`\nor `$apply_measure()`.\n\nHere use `$param()` for demonstration. Basically there are 3 format of defining\na parameter:\n\n* `object = list(field1 = c(min, max), field2 = c(min, max), ...)`\n\n  This is the basic format. `field1` and `field2` in `object` will be added as\n  two different parameters, with minimum and maximum value specified as `min`\n  and `max`.\n\n* `class := list(field1 = c(min, max), field2 = c(min, max), ...)`\n\n  This is useful when you want to treat `field1` and `field2` in all objects in\n  `class` as two different parameters. Please note the use of special notion of\n  `:=` instead of `=`.\n\n* `.(objects) := list(field1 = c(min, max), field2 = c(min, max), ...)`\n\n  Sometimes you may not want to treat a field in all objects in a class but only\n  a subset of objects. You can use a special notation on the left hand side\n  `.()`. In the parentheses can be object names or IDs.\n\n```{r}\nbc$param(\n    `CoolSys1 Chiller 1` = list(reference_cop = c(4, 6), reference_capacity = c(2.5e6, 3.0e6)),\n    .names = c(\"cop1\", \"cap1\"), .num_sim = 5\n)\n```\n\n#### Getting Sample Values and Parametric Models\n\nParameter values can be retrieved using `$samples()`.\n\n```{r}\nbc$samples()\n```\n\nGenerated `Idf`s can be retrieved using `$models()`.\n\n```{r}\nnames(bc$models())\n```\n\n#### Run simulations and gather data\n\n`$eplus_run()` runs all parametric models in parallel. Parameter `run_period`\ncan be given to insert a new `RunPeriod` object. In this case, all existing\n`RunPeriod` objects in the seed model will be commented out.\n\n```{r}\nbc$eplus_run(dir = tempdir(), run_period = list(\"example\", 7, 1, 7, 3), echo = FALSE)\n```\n\n`$data_sim()` returns a `data.table` (when `merge` is `TRUE`) or a list of 2\n`data.table` (when `merge` is `FALSE`) which contains the simulated data of\ninput and output parameters. These data will be stored internally and used\nduring Bayesian calibration using Stan.\n\nThe `resolution` parameter can be used to specify the time resolution of\nreturned data. Note that input time resolution cannot be smaller than the\nreporting frequency, otherwise an error will be issued.\n\n```{r, error = TRUE}\nbc$data_sim(\"1 min\")\n```\n\n```{r}\nbc$data_sim(\"6 hour\")\n```\n\n#### Specify Measured Data\n\n`$data_field()` takes a `data.frame` of measured value of output parameters and\nreturns a list of `data.table`s which contains the measured value of input and\noutput parameters, and newly measured value of input if applicable.\n\nFor input parameters, the values of simulation data for the first case are\ndirectly used as the measured values.\n\nFor demonstration, we use the seed model to generate fake measured output data.\n\n```{r}\n# clone the seed model\nseed \u003c- bc$seed()$clone()\n# remove existing RunPeriod objects\nseed$RunPeriod \u003c- NULL\n# set run period as the same as in `$eplus_run()`\nseed$add(RunPeriod = list(\"test\", 7, 1, 7, 3))\nseed$SimulationControl$set(\n    `Run Simulation for Sizing Periods` = \"No\",\n    `Run Simulation for Weather File Run Periods` = \"Yes\"\n)\n# save the model to tempdir\nseed$save(tempfile(fileext = \".idf\"))\n# run\njob \u003c- seed$run(bc$weather(), echo = FALSE)\n# get output data\nfan_power \u003c- epluspar:::report_dt_aggregate(job$report_data(name = bc$output()$variable_name, all = TRUE, day_type = \"normalday\"), \"6 hour\")\nfan_power \u003c- epluspar:::report_dt_to_wide(fan_power)\n# add Gaussian noice\nfan_power \u003c- fan_power[, -\"Date/Time\"][\n    , lapply(.SD, function (x) x + rnorm(length(x), sd = 0.05 * sd(x)))][\n    , lapply(.SD, function (x) {x[x \u003c 0] \u003c- 0; x})\n    ]\n\n# set field data\nbc$data_field(fan_power)\n```\n\n#### Specify Input Data for Stan\n\n`$data_bc()` takes a list of field data and simulated data, and returns a\nlist that contains data input for Bayesian calibration using the Stan model\n\n* `n`: Number of measured parameter observations.\n* `m`: Number of simulated observations.\n* `p`: Number of input parameters.\n* `q`: Number of calibration parameters.\n* `yf`: Data of measured output after z-score standardization using data of\n  simulated output.\n* `yc`: Data of simulated output after z-score standardization.\n* `xf`: Data of measured input after min-max normalization.\n* `xc`: Data of simulated input after min-max normalization.\n* `tc`: Data of calibration parameters after min-max normalization.\n\n```{r}\nstr(bc$data_bc())\n```\n\nYou can also supply your own field data and simulated data and using\n`$data_bc()` to construct the input for the Stan model. Input `data_field` and\n`data_sim` should have the same structure as the output from `$data_field()` and\n`$data_sim()`. If `data_field` and `data_sim` is not specified, the output from\n`$data_field()` and `$data_sim()` will be used.\n\n#### Get Stan file\n\nYou can save the internal Stan code using `$stan_file()`. If no path is\nspecified, a character vector that contains the stan code will be returned.\n\n```{r, out.lines = 20}\nbc$stan_file()\n```\n\n#### Run Bayesian Calibration Using Stan\n\nYou can run Bayesian calibration using Stan using `$stan_run()`.\n\nIf `data` argument is not specified, the output of `$data_bc()` is directly\nused.\n\n```{r, eval = FALSE}\noptions(mc.cores = parallel::detectCores())\nbc$stan_run(iter = 300, chains = 3)\n```\n\nInstead of using builtin Stan model, you can also provide your own Stan code\nusing `file` argument.\n\n```{r, eval = FALSE}\nbc$stan_run(file = bc$stan_file(tempfile(fileext = \".stan\")), iter = 300, chains = 3)\n```\n\nYou can also use custom data set\n\n```{r}\nres \u003c- bc$stan_run(data = bc$data_bc(), iter = 300, chains = 3)\n```\n\nThe stan model is store in `fit`\n\n```{r stan, fig.path = \"man/figures/\"}\nrstan::stan_trace(res$fit)\nrstan::stan_hist(res$fit)\n```\n\nThe predicted values is stored in `y_pred`.\n\n```{r}\nstr(res$y_pred)\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhongyuanjia%2Fepluspar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhongyuanjia%2Fepluspar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhongyuanjia%2Fepluspar/lists"}