diff --git a/docs/content/gingr.rst b/docs/content/gingr.rst index 7adbc4d..b3c4147 100644 --- a/docs/content/gingr.rst +++ b/docs/content/gingr.rst @@ -1,22 +1,30 @@ -==================================================== -Gingr: Interactive visualization of multi-alignments -==================================================== +.. image:: gingr/logo_med.png -Project home page: https://github.com/marbl/gingr +Gingr is an interactive tool for exploring large-scale phylogenies in tandem with their corresponding multi-alignments. Gingr can display informative overviews for hundreds or thousands of genomes, while allowing researchers to move quickly to more detailed views of specific subclades and genomic regions, even down to the nucleotide level of their multi-alignments. Additionally, its dynamic display of variants allows interactive selection of various filters, such as indels, poorly aligned regions and suspected sites of recombination. Gingr works chiefly in tandem with Parsnp, an efficient tool for core-genome multi-alignment and phylogenetic reconstruction. It is also applicable, however, to other analytical tools, accepting standard file formats such as multi-Fasta, XMFA, Newick and VCF. -Gingr is an interactive tool for exploring large-scale phylogenies in tandem with their corresponding multi-alignments. Gingr can display informative overviews for hundreds or thousands of genomes, while allowing researchers to move quickly to more detailed views of specific subclades and genomic regions, even down to the nucleotide level of their multi-alignments. Additionally, its dynamic display of variants allows interactive selection of various filters, such as indels, poorly aligned regions and suspected sites of recombination. Gingr works chiefly in tandem with Parsnp, an efficient tool for core-genome multi-alignment and phylogenetic reconstruction. It is also applicable, however, to other analytical tools, accepting standard file formats such as multi-Fasta, XMFA, Newick and VCF. +.. image:: gingr/screen.png + :width: 462 + :height: 290 -Contents: +**Download (v1.2)** + + * `gingr-OSX64-v1.2.zip `_ + * `gingr-Linux64-v1.2.tar.gz `_ + +**Documentation** .. toctree:: :maxdepth: 2 - gingr/quickstart - gingr/types - gingr/components - gingr/installation - gingr/paramaters - gingr/faq + gingr/requirements gingr/tutorial - gingr/source - gingr/license + gingr/types + +**Resources** + +`All releases`_ ~ `Source code`_ ~ `Report an issue`_ + +.. _All releases: https://github.com/marbl/gingr/releases +.. _Source code: https://github.com/marbl/gingr +.. _Report an issue: https://github.com/marbl/gingr/issues + diff --git a/docs/content/gingr/browsing.rst b/docs/content/gingr/browsing.rst new file mode 100644 index 0000000..b062631 --- /dev/null +++ b/docs/content/gingr/browsing.rst @@ -0,0 +1,20 @@ +Browsing a Gingr file +--------------------- +* Download :download:`Gingr input file ` + +* Open in Gingr (File->Open) + +.. image:: ggr.png + +* The phylogeny appears on the left. Hover over a clade to highlight and outline the corresponding tracks to the right. + +.. image:: clade.png + +* Click to zoom in on the clade + +.. image:: zoomed.png + +* The multiple alignment appears on the right, shown as a SNP heatmap when zoomed out. To see the full alignment, zoom in with the mouse wheel or by selecting a region in the ruler. + +.. image:: bases.png + diff --git a/docs/content/gingr/doc.rst b/docs/content/gingr/doc.rst new file mode 100644 index 0000000..14f0725 --- /dev/null +++ b/docs/content/gingr/doc.rst @@ -0,0 +1,15 @@ +==================================================== +Gingr: Interactive visualization of multi-alignments +==================================================== + +Project home page: https://github.com/marbl/gingr + +Gingr is an interactive tool for exploring large-scale phylogenies in tandem with their corresponding multi-alignments. Gingr can display informative overviews for hundreds or thousands of genomes, while allowing researchers to move quickly to more detailed views of specific subclades and genomic regions, even down to the nucleotide level of their multi-alignments. Additionally, its dynamic display of variants allows interactive selection of various filters, such as indels, poorly aligned regions and suspected sites of recombination. Gingr works chiefly in tandem with Parsnp, an efficient tool for core-genome multi-alignment and phylogenetic reconstruction. It is also applicable, however, to other analytical tools, accepting standard file formats such as multi-Fasta, XMFA, Newick and VCF. + +Contents: + +.. toctree:: + :maxdepth: 2 + + gingr/quickstart + gingr/types diff --git a/docs/content/gingr/importing.rst b/docs/content/gingr/importing.rst new file mode 100644 index 0000000..0c7b972 --- /dev/null +++ b/docs/content/gingr/importing.rst @@ -0,0 +1,42 @@ +Importing other files +--------------------- +* Create a new workspace (File->New) + +.. image:: new.png + +* Download the data files + + * Alignment: :download:`xmfa ` + * Reference: :download:`fasta ` + * Annotations: :download:`genbank ` + * Phylogeny: :download:`newick ` + +* Open the XMFA alignment (File->Open). Since XMFA files can be accompanied by reference files, the Open dialog will appear. Choose the Fasta file as the reference in this window. + +.. image:: open.png + +* The preview panes allow you to ensure that the header for the reference is the same as the first sequence in the XMFA. This allows sequences between LCBs to be shown and allows annotations to be added later. + +.. image:: xmfa.png + +* The track highlighted in blue ("england.gbk.fna.srt") is the current reference for variants. Select a new reference by right-clicking on a track. + +.. image:: reref.png + +* Next, import the phylogenetic tree (File->Open) + +.. image:: tree.png + +* Reroot the tree at the midpoint (Tree->Reroot at midpoint) + +.. image:: reroot.png + +* The tree will now be balanced at the center of the longest path + +.. image:: rerooted.png + +* Finally, import the annotations (File->Open) + +.. image:: annotated.png + +* The workspace can be saved to share or return to later (File->Save) diff --git a/docs/content/gingr/logo_med.png b/docs/content/gingr/logo_med.png new file mode 100644 index 0000000..d593545 Binary files /dev/null and b/docs/content/gingr/logo_med.png differ diff --git a/docs/content/gingr/open-gingr.png b/docs/content/gingr/open-gingr.png new file mode 100644 index 0000000..6ef125b Binary files /dev/null and b/docs/content/gingr/open-gingr.png differ diff --git a/docs/content/gingr/quickstart.rst b/docs/content/gingr/quickstart.rst index f246fb1..e69de29 100644 --- a/docs/content/gingr/quickstart.rst +++ b/docs/content/gingr/quickstart.rst @@ -1,95 +0,0 @@ -Quickstart -========== - -Before you run ---------------- - - 1. To run Gingr OSX, you will need to right click to open and bypass the unsigned developer notice: - - * Future releases will be signed - -Download, install & run ------------------------ -Parsnp is distributed as a precompiled binary that should be devoid of external dependencies (all included in dist). The three steps below represent the fastest way to start using the software: - -On OSX: -""""""" - 1. wget https://github.com/marbl/gingr/releases/download/v1.0.1/gingr-OSX64-v1.0.1.zip - 2. unzip gingr-OSX64.app.zip - -On Linux: -""""""""" - - 1. wget https://github.com/marbl/gingr/releases/download/v1.0.1/gingr-Linux64-v1.0.1.tar.gz - 2. tar -xvf gingr-Linux64-v1.0.1.tar.gz - -Basic usage: -"""""""""""" - - 1. On OSX simply click on Gingr app (right click to bypass unsigned developer notice) - 2. On Linux, simply run:: - ./gingr - - -Browsing a Gingr file --------------------- -* Download :download:`Gingr input file ` - -* Open in Gingr (File->Open) - -.. image:: ggr.png - -* The phylogeny appears on the left. Hover over a clade to highlight and outline the corresponding tracks to the right. - -.. image:: clade.png - -* Click to zoom in on the clade - -.. image:: zoomed.png - -* The multiple alignment appears on the right, shown as a SNP heatmap when zoomed out. To see the full alignment, zoom in with the mouse wheel or by selecting a region in the ruler. - -.. image:: bases.png - -Importing other files ---------------------- -* Create a new workspace (File->New) - -.. image:: new.png - -* Download the data files - - * Alignment: :download:`xmfa ` - * Reference: :download:`fasta ` - * Annotations: :download:`genbank ` - * Phylogeny: :download:`newick ` - -* Open the XMFA alignment (File->Open). Since XMFA files can be accompanied by reference files, the Open dialog will appear. Choose the Fasta file as the reference in this window. - -.. image:: open.png - -* The preview panes allow you to ensure that the header for the reference is the same as the first sequence in the XMFA. This allows sequences between LCBs to be shown and allows annotations to be added later. - -.. image:: xmfa.png - -* The track highlighted in blue ("england.gbk.fna.srt") is the current reference for variants. Select a new reference by right-clicking on a track. - -.. image:: reref.png - -* Next, import the phylogenetic tree (File->Open) - -.. image:: tree.png - -* Reroot the tree at the midpoint (Tree->Reroot at midpoint) - -.. image:: reroot.png - -* The tree will now be balanced at the center of the longest path - -.. image:: rerooted.png - -* Finally, import the annotations (File->Open) - -.. image:: annotated.png - -* The workspace can be saved to share or return to later (File->Save) diff --git a/docs/content/gingr/requirements.rst b/docs/content/gingr/requirements.rst new file mode 100644 index 0000000..d5a16f6 --- /dev/null +++ b/docs/content/gingr/requirements.rst @@ -0,0 +1,20 @@ +Requirements +------------ + +Mac +""" +* OS X 10.7 (Lion) or later (requires 64 bit architecture) + +Linux +""""" +* 64 bit architecture +* Common distributions + * The Gingr binary should work with most recent (within ~5 years) versions of common Linux distributions, e.g.: + * CentOS (6+) + * Ubuntu (9+) + * Fedora (10+) + * ...and many others +* Source + * If the Gingr binary does not work on a particular distribution, + it may be possible to build from `source `_ + * gcc 4.8+ is required for building diff --git a/docs/content/gingr/running.rst b/docs/content/gingr/running.rst new file mode 100644 index 0000000..e60ea98 --- /dev/null +++ b/docs/content/gingr/running.rst @@ -0,0 +1,24 @@ +Running Gingr +------------- + +Mac OS X +"""""""" +* Gingr.app can be moved to the Applications folder if desired +* Double-click Gingr.app to run +* Depending on your security settings, there may be an error that Gingr is not from the Mac App Store or is from an unidentified developer. To run it anyway: + * Right click on Gingr.app + * Select "Open" from the menu + * Click the "Open" button at the next prompt + +|img_open| + +Linux +""""" +* From the desktop + * Click on the "gingr" binary +* From a terminal + * Navigate to the folder with the "gingr" binary + * Run "./gingr" + +.. |img_open| image:: open-gingr.png + diff --git a/docs/content/gingr/screen-small.png b/docs/content/gingr/screen-small.png new file mode 100644 index 0000000..af09c90 Binary files /dev/null and b/docs/content/gingr/screen-small.png differ diff --git a/docs/content/gingr/screen.png b/docs/content/gingr/screen.png new file mode 100644 index 0000000..7a9104c Binary files /dev/null and b/docs/content/gingr/screen.png differ diff --git a/docs/content/gingr/tutorial.rst b/docs/content/gingr/tutorial.rst index 7828b03..01e0121 100644 --- a/docs/content/gingr/tutorial.rst +++ b/docs/content/gingr/tutorial.rst @@ -1 +1,8 @@ -fixme \ No newline at end of file +Tutorial +======== + +.. toctree:: + + running + browsing + importing