PipViewer User Guide
====================

Pipviewer is a visualizer for multiple alignements of genomic
sequences.  It highlights conserved regions and allows basic
anotations.  Its main goal is to find conserved probes for the
construction of gene order data sets.  Selected regions marked as
'probes' can be expoxted to fasta format.  It can also retreive gene
annotations form the NBCI and display this information along the
alignement.

Pipviewer is not an aligner.  You must compute the alignment with
another tool like Clustal or Multi PIP Maker.  

Pipviewer is a Free Software released under the GNU GPL version 3.
See `COPYING.txt` for the details.


The Main Window
---------------
The main window is composed of five parts:

- the conservation viewer (top);
- the text viewer (middle);
- the actions panel (lower left);
- the options panels and the informations panels (lower right).


The Conservation Viewer
~~~~~~~~~~~~~~~~~~~~~~~
The conservation viewer displays the conserved regions of the multiple
alignment by using different colors zones and a curve representation.
Gene annotations, when available, will show in the conservation viewer
area.

************************************************************************
The upper axis (Ref) represents the nucleotide position on the
reference sequence. The lower axis (Align) represents the nucleotide
position on the reference sequence after the multiple alignment;
positions are different since gaps are introduced in the alignment.
************************************************************************

Conservation Plots
^^^^^^^^^^^^^^^^^^
The conservation plots are represented by colors zones, going from poorly 
to highly conserved region:

- green/black represents a highly conserved region;
- yellow/grey represents a moderate conserved region;
- red/white represents a poorly conserved region or a gap.

The color view is more efficient when looking at a large segment of
the alignment while the curve gives the detail of the conservation.
The gray scale view if provided for color blind users.

Conservation Curve
^^^^^^^^^^^^^^^^^^
The conservation curve represents the conservation zones by going up
(highly conserved) or down (poorly conserved).

Genes Annotations
^^^^^^^^^^^^^^^^^

The gene annotations represent the genes found on the reference
sequence:

- genes found on the positive strand (Direct) are shown as green 
  rectangles;

- genes found on the negative strand are shown as purple rectangles.

************************************************************************
Gene annotations will only appear after they are retrieved from NCBI
and their positions is computed against the alignment.  You can
request this from the _tools_ menu.  Later on, you can hide the from
the _view_ menu.
************************************************************************


The Text Viewer
~~~~~~~~~~~~~~~

The text viewer displays the base pairs details of a selected region.
To select a region, drag the mouse across the conservation viewer.
Selected regions are represented by blue rectangles.  In the text
view, notice that:

- the reference sequence is always on top;
- conserved nucleotides are shown as dots ('.');
- non-conserved nucleotides are shown as letters;
- gaps are shown as dashes ('-').


The Actions Panel
~~~~~~~~~~~~~~~~~
The actions panel provides multiples actions to the user:

- probe: set a selected region as a "probe";
- break point: set a selected region as a "break point";
- trash: set a selected region as "trash";
- check score: obtain informations about the quality of the selected
                 region in term of alignment score;
- skip: unselect a selection;
- reset: reset a highlighted region.

[NOTE]
=======================================================
Typical usage is:
- probes represent highly conserved region;
- break points represent poorly conserved region;
- trash should represents a region of no interest.
=======================================================


The Options Panel
~~~~~~~~~~~~~~~~~

The options panel displays the conservation viewer size (in
nucleotides) with a spin-box; this is fully adjustable depending on
whether you looking for and overview or a detailed view.

[WARNING]
==========================================================================
The conservation viewer uses OpenGL for renderering; setting the size
of the viewer higher then 10000 without a 3D video card can result in
serious slowdown.
==========================================================================


The Informations Panels
~~~~~~~~~~~~~~~~~~~~~~~
The informations panels provides multiples informations about the region
selected :

ref. genome panel::
  Give informations about the length, the starting and the ending position 
  of a selected region on the unaligned reference sequence/genome.

align genome panel::
  Give informations about the length, the starting and the ending position
  of a selected region on the aligned reference sequence/genome.

misc panel::
  Give the number of probes the user has sets on the conservation viewer.



The Species Association Window
------------------------------
The species association window shows the number of species, the species's
names and the accession number of their sequence database on the NCBI 
website.

Note:
=========================================================================
Users can easily associate the accession number of the align sequence
by double-clicking the sequence/specie/genome in the list.
=========================================================================



The Score Window
----------------
The score window show the sequence names (target), the percentage of 
identities and the percentage of length of a selected region on the 
align reference sequence. 

***********************************************************************
The score is calculated using Blast2seq only for the sequences that 
have been assossiate with their corresponding accession number.
***********************************************************************

The Probes List Window
----------------------
The probe list window shows the list of probe set by the user on the 
conservation viewer. Each probe possess its own name, starting and 
endind position, and length.

[NOTE]
=======================================================================
Users can easily locate probes on the conservation viewer by
double-clicking on the probes in the list. This can greatly accelerate
the search for a specific probe.
=======================================================================



The File Menu
-------------

Importing Multiple Alignment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
PipViewer can import multiple alignment from PipMaker 
http://pipmaker.bx.psu.edu/pipmaker[] and from 
ClustalW http://www.ebi.ac.uk/clustalw[].

- Multiple alignment file can be import using the 'Import' option.


Saving PipViewer Files
~~~~~~~~~~~~~~~~~~~~~~

- Imported files can be saved in the PipViewer format (.psel) using the
  'save' or 'save as' options.
  
- Saved files can be opened by using the 'open' option.


Merging Files
~~~~~~~~~~~~~
PipViewer can take 2 .psel files and merge their data to obtain one.

- Files can be merge using the 'Merge' option.

[IMPORTANT] 
======================================================================
Files can only be merged if their sequence names and content are 
identical.
======================================================================

[WARNING] 
======================================================================
Merging files can result in errors if some highlighted region set by 
the user intersect with each others.
======================================================================


Exporting Probes
~~~~~~~~~~~~~~~~
DNA sequence of the probes regions sets by the user can be exported to 
FASTA file using the 'Export Probes' option.

- Suffix can also be added to probes exported (optionel).



The Views Menu
--------------

Showing Genes Annotations
~~~~~~~~~~~~~~~~~~~~~~~~~
The genes annotations can be shown on the conservation viewer by selecting
the 'Show Genes Annotations' option.

[NOTE]
==========================================================================
This option is only available if the user as performed an automated search
of the genes annotations using the 'Compute Genes Annotations' located in
the Tools menu or if the annotations have been saved in the .psel file.
==========================================================================


Locate and select probes
~~~~~~~~~~~~~~~~~~~~~~~~
The probes sets by the user can be shown via the 'Probes List..' option.

[NOTE]
**************************************************************************
Double-clicking on a probe in the list result in locate and select the 
probe on the conservation viewer.
************************************************************************** 



The Tools Menu
--------------

Associate Accession Numbers
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Accession numbers of each original sequence can be added to the 
corresponding align sequence using the 'Associate Accession Numbers'
option.

- Setting accession number are performed by double-cliking the mouse over
  the selected sequence/species/genome and entering the code inside the
  dialog box.


Obtain the Genes Annotations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Genes annotations can be compute by selecting 'Compute Genes Annotations'.

****************************************************************************
- This option require the accession number of the first sequence (Ref.)
  for working properly.
  
- Computing genes annotations can take some time depending of the reference
  sequence length and the number of genes present in it.
  
- When computing has been effectuated, it is recommended to immidiatly save 
  the result by saving the current file.
****************************************************************************
