File	Date	Author	Commit
phaccs	2012-08-02	Florent Angly	[6be65d] Initial commit (version 0.4)
CHANGES.txt	2012-08-02	Florent Angly	[6be65d] Initial commit (version 0.4)
LICENSE.txt	2012-08-02	Florent Angly	[6be65d] Initial commit (version 0.4)
README.txt	2012-08-02	Florent Angly	[6be65d] Initial commit (version 0.4)
VERSION.txt	2012-08-02	Florent Angly	[6be65d] Initial commit (version 0.4)
add_extend.m	2012-08-02	Florent Angly	[6be65d] Initial commit (version 0.4)
and.m	2012-08-02	Florent Angly	[6be65d] Initial commit (version 0.4)
anderson_darling.m	2012-08-02	Florent Angly	[6be65d] Initial commit (version 0.4)
batch_test.m	2012-08-02	Florent Angly	[6be65d] Initial commit (version 0.4)
construct_crosscontig_plot_standalone.m	2012-08-02	Florent Angly	[6be65d] Initial commit (version 0.4)
extract_mergecrossdiffs.m	2012-08-02	Florent Angly	[6be65d] Initial commit (version 0.4)
extract_mergecrossdiffs_smoothed.m	2012-08-02	Florent Angly	[6be65d] Initial commit (version 0.4)
find_ccontigs.m	2012-08-02	Florent Angly	[6be65d] Initial commit (version 0.4)
find_contigs.m	2012-08-02	Florent Angly	[6be65d] Initial commit (version 0.4)
fminbnd_wrapper.m	2012-08-02	Florent Angly	[6be65d] Initial commit (version 0.4)
get_distances.m	2012-08-02	Florent Angly	[6be65d] Initial commit (version 0.4)
maxiphi.m	2012-08-02	Florent Angly	[51d07d] More documentation update
merge_mosamples2.m	2012-08-02	Florent Angly	[6be65d] Initial commit (version 0.4)
octave-core	2012-08-02	Florent Angly	[6be65d] Initial commit (version 0.4)
read_abund.m	2012-08-02	Florent Angly	[6be65d] Initial commit (version 0.4)
read_csp.m	2012-08-02	Florent Angly	[6be65d] Initial commit (version 0.4)
run_phaccs.m	2012-08-02	Florent Angly	[6be65d] Initial commit (version 0.4)
score_contigs.m	2012-08-02	Florent Angly	[6be65d] Initial commit (version 0.4)
size_nargout_3.m	2012-08-02	Florent Angly	[6be65d] Initial commit (version 0.4)
topgray.m	2012-08-02	Florent Angly	[6be65d] Initial commit (version 0.4)
trapezoid_setup.m	2012-08-02	Florent Angly	[6be65d] Initial commit (version 0.4)

Read Me

MaxiPhi


MaxiPhi is free software for the comparison of the diversity in viral metagenomes
by performing Monte-Carlo simulations. Its input is cross-contig spectra and the
output is beta-diversity plots representing the percent of genotypes shared and
permuted in abundance. Details on how MaxiPhi works are available in this paper:
Angly FE, Felts B, Breitbart M, Salamon P, Edwards RA, et al. (2006) The Marine
Viromes of Four Oceanic Regions. PLoS Biol 4(11): e368
http://dx.doi.org/10.1371/journal.pbio.0040368

To calculate beta-diversity you'll need cross-contig spectra computed by 
Circonspect (http://sourceforge.net/projects/circonspect/) and estimates of
average genome length. See GAAS (http://sourceforge.net/projects/gaas/) to get
an estimate.


INSTALLATION

Put the MaxiPhi folder in the desired destination folder and open this folder. Then:

* Method A: Octave 3.4
Install version 3.4 of Octave (released in February 2011) or later (http://www.gnu.org/software/octave/).
Install GNUPlot as well if you want to be able to create graphs (http://www.gnuplot.info/).

* Method B: Octave and Octave-forge
You'll need to install Octave >= 3.0.1 (package octave-3.0 on GNU/Linux Debian) and its devel package (octave3.0-headers on GNU/Linux Debian). See http://www.gnu.org/software/octave/
Then download the following Octave-Forge packages:
  - miscellaneous (>=1.0.0)
      http://downloads.sourceforge.net/octave/miscellaneous-1.0.9.tar.gz?download
  - optim (>=1.0.4)
      http://downloads.sourceforge.net/octave/optim-1.0.12.tar.gz?download
Install the packages in the order you downloaded them by running:
  octave --eval  "pkg install miscellaneous-1.0.9.tar.gz optim-1.0.12.tar.gz"
Install GNUPlot as well if you want to be able to output graphs (http://www.gnuplot.info/).

* Method C: Matlab and optimization toolbox
Install Matlab 2006 or newer and its Optimization toolbox.

Now register the location of the current MaxiPhi folder. Open Octave/Matlab and
run the following (substituting by the appropriate value for your system):
  addpath(genpath('/path/to/maxiphi/dir')); savepath();
This command adds the Maxiphi scripts to Octave/Matlab's search path. But before
this step, if you have a previous version of Maxiphi installed in a different
location, you have to remove it first and update the Octave/Matlab path:
  rmpath(genpath('/path/to/old/maxiphi/dir')); savepath();



RUNNING MAXIPHI

In Octave or Matlab, try the commands below.

The MaxiPhi help explains the parameter taken by the maxiphi() function:
  help maxiphi

Example for using a simple cross-contig spectrum (metagenome A against metagenome B):
  maxiphi( {'A_vs_B.csp'} )

Same thing but specify in which folder the results should be written, which 
rank-abundance model to use (powerlaw or logarithmic), and the average genome
length to assume:
  maxiphi( {'A_vs_B.csp'}, 'results', 'logarithmic', [44000] )

Use control contig spectra (metagenome A against A and B against B) to increase
the accuracy of the beta-diversity estimates. This causes the computation to be
much longer because different average genome lengths are tested around the
specified average genome lengths:
  maxiphi( {'A_vs_B.csp', 'A_vs_A.csp', 'B_vs_B.csp'}, 'results', 'logarithmic', [44000, 48000, 42000] )

Use the genome_length_delta, genome_length_mode and nof_intermediary_lengths to
control how many genome sizes to use and how different from the specified
average genome length (see 'help maxiphi' for full details):
  maxiphi( {'A_vs_B.csp', 'A_vs_A.csp', 'B_vs_B.csp'}, 'results', 'logarithmic', [44000, 48000, 42000], 30, 'range', 101) 

Now, if you're happy with the default parameters for the optimization of the
average genome length but need to change the number of permutations of the 
Monte-Carlo simulation. For example if is it taking too much memory, decrease
it. Or if the control plots do not display nice contours, you will need to
increase it:
  maxiphi( {'A_vs_B.csp', 'A_vs_A.csp', 'B_vs_B.csp'}, 'results', 'logarithmic', [44000, 48000, 42000], [], [], [], 400, 400, 200, 200)   

To use MaxiPhi in a non-interactive way, try this in a terminal:
  octave --silent --traditional --eval "maxiphi( <snip> ); exit;"
or:
  matlab -nodesktop -nodisplay -nosplash -r "maxiphi( <snip> ); exit;"


COPYRIGHT AND LICENSE

MaxiPhi is copyright Florent Angly <florent.angly@gmail.com>, 2010

Contributions from Ben Felts and Steve Rayhawk.

MaxiPhi is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License (GPL) as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
MaxiPhi is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with MaxiPhi. If not, see <http://www.gnu.org/licenses/>.