Goal of this talk

Introduce the {box} package and show how it can be used to write modularized/organized code and manage the name space.

Disclaimer: I have been using this package for about 6 months and I’m still learning new things everyday! Please ask as many questions as you want, but I may not know the answer.

Packages Used in the Making of this Presentation/Examples

• {box}
• {cowplot}: layout multiple plots using plot_grid()
• {glue}: used to combine strings and R code (similar to paste/paste0)
• {tidyverse} specifically {dplyr}, {ggplot2}, {stringr}, and {tidyr}

{box}

Why use {box}?

• Clean-up/Manage name space
• Modular-ize code without having to write full package
  • purposeful and organized code
  • if change code within box module, importation of box module doesn’t change

• re-use code for yourself if doing similar actions frequently
• share code internally with peers/colleague (create consistency)
• share externally

Why use {box}: Name Space

Name space: group of items (data frames, functions, vectors, lists, etc.) that each have a unique name.

• {dplyr} and {stats} use the same name for certain functions, CONFLICT in the namespace
• If want to use the {stats} function, have to refer to the package: stats::filter()

R Environment: Global Environment

Why use {box}: Modular-ize

• put code in to ‘modules’ or sections
• can have each module for a specific situation or group of functions
• other coding languages used in data science have this capability as well
  • C++ with namespace
  • Python with modules/packages
  • JavaScript with node modules

Quick Example: Different Ways of Coding

• data set with both character and numeric variables
• two types of plots
  
• want to create 2 of each type of plot using different variables

Note: this is a simplified version of the example in the EX_LONG folder of the repository, using mpg data from the {ggplot2}

A: Frequency Bar Plot
Character or Discrete Numeric Variables

B: Slope Plot
Mean of Continuous Numeric Variable at Two Points

Option 1: Write Out Code

Create plots with different variables ⇒ more code (write or copy/paste)

More situations/dimensions ⇒ additional unstructured code:

• more mess and less organization
• more name space usage
• bad practice to continue to repeat code

Option 2: Multiple Functions

Create plots with different variables ⇒ can easily use functions

More situations/dimensions ⇒ more functions:

• more name space usage
  
• difficult to maintain and keep consistency (i.e. formatting across plots)

Option 3: One Long Function

Create plots with different variables ⇒ can easily use function

More situations/dimensions ⇒ Longer function

• difficult to maintain because of large size
• difficult to test (one part of the function breaks, entire function won’t work)

Option 4: 🌟 Box Modules 🌟

Comparison

Item	Option 1 Write Out Code	Option 2 Multiple Functions	Option 3 One Long Function	Option 4 Box Modules
Namespace Usage	Constantly have to create unique names for objects	Only use name space for specific functions and/or dependencies	Only use name space for specific function	Only use name space for box modules
Testing Code	Testing code as written but shouldn’t repeat code multiple times	Functions are sectioned so can test at each level	Difficult to test individual sections once function get extremely long	All testing can be done within the module
Share/Re-Use	Have to piece through which code to keep and then amend to new program	Put functions together and document dependencies	One function but may be challenging to amend to a different situation or different machine	Just send the box modules .R files
Additional Dimensions	New code either added to existing code or new section, bad practice if will use multiple times	Manageable to difficult depending on how much each of the functions and their dependencies need to change	Difficult given that the function is so large, adding a new dimension would be challenging	Adjust easily within the box module or create a new box module (depending on situation)

Let’s learn how to use {box}

Box: File/Folder Structure

EX_LONG  
| 
|---myboxes #folder with modules
|   |  
|   |---Abox.R   
|   |---admin.R   
|   |---Bbox.R  
|   
|---my.Rmd #rmd file using box modules

EX_SHORT  
| 
|---box #folder with module
|   |  
|   |---greet.R   
|   
|---my.R #r file using box module

Box: External Packages/Modules

• when starting your box module will need to use package (e.g. {ggplot2}, {dplyr}, etc.)
• may also want to use other box modules as well
• Usually load packages using library() command
• Need to load packages and functions with box::use(), NOT library()

Box: box::use()

box::use(myboxes/Abox)  

box::use(dplyr[...])

box::use(dplyr[filter, select])  

Box: Write Your Functions/Code with Roxygen

#' Title  
#' 
#' @param [param] 
#' 
#' @return  
#' @export  
#' 
#' @examples

Box: Use Module Functions (EX_SHORT)

box::use(
    glue[glue]
  , stringr[str_to_title]
)

#' not exported, used WITHIN only 
greeting <- "Hello" 

#' Greet Someone when Given a Name  
#' @param name A character string 
#' @return Greeting with input name  
#' @export 
#' @examples 
#' say_hello("Martha")
say_hello <- function(name){
  to_use <- str_to_title(name)
  glue("{greeting}, {to_use}")
}

box::use(
    box/greet 
  )

greet$say_hello("Martha")

## Hello, Martha

Box: Tips

Use Module after Changes

If you make changes to box module, need to reload module in order to changes to be in effect

box::reload(Abox) #just include name, not full pathway/folder

Pathways

#within Abox.R file
box::use( ./admin)  

EX_LONG  
| 
|---myboxes #folder with modules
|   |  
|   |---Abox.R   
|   |---admin.R  
|   |---Bbox.R  
|   
|---my.Rmd #rmd file using box modules

#within reports/my.Rmd file
box::use( ../myboxes/admin)  

EX_LONG_REPORT_FOLDER  
| 
|---myboxes #folder with modules
|   |  
|   |---Abox.R   
|   |---admin.R  
|   |---Bbox.R  
|   
|---reports #rmd file using box modules
    |  
    |---my.Rmd