Installation

Native Installation

Giotto consists of two modules: analyzer and viewer. The requirements of Giotto installation are:
  • R (at least 3.5.1)
  • Python (at least 3.0)
  • Java 1.6+
  • Unix / Linux environment

1. Native install on Ubuntu Linux

Once you have installed R, go into R, and install the following 
> remotes::install_github("RubD/Giotto")
> devtools::install_bitbucket("qzhudfci/smfishhmrf-r", ref="master")
Depending on how many pre-requisites are automatically installed, this step my take up to 30 minutes for the first time installation.

1.1. Python packages
This is necessary to run all available analyses, including Leiden / Louvain clustering and to build and use the interactive visualization tool. An alternative, but less flexible, R version for Louvain clustering is also available. It is advisable to install everything within a specific conda environment and specify the python path in the R function when required. To install python packages using the the pip package manager, get a terminal in unix/linux and enter: 
$ pip3 install --user pandas igraph networkx leidenalg community smfishHmrf
#For smfishHmrf package, if upgrading from a previous installation, then do force install:
$ pip3 install --user --upgrade --no-cache-dir --force-reinstall --no-deps smfishHmrf
1.2. Viewer
The viewer module gives you the ability to do interactive visualization of cells in physical and expression spaces, and is therefore required for an integrative experience with Giotto analyzer.
The viewer requires the following:
  • scikit-image, scikit-learn, opencv-python, smfish-image-processing (Python)
  • tileup (Ruby)
  • ImageMagick 6.7
  • Java 1.7+
$ sudo apt-get install imagemagick
$ sudo apt install ruby ruby-dev libmagickwand-dev
$ sudo gem install tileup
$ pip3 install --user --upgrade --no-cache-dir --no-deps scikit-image opencv-python scikit-learn
$ pip3 install --user --upgrade --no-cache-dir --no-deps --force-reinstall smfish-image-processing giotto-viewer


2. Native install on macOS

Download R or RStudio (version 3.5 or above). Then: 
> remotes::install_github("RubD/Giotto")
> devtools::install_bitbucket("qzhudfci/smfishhmrf-r", ref="master")
Giotto requires X11 to be present in macOS. If not, go to this link to install XQuartz 2.7.11.

2.1. Errors in macOS
You might encounter errors because of issues with building Giotto from source. If this is the case, then you might want to try the Giotto branch cless which is a version without C++ code, and this should fix some of the installation errors. 
> remotes::install_github("RubD/Giotto@cless")
Alternatively, if your errors are related to clang, you can check out this link for more details about how to solve this issue.

2.2. Python packages
Similar to how these tools are installed in Ubuntu, you can install the following python modules in macOS: 
$ pip3 install --user pandas igraph networkx leidenalg community smfishHmrf
#For smfishHmrf package, if upgrading from a previous installation, then do force install:
$ pip3 install --user --upgrade --no-cache-dir --no-deps smfishHmrf

If using the conda environment, install these packages by following these steps below. More information about creating a python virtual environment with conda can be found in this link.

Create a yaml file (e.g. environment.yml) with the following information: 
name: giotto_env
channels:
 - defaults
dependencies:
 - pip=3.4
 - pandas
 - networkx
 - python-igraph
 - leidenalg
 - python-louvain
 - python.app (!!only for OSX!!)
 - scikit-learn
 - smfishHmrf
prefix: /Users/your_username/anaconda3/envs/giotto_env
Create a conda environment based on yaml file: 
$ conda env create -f environment.yml
Your new python environment will be located in the path /Users/your_username/anaconda3/envs/giotto_env.

2.3. Viewer
Note
If you do not have images, the pre-requisites tileup and imageMagick are not required. You may directly install the giotto viewer python packages. 
$ pip3 install --user scikit-image opencv-python scikit-learn 
$ pip3 install --user --force-reinstall --upgrade --no-deps --no-cache-dir smfish-image-processing giotto-viewer
Installing tileup and imageMagick - install Homebrew first
If you require image processing capabilities, then read on. For MacOS X, we need to install the Homebrew first. Get the Homebrew environment. It is easiest to install ImageMagick within Homebrew. If you don't have Homebrew, visit https://brew.sh to learn how to install it. Once Homebrew is installed, check ~/.bash_profile that you have added /usr/local/bin to $PATH variable. 
cat ~/.bash_profile

#if the /usr/local/bin is missing from PATH variable within .bash_profile then please uncomment below line and do:
#echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bash_profile
Afterwards, do: 
$ brew install imagemagick python ruby
$ echo 'export PATH="/usr/local/opt/ruby/bin:$PATH"' >> ~/.bash_profile
$ brew unlink imagemagick
$ brew install imagemagick@6
$ brew link imagemagick@6 --force
$ echo 'export PATH="/usr/local/opt/imagemagick@6/bin:$PATH"' >> ~/.bash_profile
Note imagemagick v6 is required for Mac OSX. Version 7 is known to have compatibility problem with Ruby rmagick package, and is therefore avoided. After doing the above, close the terminal. Open the terminal to refresh environment. Then check that the command convert works: 
$ convert -version
Next install tileup in MacOS: 
$ /usr/local/opt/ruby/bin/gem install rmagick
$ /usr/local/opt/ruby/bin/gem install tileup
$ echo 'export PATH="/usr/local/lib/ruby/gems/2.6.0/bin:$PATH"' >> ~/.bash_profile   #check gems version is correct
Install the necessary python packages (Python 3.6): 
$ which python3
$ pip3 install --user scikit-image opencv-python scikit-learn
$ pip3 install --user --force-reinstall --upgrade --no-deps --no-cache-dir --no-deps smfish-image-processing giotto-viewer



3. Native install on Windows 10

We do not recommend native install of Giotto through R Windows version. This is because it has poor handling of some GNU packages such as ImageMagick. It is better to create a simulated Linux environment in Windows such as Docker or WSL2, so that any Linux package can be installed (see below). We therefore present two options: 1. (recommended) Docker image for Windows users, 2. WSL2 route.

WSL2: One can install a Linux system such as Ubuntu in Windows 10 through Windows Subsystem for Linux 2 (WSL2). See official documentation for more details about WSL2. The Ubuntu in WSL2 will behave like a native Linux system. All the Linux instructions can then be used to install Giotto. See details.