Package 'formods'

Description

Fetches the code to generate results seen in the app

Usage

ASM_fetch_code(state)

Arguments

Value

The ASM module does not generate code

Examples

# Creating a state object for testing
sess_res = ASM_test_mksession()
state = sess_res$state
code = ASM_fetch_code(state)

Description

Gets either the file name specified by the user or the default value if that is null

Usage

ASM_fetch_dlfn(state, extension = ".zip")

Arguments

Value

character object with the download file name

Examples

# Creating a state object for testing
sess_res = ASM_test_mksession()
state = sess_res$state
dlfn = ASM_fetch_dlfn(state)
dlfn

Description

Merges default app options with the changes made in the UI

Usage

ASM_fetch_state(id, input, session, FM_yaml_file, MOD_yaml_file)

Arguments

Value

list containing the current state of the app including default values from the yaml file as well as any changes made by the user. The list has the following structure:

• yaml: Full contents of the supplied yaml file.

• MC: Module components of the yaml file.

• ASM:

  • isgood: Boolean object indicating if the file was successfully loaded.

  • checksum: This is an MD5 sum of the loaded state file

• MOD_TYPE: Character data containing the type of module "ASM"

• id: Character data containing the module id module in the session variable.

• FM_yaml_file: App configuration file with FM as main section.

• MOD_yaml_file: Module configuration file with MC as main section.

Examples

# Within shiny both session and input variables will exist,
# this creates examples here for testing purposes:
sess_res = ASM_test_mksession()
session = sess_res$session
input   = sess_res$input

# Configuration files
FM_yaml_file  = system.file(package = "formods", "templates", "formods.yaml")
MOD_yaml_file = system.file(package = "formods", "templates", "ASM.yaml")

# We need to specify the ID of the ASM module
id = "ASM"

state = ASM_fetch_state(id           = id,
                        input        = input,
                        session      = session,
                        FM_yaml_file = FM_yaml_file,
                        MOD_yaml_file = MOD_yaml_file)

state

Description

Creates a list of the initialized module state

Usage

ASM_init_state(FM_yaml_file, MOD_yaml_file, id, session)

Arguments

Value

list containing an empty ASM state

Examples

# Within shiny the session variable will exist,
# this creates an example here for testing purposes:
sess_res = ASM_test_mksession()
session = sess_res$session
state = ASM_init_state(
   FM_yaml_file  = system.file(package = "formods",
                               "templates",
                               "formods.yaml"),
   MOD_yaml_file = system.file(package = "formods",
                               "templates",
                               "ASM.yaml"),
   id              = "ASM",
   session         = session)
state

Description

Converts the current ASM state into a preload list.

Usage

ASM_mk_preload(state)

Arguments

Value

list with the following elements

• isgood: Boolean indicating the exit status of the function.

• msgs: Messages to be passed back to the user.

• yaml_list: Lists with preload components.

Examples

sess_res = ASM_test_mksession()
state = sess_res$state
res = ASM_mk_preload(state)

Description

Creates a list of the initialized module state

Usage

ASM_onload(state, session)

Arguments

Value

ASM state object

Description

Populates the supplied session variable with information from list of sources.

Usage

ASM_preload(
  session,
  src_list,
  yaml_res = NULL,
  mod_ID = NULL,
  react_state = list(),
  quickload = FALSE
)

Arguments

Value

list with the following elements

• isgood: Boolean indicating the exit status of the function.

• msgs: Messages to be passed back to the user.

• session: Session object

• input: The value of the shiny input at the end of the session initialization.

• state: App state.

• react_state: The react_state components.

Description

Reads in the app state from yaml files.

Usage

ASM_read_app_state(sources = NULL)

Arguments

Value

list with the following elements

• isgood: Boolean indicating the exit status of the function.

• msgs: Messages to be passed back to the user.

• src_list: List containing the result of reading all of the sources.

• yaml_res: Lists with elements for each module ID found in src_list with elements holding the modules configuration file "mod_cfg" and the modules formods configuration file "fm_cfg"

Examples

res = ASM_read_app_state(sources=system.file(package="formods", "preload", "UD_preload.yaml"))

Description

Server function for the Save State Shiny Module

Usage

ASM_Server(
  id,
  FM_yaml_file = system.file(package = "formods", "templates", "formods.yaml"),
  MOD_yaml_file = system.file(package = "formods", "templates", "ASM.yaml"),
  deployed = FALSE,
  react_state = NULL,
  mod_ids
)

Arguments

Value

UD Server object

Examples

if(interactive()){
# These are suggested packages
library(shinydashboard)
library(ggpubr)
library(plotly)
library(shinybusy)
library(prompter)
library(utils)
library(clipr)
library(formods)

CSS <- "
.wrapfig {
  float: right;
  shape-margin: 20px;
  margin-right: 20px;
  margin-bottom: 20px;
}
"

# Default to not deployed
if(!exists("deployed")){
  deployed = FALSE
}

#https://fontawesome.com/icons?from=io
data_url =
"https://github.com/john-harrold/formods/raw/master/inst/test_data/TEST_DATA.xlsx"

ui <- dashboardPage(
  skin="black",
  dashboardHeader(title="formods"),
  dashboardSidebar(
     sidebarMenu(
       menuItem("Source Data",     tabName="upload",      icon=icon("table")) ,
       menuItem("Wrangle",         tabName="wrangle",     icon=icon("hat-cowboy")),
       menuItem("Plot",            tabName="plot",        icon=icon("chart-line")),
       menuItem("App State",       tabName="app_state",   icon=icon("archive")),
       menuItem("App Info",        tabName="sysinfo",     icon=icon("book-medical"))
     )
  ),
  dashboardBody(
  tags$head(
    tags$style(HTML(CSS))
  ),
    tabItems(
       tabItem(tabName="app_state",
                 box(title="Manage App State",
                     htmlOutput(NS("ASM", "ui_asm_compact")))),
       tabItem(tabName="upload",
               box(title="Load Data", width=12,
                 fluidRow(
                   prompter::use_prompt(),
                   column(width=6,
                     htmlOutput(NS("UD",  "UD_ui_compact"))),
                   column(width=6,
       tags$p(
           tags$img(
           class = "wrapfig",
           src   = "https://github.com/john-harrold/formods/raw/master/man/figures/logo.png",
           width = 100,
           alt = "formods logo" ),
         'Formods is a set of modules and an framework for developing modules
         which interact and create code to replicate analyses performed within an app.
         To experiment download this',
       tags$a("test dataset", href=data_url),
              'and upload it into the App using the form on the left.'))
                 )
               )
               ),
       tabItem(tabName="wrangle",
               box(title="Transform and Create Views of Your Data", width=12,
               htmlOutput(NS("DW",  "DW_ui_compact")))),
       tabItem(tabName="plot",
               box(title="Visualize Data", width=12,
               htmlOutput(NS("FG",  "FG_ui_compact")))),
       tabItem(tabName="sysinfo",
               box(title="System Details", width=12,
               shinydashboard::tabBox(
                 width = 12,
                 title = NULL,
                 shiny::tabPanel(id="sys_modules",
                          title=tagList(shiny::icon("ghost"),
                                        "Modules"),
                 htmlOutput(NS("ASM", "ui_asm_sys_modules"))
                 ),
                 shiny::tabPanel(id="sys_packages",
                          title=tagList(shiny::icon("ghost"),
                                        "Packages"),
                 htmlOutput(NS("ASM", "ui_asm_sys_packages"))
                 ),
                 shiny::tabPanel(id="sys_log",
                          title=tagList(shiny::icon("clipboard-list"),
                                        "App Log"),
                 verbatimTextOutput(NS("ASM", "ui_asm_sys_log"))
                 ),
                 shiny::tabPanel(id="sys_options",
                          title=tagList(shiny::icon("sliders"),
                                        "R Options"),
                 htmlOutput(NS("ASM", "ui_asm_sys_options"))
                 )
                 )
               ))
      )
    )
  )

# Main app server
server <- function(input, output, session) {
  # Empty reactive object to track and react to
  # changes in the module state outside of the module
  react_FM = reactiveValues()

  # This is the list of module ids used for reproducible script generation. The
  # order here is important.
  mod_ids = c("UD", "DW", "FG")

  #Populating with test data
  #FG_test_mksession(session)
  sources = c(system.file(package="formods", "preload", "ASM_preload.yaml"),
              system.file(package="formods", "preload", "UD_preload.yaml"),
              system.file(package="formods", "preload", "DW_preload.yaml"),
              system.file(package="formods", "preload", "FG_preload.yaml"))
  res = FM_app_preload(session=session, sources=sources)

  # Module servers
  formods::ASM_Server(id="ASM",
             deployed    = deployed,
             react_state = react_FM, mod_ids = mod_ids)
  formods::UD_Server( id="UD", id_ASM = "ASM",
             deployed    = deployed,
             react_state = react_FM)
  formods::DW_Server( id="DW", id_ASM = "ASM",id_UD = "UD",
             deployed    = deployed,
             react_state = react_FM)
  formods::FG_Server( id="FG", id_ASM = "ASM",id_UD = "UD", id_DW = "DW",
             deployed    = deployed,
             react_state = react_FM)
}

shinyApp(ui, server)
}

Description

Populates the supplied session variable for testing.

Usage

ASM_test_mksession(session = list())

Arguments

Value

The ASM portion of the 'all_sess_res' returned from ASM_set_app_state

See Also

ASM_set_app_state

Examples

sess_res = ASM_test_mksession()

Description

Called from download handler and used to write a saved state value if that is null

Usage

ASM_write_state(state, session, file, mod_ids)

Arguments

Value

This function only writes the state and has no return value.

Examples

# Within shiny both session and input variables will exist,
# this creates examples here for testing purposes:
sess_res = ASM_test_mksession()
session = sess_res$session
input   = sess_res$input

# Configuration files
FM_yaml_file  = system.file(package = "formods", "templates", "formods.yaml")
MOD_yaml_file = system.file(package = "formods", "templates", "ASM.yaml")

# We need to specify the ID of the ASM module
id = "ASM"

state = ASM_fetch_state(id           = id,
                        input        = input,
                        session      = session,
                        FM_yaml_file = FM_yaml_file,
                        MOD_yaml_file = MOD_yaml_file)

ASM_write_state(state, session,
                file    = tempfile(fileext=".zip"),
                mod_ids = c("UD"))

Description

Takes UI input and tries to figure out if it's numeric or text

Usage

autocast(ui_input, quote_char = TRUE)

Arguments

Value

Best guess of type casting applied to the ui_input

Examples

number = autocast('10')
text   = autocast('ten')

Description

Adds the wrangling element to the current data view.

Usage

DW_add_wrangling_element(state, dwb_res, dwee_res)

Arguments

Value

state with data set attached

Examples

library(formods)
# The example requires a formods DW state object
state  = DW_test_mksession()$state
state[["DW"]][["ui"]][["select_dw_element"]]          = "filter"
state[["DW"]][["ui"]][["select_fds_filter_column"]]   = "EVID"
state[["DW"]][["ui"]][["select_fds_filter_operator"]] = "=="
state[["DW"]][["ui"]][["fds_filter_rhs"]]             = 0

# This builds the data wrangling statement based on
# elemets scraped from the UI
dwb_res  = dwrs_builder(state)

# Here we evaluate the resulting command:
dwee_res = dw_eval_element(state, dwb_res[["cmd"]])

# Next we add this wrangling element to the state
state    = DW_add_wrangling_element(state, dwb_res, dwee_res)

# This creates a new data view and makes it active
state = DW_new_view(state)

# Here we can pluck out that data view from the state
current_view = DW_fetch_current_view(state)

# This will update the key in this view
current_view[["key"]] = "My new view"

# And this will place it back into the state
state = DW_set_current_view(state, current_view)

Description

Takes the current state of the app and appends data views to an xlsx report object.

Usage

DW_append_report(state, rpt, rpttype, gen_code_only = FALSE)

Arguments

Value

list containing the following elements

• isgood: Return status of the function.

• hasrptele: Boolean indicator if the module has any reportable elements.

• code: Code to generate reporting elements.

• msgs: Messages to be passed back to the user.

• rpt: Report with any additions passed back to the user.

See Also

FM_generate_report

Examples

# We need a state object to use below
sess_res = DW_test_mksession()
state = sess_res$state

rpt = list(summary = list(), sheets=list())

rpt_res = DW_append_report(state,
  rpt     = rpt,
  rpttype = "xlsx")

# Shows if report elements are present
rpt_res$hasrptele

# Code chunk to generate report element
cat(paste(rpt_res$code, collapse="\n"))

# Tabular summary of data views
rpt_res$rpt$summary

Description

Attaches a dataset to the DW state supplied.

Usage

DW_attach_ds(state, id_UD, session)

Arguments

Value

state with data set attached

Examples

# Within shiny both session and input variables will exist,
# this creates examples here for testing purposes:
sess_res = DW_test_mksession()
session = sess_res$session
input   = sess_res$input

# We also need a state variable
state = sess_res$state

# We need to identify the UD module with the data
id_UD = "UD"
state = DW_attach_ds(state, id_UD, session)

Description

Takes the current state and a string containing a data wranlging command and evaluates it.

Usage

dw_eval_element(state, cmd)

Arguments

Value

list with the following elements

• isgood: Return status of the function.

• msgs: Messages to be passed back to the user.

• DS: Wrangled dataset.

Examples

library(formods)
# The example requires a formods DW state object
state  = DW_test_mksession()$state
state[["DW"]][["ui"]][["select_dw_element"]]          = "filter"
state[["DW"]][["ui"]][["select_fds_filter_column"]]   = "EVID"
state[["DW"]][["ui"]][["select_fds_filter_operator"]] = "=="
state[["DW"]][["ui"]][["fds_filter_rhs"]]             = 0

# This builds the data wrangling statement based on
# elemets scraped from the UI
dwb_res  = dwrs_builder(state)

# Here we evaluate the resulting command:
dwee_res = dw_eval_element(state, dwb_res[["cmd"]])

# Next we add this wrangling element to the state
state    = DW_add_wrangling_element(state, dwb_res, dwee_res)

# This creates a new data view and makes it active
state = DW_new_view(state)

# Here we can pluck out that data view from the state
current_view = DW_fetch_current_view(state)

# This will update the key in this view
current_view[["key"]] = "My new view"

# And this will place it back into the state
state = DW_set_current_view(state, current_view)

Description

Fetches the code to generate results seen in the app

Usage

DW_fetch_code(state)

Arguments

Value

Character object vector with the lines of code and isgood)

Examples

# This will create a formods DW state object for the example
sess_res = DW_test_mksession()
state   = sess_res$state
code = DW_fetch_code(state)
cat(code)

Description

Takes a DW state and returns the current active view

Usage

DW_fetch_current_view(state)

Arguments

Value

List containing the details of the active data view. The structure of this list is the same as the structure of state$DW$views in the output of DW_fetch_state().

Examples

library(formods)
# The example requires a formods DW state object
state  = DW_test_mksession()$state
state[["DW"]][["ui"]][["select_dw_element"]]          = "filter"
state[["DW"]][["ui"]][["select_fds_filter_column"]]   = "EVID"
state[["DW"]][["ui"]][["select_fds_filter_operator"]] = "=="
state[["DW"]][["ui"]][["fds_filter_rhs"]]             = 0

# This builds the data wrangling statement based on
# elemets scraped from the UI
dwb_res  = dwrs_builder(state)

# Here we evaluate the resulting command:
dwee_res = dw_eval_element(state, dwb_res[["cmd"]])

# Next we add this wrangling element to the state
state    = DW_add_wrangling_element(state, dwb_res, dwee_res)

# This creates a new data view and makes it active
state = DW_new_view(state)

# Here we can pluck out that data view from the state
current_view = DW_fetch_current_view(state)

# This will update the key in this view
current_view[["key"]] = "My new view"

# And this will place it back into the state
state = DW_set_current_view(state, current_view)

Description

Fetches the datasets contained in the module.

Usage

DW_fetch_ds(state)

Arguments

Value

Character object vector with the lines of code

list containing the following elements

• isgood: Return status of the function.

• hasds: Boolean indicator if the module has any datasets

• msgs: Messages to be passed back to the user.

• ds: List with datasets. Each list element has the name of the R-object for that dataset. Each element has the following structure:

  • label: Text label for the dataset

  • MOD_TYPE: Short name for the type of module.

  • id: module ID

  • idx: unique numerical ID to identify this dataset in the module.

  • DS: Dataframe containing the actual dataset.

  • DSMETA: Metadata describing DS, see FM_fetch_ds() for details on the format.

  • code: Complete code to build dataset.

  • checksum: Module checksum.

  • DSchecksum: Dataset checksum.

Examples

# We need a state variable
sess_res = DW_test_mksession()
state = sess_res$state

ds = DW_fetch_ds(state)

Description

Merges default app options with the changes made in the UI

Usage

DW_fetch_state(
  id,
  input,
  session,
  FM_yaml_file,
  MOD_yaml_file,
  id_UD,
  react_state
)

Arguments

Value

List containing the current state of the DM module including default values from the yaml file as well as any changes made by the user. The structure of the list is defined below.

• yaml: Contents of the yaml file.

• MC: Module components of the yaml file.

• DW: Data wrangling state

  • isgood: Boolean status of the state. FALSE if the dataset identified by id_UD is bad.

  • checksum: MD5 sum indicating if there was a change in the datasets within the view. Use this to trigger updates in respose to changes in this module.

  • button_counters: List of counters to detect button clicks.

  • code_previous: Loading code from the UD field.

  • current_view: View id of the current active data wrangling view.

  • UD: Copy of the "UD" field of the id_UD from the react_state input.

  • ui: Current value of form elements in the UI

  • ui_hold: List of hold elements to disable updates before a full ui referesh is complete.

  • view_cntr: Counter for tracking view ids, value contains the id of the last view created.

  • views: List of data wrangling views. Each view has the following structure:

    • checksum: MD5 sum of WDS

    • code: Code to generate WDS from start to finish

    • code_dw_only: Code for just the wrangling portion.

    • code_previous: Code to load data and assign to view object.

    • elements_table: Table of data wrangling elements.

    • id: Character id (view_idx)

    • idx: Numeric id (1)

    • isgood: Boolean status of the data view. False if evaluation fails

    • key: User key (short description)

    • view_ds_object_name: Object name for this data view

    • WDS: Current value of the data view with all of the successful commands in elements_table evaluated.

• MOD_TYPE: Character data containing the type of module "DW"

• id: Character data containing the module id

• FM_yaml_file: App configuration file with FM as main section.

• MOD_yaml_file: Module configuration file with MC as main section. module in the session variable.

Examples

# Within shiny both session and input variables will exist,
# this creates examples here for testing purposes:
sess_res = DW_test_mksession()
session = sess_res$session
input   = sess_res$input

# Configuration files
FM_yaml_file  = system.file(package = "formods", "templates", "formods.yaml")
MOD_yaml_file = system.file(package = "formods", "templates", "DW.yaml")

# We need to specify both the DW module id as well as the
# id of the UD module that feeds into it.
id    = "DW"
id_UD = "UD"

# Creating an empty state object
state = DW_fetch_state(id              = id,
                       input           = input,
                       session         = session,
                       FM_yaml_file    = FM_yaml_file,
                       MOD_yaml_file   = MOD_yaml_file,
                       id_UD           = "UD",
                       react_state     = NULL)

Description

Walks through the DW state object to see if there are any datasets available

Usage

DW_hasds(state)

Arguments

Value

Logical TRUE if there is a dataset or FALSE otherwise.

Examples

sess_res = DW_test_mksession()
state = sess_res[["state"]]
DW_hasds(state)

Description

Creates a list of the initialized module state

Usage

DW_init_state(FM_yaml_file, MOD_yaml_file, id, id_UD, session)

Arguments

Value

list containing an empty DW state

Examples

# Within shiny both session and input variables will exist,
# this creates examples here for testing purposes:
sess_res = DW_test_mksession()
session = sess_res$session
input   = sess_res$input

state = DW_init_state(
   FM_yaml_file  = system.file(package = "formods",
                               "templates",
                               "formods.yaml"),
   MOD_yaml_file = system.file(package = "formods",
                               "templates",
                               "DW.yaml"),
   id              = "DW",
   id_UD           = "UD",
   session         = session)

state

Description

Converts the current DW state into a preload list.

Usage

DW_mk_preload(state)

Arguments

Value

list with the following elements

• isgood: Boolean indicating the exit status of the function.

• msgs: Messages to be passed back to the user.

• yaml_list: Lists with preload components.

Examples

sess_res = DW_test_mksession()
state = sess_res$state
res = DW_mk_preload(state)

Description

Appends a new empty data wrangling view to the DW state object and makes this new view the active view.

Usage

DW_new_view(state)

Arguments

Value

DW state object containing a new data view and that view set as the current active view. See the help for DW_fetch_state() for view format.

Examples

library(formods)
# The example requires a formods DW state object
state  = DW_test_mksession()$state
state[["DW"]][["ui"]][["select_dw_element"]]          = "filter"
state[["DW"]][["ui"]][["select_fds_filter_column"]]   = "EVID"
state[["DW"]][["ui"]][["select_fds_filter_operator"]] = "=="
state[["DW"]][["ui"]][["fds_filter_rhs"]]             = 0

# This builds the data wrangling statement based on
# elemets scraped from the UI
dwb_res  = dwrs_builder(state)

# Here we evaluate the resulting command:
dwee_res = dw_eval_element(state, dwb_res[["cmd"]])

# Next we add this wrangling element to the state
state    = DW_add_wrangling_element(state, dwb_res, dwee_res)

# This creates a new data view and makes it active
state = DW_new_view(state)

# Here we can pluck out that data view from the state
current_view = DW_fetch_current_view(state)

# This will update the key in this view
current_view[["key"]] = "My new view"

# And this will place it back into the state
state = DW_set_current_view(state, current_view)

Description

Populates the supplied session variable with information from list of sources.

Usage

DW_preload(
  session,
  src_list,
  yaml_res,
  mod_ID = NULL,
  react_state = list(),
  quickload = FALSE
)

Arguments

Value

list with the following elements

• isgood: Boolean indicating the exit status of the function.

• msgs: Messages to be passed back to the user.

• session: Session object

• input: The value of the shiny input at the end of the session initialization.

• state: App state.

• react_state: The react_state components.

Description

Server function for the data wrangling module

Usage

DW_Server(
  id,
  id_ASM = "ASM",
  id_UD = "UD",
  FM_yaml_file = system.file(package = "formods", "templates", "formods.yaml"),
  MOD_yaml_file = system.file(package = "formods", "templates", "DW.yaml"),
  deployed = FALSE,
  react_state = NULL
)

Arguments

Value

DW Server object

Examples

if(interactive()){
# These are suggested packages
library(shinydashboard)
library(ggpubr)
library(plotly)
library(shinybusy)
library(prompter)
library(utils)
library(clipr)
library(formods)

CSS <- "
.wrapfig {
  float: right;
  shape-margin: 20px;
  margin-right: 20px;
  margin-bottom: 20px;
}
"

# Default to not deployed
if(!exists("deployed")){
  deployed = FALSE
}

#https://fontawesome.com/icons?from=io
data_url =
"https://github.com/john-harrold/formods/raw/master/inst/test_data/TEST_DATA.xlsx"

ui <- dashboardPage(
  skin="black",
  dashboardHeader(title="formods"),
  dashboardSidebar(
     sidebarMenu(
       menuItem("Source Data",     tabName="upload",      icon=icon("table")) ,
       menuItem("Wrangle",         tabName="wrangle",     icon=icon("hat-cowboy")),
       menuItem("Plot",            tabName="plot",        icon=icon("chart-line")),
       menuItem("App State",       tabName="app_state",   icon=icon("archive")),
       menuItem("App Info",        tabName="sysinfo",     icon=icon("book-medical"))
     )
  ),
  dashboardBody(
  tags$head(
    tags$style(HTML(CSS))
  ),
    tabItems(
       tabItem(tabName="app_state",
                 box(title="Manage App State",
                     htmlOutput(NS("ASM", "ui_asm_compact")))),
       tabItem(tabName="upload",
               box(title="Load Data", width=12,
                 fluidRow(
                   prompter::use_prompt(),
                   column(width=6,
                     htmlOutput(NS("UD",  "UD_ui_compact"))),
                   column(width=6,
       tags$p(
           tags$img(
           class = "wrapfig",
           src   = "https://github.com/john-harrold/formods/raw/master/man/figures/logo.png",
           width = 100,
           alt = "formods logo" ),
         'Formods is a set of modules and an framework for developing modules
         which interact and create code to replicate analyses performed within an app.
         To experiment download this',
       tags$a("test dataset", href=data_url),
              'and upload it into the App using the form on the left.'))
                 )
               )
               ),
       tabItem(tabName="wrangle",
               box(title="Transform and Create Views of Your Data", width=12,
               htmlOutput(NS("DW",  "DW_ui_compact")))),
       tabItem(tabName="plot",
               box(title="Visualize Data", width=12,
               htmlOutput(NS("FG",  "FG_ui_compact")))),
       tabItem(tabName="sysinfo",
               box(title="System Details", width=12,
               shinydashboard::tabBox(
                 width = 12,
                 title = NULL,
                 shiny::tabPanel(id="sys_modules",
                          title=tagList(shiny::icon("ghost"),
                                        "Modules"),
                 htmlOutput(NS("ASM", "ui_asm_sys_modules"))
                 ),
                 shiny::tabPanel(id="sys_packages",
                          title=tagList(shiny::icon("ghost"),
                                        "Packages"),
                 htmlOutput(NS("ASM", "ui_asm_sys_packages"))
                 ),
                 shiny::tabPanel(id="sys_log",
                          title=tagList(shiny::icon("clipboard-list"),
                                        "App Log"),
                 verbatimTextOutput(NS("ASM", "ui_asm_sys_log"))
                 ),
                 shiny::tabPanel(id="sys_options",
                          title=tagList(shiny::icon("sliders"),
                                        "R Options"),
                 htmlOutput(NS("ASM", "ui_asm_sys_options"))
                 )
                 )
               ))
      )
    )
  )

# Main app server
server <- function(input, output, session) {
  # Empty reactive object to track and react to
  # changes in the module state outside of the module
  react_FM = reactiveValues()

  # This is the list of module ids used for reproducible script generation. The
  # order here is important.
  mod_ids = c("UD", "DW", "FG")

  #Populating with test data
  #FG_test_mksession(session)
  sources = c(system.file(package="formods", "preload", "ASM_preload.yaml"),
              system.file(package="formods", "preload", "UD_preload.yaml"),
              system.file(package="formods", "preload", "DW_preload.yaml"),
              system.file(package="formods", "preload", "FG_preload.yaml"))
  res = FM_app_preload(session=session, sources=sources)

  # Module servers
  formods::ASM_Server(id="ASM",
             deployed    = deployed,
             react_state = react_FM, mod_ids = mod_ids)
  formods::UD_Server( id="UD", id_ASM = "ASM",
             deployed    = deployed,
             react_state = react_FM)
  formods::DW_Server( id="DW", id_ASM = "ASM",id_UD = "UD",
             deployed    = deployed,
             react_state = react_FM)
  formods::FG_Server( id="FG", id_ASM = "ASM",id_UD = "UD", id_DW = "DW",
             deployed    = deployed,
             react_state = react_FM)
}

shinyApp(ui, server)
}

Description

Takes a DW state and an updated view and sets that view to the current view_id

Usage

DW_set_current_view(state, dw_view)

Arguments

Value

DW state object with the value of dw_view set to the current view id.

Examples

library(formods)
# The example requires a formods DW state object
state  = DW_test_mksession()$state
state[["DW"]][["ui"]][["select_dw_element"]]          = "filter"
state[["DW"]][["ui"]][["select_fds_filter_column"]]   = "EVID"
state[["DW"]][["ui"]][["select_fds_filter_operator"]] = "=="
state[["DW"]][["ui"]][["fds_filter_rhs"]]             = 0

# This builds the data wrangling statement based on
# elemets scraped from the UI
dwb_res  = dwrs_builder(state)

# Here we evaluate the resulting command:
dwee_res = dw_eval_element(state, dwb_res[["cmd"]])

# Next we add this wrangling element to the state
state    = DW_add_wrangling_element(state, dwb_res, dwee_res)

# This creates a new data view and makes it active
state = DW_new_view(state)

# Here we can pluck out that data view from the state
current_view = DW_fetch_current_view(state)

# This will update the key in this view
current_view[["key"]] = "My new view"

# And this will place it back into the state
state = DW_set_current_view(state, current_view)

Description

Populates the supplied session variable for testing.

Usage

DW_test_mksession(session = list())

Arguments

Value

The DW portion of the 'all_sess_res' returned from FM_app_preload

See Also

FM_app_preload

Examples

sess_res = DW_test_mksession()

Description

Takes a DW state and updates the checksum used to trigger downstream updates

Usage

DW_update_checksum(state)

Arguments

Value

DW state object with the checksum updated

Examples

# Within shiny both session and input variables will exist,
# this creates examples here for testing purposes:
sess_res = DW_test_mksession()
session = sess_res$session
input   = sess_res$input

# We also need a state variable
state = sess_res$state

state = DW_update_checksum(state)

Description

Takes the current ui elements and constructs the appropriate data wrangling command from the user input.

Usage

dwrs_builder(state)

Arguments

Value

list containing the following elements

• isgood: Return status of the function

• cmd: Data wrangling R command

• action: The action being performed

• pll: Preload list (pll) containing components to save with mk_preload.

• desc: Verbose description of the action

• msgs: Messages to be passed back to the user

Examples

library(formods)
# The example requires a formods DW state object
state  = DW_test_mksession()$state
state[["DW"]][["ui"]][["select_dw_element"]]          = "filter"
state[["DW"]][["ui"]][["select_fds_filter_column"]]   = "EVID"
state[["DW"]][["ui"]][["select_fds_filter_operator"]] = "=="
state[["DW"]][["ui"]][["fds_filter_rhs"]]             = 0

# This builds the data wrangling statement based on
# elemets scraped from the UI
dwb_res  = dwrs_builder(state)

# Here we evaluate the resulting command:
dwee_res = dw_eval_element(state, dwb_res[["cmd"]])

# Next we add this wrangling element to the state
state    = DW_add_wrangling_element(state, dwb_res, dwee_res)

# This creates a new data view and makes it active
state = DW_new_view(state)

# Here we can pluck out that data view from the state
current_view = DW_fetch_current_view(state)

# This will update the key in this view
current_view[["key"]] = "My new view"

# And this will place it back into the state
state = DW_set_current_view(state, current_view)

Description

Takes the current ui elements and constructs the appropriate ggplot commands forom the user input. The plot commands assume the existance of a ggplot object p.

Usage

fers_builder(state)

Arguments

Value

list containing the following elements

• isgood: Return status of the function.

• cmd: ggplot R command as a character string

• element: The type of element being added

• pll: Preload list (pll) containing components to save with mk_preload.

• desc: Verbose description of the element

• msgs: Messages to be passed back to the user

Examples

sess_res = FG_test_mksession()
state = sess_res$state
fb_res = fers_builder(state)

Description

When some buttons are clicked they will change the state of the system, but other UI components will not detect that change correctly. So those triggers are put on hold. This will fetch hold status for a specified inputId

Usage

fetch_hold(state, inputId = NULL)

Arguments

Value

Boolean value with the hold status

Examples

# Within shiny both session and input variables will exist, 
# this creates examples here for testing purposes:
sess_res = DW_test_mksession(session=list())
session = sess_res$session
input   = sess_res$input

# For this example we also need a state variable
state = sess_res$state

# This sets a hold on the specified inputID. This is normally done in 
# your XX_fetch_state() function.
state = set_hold(state, inputId = "select_dw_views")

# This will fetch the hold status of the specified inputID. 
fetch_hold(state, inputId = "select_dw_views")

# This will remove the hold and is normally done in one of the UI outputs
# with a priority set to ensure it happens after the rest of the UI has
# refreshed.
state = remove_hold(state, session, inputId = "select_dw_views")

Description

The specified package version is extracted and returned. This can simply be the version installed from CRAN or if a development version from GitHub is used details from that will be returned.

Usage

fetch_package_version(pkgname)

Arguments

Value

String with the version information

Examples

# This package should exist
fetch_package_version('digest')

# This package should not exist
fetch_package_version('bad package name')

Description

Description

Usage

FG_append_report(state, rpt, rpttype, gen_code_only = FALSE)

Arguments

Value

list containing the following elements

• isgood: Return status of the function.

• hasrptele: Boolean indicator if the module has any reportable elements.

• code: Data wrangling R command.

• msgs: Messages to be passed back to the user.

• rpt: Report with any additions passed back to the user.

See Also

FM_generate_report

Examples

sess_res = FG_test_mksession()
state = sess_res$state
# This will read in the default PowerPoint report template
rpt =
onbrand::read_template(
 template = system.file(package="onbrand","templates","report.pptx"),
 mapping  = system.file(package="onbrand","templates","report.yaml"))

rpt_res =
FG_append_report(state   = state,    rpt = rpt,
                 rpttype = "pptx", gen_code_only=TRUE)

# Shows if report elements are present
rpt_res$hasrptele

# Code chunk to generate report element
cat(paste(rpt_res$code, collapse="\n"))

Description

Takes the current state and rebuilds the active figure. If the elements table has a row flagged for deletion, it will be deleted. If the cmd input is not NULL it will attempt to append that element to the figure.

Usage

FG_build(
  state,
  del_row = NULL,
  cmd = NULL,
  pll = NULL,
  element = "unknown",
  desc = "unknown"
)

Arguments

Value

list with the following elements

• isgood: Return status of the function.

• msgs: Messages to be passed back to the user.

• pages: List with each element containing a ggplot object (p) and the code to generate that object (code)

Examples

library(formods)
# Within shiny both session and input variables will exist,
# this creates examples here for testing purposes:
sess_res = FG_test_mksession()
session = sess_res$session
input   = sess_res$input

# This will create a populated FG state object:
state   = sess_res$state

# This sets the current active figure to Fig_1
state[["FG"]][["current_fig"]]  =  "Fig_1"

# If this is a paginated figure, and we can access a specific
pg_1 = FG_extract_page(state, 1)

# This will give you access to the current figure directly:
current_fig = FG_fetch_current_fig(state)

# For example this will set the key for that figure:
current_fig$key = "Individual profiles by cohort (multiple pages)"

# Once you're done you can put it back into the state:
state = FG_set_current_fig(state, current_fig)

# If you made any changes to the actual figure, this will
# force a rebuild of the current figure:
state = FG_build( state=state, del_row = NULL, cmd = NULL)

# To create a new empty figure you can do this:
state = FG_new_fig(state)

Description

Used to extract the specified page from the current figure.

Usage

FG_extract_page(state, page)

Arguments

Value

ggplot object with the specified page.

Examples

library(formods)
# Within shiny both session and input variables will exist,
# this creates examples here for testing purposes:
sess_res = FG_test_mksession()
session = sess_res$session
input   = sess_res$input

# This will create a populated FG state object:
state   = sess_res$state

# This sets the current active figure to Fig_1
state[["FG"]][["current_fig"]]  =  "Fig_1"

# If this is a paginated figure, and we can access a specific
pg_1 = FG_extract_page(state, 1)

# This will give you access to the current figure directly:
current_fig = FG_fetch_current_fig(state)

# For example this will set the key for that figure:
current_fig$key = "Individual profiles by cohort (multiple pages)"

# Once you're done you can put it back into the state:
state = FG_set_current_fig(state, current_fig)

# If you made any changes to the actual figure, this will
# force a rebuild of the current figure:
state = FG_build( state=state, del_row = NULL, cmd = NULL)

# To create a new empty figure you can do this:
state = FG_new_fig(state)

Description

Fetches the code to generate results seen in the app

Usage

FG_fetch_code(state)

Arguments

Value

Character object vector with the lines of code

Examples

# This will create a populated FG state object:
sess_res = FG_test_mksession()
state   = sess_res$state
code  = FG_fetch_code(state)
cat(paste(code, collapse="\n"))

Description

Takes a FG state and returns the current active figure

Usage

FG_fetch_current_fig(state)

Arguments

Value

List containing the details of the active figure. The structure of this list is the same as the structure of state$FG$figs in the output of FG_fetch_state().

Examples

library(formods)
# Within shiny both session and input variables will exist,
# this creates examples here for testing purposes:
sess_res = FG_test_mksession()
session = sess_res$session
input   = sess_res$input

# This will create a populated FG state object:
state   = sess_res$state

# This sets the current active figure to Fig_1
state[["FG"]][["current_fig"]]  =  "Fig_1"

# If this is a paginated figure, and we can access a specific
pg_1 = FG_extract_page(state, 1)

# This will give you access to the current figure directly:
current_fig = FG_fetch_current_fig(state)

# For example this will set the key for that figure:
current_fig$key = "Individual profiles by cohort (multiple pages)"

# Once you're done you can put it back into the state:
state = FG_set_current_fig(state, current_fig)

# If you made any changes to the actual figure, this will
# force a rebuild of the current figure:
state = FG_build( state=state, del_row = NULL, cmd = NULL)

# To create a new empty figure you can do this:
state = FG_new_fig(state)

Description

Merges default app options with the changes made in the UI

Usage

FG_fetch_state(
  id,
  input,
  session,
  FM_yaml_file,
  MOD_yaml_file,
  id_ASM = NULL,
  id_UD = NULL,
  id_DW = NULL,
  react_state
)

Arguments

Value

list containing the current state of the app including default values from the yaml file as well as any changes made by the user. The structure of the list is defined below:

• yaml: Contents of the yaml file.

• MC: Module components of the yaml file.

• FG: Data wrangling state

  • isgood: Boolean status of the state. Currently just TRUE

  • button_counters: List of counters to detect button clicks.

  • ui_msg: Message returned when users perform actions.

  • ui: Current value of form elements in the UI.

  • ui_ids: Vector of UI elements for the module.

  • ui_hold: List of hold elements to disable updates before a full ui referesh is complete.

  • checksum: checksum of the FG module used to detect changes in the module.

  • aes_elements: Plot elements defined by aesthetics (i.e. the X in geom_X)

  • current_fig: fig_id of the currently figure.

  • fig_cntr: Counter for figures, incremented each time a new figure is created.

  • DSV: Available data sets from the UD and DW modules.

  • figs: List of figures. Each view has the following structure:

    • add_isgood: JMH

    • checksum: Checksum of the figure used to detect changes in the figure.

    • code: Code to generate figure from start to finish.

    • code_fg_only: Code to just generate the figure.

    • code_previous: Code to load and/or wrangle the dataset.

    • elements_table: Table of figure generation elements.

    • fg_object_name: JMH

    • fig_dsview: Name of the dataset view for the current figure (also the R object name of the dataset view).

    • fobj: JMH

    • id: Character id (fig_idx)

    • idx: Numeric id (1)

    • isgood: Boolean status of the figure. FALSE if evaluation/build fails.

    • key: Figure key acts as a title/caption (user editable)

    • msgs: JMH

    • notes: Figure notes (user editable)

    • num_pages: JMH

    • page: JMH

• MOD_TYPE: Character data containing the type of module "DW"

• id: Character data containing the module id module in the session variable.

• FM_yaml_file: App configuration file with FM as main section.

• MOD_yaml_file: Module configuration file with MC as main section.

Examples

# Configuration files
FM_yaml_file  = system.file(package = "formods", "templates", "formods.yaml")
MOD_yaml_file = system.file(package = "formods", "templates", "FG.yaml")

# We need to specify both the FG module id as well as the
# id of the UD module that feeds into it.
id    = "FG"
id_UD = "UD"
id_DW = "DW"

# These would be the Shiny input and session variables
input   = list()
session = list()

# Creating an empty state object
state = FG_fetch_state(id              = id,
                       input           = input,
                       session         = session,
                       FM_yaml_file    = FM_yaml_file,
                       MOD_yaml_file   = MOD_yaml_file,
                       id_UD           = id_UD,
                       id_DW           = id_DW,
                       react_state     = NULL)

state

Description

Creates a list of the initialized module state

Usage

FG_init_state(FM_yaml_file, MOD_yaml_file, id, id_UD, id_DW, session)

Arguments

Value

list containing an empty app state object

Examples

# These would be the Shiny input and session variables
input   = list()
session = list()

state = FG_init_state(
   FM_yaml_file  = system.file(package = "formods",
                               "templates",
                               "formods.yaml"),
   MOD_yaml_file = system.file(package = "formods",
                               "templates",
                               "FG.yaml"),
   id              = "FG",
   id_UD           = "UD",
   id_DW           = "DW",
   session         = session)

state

Description

Converts the current FG state into a preload list.

Usage

FG_mk_preload(state)

Arguments

Value

list with the following elements

• isgood: Boolean indicating the exit status of the function.

• msgs: Messages to be passed back to the user.

• yaml_list: Lists with preload components.

Examples

sess_res = FG_test_mksession()
state = sess_res$state
res = FG_mk_preload(state)

Description

Creates a new figure in a FG module

Usage

FG_new_fig(state)

Arguments

Value

FG state object containing a new empty figure and that figure set as the current active figure

Examples

library(formods)
# Within shiny both session and input variables will exist,
# this creates examples here for testing purposes:
sess_res = FG_test_mksession()
session = sess_res$session
input   = sess_res$input

# This will create a populated FG state object:
state   = sess_res$state

# This sets the current active figure to Fig_1
state[["FG"]][["current_fig"]]  =  "Fig_1"

# If this is a paginated figure, and we can access a specific
pg_1 = FG_extract_page(state, 1)

# This will give you access to the current figure directly:
current_fig = FG_fetch_current_fig(state)

# For example this will set the key for that figure:
current_fig$key = "Individual profiles by cohort (multiple pages)"

# Once you're done you can put it back into the state:
state = FG_set_current_fig(state, current_fig)

# If you made any changes to the actual figure, this will
# force a rebuild of the current figure:
state = FG_build( state=state, del_row = NULL, cmd = NULL)

# To create a new empty figure you can do this:
state = FG_new_fig(state)

Description

Populates the supplied session variable with information from list of sources.

Usage

FG_preload(
  session,
  src_list,
  yaml_res,
  mod_ID = NULL,
  react_state = list(),
  quickload = FALSE
)

Arguments

Value

list with the following elements

• isgood: Boolean indicating the exit status of the function.

• msgs: Messages to be passed back to the user.

• session: Session object

• input: The value of the shiny input at the end of the session initialization.

• state: App state.

• react_state: The react_state components.

Description

Server function for the figure generation module

Usage

FG_Server(
  id,
  FM_yaml_file = system.file(package = "formods", "templates", "formods.yaml"),
  MOD_yaml_file = system.file(package = "formods", "templates", "FG.yaml"),
  id_ASM = "ASM",
  id_UD = "UD",
  id_DW = "DW",
  deployed = FALSE,
  react_state = NULL
)

Arguments

Value

FG Server object

Examples

if(interactive()){
# These are suggested packages
library(shinydashboard)
library(ggpubr)
library(plotly)
library(shinybusy)
library(prompter)
library(utils)
library(clipr)
library(formods)

CSS <- "
.wrapfig {
  float: right;
  shape-margin: 20px;
  margin-right: 20px;
  margin-bottom: 20px;
}
"

# Default to not deployed
if(!exists("deployed")){
  deployed = FALSE
}

#https://fontawesome.com/icons?from=io
data_url =
"https://github.com/john-harrold/formods/raw/master/inst/test_data/TEST_DATA.xlsx"

ui <- dashboardPage(
  skin="black",
  dashboardHeader(title="formods"),
  dashboardSidebar(
     sidebarMenu(
       menuItem("Source Data",     tabName="upload",      icon=icon("table")) ,
       menuItem("Wrangle",         tabName="wrangle",     icon=icon("hat-cowboy")),
       menuItem("Plot",            tabName="plot",        icon=icon("chart-line")),
       menuItem("App State",       tabName="app_state",   icon=icon("archive")),
       menuItem("App Info",        tabName="sysinfo",     icon=icon("book-medical"))
     )
  ),
  dashboardBody(
  tags$head(
    tags$style(HTML(CSS))
  ),
    tabItems(
       tabItem(tabName="app_state",
                 box(title="Manage App State",
                     htmlOutput(NS("ASM", "ui_asm_compact")))),
       tabItem(tabName="upload",
               box(title="Load Data", width=12,
                 fluidRow(
                   prompter::use_prompt(),
                   column(width=6,
                     htmlOutput(NS("UD",  "UD_ui_compact"))),
                   column(width=6,
       tags$p(
           tags$img(
           class = "wrapfig",
           src   = "https://github.com/john-harrold/formods/raw/master/man/figures/logo.png",
           width = 100,
           alt = "formods logo" ),
         'Formods is a set of modules and an framework for developing modules
         which interact and create code to replicate analyses performed within an app.
         To experiment download this',
       tags$a("test dataset", href=data_url),
              'and upload it into the App using the form on the left.'))
                 )
               )
               ),
       tabItem(tabName="wrangle",
               box(title="Transform and Create Views of Your Data", width=12,
               htmlOutput(NS("DW",  "DW_ui_compact")))),
       tabItem(tabName="plot",
               box(title="Visualize Data", width=12,
               htmlOutput(NS("FG",  "FG_ui_compact")))),
       tabItem(tabName="sysinfo",
               box(title="System Details", width=12,
               shinydashboard::tabBox(
                 width = 12,
                 title = NULL,
                 shiny::tabPanel(id="sys_modules",
                          title=tagList(shiny::icon("ghost"),
                                        "Modules"),
                 htmlOutput(NS("ASM", "ui_asm_sys_modules"))
                 ),
                 shiny::tabPanel(id="sys_packages",
                          title=tagList(shiny::icon("ghost"),
                                        "Packages"),
                 htmlOutput(NS("ASM", "ui_asm_sys_packages"))
                 ),
                 shiny::tabPanel(id="sys_log",
                          title=tagList(shiny::icon("clipboard-list"),
                                        "App Log"),
                 verbatimTextOutput(NS("ASM", "ui_asm_sys_log"))
                 ),
                 shiny::tabPanel(id="sys_options",
                          title=tagList(shiny::icon("sliders"),
                                        "R Options"),
                 htmlOutput(NS("ASM", "ui_asm_sys_options"))
                 )
                 )
               ))
      )
    )
  )

# Main app server
server <- function(input, output, session) {
  # Empty reactive object to track and react to
  # changes in the module state outside of the module
  react_FM = reactiveValues()

  # This is the list of module ids used for reproducible script generation. The
  # order here is important.
  mod_ids = c("UD", "DW", "FG")

  #Populating with test data
  #FG_test_mksession(session)
  sources = c(system.file(package="formods", "preload", "ASM_preload.yaml"),
              system.file(package="formods", "preload", "UD_preload.yaml"),
              system.file(package="formods", "preload", "DW_preload.yaml"),
              system.file(package="formods", "preload", "FG_preload.yaml"))
  res = FM_app_preload(session=session, sources=sources)

  # Module servers
  formods::ASM_Server(id="ASM",
             deployed    = deployed,
             react_state = react_FM, mod_ids = mod_ids)
  formods::UD_Server( id="UD", id_ASM = "ASM",
             deployed    = deployed,
             react_state = react_FM)
  formods::DW_Server( id="DW", id_ASM = "ASM",id_UD = "UD",
             deployed    = deployed,
             react_state = react_FM)
  formods::FG_Server( id="FG", id_ASM = "ASM",id_UD = "UD", id_DW = "DW",
             deployed    = deployed,
             react_state = react_FM)
}

shinyApp(ui, server)
}

Description

Takes a FG state and a figure list and sets that figure list as the value for the active figure

Usage

FG_set_current_fig(state, fig)

Arguments

Value

State with the current figure updated

Examples

library(formods)
# Within shiny both session and input variables will exist,
# this creates examples here for testing purposes:
sess_res = FG_test_mksession()
session = sess_res$session
input   = sess_res$input

# This will create a populated FG state object:
state   = sess_res$state

# This sets the current active figure to Fig_1
state[["FG"]][["current_fig"]]  =  "Fig_1"

# If this is a paginated figure, and we can access a specific
pg_1 = FG_extract_page(state, 1)

# This will give you access to the current figure directly:
current_fig = FG_fetch_current_fig(state)

# For example this will set the key for that figure:
current_fig$key = "Individual profiles by cohort (multiple pages)"

# Once you're done you can put it back into the state:
state = FG_set_current_fig(state, current_fig)

# If you made any changes to the actual figure, this will
# force a rebuild of the current figure:
state = FG_build( state=state, del_row = NULL, cmd = NULL)

# To create a new empty figure you can do this:
state = FG_new_fig(state)

Description

Populates the supplied session variable for testing.

Usage

FG_test_mksession(session = list())

Arguments

Value

The FG portion of the 'all_sess_res' returned from FM_app_preload

See Also

FM_app_preload

Examples

sess_res = FG_test_mksession()

Description

Called after any changes to figures, this function will update the checksum of the module. This allows other modules to determine if there were any changes to the figures within it.

Usage

FG_update_checksum(state)

Arguments

Value

state with checksum updated.

Examples

# This will create a populated FG state object:

sess_res = FG_test_mksession()
state   = sess_res$state
state = FG_update_checksum(state)

Description

Adds a tool tip to a user element.

Usage

FM_add_ui_tooltip(
  state,
  uiele,
  tooltip = "mytooltip",
  position = "right",
  size = "medium"
)

Arguments

Value

If tooltips are enabled and the suggested packages are installed then a uiele with the tooltip added will be returned. Otherwise it will just return the original uiele unchanged.

Examples

if(interactive()){
# We need a module state object to use this function:
sess_res = UD_test_mksession()
state = sess_res$state
uiele = shiny::textInput(inputId = "my input", label="example input")

uiele = FM_add_ui_tooltip(state, uiele)
}

Description

Populates session data for testing or to load a specific analysis.

Usage

FM_app_preload(
  session,
  sources = NULL,
  react_state = list(),
  quickload = FALSE
)

Arguments

Value

list with the following elements

• isgood: Boolean indicating the exit status of the function.

• msgs: Messages to be passed back to the user.

• all_sess_res: List containing the result for each module stored in the list name with the module ID.

• session: Returning the session variable to be used in scripting (not in app).

Examples

sources=system.file(package="formods", "preload", "UD.yaml")
res = FM_app_preload(session=list(), sources=sources)

Description

Takes a character string and builds a comment so it will be formatted as a section at the specified level in RStudio

Usage

FM_build_comment(level = 1, comment_str)

Arguments

Value

Formatted comment.

Examples

FM_build_comment(1, "This is a level 1 header")

FM_build_comment(2, paste0(rep("Long string repeated.", 5), collapse=" "))

Description

Takes the current state of the app and builds a script to reproduce the analysis within the app.

Usage

FM_fetch_app_code(session, state, mod_ids)

Arguments

Value

list with the following elements:

• isgood: Boolean indicating the whether code generation was successful (TRUE)

• msgs: Any messages generated

• code: Code to regenerate the app

Examples

# We need a Shiny session object to use this function:
sess_res = DW_test_mksession()
session = sess_res$session
state   = sess_res$state
app_code = FM_fetch_app_code(session = session,
                             state   = state,
                             mod_ids = c("UD", "DW"))
cat(app_code$code)

Description

Returns diagnostic information about the app

Usage

FM_fetch_app_info(session)

Arguments

Value

List with information about the app with the following structure

• uiele: All system information as UI elements to be used in shiny apps.

• uiele_packages: UI element for installed packages to be used in shiny apps.

• uiele_options: UI element for current options.

• uiele_modules: UI element for loaded formods modules to be used in shiny apps.

• msgs: System information as text to be used in a report/terminal.

• si_packages Dataframe with currently used packages.

• si_options Dataframe with current options

Examples

# We need a Shiny session object to use this function:
sess_res = UD_test_mksession()
session = sess_res$session
app_info  = FM_fetch_app_info(session)
app_info$msgs

Description

Returns the entire state of the App

Usage

FM_fetch_app_state(session)

Arguments

Value

App state or NULL if it's not defined.

Examples

# We need a Shiny session object to use this function:
sess_res = UD_test_mksession()
session = sess_res$session
app_state = FM_fetch_app_state(session)
app_state

Description

Use this to get information about the currently supported modules. This includes short names, UI elements,

Usage

FM_fetch_current_mods()

Value

list with details about the currently supported modules.

Examples

FM_fetch_current_mods()

Description

Takes a data frame and information in the site configureation to produce formatting information to make it easier for the user to see data type information.

Usage

FM_fetch_data_format(df, state)

Arguments

Value

list with the following elements:

• col_heads: List (element for each column) of formatting information for column headers to be use with rhandsontable.

• col_subtext: List (element for each column) of subtext to be displayed in selections using 'pickerInput' from the 'shinyWidgets' package.

Examples

# We need a module state object to use this function:
sess_res = UD_test_mksession()
state = sess_res$state

data_file_local =  system.file(package="formods", "test_data", "TEST_DATA.xlsx")
sheet           = "DATA"

df = readxl::read_excel(path=data_file_local, sheet=sheet)

hfmt = FM_fetch_data_format(df, state)

# Column header formatting
head(as.vector(unlist( hfmt[["col_heads"]])))

# Column select subtext
head(as.vector(unlist( hfmt[["col_subtext"]])))

Description

For a given state and session this function will determine the module ids that are dependent as well as any packages the module elements might depend on.

Usage

FM_fetch_deps(state, session)

Arguments

Value

list with the following elements:

• mod_ids Dependent module ids.

• packages List of package dependencies.

• package_code Library commands to load packages.

Examples

# We need a Shiny session object to use this function:
sess_res = UD_test_mksession()
session  = sess_res$session
state    = sess_res$state
mod_deps = FM_fetch_deps(state, session)

Description

Loops through each specified module ID or all modules if no ID was specified. For each ID, an attempt will be made to extract any datasets available.

Usage

FM_fetch_ds(state, session, ids = NULL)

Arguments

Value

list containing the current dataset with the following format:

• isgood: Boolean indicating the whether a dataset was found (FALSE)

• ds: List of datasets with element names corresponding to the R object name for that dataset. This has the following format

  • label: Text label for the dataset (used to display to the user)

  • DS: Data frame with the dataset

  • DSMETA: Data frame with metadata about the colunns of the dataset in DS. The data frame should have the following columns:

    • col1: column 1

  • code: Code to generate the dataset.

  • checksum: Module checksum when the dataset was pulled

  • DSchecksum: Checksum of the dataframe in DS

• catalog: Dataframe containing the a tabular catalog of the datasets found.

  • label: Text label

  • object: Name of the R Object containing the data frame

  • MOD_TYPE: Short name of the type of module

  • id: Module ID

  • idx: Numerical identifyer within the module

  • checksum: Module checksum

  • DSchecksum: Checksum of the dataset

  • code: Code to generate the dataset

• modules: List with an entry for each module. The element name is the short name. Each of these is a list with an entry that is the shiny module ID. For each of these there is a checksum. For example to access the checksum of a DW module with a module ID of 'my_id', you would use the following: res$modules$DW$my_id.

Examples

# We need a module state and a Shiny session variable
# to use this function:
sess_res = UD_test_mksession()
session = sess_res$session
state   = sess_res$state
ds = FM_fetch_ds(state, session)
ds$catalog

Description

Use this to get the path to the formods log file

Usage

FM_fetch_log_path(state)

Arguments

Value

Character string with the path to the log file.

Examples

# Within shiny a session variable will exist,
# this creates one here for testing purposes:
sess_res = UD_test_mksession()
session = sess_res$session
state   = sess_res$state
FM_fetch_log_path(state)

Description

Loops through each specified module ID or all modules if no ID was specified. For each ID, an attempt will be made to extract any models available.

Usage

FM_fetch_mdl(state, session, ids = NULL)

Arguments

Value

list containing the current dataset with the following format:

• isgood: General logical indicator of successfully.

• hasmdl: Logical indicating if at least one model was found.

• modules: List of module checksums.

• mdl: Result of MM_fetch_mdl, see vignette("making_modules", package = "formods")

• catalog: Dataframe containing the a tabular catalog of the models found.

  • label: Text label for the model (e.g. one-compartment model).

  • MOD_TYPE: Type of module.

  • id: Module ID.

  • rx_obj: The rxode2 object.

  • rx_obj_name: The rxode2 object name that holds the model.

  • ts_obj: List of timescale information for the system and details of other timescales (list(system="weeks", details = list(days=list(verb="days", conv=86400))))

  • ts_obj_name: The object name that holds the timescale for this model.

  • fcn_def: Text to define the model.

  • MDLMETA: Notes about the model.

  • code: Code to generate the model.

  • checksum: Module checksum.

  • MDLchecksum: Model checksum.

Examples

# We need a module state and a Shiny session variable
# to use this function:
sess_res = UD_test_mksession()
session = sess_res$session
state   = sess_res$state
mdl = FM_fetch_mdl(state, session)
mdl$catalog

Description

Fetches the module state from the userdata under the specified id

Usage

FM_fetch_mod_state(session, id)

Arguments

Value

module state or NULL if it's not defined.

Examples

# We need a Shiny session variable to use this function:
sess_res = UD_test_mksession()
session = sess_res$session
state = FM_fetch_mod_state(session, "UD")

Description

Use this to get the path to the temporary directory where formods stores user files.

Usage

FM_fetch_user_files_path(state)

Arguments

Value

Character string with the path to the log file.

Examples

# We need a state object to use this function:
sess_res = UD_test_mksession()
state = sess_res$state
user_dir = FM_fetch_user_files_path(state)
user_dir

Description

Generates a report from the states of the different modules. The type of report is based on the file extension of file_name.

Usage

FM_generate_report(
  state,
  session,
  file_dir,
  file_name,
  ph = list(),
  gen_code_only = FALSE,
  rpterrors = TRUE
)

Arguments

Details

This function will look through the loaded modules and find those with reporting enabbled. If reporting is enabled it will look for reporting functions for that module. Reporting functions should be of the following format (name and arguments):

XX_append_report(state, rpt, rpttype)

Where XX is the module short name. The state is the current state of the module. The rpt contains the current content of the report. This will vary based on the report type:

• xlsx: List with two elements. The first is summary a data frame with two columns. The first column is called Sheet_Name and the second column is called Description. This is a catalog of sheets added to the report by the user and can be appended to using rbind. The second element in xlsx rpt is another list with element names corresponding to the report sheet names and the values corresponding to dataframes to be exported in the report.

• pptx or docx: Corresponding onbrand reporting object.

Value

List with the following elements

Examples

# Within shiny both session and input variables will exist,
# this creates examples here for testing purposes:
if(interactive()){
sess_res = FG_test_mksession(session=list(), full_session=FALSE)
session = sess_res$session
input   = sess_res$input

# This will create a populated FG state object:
state   = sess_res$state


# This is the directory to write the report:
file_dir = tempdir()

# This is the file name that determines the type of report to write:
file_name = "my_report.pptx"
#file_name = "my_report.docx"

rpt_res =
FM_generate_report(state         = state,
                   session       = session,
                   file_dir      = file_dir,
                   file_name     = file_name,
                   gen_code_only = TRUE, 
                   rpterrors     = TRUE)

# This contains the exit status of the report generation
rpt_res$isgood

# This is the underlying code that was used to generate the report
cat(paste0(rpt_res$code, collapse="\n"))
}

Description

Initializes a formods state object with common elements.

Usage

FM_init_state(
  FM_yaml_file,
  MOD_yaml_file,
  id,
  dep_mod_ids = c(),
  MT,
  button_counters,
  ui_ids,
  ui_hold,
  session
)

Arguments

Value

List with state initialized.

Examples

# Within shiny a session variable will exist,
# this creates examples here for testing purposes:
sess_res = UD_test_mksession()
session = sess_res$session
state = FM_init_state(
   FM_yaml_file  = system.file(package = "formods",
                               "templates",
                               "formods.yaml"),
   MOD_yaml_file = system.file(package = "formods",
                               "templates",
                               "UD.yaml"),
   id              = "UD",
   MT              = "UD",
   button_counters = NULL,
   ui_ids          = NULL,
   ui_hold         = NULL,
   session         = session)

state

Description

Add the supplied txt and the module type to the log file and display it to the console.

Usage

FM_le(state, entry, escape_braces = TRUE, entry_type = "alert")

Arguments

Value

Boolean value indicating success (TRUE) or failure (FALSE).

Examples

# We need a module state to use this function:
sess_res = UD_test_mksession()
state   = sess_res$state
FM_le(state, "This is a normal  message")
FM_le(state, "This is a danger  message", entry_type="danger")
FM_le(state, "This is a info    message", entry_type="info")
FM_le(state, "This is a success message", entry_type="success")
FM_le(state, "This is a warning message", entry_type="warning")

Description

Writes a message to the console depending on whether cli is installed or not.

Usage

FM_message(line, escape_braces = TRUE, entry_type = "alert")

Arguments

Value

Returns NULL

Examples

mr = FM_message("This is a normal  message")
mr = FM_message("This is a danger  message", entry_type="danger")
mr = FM_message("This is a info    message", entry_type="info")
mr = FM_message("This is a success message", entry_type="success")
mr = FM_message("This is a warning message", entry_type="warning")
mr = FM_message("This is an H1 header",      entry_type="h1")
mr = FM_message("This is an H2 header",      entry_type="h2")
mr = FM_message("This is an H3 header",      entry_type="h3")

Description

Populates session data for testing or to load a specific analysis.

Usage

FM_mk_app_preload(session)

Arguments

Value

list with the following elements

• isgood: Boolean indicating the exit status of the function.

• msgs: Messages to be passed back to the user.

• yaml_list: Lists with preload components.

• session: Returning the session variable to be used in scripting (not in app).

Examples

sources=system.file(package="formods", "preload", "UD.yaml")
sess_res = ASM_set_app_state(session=list(), sources=sources)
mkp_res = ASM_mk_app_preload(sess_res$session)

Description

Takes a vector of messages and returns a ggplot object with the text in the figure. This can be used in automated figure generation to cascade an error message to the end user.

Usage

FM_mk_error_fig(msgs)

Arguments

Value

ggplot object

Examples

FM_mk_error_fig("Oh nos! You've made a mistake!")

Description

Generates a notification that should only show once.

Usage

FM_notify(state, session)

Arguments

Value

Boolean variable indicating if the notification was triggered

Examples

if(interactive()){
library(formods)
library(shiny)
library(shinydashboard)
#https://fontawesome.com/icons?from=io

ui <- dashboardPage(
  skin="red",
  dashboardHeader(title="Test Notifications"),
  dashboardSidebar(
     sidebarMenu(
       menuItem("Notifications",    tabName="example",  icon=icon("table"))
     )
  ),
  dashboardBody(
    tabItems(
       tabItem(tabName="example",
        fluidRow(
          shiny::actionButton("set_notification", "Set Notification"),
          shiny::textInput("user_text", label="Notify Text Here", value="Notify me"),
          shiny::actionButton("show_notification", "Show Notification")
         )
       )
     )
   )
 )

# Main app server
server <- function(input, output, session) {

  # Need formods state object
  sess_res = UD_test_mksession(session, id="UD")

  # Captures input and sets the notification
  observeEvent(input$set_notification, {

    state = FM_fetch_mod_state(session, id="UD")
    state = FM_set_notification(state,
                                notify_text = isolate(input$user_text),
                                notify_id   = "example")
    FM_set_mod_state(session, id="UD", state)
   })


  # Displays the notification
  observeEvent(input$show_notification, {
    state = FM_fetch_mod_state(session, id="UD")
    FM_notify(state, session)
   })
}

shinyApp(ui, server)
}

Description

Start a modal screen pause.

Usage

FM_pause_screen(state, session, message)

Arguments

Value

Pauses the screen and has no return value.

Examples

# We need a module state object and Shiny session objects to use this function:
sess_res = UD_test_mksession()
session = sess_res$session
state = sess_res$state
FM_pause_screen(state, session)
FM_resume_screen(state, session)

Description

When displaying information in a pull down this function can be used to sort those options.

Usage

FM_pretty_sort(unsrt_data)

Arguments

Value

sorted data

Examples

# This is the full path to a test data file:
data_file_local  =  system.file(package="formods", "test_data", "TEST_DATA.xlsx")
# Excel files need a sheet specification:
sheet           = "DATA"
# We will also attach the sheets along with it
df = readxl::read_excel(path=data_file_local, sheet=sheet)
# Regular sorting:
sort(unique(df$Cohort))
FM_pretty_sort(unique(df$Cohort))

Description

Any errors that need to be passed back to the user can be set with this function.

Usage

FM_proc_include(state, session)

Arguments

Value

No return value, sets message in supplied session variable.

Examples

# We need a module state object to use this function:
sess_res = UD_test_mksession()
state = sess_res$state
session = sess_res$session
FM_proc_include(state, session)

Description

Stops Modal Screen Pause

Usage

FM_resume_screen(state, session)

Arguments

Value

No return value, called to disable screen pause.

Examples

# We need a module state object and Shiny session objects to use this function:
sess_res = UD_test_mksession()
session = sess_res$session
state = sess_res$state
FM_pause_screen(state, session)
FM_resume_screen(state, session)

Description

Takes a loaded app state and overwrites the current app state

Usage

FM_set_app_state(session, app_state, set_holds = TRUE)

Arguments

Value

No return value, just updates the app state in the session variable.

Examples

# We need a Shiny session object to use this function:
sess_res = UD_test_mksession()
session = sess_res$session
app_state = FM_fetch_app_state(session)
FM_set_app_state(session, app_state)

Description

Sets the module state from the userdata under the specified id

Usage

FM_set_mod_state(session, id, state)

Arguments

Value

Session variable with the module state set.

Examples

# We need a Shiny session variable and a module state
# object to use this function:
sess_res = UD_test_mksession()
session = sess_res$session
state   = sess_res$state
FM_set_mod_state(session, "UD", state)

Description

Generates a notification that should only show once.

Usage

FM_set_notification(state, notify_text, notify_id, type = "info")

Arguments

Value

Module state with notification text set

Examples

if(interactive()){
library(formods)
library(shiny)
library(shinydashboard)
#https://fontawesome.com/icons?from=io

ui <- dashboardPage(
  skin="red",
  dashboardHeader(title="Test Notifications"),
  dashboardSidebar(
     sidebarMenu(
       menuItem("Notifications",    tabName="example",  icon=icon("table"))
     )
  ),
  dashboardBody(
    tabItems(
       tabItem(tabName="example",
        fluidRow(
          shiny::actionButton("set_notification", "Set Notification"),
          shiny::textInput("user_text", label="Notify Text Here", value="Notify me"),
          shiny::actionButton("show_notification", "Show Notification")
         )
       )
     )
   )
 )

# Main app server
server <- function(input, output, session) {

  # Need formods state object
  sess_res = UD_test_mksession(session, id="UD")

  # Captures input and sets the notification
  observeEvent(input$set_notification, {

    state = FM_fetch_mod_state(session, id="UD")
    state = FM_set_notification(state,
                                notify_text = isolate(input$user_text),
                                notify_id   = "example")
    FM_set_mod_state(session, id="UD", state)
   })


  # Displays the notification
  observeEvent(input$show_notification, {
    state = FM_fetch_mod_state(session, id="UD")
    FM_notify(state, session)
   })
}

shinyApp(ui, server)
}

Description

Any errors that need to be passed back to the user can be set with this function.

Usage

FM_set_ui_msg(state, msgs, append = FALSE)

Arguments

Value

state with ui message set.

Examples

# We need a module state object to use this function:
sess_res = UD_test_mksession()
state = sess_res$state
state = FM_set_ui_msg(state, "Something happend.")

Description

Attempts to execute the text in cmd. This is done in a try/catch environment to capture any errors.

Usage

FM_tc(cmd, tc_env, capture)

Arguments

Value

list with the following fields:

• isgood: Boolean indicating the whether the evaluation was successful.

• error: If the evaluation failed this contains the error object.

• msgs: Character vector of messages and/or errors.

• capture: List with names of objects to be captured and values corresponding to those captured objects.

Examples

# Successful command
res_good = FM_tc("good_cmd=ls()", list(), c("good_cmd"))
res_good

# Failed command
res_bad = FM_tc("bad_cmd =not_a_command()", list(), c("bad_cmd"))
res_bad

Description

Shiny apps can often make use of the same key elements, this package provides modules for common tasks (data upload, wrangling data, figure generation and saving the app state). These modules can react and interact as well as generate code to create reproducible analyses.

Author(s)

Maintainer: John Harrold [email protected] (ORCID)

See Also

https://formods.ubiquity.tools/

Description

Looks at the suggested dependencies and checks to make sure

Usage

formods_check(verbose = TRUE)

Arguments

Value

List with the following elements:

• all_found: Boolean indicating if all packages were found

• found_pkgs: Character vector of found packages

• missing_pkgs: Character vector of missing packages