In ahart1/decisiontable: Make Customized Decision Tables

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

library(decisiontable)

library(decisiontable)

Decision tables serve a critical role in making comparisons, assessing trade-offs, and communicating consequences to decision makers. The decisiontable package combines more traditional text-based tables and graphical elements to provide a flexible visualization of data that can be tailored to the needs of different decision-making audiences.

The following introduction highlights flexible features of this package that allow alternate data input formats, labels, coloring options, layout choices, icons and summary information.

Output

The makeDecisionTable function produces a decision table that expands the cells of a traditional text-based table to also include bar charts with heights corresponding to the text value, and customizable labels, coloring options, layout, icons, and summary information. By default, each decision table is saved as a .png image to the user's working directory under the name provided to the OutputFileName argument or another directory may be specified using the OutputDirectory argument.

Data & Labels

decisiontable can visualize two data formats: a dataframe ...

# Example dataframe
set.seed(1)
data_df <- matrix(c(abs(rnorm(30,20,sd=5))), ncol = 5, nrow = 6)
colnames(data_df) <- c("Column 1", "Column 2", "Column 3", "Column 4", "Column 5")
rownames(data_df) <- c("Row 1", "Row 2", "Row 3", "Row 4", "Row 5", "Row 6")
data_df

... or a vector.

# Example vector
set.seed(1)
data_v <- c(rnorm(30,20,sd=5))

data_v

If a dataframe is provided it may be a matrix, data_table, or tibble. Data in this format will be displayed in the same configuration in the final decision table. Row and column labels will be pulled from the dataframe or can be specified using the rownames and colnames arguments. The GraphicTitle argument must be used to specify the table title.

# Decision table created using the dataframe option 
makeDecisionTable(data = data_df,
                  OutputDirectory = here::here("vignettes"),
                  OutputFileName = "dataframe_DecisionTable",
                  GraphicTitle = "Decision table made with a dataframe input",
                  RowHeader = "Example Row Header",
                  ColumnHeader = "Example Column Header",
                  figureWidth = 650,
                  figureHeight = 800)

knitr::include_graphics(here::here("vignettes/dataframe_DecisionTable.png"))

If a vector is provided, additional ncol, nrow, byrow, colnames and rownames arguments must be provided to configure the data in the final decision table.

# Decision table created using the vector data option
makeDecisionTable(data = data_v,
                  ncol = 5, # Add for vector option
                  nrow = 6, # Add for vector option
                  byrow = FALSE, # Add for vector option
                  colnames = c("Column 1", "Column 2", "Column 3", "Column 4", "Column 5"), # Add for vector option
                  rownames = c("Row 1", "Row 2", "Row 3", "Row 4", "Row 5", "Row 6"), # Add for vector option
                  OutputDirectory = here::here("vignettes"),
                  OutputFileName = "vector_DecisionTable",
                  GraphicTitle = "Decision table made with a vector input",
                  RowHeader = "Example Row Header",
                  ColumnHeader = "Example Column Header",
                  figureWidth = 650,
                  figureHeight = 800)

knitr::include_graphics(here::here("vignettes/vector_DecisionTable.png"))

For simplicity, the data_df example dataset in the dataframe format will be used throughout the remainder of this vignette.

In the event that values printed in the decision table are summary statistics, upper and lower confidence bounds can be added to bars using the Data_UpperCI and Data_LowerCI arguments. These inputs may be in either the dataframe or the vector format which also requires additional ncol, nrow, byrow arguments.

# Create example confidence bounds
LowerCI <- data_df - 0.5*data_df
UpperCI <- data_df + 0.5*data_df

# Add confidence bounds to a decision table created using the dataframe option 
makeDecisionTable(data = data_df,
                  IncludeCI = "TRUE", # Add to include confidence bounds
                  Data_LowerCI = LowerCI, # Add to include confidence bounds
                  Data_UpperCI = UpperCI, # Add to include confidence bounds
                  OutputDirectory = here::here("vignettes"),
                  OutputFileName = "CI_DecisionTable",
                  GraphicTitle = "Decision table with CI",
                  RowHeader = "Example Row Header",
                  ColumnHeader = "Example Column Header",
                  figureWidth = 650,
                  figureHeight = 800)

knitr::include_graphics(here::here("vignettes/CI_DecisionTable.png"))

Coloring Options

By default a single-color option colors all bars in the decision table grey, but the following customized coloring options are also available: 1. Change the single-color option from grey to another color to be used for all bars in the decision table 2. Use the pre-specified ranked-coloring option to visually rank bar plots from worst- to best-performing option in each row using a pre-specified color scheme 3. Change the ranked-coloring option from the pre-specified color scheme to a custom color scheme to use for visual ranking across each row

1) Change single-color option

# Decision table with a custom single-color scheme
makeDecisionTable(data = data_df,
                  OutputDirectory = here::here("vignettes"),
                  OutputFileName = "Custom_Single-Color_Option",
                  GraphicTitle = "Custom Single-Color Option",
                  RowHeader = "Example Row Header",
                  ColumnHeader = "Example Column Header",
                  figureWidth = 650,
                  figureHeight = 800,
                  barColors = "cadetblue3")

knitr::include_graphics(here::here("vignettes/Custom_Single-Color_Option.png"))

2) Use pre-specified ranked-coloring option

For tables containing up to 20 rows and 20 columns there is a pre-specified ranked-coloring option that visually reflects the relative ranked performance. To utilize this option, visualRank must be set to "TRUE", the barColors argument must be set to "defaultRankColor", and users must provide a BestPeformanceVector that indicates weather a "High" value corresponds with best performance or if a "Low" data value corresponds with best performance.

# Decision table with a pre-specified ranked-coloring scheme
makeDecisionTable(data = data_df,
                  BestPerformanceVector = rep("High", nrow(data_df)),
                  barColors = "defaultRankColor",
                  visualRank = "TRUE",
                  OutputDirectory = here::here("vignettes"),
                  OutputFileName = paste("Pre-Specified_Ranked_Color_Option"),
                  GraphicTitle = "Pre-Specified Ranked Color Option",
                  RowHeader = "Example Row Header",
                  ColumnHeader = "Example Column Header",
                  figureWidth = 650,
                  figureHeight = 800)

knitr::include_graphics(here::here("vignettes/Pre-Specified_Ranked_Color_Option.png"))

3) Change ranked-coloring option

The ranked coloring can be changed to a custom scheme by setting the barColors argument as a vector of color names equal in length to the number of columns in your input data. The first color in the vector will correspond with the worst performance in each row and the last color provided will correspond with the best performance.

# Decision table with a pre-specified ranked-coloring scheme
makeDecisionTable(data = data_df,
                  BestPerformanceVector = rep("High", nrow(data_df)),
                  barColors = c("red","darkorange", "yellow", "yellowgreen", "green4"),
                  visualRank = "TRUE",
                  OutputDirectory = here::here("vignettes"),
                  OutputFileName = paste("Custom_Ranked_Color_Option"),
                  GraphicTitle = "Custom Ranked Color Option",
                  RowHeader = "Example Row Header",
                  ColumnHeader = "Example Column Header",
                  figureWidth = 650,
                  figureHeight = 800)

knitr::include_graphics(here::here("vignettes/Custom_Ranked_Color_Option.png"))

Layout

The following arguments can be used to alter the dimensions and layout of the resulting figure to meet specific needs: - figureWidth Specifies the width of the final figure in pixels, default = 500. - figureHeight Specifies the height of the final figure in pixels, default = 800. If horizontal division lines do not appear, try increasing the figure height using this argument. - resolution Increases the image resolution by scaling the number of pixels in the length and width by an equal amount specified using this argument. Increasing the resolution (higher numbers) will result in a larger image which can be adjusted in any image processing software to the desired dimension, default = 1 (no scaling up). - graphicCellWidths Is a vector of length 2 specifying first the width of the row label column and second the data column width - graphicCellHeight Is a number specifying the height of data rows - yscalerow Is a string specifying the type of scaling for the y-axis of bar charts, default = "FALSE"

# Higher resolution decision table with custom row and column dimensions and figure dimensions.
makeDecisionTable(data = data_df,
                  BestPerformanceVector = rep("High", nrow(data_df)),
                  barColors = "defaultRankColor",
                  visualRank = "TRUE",
                  OutputDirectory = here::here("vignettes"),
                  OutputFileName = paste("Layout_Options"),
                  GraphicTitle = "Custom Layout Options",
                  RowHeader = "Example Row Header",
                  ColumnHeader = "Example Column Header",
                  figureWidth = 750, # Add for custom figure dimensions
                  figureHeight = 900, # Add for custom figure dimensions
                  resolution = 2, # Add for custom figure resolution
                  graphicCellWidths = c(5,1), # Add for custom column widths
                  graphicCellHeight = 0.5) # Add for custom row heights

knitr::include_graphics(here::here("vignettes/Layout_Options.png"))

yscalerow is a powerful argument for structuring comparisons across rows or across the entire decision table using a common y-axis scale for bar charts. When the default settings are used yscalerow = "FALSE" which results in a single y-axis scale for all bar charts in the decision table except the summary row. This means that all bar charts in the table can be compared by height to interpret differences in value. In contrast, if yscalerow = "TRUE" the y-axis is scaled independently for each row in the decision table. This allows the visual comparison of all bar charts in the same row, but bar charts in different rows will be plotted along y-axes of different magnitudes so more care must be taken when comparing between rows. This second option is particularly useful when rows contain different types of information (e.g. one row represents data in meters and another row represents data in centimeters) which could result in data of different magnitudes.

# Decision table with bar chart y-axes scaled independtly by row
makeDecisionTable(data = data_df,
                  BestPerformanceVector = rep("High", nrow(data_df)),
                  barColors = "defaultRankColor",
                  visualRank = "TRUE",
                  OutputDirectory = here::here("vignettes"),
                  OutputFileName = paste("Layout_Options_yscalerow"),
                  GraphicTitle = "Pick a unique y-axis scale for each row",
                  RowHeader = "Example Row Header",
                  ColumnHeader = "Example Column Header",
                  figureWidth = 650,
                  figureHeight = 800,
                  yscalerow = "TRUE") # Add to set an independent y-axis scale for each row in the decision table

knitr::include_graphics(here::here("vignettes/Layout_Options_yscalerow.png"))

Icons

Up to 3 icons can be printed to the right of the decision table title using the IconList argument. These icons (identified by string names in a vector) can be selected from the following list that accompanies the package or the filename of the desired icon with a .png extension can be provided. Icon coloring for package icons can be changed using the IconColor argument. Alternatively, the file path to a custom icon can be provided to the IconList argument.

Package icons

• "Commercial_Fisheries_Herring_Mackerel_Lobster"

knitr::include_graphics(here::here("vignettes/Commercial_Fisheries_Herring_Mackerel_Lobster.png"))

• "Environmental_Considerations"

knitr::include_graphics(here::here("vignettes/Environmental_Considerations.png"))

• "Groundfish_Fishery"

knitr::include_graphics(here::here("vignettes/Groundfish_Fishery.png"))

• "Groundfish_Species"

knitr::include_graphics(here::here("vignettes/Groundfish_Species.png"))

• "Herring_Fishery_Option1"

knitr::include_graphics(here::here("vignettes/Herring_Fishery_Option1.png"))

• "Herring_Fishery_Option2"

knitr::include_graphics(here::here("vignettes/Herring_Fishery_Option2.png"))

• "Lobster"

knitr::include_graphics(here::here("vignettes/Lobster.png"))

• "Lobster_Fishery"

knitr::include_graphics(here::here("vignettes/Lobster_Fishery.png"))

• "Predator_Fisheries_Tuna_Haddock_Flatfish"

knitr::include_graphics(here::here("vignettes/Predator_Fisheries_Tuna_Haddock_Flatfish.png"))

• "Predator_Species_Tuna_Haddock_Flatfish"

knitr::include_graphics(here::here("vignettes/Predator_Species_Tuna_Haddock_Flatfish.png"))

• "Primary_Production"

knitr::include_graphics(here::here("vignettes/Primary_Production.png"))

• "Protected_Species"

knitr::include_graphics(here::here("vignettes/Protected_Species.png"))

• "Protected_Species_and_Tourism"

knitr::include_graphics(here::here("vignettes/Protected_Species_Tourism.png"))

• "Tourism"

knitr::include_graphics(here::here("vignettes/Tourism.png"))

• "Tuna"

knitr::include_graphics(here::here("vignettes/Tuna.png"))

• "Tuna_Fishery"

knitr::include_graphics(here::here("vignettes/Tuna_Fishery.png"))

# Decision table with 3 icons
makeDecisionTable(data = data_df,
                  BestPerformanceVector = rep("High", nrow(data_df)),
                  barColors = "defaultRankColor",
                  visualRank = "TRUE",
                  OutputDirectory = here::here("vignettes"),
                  OutputFileName = paste("Icon_Decision_Table"),
                  GraphicTitle = "Decision Table with Icons",
                  RowHeader = "Example Row Header",
                  ColumnHeader = "Example Column Header",
                  figureWidth = 650,
                  figureHeight = 800,
                  IconList = c("https://upload.wikimedia.org/wikipedia/commons/b/bc/Fish_P_icon.png", "Commercial_Fisheries_Herring_Mackerel_Lobster", "Environmental_Considerations"),
                  IconColor = "blue")

knitr::include_graphics(here::here("vignettes/Icon_Decision_Table.png"))

Summary Information

A number of statistics can be automatically calculated to summarize data in each column of the decision table and included as an additional summary row. These options include: 1. "Off" By default no summary row is included 2. "MeanRank" 3. "SumRank"
4. "MedianRank" 5. "MeanValue" 6. "SumValue" 7. "MedianValue" 8. "WhiskerPlot" = Summary row added, box and whisker plot summarizes data contained in each column, high/low value corresponding with best performance must be specified

Note: Options 2-4 should only be used when visualRank = "TRUE"

2) "MeanRank" Option

This option calculates the mean rank across all rows in each column. The highest rank always corresponds with the best performance, however high ranks could be associated with either high or low values based on the BestPerformanceVector.

# Decision table with a summary row showing mean rank in each column
makeDecisionTable(data = data_df,
                  BestPerformanceVector = rep("High", nrow(data_df)),
                  barColors = "defaultRankColor",
                  visualRank = "TRUE",
                  OutputDirectory = here::here("vignettes"),
                  OutputFileName = paste("MeanRank_Summary_Row"),
                  GraphicTitle = "Mean Rank Summary Row Option",
                  RowHeader = "Example Row Header",
                  ColumnHeader = "Example Column Header",
                  figureWidth = 650,
                  figureHeight = 900, # Increase the figure height if horizontal divisions do not appear
                  SummaryRowOption = "MeanRank") # Include this argument to add a summary row

knitr::include_graphics(here::here("vignettes/MeanRank_Summary_Row.png"))

3) "SumRank" Option

This option calculates the sum of ranks in each column. The highest summed rank always corresponds with the best performance, however high ranks could be associated with either high or low values based on the BestPerformanceVector.

# Decision table with a summary row showing sum rank in each column
makeDecisionTable(data = data_df,
                  BestPerformanceVector = rep("High", nrow(data_df)),
                  barColors = "defaultRankColor",
                  visualRank = "TRUE",
                  OutputDirectory = here::here("vignettes"),
                  OutputFileName = paste("SumRank_Summary_Row"),
                  GraphicTitle = "Sum Rank Summary Row Option",
                  RowHeader = "Example Row Header",
                  ColumnHeader = "Example Column Header",
                  figureWidth = 650,
                  figureHeight = 900, 
                  SummaryRowOption = "SumRank") # Include this argument to add a summary row

knitr::include_graphics(here::here("vignettes/SumRank_Summary_Row.png"))

4) "MedianRank" Option

This option calculates the median rank across all rows in each column. The highest median rank always corresponds with the best performance, however high ranks could be associated with either high or low values based on the BestPerformanceVector.

# Decision table with a summary row showing median rank in each column
makeDecisionTable(data = data_df,
                  BestPerformanceVector = rep("High", nrow(data_df)),
                  barColors = "defaultRankColor",
                  visualRank = "TRUE",
                  OutputDirectory = here::here("vignettes"),
                  OutputFileName = paste("MedianRank_Summary_Row"),
                  GraphicTitle = "Median Rank Summary Row Option",
                  RowHeader = "Example Row Header",
                  ColumnHeader = "Example Column Header",
                  figureWidth = 650,
                  figureHeight = 900, 
                  SummaryRowOption = "MedianRank") # Include this argument to add a summary row

knitr::include_graphics(here::here("vignettes/MedianRank_Summary_Row.png"))

5) "MeanValue" Option

This option calculates the mean value of data across all rows in each column. An additional SummaryBestPerformance argument must also be provided to specify whether "High" or "Low" values should be considered the best performance.

# Decision table with a summary row showing the mean value in each column
makeDecisionTable(data = data_df,
                  BestPerformanceVector = rep("High", nrow(data_df)),
                  barColors = "defaultRankColor",
                  visualRank = "TRUE",
                  OutputDirectory = here::here("vignettes"),
                  OutputFileName = paste("MeanValue_Summary_Row"),
                  GraphicTitle = "Mean Value Summary Row Option",
                  RowHeader = "Example Row Header",
                  ColumnHeader = "Example Column Header",
                  figureWidth = 650,
                  figureHeight = 900, 
                  SummaryRowOption = "MeanValue", # Include this argument to add a summary row
                  SummaryBestPerformance = "High") # Include this argument to add a summary row

knitr::include_graphics(here::here("vignettes/MeanValue_Summary_Row.png"))

6) "SumValue" Option

This option calculates the summed value of data across all rows in each column. An additional SummaryBestPerformance argument must also be provided to specify whether "High" or "Low" values should be considered the best performance.

# Decision table with a summary row showing the mean value in each column
makeDecisionTable(data = data_df,
                  BestPerformanceVector = rep("High", nrow(data_df)),
                  barColors = "defaultRankColor",
                  visualRank = "TRUE",
                  OutputDirectory = here::here("vignettes"),
                  OutputFileName = paste("SumValue_Summary_Row"),
                  GraphicTitle = "Sum Value Summary Row Option",
                  RowHeader = "Example Row Header",
                  ColumnHeader = "Example Column Header",
                  figureWidth = 650,
                  figureHeight = 900, 
                  SummaryRowOption = "SumValue", # Include this argument to add a summary row
                  SummaryBestPerformance = "High") # Include this argument to add a summary row

knitr::include_graphics(here::here("vignettes/SumValue_Summary_Row.png"))

7) "MedianValue" Option

This option calculates the median data value in each column. An additional SummaryBestPerformance argument must also be provided to specify whether "High" or "Low" values should be considered the best performance.

# Decision table with a summary row showing the mean value in each column
makeDecisionTable(data = data_df,
                  BestPerformanceVector = rep("High", nrow(data_df)),
                  barColors = "defaultRankColor",
                  visualRank = "TRUE",
                  OutputDirectory = here::here("vignettes"),
                  OutputFileName = paste("MedianValue_Summary_Row"),
                  GraphicTitle = "Median Value Summary Row Option",
                  RowHeader = "Example Row Header",
                  ColumnHeader = "Example Column Header",
                  figureWidth = 650,
                  figureHeight = 900, 
                  SummaryRowOption = "MedianValue", # Include this argument to add a summary row
                  SummaryBestPerformance = "High") # Include this argument to add a summary row

knitr::include_graphics(here::here("vignettes/MedianValue_Summary_Row.png"))

8) "WhiskerPlot" Option

This option calculates the median data value in each column. An additional SummaryBestPerformance argument must also be provided to specify whether "High" or "Low" values should be considered the best performance. The median value is printed below each whisker plot in the summary row

# Decision table with a summary row showing the mean value in each column
makeDecisionTable(data = data_df,
                  BestPerformanceVector = rep("Low", nrow(data_df)), # Change so low values represent best performance
                  barColors = "defaultRankColor",
                  visualRank = "TRUE",
                  OutputDirectory = here::here("vignettes"),
                  OutputFileName = paste("WhiskerPlot_Summary_Row"),
                  GraphicTitle = "Whisker Plot Summary Row Option",
                  RowHeader = "Example Row Header",
                  ColumnHeader = "Example Column Header",
                  figureWidth = 650,
                  figureHeight = 900, 
                  SummaryRowOption = "WhiskerPlot", # Include this argument to add a summary row
                  SummaryBestPerformance = "Low", # Include this argument to add a summary row
                  IconList = c("Groundfish_Fishery", "Lobster", "Tuna")) 

knitr::include_graphics(here::here("vignettes/WhiskerPlot_Summary_Row.png"))

ahart1/decisiontable documentation built on March 17, 2021, 4:18 a.m.