View source for Description of GenGIS plugins

GenGIS provides the following Python plugins which can be accessed through the ''Plugins'' menu. Please [mailto:beiko@cs.dal.ca?Subject=GenGIS%20plugin%20feedback contact us] if you have questions about using the plugins, or if you have suggestions for new plugins.

==Alpha Diversity==

The ''Alpha Diversity'' plugin calculates [http://en.wikipedia.org/wiki/Alpha_diversity alpha diversity] for active locations. It currently calculate richness, Shannon, and Simpson alpha diversity. To calculate alpha diversity, you must select the ''Measure'' you wish to calculate and the ''Category field'' in your sequence file over which diversity will be calculated. You may optionally select a ''Count field'' which indicates the number of times a given sequence is observed at a location. Pressing ''Calculate'' causes alpha diversity to be calculated. Results are reported within the plugin and added to the location table for use within GenGIS and other plugins.

[[Image:AlphaDiversityCalculator.png|thumb|center|401px|Alpha Diversity plugin.]]

==Alpha Diversity Visualizer==

The ''Alpha Diversity Visualizer'' plugin can calculate [http://en.wikipedia.org/wiki/Alpha_diversity alpha diversity] for active locations, regress alpha diversity against location specific metadata, and produce visualizations of the resulting linear regression analysis. It currently calculate richness, Shannon, and Simpson alpha diversity. To calculate alpha diversity, you must select the ''Measure'' you wish to calculate and the ''Category field'' in your sequence file over which diversity will be calculated. You may optionally select a ''Count field'' which indicates the number of times a given sequence is observed at a location. Pressing ''Calculate'' causes alpha diversity to be calculated. Linear regression results of alpha diversity versus all numeric fields associated with locations are reported within the ''Linear Regression Results'' table. Selecting a row within this table causes a linear regression scatter plot of alpha diversity versus the selected ''Field'' to be generated. The ''Viewport Display'' section allows different Viewport visualization to be produced.

[[Image:AlphaDiversityVisualizer.png|thumb|center|600px|Alpha Diversity Visualizer plugin.]]

==Bar Graph==

The ''Bar Graph'' plugin provides bar graphs showing the relative abundance of sequence data from two groups. Groups can be defined be any field in your ''Location'' file and bar plots created for any numeric field in your ''Sequence'' file. You may optionally specify a ''Count field'' from the ''Sequence'' file indicates the number of times a given sequence is observed. This allows both qualitative and quantitative bar plots to be generated.

[[Image:BarPlotPlugin.jpg|thumb|center|600px|Bar Graph plugin.]]

==Beta Diversity Calculator==

The ''Beta Diversity'' plugin calculates [http://en.wikipedia.org/wiki/Beta_diversity beta diversity] between active locations. The resulting biotic dissimilarity matrix can be saved to file and visualized in GenGIS using the ''Dissimilarity Matrix Viewer'' plugin. It currently calculate 9 measures of beta diversity (e.g., Bray-Curtis, Jaccard) across any field defined in your ''Sequence File''. Sequences classified as Other or Unclassified can be optionally ignored during the calculation of beta diversity. In order to account for unequal sampling depth, subsampling with replacement (i.e., jackknifing) can be performed and the mean beta-diversity between jackknifed samples reported. Hierarchical cluster trees indicating the relative similarity of locations can be produced and used as an input ''Tree File'' to GenGIS. 

[[Image:BetaDiversityPlugin.png‎|thumb|center|401px|Beta Diversity Plugin‎]]

==Canonical Correlation Analysis==

* '''Requirements''': ''R'' with the ''cca'' library must be installed on your system (see the [[The_GenGIS_2.0_Manual#R_and_GenGIS|GenGIS manual]]).

The ''Canonical Correlation Analysis'' or CCA plugin implements the widely used statistical technique for joint analysis of biodiversity and environmental data across a number of sites. The plugin also generates Phenotype-Environment Network (PEN) graphs as described in [http://genome.cshlp.org/content/20/7/960.long Patel et al. (2010) Analysis of membrane proteins in metagenomics: Networks of correlated environmental features and protein families] once a CCA has been carried out. The reference for the required R CCA package is [http://www.jstatsoft.org/v23/i12/paper Gonzalez et al (2008)]. The following example uses data from the Global Ocean Sampling dataset.

===Step 1: Matrix Correlation===

Before carrying out CCA, run the 'Matrix Correlation' function to ensure there is some level of correlation in the dataset. The figure below shows some evidence of strong and negative correlations, so we can proceed to the next step.

[[Image:GOS1-MatCorr.png|thumb|center|401px|CMatrix Correlation.]]

===Step 2: Grid Search===

The cca library implements a grid search function to determine the optimum value of two key parameters, λ1 and λ2. To perform the grid search in reasonable time, we recommend starting with a coarse search (e.g., the default ranges as specified by the plugin) and iteratively seeking the best values by refining the parameters.

[[Image:GOS2-GridSearch.png|thumb|center|401px|Grid Search.]]

===Step 3: Run CCA===

After choosing the most appropriate values of λ1 and λ2, we run the CCA to generate biplots that show the relationships between our input habitat and sequence count variables. The abundance of certain taxonomic classes seems to correlate with the three environmental variables considered.

[[Image:GOS3-CCA.png|thumb|center|601px|CCA output.]]

===Step 4: Generate PEN and view in Cytoscape===

To gain a better perspective on the relationships between variables, we can generate a phenotype-environment network that displays each variable as a node, and connects nodes for which the products of canonical correlates for the chosen number of dimensions sum to an absolute value greater than the chosen threshold. The network below, exported as a .xgmml file and imported into Cytoscape, shows relationships based on the first two dimensions, with positive correlations in green and negative ones in red. 

[[Image:GOS4-PENnetwork.png|thumb|center|601px|Phenotype-environment network viewed in Cytoscape.]]

==Dissimilarity Matrix Viewer==

The ''Dissimilarity Matrix Viewer'' plugin provides functionality for visualizing a matrix which indicates the dissimilarity between all pairs of locations. The dissimilarity matrix must be in the following format, where a \t indicates a tab:

<pre>
 3
A\t0\t2\t3
B\t1\t0\t4
C\t3\t5\t0
</pre>

The first line indicates the number of locations and each of the following rows gives the dissimilarity values for the specified location. The location names (first column) must match those in your location file. The upper and lower triangles of the matrix can be different. For example, in this [[HIV-1 subtype B mobility in Europe | HIV-1 data set]], the two triangle indicate import and export rates.

Elements in the matrix are selected by setting the ''Selection criteria''. 

[[Image:DissimilarityMatrixViewer.png|thumb|center|600px|Dissimilarity Matrix Viewer plugin.]]

Lines between the selected pairs are displayed in the ''Viewport'' using the specified ''Visual properties''. To update the ''Viewport'' display click ''Apply''. 

[[Image:DissimilarityMatrixViewport.png|thumb|center|322px|Display of all matrix elements between 5 and 10.]]

==Linear Regression==

The ''Linear Regression'' plugin can be used to perform a linear regress between any two variables in the ''Location Table'' (see Location Table Viewer below). To perform the regression, the independent and dependent variables must be specified in the ''Regression analysis'' section of the plugin. 

[[Image:LinearRegression.png|thumb|center|600px|Linear Regression plugin.]]

The results of the regression are reported within the plugin and shown as a scatter plot. A visualization within the GenGIS ''Viewport'' is also generated based on the properties set in the ''Viewport display'' section of the plugin. 

[[Image:LinearRegressionViewport.png|thumb|center|596px|Residuals of linear regression shown within the GenGIS Viewport.]]

==Location Table Viewer==

The ''Location Table Viewer'' plugin display a table indicating the metadata associated with each location. Other plugins and custom Python scripts can be used to add data to the ''Location Table''. By default, only data for active locations is shown. To show data for all locations check the ''Show data for all locations'' checkbox.

[[Image:LocationTable.png|thumb|center|600px|Location Table plugin.]]

==Mantel Test==

* '''Requirements''': ''R'' with the ''ade4'' library must be installed on your system (see the [[The_GenGIS_2.0_Manual#R_and_GenGIS|GenGIS manual]]).

The ''Mantel'' plugin can be used to perform a Mantel test between any two variables in the ''Location Table'' or ''Sequence Table''.

[[Image:Mantel.png|thumb|center|600px|Mantel plugin.]]

==Multi-Tree Optimal-Crossing Test==

This plugin will calculate the optimal angle for a set of loaded trees, and show the distribution of crossings for any azimuthal angle. A bar graph shows, for each tree, how close the number of crossings is to the number of crossings observed in the optimal layout for that tree.

[[Image:MultiTreeOptimalCrossingTest.png|thumb|center|600px|Multi-Tree Optimal-Crossing Test plugin.]]

==Sequence Table Viewer==

The ''Sequence Table Viewer'' plugin display a table indicating the metadata associated with each sequence. Other plugins and custom Python scripts can be used to add data to the ''Sequence Table''. By default, only data for active locations and active sequences is shown. To show data for all locations check the ''Show data for all locations'' checkbox. To show data for all sequences check the ''Show data for all sequences'' checkbox. 

[[Image:SequenceTable.png|thumb|center|600px|Sequence Table plugin.]]

==Reference Condition Analysis==
* '''Overview''': 
** The ''Reference Condition Analysis'' plugin is used to evaluate impacts on biodiversity by computing the expected diversity based on several types of habitat metadata and compares these to the observed diversity.
** Also, see the [[RCA_Tutorial]].
* '''Requirements''': 
** ''R'' with the ''Vegan'' library must be installed on your system (see the [[The_GenGIS_2.0_Manual#R_and_GenGIS|GenGIS manual]]).
* '''Running RCA''': 
** Choose the appropriate ''RCA Model'' (currently only 'atlantic_rca_model' available). Select the appropriate data labels for ''Taxon Names'' and ''Taxon Counts''.
* '''Browsing Results''': 
** The O/E (Observed over Expected diversity ratios) are displayed in the table for various alpha diversity measures including Richness, Shannon, Simpson, Pielou, and Berker-Parker. 
** Each of these results can be plotted on the main GenGIS map by selecting a column in the table, optionally adjusting the "Bar plot scale factor", and clicking "Plot Selected Data". 
** The data can be exported from the plugin table into GenGIS as another metadata habitat field allowing the use of other plugins (e.g. [[Description_of_GenGIS_plugins#LinearRegression|Linear Regression]]) by selecting a column and clicking "Add Selected To GenGIS". 
** Lastly, the entire table of results can be saved to a tab-delimited file by using the "Browse" button. 

[[Image:RCA_plugin.png|thumb|center|600px|Reference Condition Analysis plugin.]]