Getting Started

Requirements

• R (>= 3.5.1)

• Python (>= 3.0)

• Windows, MacOS or Linux specific installation tools.

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

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

Part 1: R Giotto Requirements

1.1: R Package Installation

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

1.2: 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("drieslab/Giotto@master")

Warning

If you are having compilation (gfortran) problems check goftran.

This version does not require C Compliation

remotes::install_github("drieslab/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

2.1: Python Package Installation

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.

2.2: 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

1. 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
   

2. Create Conda Environment Based on yaml File:

   conda env create -f environment.yml
   

3. 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

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

Tip

Check out the Examples Section to get a better understanding of the Giotto workflow.

Giotto Analyzer and Viewer interaction [work in progress]

• How to switch between Giotto Analyzer and Viewer?

Tips and Tricks

• Different ways of subsetting Giotto results?

• How to create global instructions and show or save your created plots?

• Different ways to visualize your spatial data?

• How to test and store multiple parameters or analyses?

• Visualize spatial data with voronoi plots

• Working with the Giotto class

• Adding and Working with Images in Giotto

Giotto Workflow Analyses Guided Steps

0. *Optional* Install a Giotto Environment

1. Create a Giotto Object

2. Process and Filter a Giotto Object

3. Dimension Reduction

4. Cluster cells or spots

5. Identify differentially expressed genes

6. Annotate clusters

7. Cell-type enrichment or deconvolution per spot

8. Create a Spatial grid or Network

9. Find genes with a spatially coherent gene expression pattern

10. Identify genes that are spatially co-expressed

11. Explore spatial domains with HMRF

12. Calculate spatial cell-cell interaction enrichment

13. Find cell-cell interaction changed genes (ICG)

14. Identify enriched or depleted ligand-receptor interactions in hetero and homo-typic cell interactions

15. Export Giotto results to use in Giotto viewer

HowTos

• Different ways of subsetting Giotto results?

• How to create global instructions and show or save your created plots?

• Different ways to visualize your spatial data?

• How to test and store multiple parameters or analyses?

• Visualize spatial data with voronoi plots

• Working with the Giotto class

• Adding and Working with Images in Giotto

Giotto Analyzer and Viewer interaction [work in progress]

• How to switch between Giotto Analyzer and Viewer?

See also

FAQs for more help.