Configuration

SPS has many options you can change. These options will determine how the app behaves.

Config SPS

Let us start by creating an example SPS project. For demo purpose, we are using the /tmp folder but one should use a regular location instead of the temp in a real case.

suppressPackageStartupMessages(library(systemPipeShiny))
spsInit(app_path = tempdir(), project_name = "config_demo", overwrite = TRUE, change_wd = FALSE)

## [SPS-DANGER] 2021-12-15 00:08:50 Done, Db created at '/tmp/Rtmpgas05w/config_demo/config/sps.db'. DO NOT share this file with others or upload to open access domains.
## [SPS-INFO] 2021-12-15 00:08:50 Key md5 405b200ceb5c90dbb5c097c88d582dcb
## [SPS-INFO] 2021-12-15 00:08:50 SPS project setup done!

## save project path 
(sps_dir <- file.path(tempdir(), "config_demo"))

## [1] "/tmp/Rtmpgas05w/config_demo"

To reproduce code locally, run the following chunk instead.

library(systemPipeShiny)
spsInit()
sps_dir <- normalizePath(".")

SPS structure

SPS_xx/  
├── server.R               | 
├── global.R               | Most important server, UI and global files, unless special needs, `global.R` is the only file you need to edit manually   
├── ui.R                   |  
├── deploy.R               | Deploy helper file  
├── config                 | Important app config files. Do not edit them by hand if you don't know  
│   ├── sps.db             | SPS database 
│   ├── sps_options.yaml   | SPS default option list 
│   └── tabs.csv           | SPS tab registration information 
├── data                   | App example data files 
│   ├── xx.csv             
├── R                      | All SPS additional tab files, helper R function, interactive guides files 
│   ├── tab_xx.R            
├── README.md              
├── results                | Not in use for this current version, but you can store some data been generated from the app 
│   └── README.md          
└── www                    | Internet resources  
    ├── css                | CSS files  
    │   └── sps.css         
    ├── img                | App image resources    
    │   └── xx.png         
    ├── js                 | Javascripts
    │   └── xx.js           
    ├── loading_themes     | Loading screen files 
    │   └── xx.html         
    └── plot_list          | Image files for custom visualization tab thumbnails  
        └── plot_xx.jpg

This is a reminder of what you will get when a SPS project is initiated with spsInit().

  1. For most users, the global.R file is the only file that one needs to make change.
  2. The second important files are the files inside config folder. For normal users, these files are controlled by SPS functions. No need to make any modification. For advanced users, deep customization is possible.
    • sps_options.yaml stores all default and valid values for SPS, details are listed below
    • tabs.csv all SPS tab registration information. Read Manage tabs
    • sps.db A SQLite database to store data generated in SPS. Read SPS database for more information.
  3. R folder stores all custom tab files, your helper functions. This .R or .r files under this folder will be automatically sourced when SPS starts. This is discussed in Manage tabs.
  4. www folder is where you add the internet resources, like images you want to show in the app, css style sheets to attach. Read more here.

App options

View/Set all options

App options in SPS are controlled by “SPS options”. These options can change app appearance, debugging level, server behaviors, etc. The valid options can be found and change on the global.R file. They are similar to Shiny options, but unlike shiny options that are single values, SPS options are passed using the Option(sps = list(...)) function in global.R as a group. To view all options and their default, valid values('*' means any value is okay) see global.R from the line starting with ## SPS options. We provided some comments below that line to generally describe what each option is and valid values for options. Use function spsOptDefaults to see the default and other valid options.

spsOptDefaults(app_path = sps_dir)

## title:
##     Default: systemPipeShiny 
##     Other: * 
## title_logo:
##     Default: img/sps_small.png 
##     Other: * 
## mode:
##     Default: local 
##     Other: server 
## login_screen:
##     Default: FALSE 
##     Other: TRUE 
## login_theme:
##     Default: random 
##     Other: * 
## use_crayon:
##     Default: TRUE 
##     Other: FALSE 
## verbose:
##     Default: FALSE 
##     Other: TRUE 
## admin_page:
##     Default: TRUE 
##     Other: FALSE 
## admin_url:
##     Default: admin 
##     Other: * 
## warning_toast:
##     Default: FALSE 
##     Other: TRUE 
## module_wf:
##     Default: TRUE 
##     Other: FALSE 
## module_rnaseq:
##     Default: TRUE 
##     Other: FALSE 
## module_ggplot:
##     Default: TRUE 
##     Other: FALSE 
## tab_welcome:
##     Default: TRUE 
##     Other: FALSE 
## tab_vs_main:
##     Default: TRUE 
##     Other: FALSE 
## tab_canvas:
##     Default: TRUE 
##     Other: FALSE 
## tab_about:
##     Default: TRUE 
##     Other: FALSE 
## note_url:
##     Default: https://raw.githubusercontent.com/systemPipeR/systemPipeShiny/master/inst/remote_resource/notifications.yaml 
##     Other: * 
## traceback:
##     Default: FALSE 
##     Other: TRUE 
## is_demo:
##     Default: FALSE 
##     Other: TRUE 
## welcome_guide:
##     Default: TRUE 
##     Other: FALSE 
## * means any value will be accepted

After the app has started once, you can use spsOptions() to see all current settings.

spsOptions(app_path = sps_dir)

## Current project option settings: 
## title:
##     systemPipeShiny 
## title_logo:
##     img/sps_small.png 
## mode:
##     local 
## login_screen:
##     FALSE 
## login_theme:
##     random 
## use_crayon:
##     TRUE 
## verbose:
##     FALSE 
## admin_page:
##     TRUE 
## admin_url:
##     admin 
## warning_toast:
##     FALSE 
## module_wf:
##     TRUE 
## module_rnaseq:
##     TRUE 
## module_ggplot:
##     TRUE 
## tab_welcome:
##     TRUE 
## tab_vs_main:
##     TRUE 
## tab_canvas:
##     TRUE 
## tab_about:
##     TRUE 
## note_url:
##     https://raw.githubusercontent.com/systemPipeR/systemPipeShiny/master/inst/remote_resource/notifications.yaml 
## traceback:
##     FALSE 
## is_demo:
##     FALSE 
## welcome_guide:
##     TRUE 
## ********
## Option legends:
##     known options        Hidden/custom options* and values+
## Value legends:
##     same as default values        different from defaults+

A copy of options in global.R:

spsOption(.list = list(
    title = "systemPipeShiny",
    title_logo = "img/sps_small.png",
    mode = "local",
    warning_toast = FALSE,
    login_screen = FALSE,
    login_theme = "random",
    use_crayon = TRUE,
    verbose = FALSE,
    admin_page = TRUE,
    admin_url = "admin",
    note_url = 'https://raw.githubusercontent.com/systemPipeR/systemPipeShiny/master/inst/remote_resource/notifications.yaml',
    tab_welcome = TRUE,
    tab_vs_main = TRUE,
    tab_canvas = TRUE,
    tab_about = TRUE,
    module_wf = TRUE,
    module_rnaseq = TRUE,
    module_ggplot = TRUE,
    traceback = FALSE,
    is_demo = FALSE,
    welcome_guide = TRUE
))

Note: Do not worry if you set some invalid values, on app start, `sps()` will check all SPS options, ignore unknown values and set invalid values back to default. You will see warning messages on console to tell you specifically what is wrong with your options.

Option Description Default Other
mode running mode “local” “server”
title App title “systemPipeShiny” any string
title_logo App logo to display on browser tab “img/sps_small.png” any path
warning_toast show security warnings? TRUE FALSE
login_screen add login screen? TRUE FALSE
login_theme login screen theme “random” see details
use_crayon colorful console message? TRUE FALSE
verbose more details for SPS functions? FALSE TRUE
admin_page enable admin page? FALSE TRUE
admin_url admin_page query url “admin” any string
warning_toast for internal test only TRUE FALSE
module_wf load workflow module? TRUE FALSE
module_rnaseq load RNAseq module? TRUE FALSE
module_ggplot load quick ggplot module? TRUE FALSE
tab_welcome load welcome tab? TRUE FALSE
tab_vs_main load custom visualization main tab? TRUE FALSE
tab_canvas load Canvas tab? TRUE FALSE
tab_about load about tab? TRUE FALSE
note_url SPS notification remote URL see code above any URL
is_demo useful if deploy the app as a demo FALSE TRUE
welcome_guide enable the welcome guide TRUE FALSE
app_path hidden, automatically added N.A. N.A.

Details

  • mode: see [App security] this option will change how the upload files are selected.
  • title & title_logo: see [Other customizations]
  • warning_toast: see [App security], A toast pop-up message to help you check pre-deploy for security problems.
  • login_screen & login_theme & admin_page & admin_url: see [Accounts, Login and Admin].
  • verbose: Give you more information on debugging. Most SPS core functions has this option. If it is on, more debugging information will be printed on console. See [Debugging]
  • module_xx – tab_xx: see [Toggle tabs] for loading and unloading tabs.
  • tab_xx: see [Overwrite tabs] for customizing core SPS default tabs.
  • note_url: see [Notification system] for customizing SPS notifications.
  • is_demo: see [Workflow module].
  • welcome_guide: whether to enable the welcome guide on app start, see first image on SPS guide.
  • app_path: a hidden option. This will be added after the app starts. If not specified in sps(), use current working directory.

View/Set a single option

SPS values are globally set, which means you can get/change the these options at inside any R code, R functions and while the app is running (change options after app started is not recommended).

To view a single option value, use spsOption(opt = "OPTION_NAME"); to overwrite a single option, use spsOption(opt = "OPTION_NAME", value = "NEW_VALUE").

spsOption(opt = "mode")

## [1] "local"

To overwrite the “mode” option:

spsOption(opt = "mode", "local")

Check again, the value has changed to “local”:

spsOption(opt = "mode")

## [1] "local"

If any option does not exist, or the value is “empty” or 0, when getting the value spsOption will return FALSE. Common “empty” values:

  • NA
  • NULL
  • length(value) == 0
  • "" (empty string)

Read the help file of ?emptyIsFalse for more information.

spsOption(opt = "random_opt")

## [1] FALSE

However, these “empty” values can be meaningful in some cases, so use empty_is_false = FALSE to return the original value instead of FALSE

spsOption(opt = "random_opt", empty_is_false = FALSE)

## NULL

Add your own options

SPS is very flexible which allows you to add your own options. To do so, you need to edit the “config/sps_options.yaml” file under your project root.

You can use other options as templates to add more. There are two required entries:

  • default: will be used as default when you load SPS package.
  • other: Other valid options. If your user provided a value that is other than the default or the other, SPS will show warnings and use default instead. You can write "*" as the other value. It means any value will be accepted. SPS will skip to check other valid values for this option.

Currently, the default value can only be length of 1 but other value can be a yaml array, which use [] to define: [value1, value2, ...].

For example, we can add some but opening the file with a text editor, here we do it programmatically:

new_options <- 
'
my_opt1:
    default: true
    other: [false]

my_opt2:
    default: "a"
    other: ["*"]
'
write(x = new_options, file = file.path(sps_dir, "config", "sps_options.yaml"), append = TRUE)

Then we can use spsOptDefaults to check

spsOptDefaults(app_path = sps_dir)

## title:
##     Default: systemPipeShiny 
##     Other: * 
## title_logo:
##     Default: img/sps_small.png 
##     Other: * 
## mode:
##     Default: local 
##     Other: server 
## login_screen:
##     Default: FALSE 
##     Other: TRUE 
## login_theme:
##     Default: random 
##     Other: * 
## use_crayon:
##     Default: TRUE 
##     Other: FALSE 
## verbose:
##     Default: FALSE 
##     Other: TRUE 
## admin_page:
##     Default: TRUE 
##     Other: FALSE 
## admin_url:
##     Default: admin 
##     Other: * 
## warning_toast:
##     Default: FALSE 
##     Other: TRUE 
## module_wf:
##     Default: TRUE 
##     Other: FALSE 
## module_rnaseq:
##     Default: TRUE 
##     Other: FALSE 
## module_ggplot:
##     Default: TRUE 
##     Other: FALSE 
## tab_welcome:
##     Default: TRUE 
##     Other: FALSE 
## tab_vs_main:
##     Default: TRUE 
##     Other: FALSE 
## tab_canvas:
##     Default: TRUE 
##     Other: FALSE 
## tab_about:
##     Default: TRUE 
##     Other: FALSE 
## note_url:
##     Default: https://raw.githubusercontent.com/systemPipeR/systemPipeShiny/master/inst/remote_resource/notifications.yaml 
##     Other: * 
## traceback:
##     Default: FALSE 
##     Other: TRUE 
## is_demo:
##     Default: FALSE 
##     Other: TRUE 
## welcome_guide:
##     Default: TRUE 
##     Other: FALSE 
## my_opt1:
##     Default: TRUE 
##     Other: FALSE 
## my_opt2:
##     Default: a 
##     Other: * 
## * means any value will be accepted

You can see the my_opt1 and my_opt2 have been added to SPS options.

Last modified 2021-12-15 : sps updates no_render (9924dd38)