Skip to contents

Introduction to quantrr

Source: vignettes/quantrr.Rmd
quantrr.Rmd

quantrr is a streamlined, opinionated, “risk quant on rails” tool designed to make it easy to get started with quantifying risk using R, first presented as a demo in my 2024 SIRAcon talk, “UnFAIR: Simplifying and Expanding Technology Risk Quantification.” quantrr includes functions and a report template that uses data from an Excel spreadsheet to forecast one or more risks related to a technology system, such as the risk of a cybersecurity breach and the risk of unplanned outages.

I originally wanted to name it “qrisk”, but that’s already trademarked.

quantrr can be installed as a standalone application (for novice users) or integrated into your R development workflow (for advanced users). A rendered version of the standalone sample report is available here.

Standalone

The “standalone” version of quantrr provides all the files needed to create reports using quantrr, and is intended for those who want to get started quickly, or are new to R and don’t have an existing development and publishing workflow.

Installing

To install the standalone version of quantrr:

  1. Install R. There are several ways to to this, but I recommend using the official binary distributions. Windows users will also need to install Rtools. R can be installed manually, using a package manager (Homebrew for macOS, Chocolatey for Windows), or with rig. I currently use rig as it supports installation of multiple versions of R concurrently, but don’t use pak (rig install release --without-pak) or the Posit Package Manager. Before that, I installed the official binaries with Homebrew (brew install --cask r).
  2. Install Quarto. Download and install the Quarto CLI. Quarto is used to generate the HTML report. (brew install quarto)
  3. Download and install the Lato font family. The Lato font is used in the plots in the report. (brew install font-lato)
  4. Download and extract the “standalone” directory from the quantrr GitHub repository. You may rename it if you like.
  5. Using the command line (Terminal on macOS, Command Prompt on Windows), navigate to the standalone directory, and run the command: Rscript setup.R to install the R packages needed to generate the report.

The standalone version contains an example analysis for the “Widget Management System”. If everything is correctly installed, running the following command in the standalone directory will generate and launch a website locally on your system:

quarto preview

Data Collection

Collect data using a copy of the widgetsys.xlsx spreadsheet. The reporting tool uses only two tabs, “Risks” and “Estimates”, all other tabs are ignored.

The Risks sheet is used for scoping the assessment, and has two columns:

  1. “Risk”, the short name of the risk, also used in the Estimates tab
  2. “Description”, the long description of the risk

There is no set limit on the number of risks, but each must be unique and there must be at least one risk.

The Estimates sheet is used for gathering estimates from Subject Matter Experts, and has 6 columns:

  1. “Risk”, the short name of the risk, which must match one of the risks in the Risk tab
  2. “Expert”, the name or identifier of the SME providing the estimate
  3. “Frequency (per year)”, the average number of times an event is expected to occur per year, used as the value of λ\lambda for the Poisson loss frequency distribution. Fractional values represent once every 1x\frac{1}{x} years; once every 4 years is 0.25.
  4. “Low (5%)”, the estimate of the low (5th percentile) value for a single loss event.
  5. “High (95%)”, the estimate of the high (95th percentile) value for a single loss event.
  6. “Most Likely”, the estimate of the median (50th percentile) value for a single loss event.

The Low and High values are used to calculate the parameters for the log-normal loss magnitude distribution, and the Most Likely is used as a check to see how close the estimates fit log-normal.

SMEs can provide estimates for one or more risks, and their estimates can be left blank. Typically this is because they have confidence in only the loss frequency or loss magnitude.

Reporting

To generate the report, copy or replace widgetsys.Rmd with an updated value for report_file, and appropriate text for the Environment Statement and Import sections. Generate and preview html using Quarto:

quarto render
quarto preview

For more information, see the Quarto documentation.

Integrated

The “integrated” version of quantrr consists of the quantrr package itself, and is intended for RStudio users who want to integrate it into their existing development and publishing workflow.

Installing

quantrr is not (yet) available on CRAN. You can install the development version of quantrr from GitHub using remotes:

# install.packages("remotes")
remotes::install_github("jabenninghoff/quantrr")

Or by using renv:

# install.packages("renv")
renv::install("jabenninghoff/quantrr")

quantrr includes common functions and an R Markdown template, “Risk Analysis Report”, that can be accessed in RStudio via File > New File > R Markdown… > From Template.

Data Collection

As noted above, use the widgetsys.xlsx spreadsheet as a template for data collection.

Reporting

The “Risk Analysis Report” template works as an R Notebook in RStudio, and can be published using any system that supports R Markdown and HTML widgets (for the dynamic plots using plotly). I publish to GitHub Pages using rdev.