Requirements

enviMass is a software package to be run locally from the R statistical environment, including a browser-based interface to facilitate its usage.

enviMass is mainly (but not exclusively) developed, tested and hence recommended for 64bit Windows 7 or later. For ease of installation, enviMass and all its R dependency packages can thus be downloaded for 64bit Windows as described in the below installation option 1. In addition, installations for 32bit Windows or other OS may retrieve enviMass from its GitHub repository, as exemplified for Windows 32bit in the installation options 2 and 3. Please read the installation instructions carefully and adhere to them.

enviMass requires installed R version 3.3.3 and the latest version of a web-browser (preferably Firefox), both freely available. A memory minimum of 16GB RAM is highly recommended; the more and the larger files analyzed, the more RAM will be required though. You must be online for installation and when accessing certain help pages and internal data sets thereafter. Ensure you have administrator rights on your computer and write/read access to all concerned folders, both during installation and also when running enviMass.

Updates on enviMass beta v3.3:31.08.17 / Replicate profiling patch.

Installation - option 1

  1. Download the freely available Windows R statistical environment version 3.3.3 (not to be confused with RStudio) and install it on your computer:

    → R v3.3.3

  2. Have the the latest version of, e.g., Firefox or Google Chrome installed on you computer and set as default browser.

  3. Download the

    → enviMass_packages.zip folder

    containing all required enviMass and dependency R packages for 64bit Windows (99MB).

  4. Unzip/extract that folder (but not the library folders contained therein); you may need to install a zip-program first (e.g., →7zip).

  5. Open R as administrator by, e.g., RIGHT-clicking on its x64 desktop icon (select 'Run as administrator') - the R console pops up. In the console, navigate to Packages and then Install package(s) from local files to get to a Select files menu. With this menu, navigate to the unzipped packages and select all packages in that folder to be opened, i.e., installed (you can use the shift key to select all these zip-files at once). (If a message with '...install into your personal library instead' appears, you are not running R as adiministrator; abort)

  6. enviMass and all its dependency packages should now have been locally installed into the R library folder and the enviMass user interface (UI) available. Simply, in the R console type&enter:

    library(enviMass)
    webMass()

    The enviMass library should thereby be loaded into R and its user interface should appear in your web-browser.

Updating

From time to time, enviMass or the packages it depends on may change as software gets updated or debugged. To update enviMass and its dependencies for 64bit Windows 7 or later, simply repeat steps (3) to (6) of the above installation option 1. Please also ensure to have the latest R and browser versions installed; repeat all the steps of the above installation option 1 to update these as well.

Installation - option 2

For downloading and installing enviMass on any other system, you may do the following (Windows 32 bit example):

  1. Download the freely available Windows R statistical environment version 3.3.3 (not to be confused with RStudio) and install it on your computer:

    → R v3.3.3

  2. Have the the latest version of, e.g., Firefox or Google Chrome installed on you computer and set as default browser.

  3. Have the latest version of Rtools installed from http://cran.r-project.org/bin/windows/Rtools/. During the Rtools installation, make sure to check “edit system PATH” (this will enable your computer to access Rtools from within R).

  4. Open R (not to be confused with R studio) as administrator by RIGHT-clicking on its icon (select 'run as adiminstrator') - the R console pops up. Copy&paste the following command into the console and press enter:

    install.packages(c("devtools","enviPick", "enviPat", "nontarget", "mgcv", "htmlTable", "networkD3","shiny","shinyFiles","shinyBS","DT", "shinyjs", "shinytoastr", "plotly", "MASS"),dependencies=TRUE)

    Choose any mirror you like if being asked. This installs most of the packages enviMass depends on and can take several minutes (in rare cases, you will be asked if you want to install packages in personal libraries - check the below troubleshooting section).

  5. Together with the above Rtools, you can now easily download, compile and install enviMass and other latest dependencies from their GitHub repository. To do so, copy&paste the following two commands into the R console (ignore warnings during installation, if any):

    library(devtools)
    install_github("blosloos/enviPick",dependencies=TRUE)
    install_github("blosloos/enviPat",dependencies=TRUE)
    install_github("blosloos/nontarget",dependencies=TRUE)
    install_github("blosloos/enviMass",dependencies=TRUE)

    enviMass and all its dependency packages are thereby locally installed into the R library folder (again, freely choose a mirror for these dependencies). Again, ensure you are eligible to write into the R library folder.

  6. Now, the enviMass user interface (UI) should be available. Simply, in the R console type&enter:

    library(enviMass)
    webMass()

Updating

From time to time, enviMass or the packages it depends on may change as software gets updated or debugged. To update enviMass installations resulting from the above installation option 2, repeat the steps (4) to (6). Please also ensure to have the latest R, Rtools and browser versions installed; repeat all the steps of the above installation option 2 to update these as well.

Installation - option 3

For situations with somewhat user-restricted web access, the above installation option 2 might fail for steps (5) and (6). In that case, try the following after having completed above steps (1) to (4) of the named installation option:

  1. In your webbrowser, visit https://github.com/blosloos/enviMass.

  2. With the green button "Clone or download", use "Download ZIP". Download the .zip file to a location of your choice and unzip it to a folder (you may need a zip-program such as 7zip). Let this folder be, e.g., C:/my_installations, thuse resulting in the unzipped folder C:/my_installations/enviMass-master.

  3. Open R (not to be confused with R studio) by clicking on its icon - the R Console pops up. Copy&paste the following commands into the R console (if asked, choose any R mirror you like; ignore warnings during installation, if any):

    library(devtools)
    install("C:/my_installations/enviMass-master",dependencies=TRUE)

  4. Repeat these steps (5) to (7) also for the repositories

    install_github("blosloos/enviPick",dependencies=TRUE)
    install_github("blosloos/enviPat",dependencies=TRUE)
    install_github("blosloos/nontarget",dependencies=TRUE)

  5. Now, the enviMass user interface (UI) should be available. Simply, in the R console type&enter:

    library(enviMass)
    webMass()

Updating

From time to time, enviMass or the packages it depends on may change as software gets updated or debugged. To update enviMass installations resulting from the above installation option 3, repeat the above steps (5) to (9). Please also ensure to have the latest R, Rtools and browser versions installed; repeat all the steps of the above installation options 2/3 to update these as well.

Troubleshooting

  • You have no administrator rights. Even if, you are not running R as administrator (try right-mouse click on R icon -> Run as administrator).

  • You have opened several R sessions in parallel. Close all, use only one while installing / updating.

  • You are confusing the specific updates for the different installation options.

  • You have other version of R than 3.3.3 and/or Rtools <3.4 and/or out-dated browsers (pre-)installed on your computer. Please update by repeating the above steps (1) to (3).

  • Sometimes, R packages are installed into personal libraries instead of the R library folder if you have no write access to the latter. This may not always result in problems. Nonetheless, avoid doing so. Instead, ensure you can write to the R library folder having appropriate administrator rights: under Windows, navigate to the R library folder (mostly C:/Program Files/R/R-X.X.X/library), right-mouse-click on the folder, select properties and adapt the settings in the security tab accordingly.

  • You keep on trying to install from within RStudio.

  • You cannot properly access the internet (or partly from within R during above step 4); consult your network administrator, check your firewall settings.

  • You have used backslash instead of forward slash in R path specifications. You have made typos in R.

  • On installation option 1 - check if any problems arise while the individual packages in the R console get installed - are any error messages reported, even just sporadically? If yes, unzip the packages and brutely copy/paste these to the R library folder directly (mostly to be found under C:/Program Files/R/R-X.X.X/library in Windows).

  • Still no clean installation achieved? Uninstall R (and Rtools if involved), delete the remaining R folders manually (mostly to be found under C:/Program Files/R/... in Windows - unfortunately often not removed automatically while uninstalling R) as well as any 'personal' Windows user R libraries (mostly to be found under sth like XY:\Users\User_XY\Documents\R\win-library). Please repeat the installation (inclusive of renewed downloads) and make sure you adhere to all instructions (administrator rights, no RStudio, 64bit vs. 32bit, no shifting between installation options or unrelated updates, ...).

  • You could install enviMass, but upon starting the interface via webMass() a time-out error message appears before the enviMass interface has been loaded in your browser? This may have different reasons. First, check the timeout-configurations both in your browser and also in R itself (command getOption("timeout")) - the enviMass interface requires more than just a few seconds to build up. Second, check if the proxy settings of your browser interfere with adressing the R localhost server: is a proxy-auto-configuration file adressed? Check if enabling the automatic detection of proxy settings in your browser can solve the problem (at your own risk). Any other security settings which may interfere with adressing the localhost (IP-adress 127.0.0.1)? Talk to your network administrator.

  • If indeed none of all that helps, you may contact us. Please report your problem in a comprehensible way.

Installation of development version

Apart from the latest release, the current development version can also be installed from GitHub. To do so, use the R command


install_github("blosloos/enviMass_devel",dependencies=TRUE)
instead of
install_github("blosloos/enviMass",dependencies=TRUE)


in the above Installation - option 2. For the installation option 3, visit https://github.com/blosloos/enviMass_devel instead of https://github.com/blosloos/enviMass.