Getting Started¶
Requirements¶
R (>= 3.5.1)
Python (>= 3.0)
Installation¶
Giotto is installed via R but there are required Python modules which must be installed in order for Giotto to function properly. Below are the instructions for both the Giotto Package Installation (Part 1) done via R and the Installation of Required Python Modules (Part 2). In order to use Giotto successfully, users must have both the Giotto Package installed as well as the required Python Packages.
Important
Make sure that your system has satisfied all of the requirements needed to sucessfully install Giotto.
For ease of acces, there is a method which allows users to automatically install all of the necessary python modules from within R (see Part 2.2 Giotto-Specific Python Packages for more information).
Checkout out the Common Errors and Solutions for more troubleshooting tips on common installation issues.
Giotto Installation Workflow¶
This workflow image is designed to help with Giotto Installation. Users should follow the installation process by answering Yes or No to the following quetions. There are three potential paths aimed to guide users through the installation process (see the diagram below for an overview).
Part 1: R Giotto Requirements of Giotto Installation is centered around preparing your R Environment
Part 2: Python Giotto Requirements of Giotto Installation is centered around preparing your Python Environment
Workflow Diagram
Quickest Installation [Automatic]¶
You can install Giotto Suite on any platform in 2 easy steps which are outlined in more detail in the section below.
library(remotes)
remotes::install_github("RubD/Giotto@suite")
The python environment only needs to be installed once.
library(Giotto)
installGiottoEnvironment()
This command only needs to be run once and then Giotto will automatically detect the environment in the future.
In-Depth installation¶
Part 1: R Giotto Requirements¶
Have you ever installed an R package that is in development?
Yes
Move on to the next step: Giotto Installation.
No
If this is the first time you build and install an R package you can follow this link, which has simple installation instructions for Windows, Mac OSX and Linux. To specifically install the command-line tools of Xcode for Mac OSX you might also need to run this line in terminal:
xcode-select -- install
Move on to the next step: Giotto Installation
Have you installed Giotto before?
Yes
Run the following code to load giotto intto your R workspace.
library(Giotto)
Move on to the next step: Python Package Installation
No
If you have installed an R Package before but this is your first time installting Giotto pleae follow the instructions below. Giotto can be installed within 1-5 mins.
This version requires C Compilation
library(devtools) # If not installed: install.packages('devtools')
library(remotes) #If not installed: install.packages('remotes')
remotes::install_github("RubD/Giotto")
Warning
If you are having compilation (gfortran) problems check goftran.
This version does not require C Compliation
remotes::install_github("RubD/Giotto@cless")
Next, run the following code to load giotto intto your R workspace.
library(Giotto)
Then, move on to the next step: Python Package Installation
Part 2: Python Giotto Requirements¶
Have you ever installed a Python Package?
Yes
Move on to the next step: Giotto-Specific Python Packages
No
Information on how to install a Python package can be found here. Once you have read through the information proceeed to the next step: Giotto-Specific Python Packages.
Have you installed the python modules necessary for Giotto to run?
Required Modules
To perform all potential steps and analysis in the Giotto spatial toolbox the user needs to have a number of python modules installed. To make this process as flexible and easy as possible two different strategies can be used
pandas
python-igraph (igraph)
networkx
leidenalg
python-louvain (community)
smfishHmrf
python.app (OSX only)
scikit-learn
These are necessary to run all available analyses, but can be installed automatically (see 2.2A Automatic Installation) or manually (see 2.2B Manual Installation) explained in detail below (Reponse “No”).
Yes
Move on to the next step: Python Path Specification
No
There are two methods through which users may install the required python modules (‘Automatic Installation’ vs. ‘Manual Installation’)
2.2A: Automatic Installation
The python modules will be installed automatically in a miniconda environment when installing Giotto. However, it will ask you whether you want to install them and you can opt out and select your preferred python path. In that case you need to do a manual installation of the python modules. To perform all potential steps and analysis in the Giotto spatial toolbox the user needs to have a number of python modules installed. Installation of the Giotto Environment allows users to install the required Python environment via MiniConda without specifying their python path.
With this option, the user can just install a Giotto python environment using r-miniconda. This is done after installation of the Giotto package via R (see Part 1: Giotto Installation for more information).
First, load the Giotto Package then proceed to environment installation and/or removal.
library(Giotto)
Install Giotto Environment
installGiottoEnvironmnt()
Re-Install the Giotto environment
installGiottoEnvironment(force_environment = TRUE)
Re-install mini-conda and environment
installGiottoEnvironment(force_miniconda = TRUE)
Remove Giotto Environment
removeGiottoEnvironment()
Note
With the automatic installation option, the user DOES NOT have to specify a python path.
2.2B: Manual Installation
There are two methods thorugh which users can install the necessary Python modules manually with (1) Pip in Python3 or (2) Conda.
Warning
With either one of the Manual Installation options (Install with Pip in Python3 or Install with Conda) users will have to provide the python path to createGiottoInstructions. If this is not done, Giotto will not be able to use the installed python modules.
Note: If pip install does not work, try installing the modules within a conda environment. For more inforomation on vitual environments with conda visit this page.
1. Install with Pip in Python3
For OSX, Windows, or Linux:
pip3 install pandas python-igraph networkx python-louvain leidenalg scikit-learn smfishHmrf
2. Install with Conda
Create 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 prefix: /Users/your_username/anaconda3/envs/giotto_env
Create Conda Environment Based on yaml File:
conda env create -f environment.yml
Use the path to this environment when you create the Giotto instructions or Giotto object
For OSX
/Users/your_username/anaconda3/envs/giotto_env/bin/pythonw
For Windows
/Users/your_username/anaconda3/envs/giotto_env/python.exe
For Linux
/Users/your_username/anaconda3/envs/giotto_env/bin/python
Warning
With either one of the Manual Installation options users must specify their Python path.
Please move on to the next step: 2.3 Python Path Specification
Have you specified your python path in R?
Note
With the Manual Installation option, once the user has installed all of the necessary modules, via either of the methods (e.g. Conda), the path to their python environment can be provided as an instruction in R.
Yes
You can now start using Giotto
No
With the Manual Installation option, once the user has installed all of the necessary modules, via either of the methods above (e.g. Conda), the path to their python environment can be provided as an instruction in R.
# Within R
library(Giotto)
my_instructions = createGiottoInstructions(python_path = 'your/python/path')
my_giotto_object = createGiottoObject(
raw_exprs = '...',
spatial_locs = '...',
instructions = my_instructions)
You can now start using Giotto
Tutorials for Giotto Specific Tasks¶
