Contents

1 Overview

The levi (Landscape Expression Visualization Interface) is a package for the R environment, developed to enable the visualization of the projection of gene expression on a biological network. levi is based on two other software, the first is the Viacomplex ((???)), which was written in Fortran using the Dislin library to plot the data. The second is Galant ((???)), which corresponds to a plugin for Cytoscape software.

Two files are required to use levi: The file containing the expression levels of the genes and a file containing the biological network.

2 Files

2.1 Gene Expression Levels

This file should contain the genes of interest previously normalized by the user. The expression file (see Example) must have a column with the identification of genes (Gene Symbol, Entrez, etc.) and at least one column with gene expression levels (treatment, case, control, etc.). The user can compare the expression levels between samples if there are more columns containing these data.

If the expression file does not have values for all the genes of the network, a message will be displayed showing log file path to a temporary directory with the gene names. In the landscape construction, genes with no expression value will be displayed with values close to 0.5 demonstrating that there were no changes (down-regulated or up-regulated genes).

Data sets of gene expression can be obtained from online databases:

2.2 Biological Network

The levi supports several extensions of biological network files (*.net, *.dyn, *.txt, *.dat). The user should build the biological network using specific tools such as: Cytoscape, RedeR, Medusa, etc. To build the biological network is recommended the obtention of interaction data/ biological associations from online repositories:

Extension File Type Link
dat Medusa (DAT) Example DAT
dyn RedeR (DYN) Example DYN
net Pajek (NET) Example NET
stg STRING / STITCH Example coordinates
stg STRING / STITCH Example interactions

#Viewing Modes

levi has two viewing modes: Graphical User Interface (GUI) and script.

2.3 Graphical User Interface (GUI)

The GUI mode was developed using Shiny package (Figure 1). This viewing mode can be used in the R environment (browser=FALSE) or in the user’s default operating system browser (browser=TRUE).

library(levi)
LEVIui(browser=TRUE)  #Launch Levi to Browser.
LEVIui(browser=FALSE) #Launch Levi to R environment.
Figure 2: Graphical User Interface (GUI).
  • 1 - Tabs
    • File - General options for uploading the data files.
    • Settings - Options to build the landscape.
  • 2 - Network input type: - Selection of the biological network input format. The options are available on the table 1.
  • 3 - Upload the network file - Input button to select the biological network file.
  • 4 - Upload the expression file - Input button to select the gene expression levels file.
  • 5 - Expression values in log scale - select when there is low variation between expression data
  • 6 - Selected fields - Selecting the type of analysis. Comparison between two samples or a single sample.
  • 7 - Select gene symbol field - Selection of the gene ID contained in the gene expression levels file. The gene ID in the biological network file must be the same in the gene expression levels file. Select test field
  • Select the case/test sample. Select control field - Select the control sample. If levi detects the case/test sample and control sample as equal, then levi will apply the “single sample” analysis.
  • 8 - Chart Colors - Color palette to build the landscape. There is two options the Multicolor has 20 color levels combined. The Two colors has two categories of color palettes, multicolor and two colors. For the selection of two colors the available options are: purple_pink, green_blue, blue_yellow, pink_green, orange_purple, green_marine. Both of them is targeted to show the biological network with higher expression. (Figure 3 and Figure 4).
  • 9 - Chart with contour - Enable or disable the contour lines in the landscape.
  • 10 - landscape Image display area. The user can select specific areas of the image to inspect the gene name and position.
  • 11 - Expression area: - Total expression value of the selected area in the image.
  • 12 - Download options
    • File format to landscape - Select the output format of the landscape. The options available are: TIFF, BMP, JPEG and PNG. We recommend using this option in the browser.
    • Download Plot - Button to save the file.
  • 13 - Visualization of gene name and expression value of the selected area in the landscape. The user can save the table in a csv file (button Download Data)
  • 14 - Settings
    • Contrast - Constrast value in the landscape. The variable range is 1 to 100. The default value is 50.
    • Resolution - Image size of the landscape. The variable range is 1 to 100. The default value is 50. If this parameter is higher, then the total time required will be longer.
    • Smoothing - Smoothing of the landscape. The variable range is 1 to 100. The default value is 50.I f this parameter is higher, then the total time required will be longer.
    • Zoom - Zoom value for the landscape. The variable range is 1 to 100. The default value is 50.

2.4 Script

The levi scripting mode also has the settings for landscape building (see example below).

library(levi)

template_network <- file.path(system.file(package="levi"),"extdata",
                                "medusa.dat", fsep = .Platform$file.sep)

template_expression <- file.path(system.file(package="levi"),
                                "extdata","expression.dat", 
                                fsep = .Platform$file.sep)

multicolor <- levi(networkCoordinatesInput = template_network,
                expressionInput = template_expression, fileTypeInput = "dat",
                geneSymbolnput = "ID", 
                readExpColumn=
                readExpColumn("TumorCurrentSmoker-NormalNeverSmoker"), 
                contrastValueInput = 50, resolutionValueInput  = 50, 
                zoomValueInput = 50, smoothValueInput = 50, contourLevi = TRUE)
## Coordinate system already present. Adding new coordinate system, which will replace the existing one.

twocolors <- levi(networkCoordinatesInput = template_network,
                expressionInput = template_expression, fileTypeInput = "dat",
                geneSymbolnput = "ID", 
                readExpColumn=
                readExpColumn("TumorCurrentSmoker-NormalNeverSmoker"),
                setcolor = "pink_green", contourLevi = FALSE)
## Coordinate system already present. Adding new coordinate system, which will replace the existing one.

The script mode allows the user to compare combinations between two experiments in the gene expression levels file. The readExpColumn function can be used to this task to inform the combination separating by dash (-) and to add more combinations separate by comma (,).

library(levi)
base <- readExpColumn("TumorFormerSmoker-NormalFormerSmoker", 
                        "TumorNeverSmoker-TumorNeverSmoker")

template_network <- file.path(system.file(package="levi"),"extdata",
                                "medusa.dat", fsep = .Platform$file.sep)

template_expression <- file.path(system.file(package="levi"),
                                "extdata","expression.dat", 
                                fsep = .Platform$file.sep)

multicolor <- levi(networkCoordinatesInput = template_network,
                    expressionInput = template_expression, 
                    fileTypeInput = "dat",
                    geneSymbolnput = "ID", readExpColumn= base, 
                    contrastValueInput = 50, resolutionValueInput  = 50, 
                    zoomValueInput = 50, smoothValueInput = 50, 
                    contourLevi = FALSE)
## Coordinate system already present. Adding new coordinate system, which will replace the existing one.
## Coordinate system already present. Adding new coordinate system, which will replace the existing one.

twocolors <- levi(networkCoordinatesInput = template_network,
                expressionInput = template_expression, fileTypeInput = "dat",
                geneSymbolnput = "ID", 
                readExpColumn= base,
                setcolor = "pink_green", contourLevi = FALSE)
## Coordinate system already present. Adding new coordinate system, which will replace the existing one.
## Coordinate system already present. Adding new coordinate system, which will replace the existing one.

3 Session information

## R version 4.2.1 (2022-06-23)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 20.04.5 LTS
## 
## Matrix products: default
## BLAS:   /home/biocbuild/bbs-3.16-bioc/R/lib/libRblas.so
## LAPACK: /home/biocbuild/bbs-3.16-bioc/R/lib/libRlapack.so
## 
## locale:
##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
##  [3] LC_TIME=en_GB              LC_COLLATE=C              
##  [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] levi_1.16.0      BiocStyle_2.26.0
## 
## loaded via a namespace (and not attached):
##  [1] tidyselect_1.2.0     xfun_0.34            bslib_0.4.0         
##  [4] shinyjs_2.1.0        reshape2_1.4.4       testthat_3.1.5      
##  [7] colorspace_2.0-3     vctrs_0.5.0          generics_0.1.3      
## [10] htmltools_0.5.3      yaml_2.3.6           utf8_1.2.2          
## [13] rlang_1.0.6          isoband_0.2.6        jquerylib_0.1.4     
## [16] pillar_1.8.1         later_1.3.0          withr_2.5.0         
## [19] glue_1.6.2           DBI_1.1.3            RColorBrewer_1.1-3  
## [22] lifecycle_1.0.3      plyr_1.8.7           stringr_1.4.1       
## [25] munsell_0.5.0        gtable_0.3.1         htmlwidgets_1.5.4   
## [28] evaluate_0.17        labeling_0.4.2       knitr_1.40          
## [31] fastmap_1.1.0        httpuv_1.6.6         fansi_1.0.3         
## [34] highr_0.9            Rcpp_1.0.9           xtable_1.8-4        
## [37] scales_1.2.1         promises_1.2.0.1     DT_0.26             
## [40] BiocManager_1.30.19  cachem_1.0.6         magick_2.7.3        
## [43] jsonlite_1.8.3       farver_2.1.1         mime_0.12           
## [46] brio_1.1.3           ggplot2_3.3.6        digest_0.6.30       
## [49] stringi_1.7.8        bookdown_0.29        dplyr_1.0.10        
## [52] shiny_1.7.3          grid_4.2.1           cli_3.4.1           
## [55] tools_4.2.1          magrittr_2.0.3       sass_0.4.2          
## [58] tibble_3.1.8         pkgconfig_2.0.3      ellipsis_0.3.2      
## [61] xml2_1.3.3           shinydashboard_0.7.2 assertthat_0.2.1    
## [64] rmarkdown_2.17       httr_1.4.4           R6_2.5.1            
## [67] igraph_1.3.5         compiler_4.2.1

4 Reference