--- title: "Symbol Table Functions" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Symbol Table Functions} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) ``` The **macro** package includes several functions to manage the macro symbol table. These functions provide an interface between regular R code and the macro language. The symbol table functions are as follows: * **`symput()`**: Adds a macro variable to the macro symbol table. * **`symget()`**: Gets a macro variable value from the macro symbol table. * **`symtable()`**: Extracts and views the macro symbol table. * **`symclear()`**: Clears the values from the macro symbol table. In this article, we will look at the different ways the functions can be used, and how they can be used together. ## How to Use Since the symbol table functions are regular R functions, they can be used before or after the call to `msource()`. One common way to use them is to set macro variable values for a standard macro program, and then examine the symbol table after the standard macro program completes. For example, let's say you have a template macro program to perform an analysis on some data. You want to specify the input dataset, the variables to perform the analysis on, and you want some control over which statistics are calculated. ### Template Macro Program Here is a sample program that meets the above criteria. It is included in the **macro** package as "Demo5.R". Note the following about this template code: * The macro function `%get_analysis()` is defined in the program, with three parameters. * The program sets up a "do" loop for each analysis variable, and calls "%get_analysis" for each. * The macro function performs the analysis and dynamically creates a result data frame. * The result data frames are bound together into a "final" data frame. This data frame will have one row for each analysis variable. * The "final" data frame is printed to the console at the end of the program. ```{r eval=FALSE, echo=TRUE} #% Demo5: Template Analysis Program %# library(dplyr) # Perform Analysis ------------------------------------ #% Macro for Dynamic Descriptive Stats #%macro get_analysis(dat, var, stats) anl_&var <- `&dat` |> summarize(VAR = "&var", #%if ("mean" %in% &stats) MEAN = mean(`&var`, na.rm = TRUE), #%end #%if ("median" %in% &stats) MEDIAN = median(`&var`, na.rm = TRUE), #%end #%if ("sd" %in% &stats) SD = sd(`&var`, na.rm = TRUE), #%end #%if ("min" %in% &stats) MIN = min(`&var`, na.rm = TRUE), #%end #%if ("max" %in% &stats) MAX = max(`&var`, na.rm = TRUE), #%end END = NULL ) #%mend #% Loop through analysis variables #%do idx = 1 %to %sysfunc(length(&vars)) #%let var <- %sysfunc(&vars[&idx]) #%get_analysis(&dat, &var, &stats) #%end #% Get datasets to bind #%let dsets <- %sysfunc(paste0("anl_", &vars, collapse = ", ")) # Bind analysis datasets final <- bind_rows(`&dsets`) # Print results print(final) ``` As you can see, the above template program displays quite a bit of macro functionality. ### Run #1 Now let's set some parameters and execute the template program. Note the following about the run below: * The `symput()` functions are used to assign values to the macro variables "&dat", "&vars", and "&stats". * The `msource()` function is called with the "clear" parameter set to FALSE. Setting the "clear" parameter to FALSE is needed so that we do not wipe out the values assigned by `symput()`. * The `symtable()` function allows us to investigate the macro symbol table at the end of the run. * Since the "clear" parameter on the `msource()` function is set to FALSE, it is a good practice to clear out the symbol table by calling `symclear()`. That way, if we need to re-run the program, we can start with a clean symbol table. ```{r eval=FALSE, echo=TRUE} library(macro) # Get demo program pth <- system.file("extdata/Demo5.R", package = "macro") # Set macro variables symput("dat", "mtcars") symput("vars", c("mpg", "disp", "drat")) symput("stats", c("mean", "median", "sd")) # Macro Source demo program msource(pth, clear = FALSE) # --------- # library(dplyr) # # # Perform Analysis ------------------------------------ # # # anl_mpg <- mtcars |> # summarize(VAR = "mpg", # MEAN = mean(mpg, na.rm = TRUE), # MEDIAN = median(mpg, na.rm = TRUE), # SD = sd(mpg, na.rm = TRUE), # END = NULL # ) # anl_disp <- mtcars |> # summarize(VAR = "disp", # MEAN = mean(disp, na.rm = TRUE), # MEDIAN = median(disp, na.rm = TRUE), # SD = sd(disp, na.rm = TRUE), # END = NULL # ) # anl_drat <- mtcars |> # summarize(VAR = "drat", # MEAN = mean(drat, na.rm = TRUE), # MEDIAN = median(drat, na.rm = TRUE), # SD = sd(drat, na.rm = TRUE), # END = NULL # ) # # # Bind analysis datasets # final <- bind_rows(anl_mpg, anl_disp, anl_drat) # # # Print results # print(final) # --------- # VAR MEAN MEDIAN SD # 1 mpg 20.090625 19.200 6.0269481 # 2 disp 230.721875 196.300 123.9386938 # 3 drat 3.596563 3.695 0.5346787 # View symbol table symtable() # # Macro Symbol Table: 6 macro variables # Name Value # 1 &dat mtcars # 2 &dsets anl_mpg, anl_disp, anl_drat # 3 &idx 3 # 4 &stats mean, median, sd # 5 &var drat # 6 &vars mpg, disp, drat # # Macro Function List: 1 functions # # Function '%get_analysis': 3 parameters # - dat # - var # - stats # Get a specific variable value symget("dat") # [1] "mtcars" # Clear the symbol table symclear() # Clearing macro symbol table... # 8 items cleared. ``` Observe that the "final" dataset contains an analysis for all three requested variables. The macro parameters allow you change the input dataset, the analysis variables, and the statistics generated. ### Run #2 For illustration purposes, let's run "Demo5.R" again with different parameters. This time we will use the "iris" dataset: ```{r eval=FALSE, echo=TRUE} library(macro) # Get demo program pth <- system.file("extdata/Demo5.R", package = "macro") # Set macro variables symput("dat", "iris") symput("vars", c("Sepal.Length", "Sepal.Width", "Petal.Length", "Petal.Width")) symput("stats", c("mean", "median", "sd", "min", "max")) # Macro Source demo program msource(pth, clear = FALSE) # --------- # library(dplyr) # # # Perform Analysis ------------------------------------ # # # anl_Sepal.Length <- iris |> # summarize(VAR = "Sepal.Length", # MEAN = mean(Sepal.Length, na.rm = TRUE), # MEDIAN = median(Sepal.Length, na.rm = TRUE), # SD = sd(Sepal.Length, na.rm = TRUE), # MIN = min(Sepal.Length, na.rm = TRUE), # MAX = max(Sepal.Length, na.rm = TRUE), # END = NULL # ) # anl_Sepal.Width <- iris |> # summarize(VAR = "Sepal.Width", # MEAN = mean(Sepal.Width, na.rm = TRUE), # MEDIAN = median(Sepal.Width, na.rm = TRUE), # SD = sd(Sepal.Width, na.rm = TRUE), # MIN = min(Sepal.Width, na.rm = TRUE), # MAX = max(Sepal.Width, na.rm = TRUE), # END = NULL # ) # anl_Petal.Length <- iris |> # summarize(VAR = "Petal.Length", # MEAN = mean(Petal.Length, na.rm = TRUE), # MEDIAN = median(Petal.Length, na.rm = TRUE), # SD = sd(Petal.Length, na.rm = TRUE), # MIN = min(Petal.Length, na.rm = TRUE), # MAX = max(Petal.Length, na.rm = TRUE), # END = NULL # ) # anl_Petal.Width <- iris |> # summarize(VAR = "Petal.Width", # MEAN = mean(Petal.Width, na.rm = TRUE), # MEDIAN = median(Petal.Width, na.rm = TRUE), # SD = sd(Petal.Width, na.rm = TRUE), # MIN = min(Petal.Width, na.rm = TRUE), # MAX = max(Petal.Width, na.rm = TRUE), # END = NULL # ) # # # Bind analysis datasets # final <- bind_rows(anl_Sepal.Length, anl_Sepal.Width, anl_Petal.Length, anl_Petal.Width) # # # Print results # print(final) # # --------- # VAR MEAN MEDIAN SD MIN MAX # 1 Sepal.Length 5.843333 5.80 0.8280661 4.3 7.9 # 2 Sepal.Width 3.057333 3.00 0.4358663 2.0 4.4 # 3 Petal.Length 3.758000 4.35 1.7652982 1.0 6.9 # 4 Petal.Width 1.199333 1.30 0.7622377 0.1 2.5 # View symbol table symtable() # # Macro Symbol Table: 6 macro variables # Name Value # 1 &dat iris # 2 &dsets anl_Sepal.Length, anl_Sepal.Width, anl_Petal.Length, anl_Petal.Width # 3 &idx 4 # 4 &stats mean, median, sd, min, max # 5 &var Petal.Width # 6 &vars Sepal.Length, Sepal.Width, Petal.Length, Petal.Width # # Macro Function List: 1 functions # # Function '%get_analysis': 3 parameters # - dat # - var # - stats # Clear symbol table symclear() # Clearing macro symbol table... # 7 items cleared. ``` By changing the macro parameters, we were able to perform a different analysis on a completely different set of data. A macro-enabled program such as this offers considerable flexibility over other methods. It would be troublesome to achieve such flexibility in a regular R program, especially one that makes heavy use of non-standard evaluation. ### Other Uses While the above scenario demonstrates the most common application of symbol table functions, there are some other scenarios where these functions may be helpful. Here are some of them: * **Interactive usage:** Symbol table functions can be used on the command line to set macro variable values, observe variable values, and clear the symbol table in preparation for the next run. * **Debugging:** Symbol table functions can be helpful for debugging. You can use them to temporarily set parameter values while writing a macro function, or print out macro variable values to the console. * **Logging:** The symbol table functions may be useful for logging, especially the `symget()` and `symtable()` functions. You can use these to log incoming macro parameter values, or log the state of the symbol table at the end of the run. Next: [Debugging](macro-debug.html)