Skip to content

Installation

Jump to bottom
palmerito0 edited this page Apr 29, 2023 · 44 revisions

The kboolnet package and associated dependencies can be installed locally/manually or via a Docker container. Despite being a more complicated process, local/manual installation is recommended and has been most extensively tested.

Local/manual installation

The installation of kboolnet consists of four main tasks: 1. installing python, rxncon, and its dependencies, 2. installing R and setting up an R build environment, 3. installing the kboolnet R package, and 4. configuring the kboolnet package.

Manual installation has been tested on the following platforms:

  • Windows 10
  • Ubuntu 22.04.2, 21.10, 20.04.1
  • Fedora 37
  • CentOS 7
  • MacOS 13.2.1

If you're really in a hurry, there is an abridged version of the manual installation instructions here.

1. Installing python3, pip, rxncon, and relevant python dependencies

Installing python3

rxncon is a python package and requires python3. If you don’t have python3 installed on your computer, there are several ways to install it:

Note for Linux users: on some Linux distributions it may be necessary to also install the python3-dev/python3-devel packages with the system package manager (i.e. apt, yum, dnf, etc.) to provide C headers needed for rxncon dependency compilation.

Following installation, make sure the directory where the python3 executable resides is added to the PATH system environment variable. Successful installation and PATH configuration can be verified by opening a new terminal (on Linux or MaxOS) or command prompt (on Windows) and typing python --version or python3 --version.

Installing pip

rxncon is a python package and requires pip (the python package manager) for its installation. Pip is usually installed automatically alongside python3; if not, there are several ways to install it:

Verify the successful installation by typing python -m pip --version in a terminal (on Linux or MacOS) or command prompt (on Windows).

Installing rxncon and openpyxl

Given working installations of python3 and pip, the rxncon python package can be installed in any environment by running python -m pip install rxncon in the command line. More information about rxncon is available at https://rxncon.org/

Note for Windows users: There is a known issue with installation of PyEDA, a package rxncon depends on, on Windows. See the FAQ for instructions on how to resolve this.

An additional python package required for kboolnet is openpyxl, which can be installed by running the following in the command line: python -m pip install openpyxl.

Successful installation of both rxncon and openpyxl can be verified by typing python -c "import rxncon; import openpyxl" at the command line; if both packages are properly installed, no errors will be reported.

2. Installing R and setting up an R build environment

Installing R

kboolnet is an R package and requires a working installation of R version 4.0 or above. If you don’t have R installed on your computer, download and install it by following the instructions on https://cran.r-project.org/.

Following installation, make sure the directory where the R and Rscript executables reside is added to the PATH system environment variable. Successful installation and PATH configuration can be verified by opening a new terminal (on Linux or MaxOS) or command prompt (on Windows) and running R --version and Rscript --version.

Optional: Installing Rstudio

Rstudio is an IDE for R which facilitates R script and package development. We recommend you install it by following the instructions at https://posit.co/download/rstudio-desktop/.

Setting up an R build environment

kboolnet is an R package that is compiled from source; for this reason, it requires an R build environment.

Windows

First, install RTools from https://cran.r-project.org/bin/windows/Rtools/. Then install the devtools R package by running install.packages("devtools") in an R session.

Linux

Install the devtools R package by running install.packages("devtools") in an R session.

This will likely result in multiple errors due to missing system libraries. The exact list of necessary libraries is strongly system-dependent, but may include the following: libssl, libcurl, libxml, libfontconfig, libfreetype, libpng, libtiff, libjpeg, etc. THIS IS NOT AN EXHAUSTIVE LIST. Fortunately, the output of install.packages(“devtools”) provides a clear indication of what is missing; follow its instructions and install the missing libraries using the system terminal (not the R session). For example:

  • on Ubuntu: sudo apt install libssl-dev libcurl4-openssl-dev libxml2-dev
  • on Fedora: sudo dnf install openssl-devel libcurl-devel libxml2-devel
  • etc.

Once system library dependencies are in place, run install.packages(“devtools”) in the R session again. It may be necessary to repeat this process multiple times.

MacOS

To provide necessary build tools such as C, C++, and Fortran compilers, install Xcode from the App Store or by running xcode-select --install. Afterward, install the devtools R package by running install.packages("devtools") in an R session.

3. Building and installing the kboolnet R package

kboolnet depends on R packages located in the Bioconductor repository. In order to install them, the BiocManager R package manager is required. BiocManager can be installed by running the following in an R shell:

if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install("remotes")

It is now possible to install the kboolnet R package using either BiocManager::install() or by manually building the package from source. The BiocManager method is highly recommended for most users as it automatically resolves kboolnet's R package dependencies. Manually building from source is only necessary during package development.

BiocManager method

Install kboolnet by running BiocManager::install("Kufalab-UCSD/kboolnet") in an R shell. Verify the installation by running library(kboolnet) in an R shell; if properly installed, no errors will be reported.

Manually build from source

Before building from source, kboolnet's R dependencies must by installed by running the following in an R session:

BiocManager::install(c("numbers", "BoolNet", "googledrive", "tidyr", "dplyr", "ggplot2", "egg", "openxlsx", "optparse", "igraph", "RCy3", "rappdirs"))

Then, clone or otherwise download the repository from https://github.com/Kufalab-UCSD/kboolnet. kboolnet can then by built and installed by either:

  • Starting RStudio, creating a new project in the root directory of the kboolnet repository, and clicking Build -> Install & Restart
  • Running the following commands in an R session:
setwd('/path/to/kboolnet/repository/root')
pkg_build <- devtools::build()
if ("kboolnet" %in% .packages()) detach("package:kboolnet", unload=TRUE) 
install.packages(pkg_build)

Verify the installation by running library(kboolnet) in an R shell; if properly installed, no errors will be reported.

Dependencies for optional features

BioNetGen rule-based pseudo-quantitative modeling

To allow for BioNetGen rule-based reaction modeling, install BioNetGen 2.5.2 by downloading and extracting the appropriate archive from https://github.com/RuleWorld/bionetgen/releases/tag/BioNetGen-2.5.2

Simulation animation

To enable animation of simulation trajectories using the AnimatePath.R script, Cytoscape 3 and imagemagick are required. Installation instructions for Cytoscape are available here: http://manual.cytoscape.org/en/stable/Launching_Cytoscape.html. imagemagick can be installed using your system package manager or by following the installation instructions available here: https://imagemagick.org/script/download.php

4. Configure the kboolnet package

Now that the kboolnet R package has been installed, it must be properly configured. This is accomplished by running the following commands in an R shell and following the prompts:

library(kboolnet)
setupKboolnet()

Most users will find the default configuration values (displayed in parentheses before each prompt) appropriate. To keep the default value for a prompt, simply press the Enter key.

A (highly) abridged version of the above 4 steps:

  • Install python3 + pip
  • Install rxncon and openpyxl using pip (python -m pip install rxncon openpyxl)
  • Install R version 4.0 or greater
  • Install system dependencies for an R build environment
    • Windows: RTools
    • MacOS: Xcode
    • Linux: many, many system libraries; R will tell you which ones to install during the devtools R package installation
  • Install devtools R package (install.packages("devtools"))
  • Install BiocManager R package (install.packages("BiocManager"); BiocManager::install("remotes"))
  • Install kboolnet R package (BiocManager::install("Kufalab-UCSD/kboolnet"))
  • Configure the kboolnet R package (library(kboolnet); setupKboolnet())
  • Done!

Docker container installation

First, install the Docker Engine by following the instructions at https://docs.docker.com/engine/install/. Then, clone or otherwise download the repository from https://github.com/Kufalab-UCSD/kboolnet. Open a terminal and change directories to the repository root. The Docker image can then be built by running docker build . -t kboolnet (this will take a while to complete!).

Clone this wiki locally