---
title: "Install organisms from EnsemblGenomes"
author: "Bruno Contreras, Yvon Mbouamboua & Jacques van Helden"
date: '`r Sys.Date()`'
output:
  html_document:
    fig_caption: yes
    highlight: zenburn
    theme: cerulean
    toc: yes
    toc_depth: 5
  pdf_document:
    fig_caption: yes
    highlight: zenburn
    toc: yes
    toc_depth: 5
---


# Introduction

The goal of this tutorial is to explain how to install genomes from Ensembl and EnsemblGenomes in your RSAT server. 

# Prerequisite

This protocol assumes that you have a working instance of the RSAT server, and that you are familar with the Unix terminal. 

# Protocol

## Checking the version of Ensembl libraries

Ensembl queries rely on Perl libraries that are updated with every new Ensembl release. 
Before starting any installation, we need to make sure that we use the latest version of the genome. 

1. In a Web browser, open a connection to <http://ensembl.org>, and check the current version of Ensembl. At the time of writing this tutorial (July 2016), we are at **version 84**.  

2. Open now a connection to <http://ensemblgenomes.org>, and check the current version of Ensembl. At the time of writing this tutorial (July 2016), we are at **version 31**^[**Ensembl vs EnsemblGenomes**. [Ensembl](http://ensembl.org/) only contains a subset of the genomes supported at EBI. More recently, a second project named EnsemblGenomes [EnsemblGenomes](http://ensemblgenomes.org/) was lanched, which is organized by taxa (Metazoa, Plants, Fungi, Protists, Bacteria), and which supports tens of thousands of genomes.  For some historical reason, ensemblgenome releases bear different numbers. In principle the versions are now synchronized, so there should always be a difference of 53 between Ensembl and EnsemblGenomes versions. ]. 

2. We will now check the local version of the Ensembl Perl libraries. In you terminal, type the following command. 

```
make -f makefiles/install-ensembl-genomes_demo.mk list_param
```

If there is a difference between the two versions, install the new libraries as follows.

Update your local RSAT configuration, and replace, for all ensembl-related parameters, the old version by the current one. 

```
perl $RSAT/perl-scripts/configure_rsat.pl
```

After this, check that the Ensembl-related parameters have well been adapted, and install the new version of Ensembl Perl libraries. 

```
make -f makefiles/install-ensembl-genomes_demo.mk list_param
make -f makefiles/install_software.mk install_ensembl_api_param
make -f makefiles/install_software.mk install_ensembl_api
```

In principle, the updated versions of the Ensembl API Perl libraries are now installed in your RSAT folder. You can check it like this: 

```
ls -ltr $RSAT/ext_lib
```


## Get the list of organisms for a given EnsemblGenome server

Before downloading a genome, we need to know which genomes are available on Ensembl and EnsemblGenomes servers. 

```
make -f makefiles/install-ensembl-genomes_demo.mk available_species
```

This command will address queries to ensembl and ensemblgenomes servers, and the respective answers will be stored in different files (the file paths will be displayed on the terminal at the end of the task). 

## Download one genome

The commands are slighly different depending on whether your genome has to be downloaded from the "historical" ensembl or from ensemblgenoems. We give hereafter one example of each. 

### Download one genome from ensembl

Downloading vertebrate genomes can take a while. We suggest to set a high verbosity (option `-v 2`) in order to better see the progress of the download and installation. 

```
install-ensembl-genome -v 2 -db ensembl -species Homo_sapiens
```

## Adding support for variations


Polymorphic variations (genetic differences between individuals of a same species) are available for some species in ensembl and ensemblgenomes. If you intend to analyze the impact of polymorphic variations on regulation, you also need to download the variations for your species of interest. This can be done by adding the option `-task variations` to the  `install-ensembl-genome` command.

Before doing this, we need to check if variations are supported for the selected organism. 

In our example, we will analyse the human genome (species: Homo_sapiens). 

We will first download the list of available species from ensembl, and check if variations are available for Homo_sapiens. 

```
install-ensembl-genome -v 1 -db ensembl -available_species \
                -o available_species_ensembl.txt
grep sapiens available_species_ensembl.txt

```

The result looks like this: 

`Homo_sapiens    genome, features, variations`

We can thus download variations, using the next command. 

```
install-ensembl-genome -v 2 -db ensembl -species Homo_sapiens \
   -task variations
```

### Download one genome from EnsemblGenomes

We download the genome from EnsemblGenomes, and for this we will use a faster protocol developed by Bruno Contreras-Moreira, based on data available on ensemblgenomes FTP site. 
The script needs to be tuned to take into account the taxon-specific FTP sites.

As a study case, we show how to install *Hordeum vulgarum* from the **Plant** ensemblgenomes server. 

In addition, we can  choose a specific release of EnsemblGenomes (e.g. 28). 

Before running the task, we can check the parameters. 

```
make -f makefiles/ensemblgenomes_FTP_client.mk \
    SPECIES=hordeum_vulgare  GROUP=Plants RELEASE=28 list_param
```

After having checked that the parameters seem suitable, run the task **.

```
make -f makefiles/ensemblgenomes_FTP_client.mk \
    SPECIES=hordeum_vulgare GROUP=Plants RELEASE=28 
```
