Configuration


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-INFO] 2021-04-12 11:43:17 Start to create a new SPS project
## [SPS-INFO] 2021-04-12 11:43:17 Create project under /tmp/Rtmp0DT2yS/config_demo
## [SPS-INFO] 2021-04-12 11:43:17 Now copy files
## [SPS-INFO] 2021-04-12 11:43:17 Create SPS database
## [SPS-INFO] 2021-04-12 11:43:17 Created SPS database method container
## [SPS-INFO] 2021-04-12 11:43:17 Creating SPS db...
## [SPS-DANGER] 2021-04-12 11:43:17 Done, Db created at '/tmp/Rtmp0DT2yS/config_demo/config/sps.db'. DO NOT share this file with others or upload to open access domains.
## [SPS-INFO] 2021-04-12 11:43:17 Key md5 e55c4f696d0b55d79a13732f75c7ad0b
## [SPS-INFO] 2021-04-12 11:43:17 SPS project setup done!
## save project path 
(sps_dir <- file.path(tempdir(), "config_demo"))
## [1] "/tmp/Rtmp0DT2yS/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 if you don't know  
│   ├── sps.db             | SPS database 
│   ├── sps_options.yaml   | SPS default option list 
│   └── tabs.csv           | SPS tab information 
├── data                   | App example data files 
│   ├── xx.csv             
├── R                      | All SPS additional tab files and helper R function files 
│   ├── tab_xx.R            
├── README.md              
├── results                | Not in use for this current version, you can store some data been generated from the app 
│   └── README.md          
└── www                    | Internet resources  
    ├── about              | About tab information 
    │   └── xx.md          
    ├── 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. Please read the Developer sections.
    • sps_options.yaml stores all default and valid values for SPS.
    • tabs.csv all SPS tab registration information.
    • sps.db A SQLite database to store data generated in SPS. Since we have the new Canvas module which is purely client-side served, this database is not heavily used. However, it provides you some tables storing project information and a SHA key pair in case you want to encrypt password or files. Read Developer sections 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.
  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

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 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: TRUE 
##     Other: FALSE 
## login_theme:
##     Default: vhelix 
##     Other: * 
## use_crayon:
##     Default: TRUE 
##     Other: FALSE 
## verbose:
##     Default: FALSE 
##     Other: TRUE 
## admin_page:
##     Default: FALSE 
##     Other: TRUE 
## admin_url:
##     Default: admin 
##     Other: * 
## warning_toast:
##     Default: TRUE 
##     Other: FALSE 
## 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 
## * 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: 
## verbose:
##     FALSE 
## use_crayon:
##     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
))

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”
warning_toast show security warnings? TRUE FALSE
loading_screen show loading screen? TRUE FALSE
loading_theme loading screen theme “vhelix” any string
use_crayon colorful console message? TRUE FALSE
verbose more details for SPS functions? FALSE TRUE
admin_page show 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
app_path hidden, automatically added N.A. N.A.

Some details

  • mode: this option will change how the upload files are selected.
    • local: You can choose file from server side, and it is a direct link, no file will be copied to server. Most often used when you are on you own computer. It is still choosing files from the server side, because you are using your own computer as a Shiny server.
    • server: Choose files from the client side, and upload as a temp file to the server.
    • If you are on you own computer, there is no difference, but local mode can avoid copy your files to temp. If you are deploying the app to cloud, please use server mode
    • Functions directly associated with this option are dynamicFile and dynamicFileServer. We will discuss details in Developer sections
  • warning_toast: A toast pop-up message when you are under some dangerous options when app starts (For internal testing only under current version).
  • loading_theme: loading_screen must be TRUE. Only one theme for now, we will add more in future.
  • 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.
  • admin_url (disabled in current version): the admin page URL, admin_page must be TRUE for it to work. It will be added in an upcoming version, a preview can be seen by adding “/?admin” to the end of app url, e.g. “https://tgirke.shinyapps.io/systemPipeShiny/?admin”.

get/set option values

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] FALSE

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

session info

sessionInfo()
## R version 4.0.3 (2020-10-10)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 18.04.5 LTS
## 
## Matrix products: default
## BLAS:   /usr/lib/x86_64-linux-gnu/blas/libblas.so.3.7.1
## LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.7.1
## 
## locale:
##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
##  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8    
##  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
##  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
##  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] systemPipeShiny_1.1.30 drawer_0.1.0.9         spsComps_0.1.9.99     
## [4] spsUtil_0.1.0.9        shiny_1.6.0.9000      
## 
## loaded via a namespace (and not attached):
##  [1] httr_1.4.2               sass_0.3.1               shinyFiles_0.9.0        
##  [4] tidyr_1.1.2              bit64_4.0.5              vroom_1.3.2             
##  [7] jsonlite_1.7.2           viridisLite_0.3.0        bslib_0.2.4             
## [10] assertthat_0.2.1         askpass_1.1              blob_1.2.1              
## [13] yaml_2.2.1               backports_1.2.1          pillar_1.5.0            
## [16] RSQLite_2.2.3            glue_1.4.2               digest_0.6.27           
## [19] promises_1.1.1           colorspace_2.0-0         htmltools_0.5.1.1       
## [22] httpuv_1.5.5             pkgconfig_2.0.3          bookdown_0.21.6         
## [25] purrr_0.3.4              xtable_1.8-4             scales_1.1.1            
## [28] later_1.1.0.1            tibble_3.1.0             openssl_1.4.3           
## [31] styler_1.3.2             generics_0.1.0           ggplot2_3.3.3           
## [34] ellipsis_0.3.1           DT_0.17                  shinyjs_2.0.0           
## [37] cachem_1.0.1             lazyeval_0.2.2           magrittr_2.0.1          
## [40] crayon_1.4.1             mime_0.9                 memoise_2.0.0           
## [43] evaluate_0.14            shinytoastr_2.1.1        fs_1.5.0                
## [46] fansi_0.4.2              shinydashboard_0.7.1     blogdown_1.2            
## [49] tools_4.0.3              data.table_1.13.6        lifecycle_1.0.0         
## [52] stringr_1.4.0            plotly_4.9.3             munsell_0.5.0           
## [55] shinyAce_0.4.1           compiler_4.0.3           jquerylib_0.1.3         
## [58] rlang_0.4.10             shinyjqui_0.3.3          grid_4.0.3              
## [61] shinydashboardPlus_2.0.0 rstudioapi_0.13          htmlwidgets_1.5.3       
## [64] rmarkdown_2.7.7          shinyWidgets_0.6.0       gtable_0.3.0            
## [67] DBI_1.1.1                R6_2.5.0                 lubridate_1.7.9.2       
## [70] knitr_1.31               dplyr_1.0.3              fastmap_1.1.0           
## [73] bit_4.0.4                utf8_1.1.4               bsplus_0.1.2            
## [76] stringi_1.5.3            Rcpp_1.0.6               vctrs_0.3.6             
## [79] tidyselect_1.1.0         xfun_0.22
Last modified 0001-01-01