Rename default data sets to the mythical MetroCare Hospital

Author: davidski

NEWS.md

@@ -50,6 +50,9 @@ contain their initial quantitative inputs. These users may also use
   Evaluator to new models.
 
 ## Other Changes
+* Renamed the default sample dataset to the hypothetical MetroCare Hospital. 
+  The default sets now all consistently use the `mc_` prefix to distinguish 
+  them from parameter names.
 * Deprecated `load_data()`. Use `read_qualitative_inputs()` or 
   `read_quantitative_inputs()` as appropriate.
 * Re-export the pipe operator `%>%`

R/common_graphs.R

@@ -50,8 +50,8 @@ theme_evaluator <- function(base_family = "BentonSansRE") {
 #' @return A ggplot object.
 #' @export
 #' @examples
-#' data(domain_summary)
-#' generate_heatmap(domain_summary)
+#' data(mc_domain_summary)
+#' generate_heatmap(mc_domain_summary)
 generate_heatmap <- function(domain_summary) {
   dat <- domain_summary %>% dplyr::arrange(.data$domain_id) %>%
     dplyr::mutate(full_label = paste0(.data$domain_id, "\n",
@@ -86,8 +86,8 @@ generate_heatmap <- function(domain_summary) {
 #' @return A ggplot object.
 #' @export
 #' @examples
-#' data(simulation_results)
-#' generate_scatterplot(simulation_results, scenario_id = "50")
+#' data(mc_simulation_results)
+#' generate_scatterplot(mc_simulation_results, scenario_id = "50")
 generate_scatterplot <- function(simulation_results, scenario_id){
   all_results <- unnest(simulation_results, .data$results)
   dat <- all_results[all_results$scenario_id == scenario_id, ]
@@ -123,8 +123,8 @@ generate_scatterplot <- function(simulation_results, scenario_id){
 #' @return ggplot object.
 #' @export
 #' @examples
-#' data(domain_summary)
-#' generate_event_outcomes_plot(domain_summary)
+#' data(mc_domain_summary)
+#' generate_event_outcomes_plot(mc_domain_summary)
 generate_event_outcomes_plot <- function(domain_summary, domain_id = domain_id) {
   domain_id <- rlang::ensym(domain_id)
   all_domains <- domain_summary

R/data.R

@@ -1,6 +1,11 @@
 #' Capabilities
 #'
-#' A qualitative dataset of sample capabilities and qualitative level of effectiveness.
+#' A sample set of capabilities for the demonstration (and artificial)
+#' MetroCare information security program.
+#'
+#' @source
+#' This is hypothetical information. Any similarity to any other
+#' entitiy is completely coincidental.
 #'
 #' @format
 #' \describe{
@@ -9,12 +14,16 @@
 #'   \item{capability}{full text summary of the capability}
 #'   \item{diff}{qualitative label of control effectiveness}
 #' }
-"capabilities"
+"mc_capabilities"
 
 #' Qualitative to quantitative mappings
 #'
-#' A dataset of sample mappings from qualitative labels to quantitative
-#'   distribution parameters.
+#' A sample set of qualitative to quantitative mappings for the demonstration
+#' (and artificial) MetroCare information security program.
+#'
+#' @source
+#' This is hypothetical information. Any similarity to any other
+#' entitiy is completely coincidental.
 #'
 #' @format
 #' \describe{
@@ -25,23 +34,33 @@
 #'   \item{h}{BetaPERT high value}
 #'   \item{conf}{BetaPERT confidence value}
 #' }
-"mappings"
+"mc_mappings"
 
 #' Domain mappings
 #'
-#' A dataset of domains and domain IDs.
+#' A sample set of the domains for the demonstration (and artificial)
+#' MetroCare information security program.
+#'
+#' @source
+#' This is hypothetical information. Any similarity to any other
+#' entitiy is completely coincidental.
 #'
 #' @format
 #' \describe{
 #'   \item{domain_id}{abbreviated name of the domain}
 #'   \item{domain}{full title of the domain}
 #' }
-"domains"
+"mc_domains"
 
 #' Domain-level risk summary
 #'
-#' A dataset of quantified information security risk, summarized at the
-#'   domain level.
+#' A sample set of quantified information security risk exposure, summarized
+#' at the domain level, for the demonstration (and artificial)
+#' MetroCare information security program.
+#'
+#' @source
+#' This is hypothetical information. Any similarity to any other
+#' entitiy is completely coincidental.
 #'
 #' @format
 #' \describe{
@@ -62,12 +81,17 @@
 #'   \item{mean_diff_exceedance}{mean difficulty exceedance}
 #'   \item{mean_vuln}{mean vulnerability of the scenario}
 #' }
-"domain_summary"
+"mc_domain_summary"
 
 #' Scenario-level risk summary
 #'
-#' A dataset of quantified information security risk, summarized at the
-#'   scenario level.
+#' A sample set of quantified information security risk exposure, summarized
+#' at the scenario level, for the demonstration (and artificial)
+#' MetroCare information security program.
+#'
+#' @source
+#' This is hypothetical information. Any similarity to any other
+#' entitiy is completely coincidental.
 #'
 #' @format
 #' \describe{
@@ -90,10 +114,17 @@
 #'   \item{mean_diff_exceedance}{mean difficulty exceedance}
 #'   \item{mean_vuln}{mean vulnerability of the scenario}
 #' }
-"scenario_summary"
+"mc_scenario_summary"
 
 #' Quantified information risk scenarios
 #'
+#' A sample set of quantified information security risk scenarios for the
+#' demonstration (and artificial) MetroCare information security program.
+#'
+#' @source
+#' This is hypothetical information. Any similarity to any other
+#' entitiy is completely coincidental.
+#'
 #' @format
 #' A dataset of quantified risk scenarios, with parameters
 #'   describing the distribution of each input.
@@ -105,14 +136,19 @@
 #'   \item{domain_id}{domain id}
 #'   \item{control_descriptons}{named list of the text description of controls involved}
 #'   \item{scenario}{\code{\link{tidyrisk_scenario}} objects}
-
 #' }
-"quantitative_scenarios"
+"mc_quantitative_scenarios"
 
 #' Qualitative information security risk scenarios
 #'
-#' A dataset of qualitative information security risk scenarios.
+#' A sample set of qualitative information security risk scenarios for the
+#' demonstration (and artificial) MetroCare information security program.
 #'
+#' No connection with any other similarly named entity is intended or implied.
+#'
+#' @source
+#' This is hypothetical information. Any similarity to any other
+#' entitiy is completely coincidental.
 #' @format
 #' \describe{
 #'   \item{scenario_id}{id of the scenario, primary key}
@@ -124,17 +160,22 @@
 #'   \item{domain_id}{domain id}
 #'   \item{controls}{comma delimited list of controls ids}
 #' }
-"qualitative_scenarios"
+"mc_qualitative_scenarios"
 
-#' Information security risk simulation results
+#' Simulation results
+#'
+#' A sample set of information security risk scenario simulation results
+#' for the demonstration (and artificial) MetroCare information security
+#' program.
 #'
-#' A dataset containing the full results of sample Monte Carlo
-#'   simulations of information security risk scenarios.
+#' @source
+#' This is hypothetical information. Any similarity to any other
+#' entitiy is completely coincidental.
 #'
 #' @format
 #' \describe{
 #'   \item{scenario_id}{id of the scenario}
 #'   \item{domain_id}{domain id}
 #'   \item{results}{nested data frame of simulation results for the scenario}
 #' }
-"simulation_results"
+"mc_simulation_results"

R/encode.R

@@ -16,8 +16,8 @@
 #' @export
 #' @return A dataframe of capabilities for the scenario and parameters for quantified simulation.
 #' @examples
-#' data(qualitative_scenarios, capabilities, mappings)
-#' encode_scenarios(qualitative_scenarios, capabilities, mappings)
+#' data(mc_qualitative_scenarios, mc_capabilities, mc_mappings)
+#' encode_scenarios(mc_qualitative_scenarios, mc_capabilities, mc_mappings)
 encode_scenarios <- function(scenarios, capabilities, mappings) {
   # fetch DIFF params
   scenarios$diff_params <- purrr::map(scenarios$controls,
@@ -85,9 +85,9 @@ encode_scenarios <- function(scenarios, capabilities, mappings) {
 #' @return A named list of control IDs and descriptions.
 #' @export
 #' @examples
-#' data(capabilities)
+#' data(mc_capabilities)
 #' capability_ids <- c("1, 3")
-#' derive_control_key(capability_ids, capabilities)
+#' derive_control_key(capability_ids, mc_capabilities)
 derive_control_key <- function(capability_ids, capabilities) {
   control_list <- stringi::stri_split_fixed(capability_ids, ", ") %>% unlist()
 
@@ -118,11 +118,11 @@ derive_control_key <- function(capability_ids, capabilities) {
 #'   applicable to a given scenario.
 #' @export
 #' @examples
-#' data(capabilities)
+#' data(mc_capabilities)
 #' capability_ids <- c("1, 3")
 #' mappings <- data.frame(type = "diff", label = "1 - Immature", l = 0, ml = 2, h = 10,
 #'                        conf = 3, stringsAsFactors = FALSE)
-#' derive_controls(capability_ids, capabilities, mappings)
+#' derive_controls(capability_ids, mc_capabilities, mappings)
 derive_controls <- function(capability_ids, capabilities, mappings) {
   control_list <- stringi::stri_split_fixed(capability_ids, ", ") %>% unlist()
 

R/import.R

@@ -54,8 +54,8 @@ import_spreadsheet <- function(survey_file = system.file("survey",
 #' @export
 #' @return Extracted qualitative scenarios as a dataframe.
 #' @examples
-#' data(domains)
-#' import_scenarios(domains = domains)
+#' data(mc_domains)
+#' import_scenarios(domains = mc_domains)
 import_scenarios <- function(survey_file = NULL, domains = NULL) {
 
   survey_file <- if (is.null(survey_file)) {
@@ -68,8 +68,9 @@ import_scenarios <- function(survey_file = NULL, domains = NULL) {
 
   # use default domains if none supplied
   domains <- if (is.null(domains)) {
-    utils::data(domains, package = "evaluator", envir = environment())
-    domains
+    env <- new.env()
+    utils::data("mc_domains", package = "evaluator", envir = env)
+    get("mc_domains", envir = env)
   } else {domains}
 
   # scenarios begin with the list of domains
@@ -111,8 +112,8 @@ import_scenarios <- function(survey_file = NULL, domains = NULL) {
 #' @return Extracted capabilities as a dataframe.
 #' @inheritParams import_scenarios
 #' @examples
-#' data(domains)
-#' import_capabilities(domains = domains)
+#' data(mc_domains)
+#' import_capabilities(domains = mc_domains)
 import_capabilities <- function(survey_file = NULL, domains = NULL){
 
   survey_file <- if (is.null(survey_file)) {
@@ -125,8 +126,9 @@ import_capabilities <- function(survey_file = NULL, domains = NULL){
 
   # use default domains if none supplied
   domains <- if (is.null(domains)) {
-    utils::data(domains, package = "evaluator", envir = environment())
-    domains
+    env <- new.env()
+    utils::data("mc_domains", package = "evaluator", envir = env)
+    get("mc_domains", env)
   } else {domains}
 
   raw_domains <- domains %>%

R/load_data.R

@@ -1,4 +1,4 @@
-#' Create a directory structure for risk analysis, prepopulate with templates
+#' Create a directory structure for risk analysis, pre-populated with templates
 #'
 #' Copy the sample files into an `inputs` subdirectory. This makes the starter
 #'   files available for customizing and data collection. The `inputs`

R/openfair.R

@@ -281,8 +281,8 @@ select_loss_opportunities <- function(tc, diff, n = NULL, ...) {
 #' @family OpenFAIR helpers
 #' @export
 #' @examples
-#' data(quantitative_scenarios)
-#' params <- quantitative_scenarios[[1, "scenario"]]$parameters
+#' data(mc_quantitative_scenarios)
+#' params <- mc_quantitative_scenarios[[1, "scenario"]]$parameters
 #' openfair_tef_tc_diff_lm(params$tef, params$tc, params$diff, params$lm, 10)
 openfair_tef_tc_diff_lm <- function(tef, tc, diff, lm, n = 10^4, verbose = FALSE) {
 

R/simulate.R

@@ -16,8 +16,8 @@
 #' @export
 #' @return Dataframe of results.
 #' @examples
-#' data(quantitative_scenarios)
-#' run_simulation(quantitative_scenarios[[1, "scenario"]], 10)
+#' data(mc_quantitative_scenarios)
+#' run_simulation(mc_quantitative_scenarios[[1, "scenario"]], 10)
 run_simulation <- function(scenario, iterations = 10000L,
                             ale_maximum = NULL,
                             verbose = FALSE, simulation_count = NULL) {
@@ -84,10 +84,10 @@ run_simulation <- function(scenario, iterations = 10000L,
 #' @export
 #' @examples
 #' # fetch three scenarios for this example
-#' data(quantitative_scenarios)
-#' scenario_a <- quantitative_scenarios[[1, "scenario"]]
-#' scenario_b <- quantitative_scenarios[[2, "scenario"]]
-#' scenario_c <- quantitative_scenarios[[3, "scenario"]]
+#' data(mc_quantitative_scenarios)
+#' scenario_a <- mc_quantitative_scenarios[[1, "scenario"]]
+#' scenario_b <- mc_quantitative_scenarios[[2, "scenario"]]
+#' scenario_c <- mc_quantitative_scenarios[[3, "scenario"]]
 #' run_simulations(scenario_a, scenario_b, scenario_c, iterations = 10)
 #'
 run_simulations <- function(scenario, ..., iterations = 10000L,

R/summarize.R

@@ -20,9 +20,9 @@
 #' @export
 #' @return Dataframe of summary statistics.
 #' @examples
-#' data(simulation_results)
+#' data(mc_simulation_results)
 #' # summarize a single scenario
-#' summarize_scenario(simulation_results[[1, "results"]])
+#' summarize_scenario(mc_simulation_results[[1, "results"]])
 #'
 summarize_scenario <- function(simulation_results) {
   scenario_summary <- simulation_results %>%
@@ -60,8 +60,8 @@ summarize_scenario <- function(simulation_results) {
 #' @rdname summarize_scenario
 #' @examples
 #' # summarize all scenarios in a data frame
-#' data(simulation_results)
-#' summarize_scenarios(simulation_results)
+#' data(mc_simulation_results)
+#' summarize_scenarios(mc_simulation_results)
 summarize_scenarios <- function(simulation_results) {
   dplyr::mutate(simulation_results, summary = purrr::map(.data$results, summarize_scenario)) %>%
     tidyr::unnest(summary)
@@ -91,8 +91,8 @@ summarize_scenarios <- function(simulation_results) {
 #' @export
 #' @return Dataframe.
 #' @examples
-#' data(simulation_results)
-#' summarize_iterations(simulation_results$results)
+#' data(mc_simulation_results)
+#' summarize_iterations(mc_simulation_results$results)
 summarize_iterations <- function(simulation_results, ..., .key = "iteration") {
 
   key <- rlang::ensym(.key)
@@ -144,8 +144,8 @@ summarize_iterations <- function(simulation_results, ..., .key = "iteration") {
 #' @return Simulation results summarized across domains.
 #' @examples
 #' \dontrun{
-#' data(simulation_results)
-#' summarize_domains(simulation_results)
+#' data(mc_simulation_results)
+#' summarize_domains(mc_simulation_results)
 #' }
 summarize_domains <- function(simulation_results, domain_variable = "domain_id") {
   domain_variable <- rlang::ensym(domain_variable)
@@ -194,9 +194,8 @@ summarize_domains <- function(simulation_results, domain_variable = "domain_id")
 #' @return Tibble with paths to the created data files.
 #' @examples
 #' \dontrun{
-#' data(simulation_results)
-#' data(domains)
-#' summarize_to_disk(simulation_results)
+#' data(mc_simulation_results)
+#' summarize_to_disk(mc_simulation_results)
 #' }
 summarize_to_disk <- function(simulation_results, results_dir = "~/results") {
   if (!dir.exists(results_dir)) dir.create(results_dir)