annotate readme.md @ 5:06470b2e491f draft

planemo upload for repository https://github.com/TGAC/earlham-galaxytools/tree/master/workflows/GeneSeqToFamily commit 2c7c545579169dda723cd7d91d9ccef1c5061fed

# GeneSeqToFamily: the Ensembl GeneTrees pipeline as a Galaxy workflow


## Introduction

GeneSeqToFamily is an open-source Galaxy workflow based on the [Ensembl GeneTrees](http://www.ensembl.org/info/genome/compara/homology_method.html) pipeline. The Ensembl GeneTrees pipeline [1] infers the evolutionary history of gene families, represented as gene trees. It is a computational pipeline that comprises clustering, multiple sequence alignment, and tree generation (using [TreeBeST](http://treesoft.sourceforge.net/treebest.shtml)), to discover familial relationship.

## Installation 

To use this workflow, please [install](https://galaxyproject.org/admin/tools/add-tool-from-toolshed-tutorial/) the required tools (listed below) into Galaxy from the Galaxy ToolShed. Also [install and import](https://galaxyproject.org/toolshed/workflow-sharing/#finding-workflows-in-toolshed-repositories) the workflow from the Galaxy ToolShed. 

### List of required tools
The 3 workflows in this repository requires Galaxy tools from the following ToolShed repositories:

* [emboss_5](https://toolshed.g2.bx.psu.edu/view/devteam/emboss_5/)
* [ncbi_blast_plus](https://toolshed.g2.bx.psu.edu/view/devteam/ncbi_blast_plus/) 
* [blast_parser](https://toolshed.g2.bx.psu.edu/view/earlhaminst/blast_parser/)
* [hcluster_sg](https://toolshed.g2.bx.psu.edu/view/earlhaminst/hcluster_sg/)
* [hcluster_sg_parser](https://toolshed.g2.bx.psu.edu/view/earlhaminst/hcluster_sg_parser/)
* [t_coffee](https://toolshed.g2.bx.psu.edu/view/earlhaminst/t_coffee/) 
* [filter_by_fasta_ids](https://toolshed.g2.bx.psu.edu/view/galaxyp/filter_by_fasta_ids/)
* [treebest_best](https://toolshed.g2.bx.psu.edu/view/earlhaminst/treebest_best)
* [gafa](https://toolshed.g2.bx.psu.edu/view/earlhaminst/gafa/)
* [fasta_to_tabular](https://toolshed.g2.bx.psu.edu/view/devteam/fasta_to_tabular/)
* [text_processing](https://toolshed.g2.bx.psu.edu/view/bgruening/text_processing/)
* [uniprot_rest_interface](https://toolshed.g2.bx.psu.edu/view/bgruening/uniprot_rest_interface/)
* [suite_ensembl_rest](https://toolshed.g2.bx.psu.edu/view/earlhaminst/suite_ensembl_rest/)

Helper tools for data preparation:

* [ensembl_longest_cds_per_gene](https://toolshed.g2.bx.psu.edu/view/earlhaminst/ensembl_longest_cds_per_gene/)
* [ete](https://toolshed.g2.bx.psu.edu/view/earlhaminst/ete/)
* [gstf_preparation](https://toolshed.g2.bx.psu.edu/view/earlhaminst/gstf_preparation/) - to convert gene feature files from GFF3 and/or JSON format to SQLite and format CDS sequence headers


## Workflow inputs and steps

### Inputs
GeneSeqToFamily requires the following inputs:

* the coding sequences (CDS) in FASTA format (this can be achieved with GeneSeqToFamily preparation tool)
* gene feature information in SQLite format (this can be achieved with GeneSeqToFamily preparation tool)
* a species tree in Newick format (this can be generated by ete tool in Galaxy)

### Steps

The pipeline is made up of 7 main steps:

1. Translation of CDS to protein sequences
2. All-vs-all BLASTP of protein sequences
3. Cluster protein sequences using [hcluster_sg](https://github.com/douglasgscofield/hcluster) and BLASTP scores
4. Multiple sequence alignment (MSA) for each cluster using [T-Coffee](http://www.tcoffee.org/Projects/tcoffee/)
5. Generate gene trees from MSAs using [TreeBeST](http://treesoft.sourceforge.net/treebest.shtml)
6. Create an SQLite database from the MSAs, gene trees and gene feature information using Gene Alignment and Family Aggregator (GAFA)
7. Visualise the GAFA dataset using Aequatus


### Helper tools:

We have developed various tools to help with data preparation for the workflow. This includes tools for retrieving sequences, and features from Ensembl using its REST API, and tools to parse Ensembl results into the required formats for the workflow. We also developed a tool to merge gene feature files and convert them from GFF3 (Gene Feature File) and/or JSON format to SQLite, which is then used to generate the Aequatus dataset.


## Results

The resulting gene families can be visualised using the [Aequatus.js](https://github.com/TGAC/aequatus.js) interactive tool, which is developed as part of the [Aequatus software](https://github.com/TGAC/aequatus) [2].

The Aequatus.js plugin provides an interactive visual representation of the phylogenetic and structural relationships among the homologous genes, using a shared colour scheme for coding regions to represent homology in internal gene structure alongside their corresponding gene trees. It is also able to indicate insertions and deletions in homologous genes with respect to shared ancestors.


## Citation information:

If you are using GeneSeqToFamily for any kind of research purpose, please cite the following paper:

Anil S. Thanki, Nicola Soranzo, Wilfried Haerty, Robert P. Davey (2018) [GeneSeqToFamily: a Galaxy workflow to find gene families based on the Ensembl Compara GeneTrees pipeline](https://doi.org/10.1093/gigascience/giy005) *GigaScience* 7(3), giy005, doi: 10.1093/gigascience/giy005


## References

1. Vilella AJ, Severin J, Ureta-Vidal A, Heng L, Durbin R, Birney E (2009) [EnsemblCompara GeneTrees: Complete, duplication-aware phylogenetic trees in vertebrates.](http://genome.cshlp.org/content/19/2/327) *Genome Res.* 19(2):327–335, doi: 10.1101/gr.073585.107
2. Thanki AS, Ayling S, Herrero J, Davey RP (2016) [Aequatus: An open-source homology browser.](http://biorxiv.org/content/early/2016/06/01/055632) *bioRxiv*, doi: 10.1101/055632


## Project contacts:

* Anil Thanki <[e-mail]>
* Nicola Soranzo <[e-mail]>
* Robert Davey <[e-mail]>

Copyright &copy; 2016-2018 Earlham Institute, Norwich, UK