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-08-06 16:56:40 Done, Db created at '/tmp/RtmpO13I8T/config_demo/config/sps.db'. DO NOT share this file with others or upload to open access domains.
## [SPS-INFO] 2021-08-06 16:56:40 Key md5 438dacd911e5308b8ba0b5dbb3d16128
## [SPS-INFO] 2021-08-06 16:56:40 SPS project setup done!

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

## [1] "/tmp/RtmpO13I8T/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   
├── ui.R                   |  
├── deploy.R               | Deploy helper file  
├── config                 | Important app config files. Do not edit them 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 custom tab files and helper R function files 
│   ├── tab_xx.R            
├── README.md              
├── results                | To store data generated from the app, like the workflow module 
│   └── 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 plot gallery  
        └── 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 legend:
##     known options        Hidden/custom options* and values+
## Value legend:
##     same as default values        different from defaults+

A copy of options in global.R:

options(sps = 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.