Package 'reportbrick'

Title: Reporting package for BRICK
Description: This package contains BRICK-specific routines to report model results. The main functionality is to generate a mif-file from a given BRICK model run folder.
Authors: Robin Hasse [aut, cre] (ORCID: <https://orcid.org/0000-0003-1818-3186>), Ricarda Rosemann [aut] (ORCID: <https://orcid.org/0009-0006-5939-3197>)
Maintainer: Robin Hasse <[email protected]>
License: LGPL-3
Version: 0.17.0
Built: 2026-06-03 13:24:29 UTC
Source: https://github.com/pik-piam/reportbrick

Help Index

Add carrier dimension based on heating system technology

Description

Add carrier dimension based on heating system technology

Usage

.addCarrierDimension(v_stock, hsCarrier)

Arguments

v_stock

MagPIE object, BRICK variable
hsCarrier

data.frame, mapping between heating technology and energy carrier

Value

MagPIE object with additional carrier dimension

Author(s)

Robin Hasse

Aggregate

Description

Aggregate

Usage

.agg(x, agg, silent = TRUE)

Arguments

x

MagPIE object, BRICK object
agg

named vector of dimensions to aggregate.
silent

logical, suppress warnings and printing of dimension mapping

Value

aggregated MagPIE objects without sub dimensions in dim 3

Check if the tolerance is violated anywhere

Description

Check if the tolerance is violated anywhere

Usage

.checkForDeviation(stockBal, name, tol = 0.01)

Arguments

stockBal

data frame with evaluation of a stock balance equation
name

character, name/identifier of the stock balance equation
tol

numeric, tolerance to check the equation against

All Combinations of dimension elements

Description

All Combinations of dimension elements

Usage

.combinations(lst)

Arguments

lst

names list of dimension entries

Value

character vector with all combinations of the dimension elements each separated by .

Author(s)

Robin Hasse

Compute the mean value in a data frame

Description

Compute the mean value in a data frame

Usage

.computeAvg(df, rprt = "", valueName = "value", exclude = list())

Arguments

df

data frame, containing the data to be evaluated
rprt

character, column names for which the mean should be reported separately
valueName

character, name of the column containing the values to be manipulated
exclude

named list with entries to be excluded from the data. The name gives the column name from which the entries given by the value should be removed.

Value

data frame averages as value column

Compute the deviation to target data

Description

Compute the deviation to target data

Usage

.computeDeviation(df, dfTarget)

Arguments

df

data frame, containing data from calibration run
dfTarget

data frame, containing historical data as calibration target

Value

data frame where the value column contains the deviation from target data

Compute the sum of construction and renovation flow values

Description

Compute the sum of construction and renovation flow values

Usage

.computeFlowSum(flows, squareAndRoot = FALSE)

Arguments

flows

named list of data frames, each containing flow quantities. Entries need to include construction and at least one entry with renovation as part of the name.
squareAndRoot

logical, whether the square should be taken before summing and the root afterwards. This option should be active if we're summing up roots of summed squares.

Value

data frame with the sum in the value column

Compute the ratio of the squares for two data sets

Description

Compute the ratio of the squares for two data sets

Usage

.computeRatioSq(dfx, dfy, addSign = TRUE)

Arguments

dfx

data frame containing the data of the nominator
dfy

data frame containing the data of the denominator
addSign

logical indicating whether a heuristic sign of the squares should be computed

Value

data frame with squared ratio

Compute the relative deviation to calibration target data as the relative euclidean distance

Description

Compute the relative deviation to calibration target data as the relative euclidean distance

Usage

.computeRelDev(dfDev, dfTarget, tCalib, notInTargetGrp = NULL)

Arguments

dfDev

data frame, containing deviation between calibration result and target data
dfTarget

data frame or a list of one or two data frames, containing target data. The option to pass two data frames is used to combine construction and renovation flows. If two data frames are passed, the first one is assumed to be construction, the second renovation
tCalib

numerical/factor, calibration time periods to filter calibration target data
notInTargetGrp

character vector, pass columns that target data should not be grouped by when computing the sum of the squares, although they exist in the data

Value

data frame with relative deviation in value column

Compute the sum

Description

Compute the sum

Usage

.computeSum(df, rprt = "", exclude = list())

Arguments

df

data frame containing the data to be evaluated
rprt

character, column names for which the sum should be reported separately
exclude

named list with entries to be excluded from the data. The name gives the column name from which the entries given by the value should be removed.

Value

data frame with summed values

Compute the square root of the sum of the squares in a data frame

Description

Compute the square root of the sum of the squares in a data frame

Usage

.computeSumSq(df, tCalib, rprt = "", addSign = TRUE)

Arguments

df

data frame, containing the data to be evaluated
tCalib

numeric, time periods the model was calibrated on
rprt

character, column names for which the sum of the squares should be reported separately
addSign

logical indicating whether the heuristic sign of the square should be computed

Value

data frame with the square root of the sum of squares as value column

Construct dimension mapping (either aggregation or reporting) with explicit set elements for each dimension

Description

Construct dimension mapping (either aggregation or reporting) with explicit set elements for each dimension

Usage

.constructDimMapping(agg, rprt, brickSets, silent)

Arguments

agg

named vector of dimensions to aggregate
rprt

named vector of dimensions to report individually
brickSets

named list with definition of common set elements
silent

logical, suppress warnings and printing of dimension mapping

Value

nested named list with dimension mapping

Escape tag in curly brackets

Description

Escape tag in curly brackets

Usage

.embrace(tag)

Arguments

tag

character tag

Value

character, tag in curly brackets

Author(s)

Robin Hasse

Exclude data matching giving filter criteria from a data set

Description

Exclude data matching giving filter criteria from a data set

Usage

.excludeRows(data, exclude)

Arguments

data

data frame with the data set
exclude

named list with entries to be excluded from the data. The name gives the column name from which the entries given by the value should be removed.

Value

the given data set without the rows identified by the filter criteria

Extend dimensions of a data frame by adding NA entries, add variable name

Description

Extend dimensions of a data frame by adding NA entries, add variable name

Usage

.expandDims(df, varName, allSets)

Arguments

df

data frame to be extended
varName

character, variable name to be added
allSets

character, sets that need to be included as column names

Value

data frame

Find inconsistencies in set elements between reporting template and gdx

Description

Find inconsistencies in set elements between reporting template and gdx

Usage

.findInconsistenSetElements(brickSets, gdx)

Arguments

brickSets

character, BRICK reporting template
gdx

file path to a BRICK gdx

Value

named list of missing and surplus sets elements

Find all tags in name escaped in curly brackets

Description

Find all tags in name escaped in curly brackets

Usage

.findTags(name)

Arguments

name

character, variable name

Value

vector of tags in name, NULL if there are none

Get dimension names from stock and flow objects

Description

Gives the column names of a list of data frames except the first and the last one, i.e. qty and value.

Usage

.getDims(calibObj, removeDims = NULL)

Arguments

calibObj

list, calibration targets
removeDims

character, additional dimensions to be removed from the output

Value

character with dimension names

List any missing elements in any given dimension

Description

List any missing elements in any given dimension

Usage

.missingElements(x, dimLst)

Arguments

x

MagPIE object, BRICK object
dimLst

named vector, dimension ans names and elements as values

Value

vector of missing dimension elements in x

Read a symbol from several gdx files and combine in one data frame

Description

Read a symbol from several gdx files and combine in one data frame

Usage

.readGdxIter(
  gdx,
  symbol,
  maxIter,
  minIter = 0,
  asMagpie = TRUE,
  ttotFilter = NULL,
  replaceVar = FALSE,
  dims = NULL
)

Arguments

gdx

Path to gdx files; all gdx file names are assumed to be numbered and adhere to the structure: If gdx = <path/to/file/name.gdx, the function looks for <path/to/file/name_0.gdx>, <path/to/file/name_1.gdx>, ...
symbol

Symbol to be read from the gdxes
maxIter

Last iteration to be read
minIter

First iteration to be read
asMagpie

logical, convert to magpie object?
ttotFilter

numeric/factor, time periods to filter for
replaceVar

logical, replace column names bs and hs by bsr and hsr?
dims

character, containing the colum names expected for the object that is read in. Only required if the object does not exist to create replacement with NAs

Value

data frame of all results read in

Replace column names bs and hs by bsr and hsr

Description

Replace column names bs and hs by bsr and hsr

Usage

.replaceVarName(df)

Arguments

df

data frame

Value

data frame where column names have been replaced

select values from MAgPIE-obect

Description

This is a wrapper around magclass::mselect that also allows the selection of combinations of multiple dimensions.

Usage

.select(x, ...)

Arguments

x

MAgPIE object
...

entry selection. Combined dimensions have to be seperated with . for both the set names and the set elements.

Value

MAgPIE object containing only selected entries

Wrapper around setNames

Description

Wrapper around setNames

Usage

.setNames(object, nm)

Arguments

object

MAgPIE object
nm

a vector of names current names should be replaced with. If only one data element exists you can also set the name to NULL.

Value

NULL if object is NULL else object with manipulated names

Split dimension names

Description

Split each entry of a character vector and return one unnested character vector.

Usage

.split(x, split = "\\.")

Arguments

x

character vector
split

character used to split x

Value

character vector with each dimension as an own entry

Author(s)

Robin Hasse

Check the matching results for inconsistencies

Description

Check the matching results for inconsistencies

Usage

checkMatching(path, tol = 0.01)

Arguments

path

character, path to the matching result files
tol

numeric, absolute tolerance in million m2 against which to check the stock balance equations

Author(s)

Ricarda Rosemann

Read in GDX from BRICK and write *.mif reporting

Description

Read in all information from GDX file that was generated with BRICK and create the *.mif reporting

Usage

convGDX2MIF(
  gdx,
  tmpl = NULL,
  file = NULL,
  scenario = "default",
  t = NULL,
  silent = TRUE
)

Arguments

gdx

file path to a BRICK gdx
tmpl

character, BRICK reporting template. There has to be a brickSets mapping named with the same suffix: brickSets_<tmpl>.yaml
file

name of the mif file which will be written, if no name is provided a magpie object containing all the reporting information is returned
scenario

scenario name that is used in the *.mif reporting
t

numeric vector of reporting periods (years)
silent

boolean, suppress warnings and printing of dimension mapping

Author(s)

Robin Hasse

Crop MagPIE object to given periods and fill missing periods

Description

Crop MagPIE object to given periods and fill missing periods

Usage

extendPeriods(x, periods, fill = NA)

Arguments

x

MagPIE object
periods

numeric vector with target periods
fill

value to fill missing period values

Value

MagPIE object with given periods in temporal dimension

Author(s)

Robin Hasse

Render the BRICK calibration plotting routine

Description

Renders the file plotCalibration.Rmd to create the plots for the BRICK calibration

Usage

plotBRICKCalib(
  path = ".",
  cal = "BRICK_calibration_report.csv",
  outName = "",
  scenNames = NULL
)

Arguments

path

(named) character vector, path(s) to output directories. If several paths are given, the names can be used to pass short scenario names.
cal

character vector, name(s) of file(s) with calibration reporting results
outName

character, string added to the pdf file name and names of additionally saved plots
scenNames

character vector, scenario names for different paths. Needs to be specified if path is unnamed and contains more than one element.

Author(s)

Ricarda Rosemann

Matching reporting

Description

Plot the following matching reporting

  • comparison of the matching values and reference targets

  • share of initial heating systems thar have been removed over time

Usage

plotMatching(path, outputFolder = NULL)

plotMatchingComparison(path, outputFolder = NULL)

Arguments

path

character, path to the run
outputFolder

character, directory where output file is stored. If NULL, the plots folder inside the given path is used.

Value

file path to created output file

Author(s)

Robin Hasse

Read brickSets mapping

Description

This function creates an explicit named list with the elements of all BRICK dimensions and corresponding reporting names.

Usage

readBrickSets(tmpl = NULL)

Arguments

tmpl

character, BRICK reporting template

Value

named list with definition of common set elements

Author(s)

Robin Hasse

Read symbol from gams container

Description

Read symbol from gams container

Usage

readGdxSymbol(
  gdx,
  symbol,
  field = "level",
  asMagpie = NULL,
  stringAsFactor = TRUE,
  removeDescription = TRUE
)

Arguments

gdx

character, file path to GDX file
symbol

character, name of gams object
field

character, field to read (only relevant for variables)
asMagpie

boolean, return Magpie object. By default (NULL), variables are reported as mapgie and sets as data frames
stringAsFactor

logical, keep default factors from gams
removeDescription

logical, if TRUE, the description column of set records (element_text) is removed

Value

MagPIE object with data of symbol

Author(s)

Robin Hasse

Report aggregated quantities

Description

Report aggregated quantities

Usage

reportAgg(
  x,
  name,
  brickSets = readBrickSets(NULL),
  agg = NULL,
  rprt = NULL,
  silent = TRUE
)

Arguments

x

MagPIE object, BRICK object
name

character, name of reporting variable. reported dimensions passed with rprt have to be escaped with curly brackets.
brickSets

named list, BRICK reporting template
agg

named vector of dimensions to aggregate. Names are dimension names of x and values are either set elements or subsets of set elements to consider.
rprt

named vector of dimensions to report individually. Names are dimension names of x and values are either set elements or subsets of set elements to report.
silent

boolean, suppress warnings and printing of dimension mapping

Note

To consider specific combinations of dimensions in both agg or rprt, the combination can be given just like one dimension separated by ..

Author(s)

Robin Hasse

Report building Stock

Description

Report quantities describing the stock of buildings

Usage

reportBuildingStock(gdx, brickSets = NULL, silent = TRUE)

Arguments

gdx

gams transfer container of the BRICK GDX
brickSets

character, BRICK reporting template
silent

boolean, suppress warnings and printing of dimension mapping

Author(s)

Robin Hasse

Read in model results from calibration for each iteration, calculate deviation

Description

Read in model results from calibration for each iteration, calculate deviation

Usage

reportCalibration(gdx, flowTargets = TRUE)

Arguments

gdx

path to a gdx; it is assumed that for each iteration a gdx is present with this path and the iteration number inserted at the end.
flowTargets

logical, if set to FALSE, the function does not expect the presence of targets for the flows

Author(s)

Ricarda Rosemann

Report construction

Description

Report quantities describing the construction of new buildings

Usage

reportConstruction(gdx, brickSets = NULL, silent = TRUE)

Arguments

gdx

gams transfer container of the BRICK GDX
brickSets

character, BRICK reporting template
silent

boolean, suppress warnings and printing of dimension mapping

Author(s)

Robin Hasse

Report demolition

Description

Report quantities describing the demolition of buildings

Usage

reportDemolition(gdx, brickSets = NULL, silent = TRUE)

Arguments

gdx

gams transfer container of the BRICK GDX
brickSets

character, BRICK reporting template
silent

boolean, suppress warnings and printing of dimension mapping

Author(s)

Robin Hasse

Report emissions

Description

Report CO2 emissions from space heating

Usage

reportEmissions(gdx, brickSets = NULL, silent = TRUE)

Arguments

gdx

gams transfer container of the BRICK GDX
brickSets

character, BRICK reporting template
silent

boolean, suppress warnings and printing of dimension mapping

Author(s)

Robin Hasse

Report energy demand

Description

Report final and useful energy demand for space heating

Usage

reportEnergy(gdx, brickSets = NULL, silent = TRUE)

Arguments

gdx

gams transfer container of the BRICK GDX
brickSets

character, BRICK reporting template
silent

boolean, suppress warnings and printing of dimension mapping

Author(s)

Robin Hasse

Report renovation of heating systems

Description

Report quantities describing the renovation of heating systems

Usage

reportRenovation(
  gdx,
  renovatedObj = c("bs", "hs"),
  brickSets = NULL,
  silent = TRUE
)

Arguments

gdx

gams transfer container of the BRICK GDX
renovatedObj

character, renovation measure considered, needs to be either bs (building shell) or hs (heating system).
brickSets

character, BRICK reporting template
silent

boolean, suppress warnings and printing of dimension mapping

Author(s)

Ricarda Rosemann

Plot comparison between matching references and model values

Description

Create stacked bar plots to verify matching accuracy

Usage

showMatchingComparison(path, showTitles = TRUE)

Arguments

path

character, path to the run
showTitles

logical, if TRUE, the references name and basic variable name are shown as title in each plot. No titles otherwise.

Value

named list of ggplot2 objects

Author(s)

Robin Hasse

Plot share of initial heating systems removed

Description

Show the share of heating systems standing in the initial time step that have been removed over time. The tunnel marks the allowed space between the lower and upper limit defined in p_shareRenHSinit and the solid line shows the value eventually chosen in the matching by v_shareRenHSinit. The dashed line shows the extrapolation of this result to future time steps that go beyond the temporal scope of the matching. The dotted line marks the central value that results from an evenly distributed installation up until the initial time steps. The central value is not considered in the optimisation but used as supporting point in the extrapolation.

Usage

showMatchingStandingStock(path)

Arguments

path

character, path to the run

Value

named list of ggplot2 objects

Author(s)

Robin Hasse

Plot Sankey diagram

Description

Visualise transitions from one state to another. This plot helps to follow the exact renovation flows, though it quickly gets very complex.

Usage

showSankey(
  path,
  fill = c("bs", "hs"),
  showOnlyRenovation = FALSE,
  filterData = NULL,
  maxPeriodsInRow = NULL,
  save = TRUE
)

Arguments

path

character, path to the run
fill

character, dimension mapped to fill, either "bs" (building shell) or "hs" (heating system).
showOnlyRenovation

logical, if FALSE, the stock and all flows are shown including untouched buildings. If TRUE, only renovation activities are shown. This is helpful to better observe the renovation decision, especially with short time steps where renovation only affects a small share of the stock.
filterData

named list to filter the data before plotting
maxPeriodsInRow

maximum number of time steps to plot in one row. If there is more data, it is broken across multiple lines. If NULL, all data is shown in one line.
save

control how the plot should be saved:

  • 'TRUE': plot is saved in plots folder of run path

  • 'FALSE': plot is not saved (but always returned invisibly)

  • character: plot is saved in given directory

Author(s)

Robin Hasse