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-04-25 19:43:24 Done, Db created at '/tmp/RtmphrNOOX/config_demo/config/sps.db'. DO NOT share this file with others or upload to open access domains.
## [SPS-INFO] 2021-04-25 19:43:24 Key md5 ee81377a81fdb757fbbbb6af38644756
## [SPS-INFO] 2021-04-25 19:43:24 SPS project setup done!
## save project path 
(sps_dir <- file.path(tempdir(), "config_demo"))
## [1] "/tmp/RtmphrNOOX/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.

OptionDescriptionDefaultOther
moderunning mode“local”“server”
titleApp title“systemPipeShiny”any string
title_logoApp logo to display on browser tab“img/sps_small.png”any path
warning_toastshow security warnings?TRUEFALSE
login_screenadd login screen?TRUEFALSE
login_themelogin screen theme“random”see details
use_crayoncolorful console message?TRUEFALSE
verbosemore details for SPS functions?FALSETRUE
admin_pageenable admin page?FALSETRUE
admin_urladmin_page query url“admin”any string
warning_toastfor internal test onlyTRUEFALSE
module_wfload workflow module?TRUEFALSE
module_rnaseqload RNAseq module?TRUEFALSE
module_ggplotload quick ggplot module?TRUEFALSE
tab_welcomeload welcome tab?TRUEFALSE
tab_vs_mainload custom visualization main tab?TRUEFALSE
tab_canvasload Canvas tab?TRUEFALSE
tab_aboutload about tab?TRUEFALSE
note_urlSPS notification remote URLsee code aboveany URL
is_demouseful if deploy the app as a demoFALSETRUE
welcome_guideenable the welcome guideTRUEFALSE
app_pathhidden, automatically addedN.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-10-10: Bot build site (d0c34823)