README.md
In KopfLab/isoviewer: Visualize IRMS data

isoviewer

The isoviewer graphical user interface (GUI) provided by this package is based on the functionlity implemented by the isoreader and isoprocessor packages The purpose of the GUI is two fold.

First and foremost, it is a learning tool to illustrate how to build literate RMarkdown data processing files for IRMS data using the underlying isoreader package as a unified interface for reading, converting and quickly visualizing various raw IRMS data file formats.

The second purpose is to provide an example for a web-based IRMS data repository that is easy to run on any computer/server completely platform-independent and open-source. The isoviewer package provides some rudimentary GUI modules that could be used in other more customized applications.

isoviewer is still in development and not yet available on the Comprehensive R Archive Network (CRAN) but it and its dependencies can be installed from GitHub using the devtools package:

# installs the development tools package if not yet installed
if(!requireNamespace("devtools", quietly = TRUE)) install.packages("devtools")
devtools::install_github("isoverse/isoprocessor")
devtools::install_github("isoverse/isoviewer")

Once isoviewer is installed, you can launch the user interface on your local machine by using the iso_start_viewer() function which will search for all iso file objects in your workspace and make them accessible through the graphical interface.

isoviewer::iso_start_viewer()

Troubleshooting: if you run into any issues with the viewer crashing unexpectedly and getting stuck during restart. Try resetting it with isoviewer::iso_start_viewer(reset = TRUE). Also, please consider reporting the details of the crash at https://github.com/isoverse/isoviewer/issues.

To run a local isoviewer server to which other users on your network can connect, simply use the iso_start_viewer_server() server function and direct others to your IP address, port 3838 (for example 192.168.0.42:3838). Note that this won’t work if your firewall or local network block port 3838. Keep the R session open as long as you want to run the server and stop by it by pressing Esc or closing your R/RStudio session.

isoviewer::iso_start_viewer_server()

To run a web server with your isofiles (e.g. on www.shinyapps.io), create a new R project folder with a script file called app.R at the top level (= working directory) of the project. In this file, add the following code and adjust which iso objects to make available in the viewer GUI. Note that for your app to launch quickly when a user connects, it is higly recommended to load only .rds collections of iso files (i.e. save your iso objects via isoreader’s iso_save() function and then load them from there for your isoviewer server). To test the server, launch it on your own computer by running shiny::runApp() from the R console in your project. To deploy this app e.g. to www.shinyapps.io, follow their instructions to get your rsconnect credentials set up and then simply run rsconnect::deployApp() from the R console in your project. Note that the bioconductor packages used by isoreader sometimes cause trouble during the upload, in which case you may have to explicitly re-install them before deploying your app (e.g. by using BiocManager::install()) and setting the bioconductor repositories using options(repos = BiocManager::repositories()).

# start isoviewer server
library(isoreader)
isoviewer::iso_start_viewer_server(
  # provide a list of objects to make accessible
  iso_objects = list(
    di_example = iso_read_dual_inlet("di_example.di.rds"),
    cf_example = iso_read_continuous_flow("cf_example.cf.rds"),
    scan_example = iso_read_scan("scan_example.scan.rds")
  ),
  # make sure it doesn't launch on its own
  launch = FALSE
)

This code example is actually the one available as the online demo below.

Online Demo

An online demo of the isoviewer GUI is available on our server but has limited computational resources (i.e. could be slow).

isoviewer is and will always be fully open-source (i.e. free as in ‘freedom’ and free as in ‘free beer’) and is provided as is. The source code is released under GPL-2.