
			 BAMMDS README

Please send problems and feedback to bammds-users@nongnu.org.


= Presentation of BAMMDS =

Based on a reference set and BAM-files with sequencing data (one BAM
file per individual) bammds generates an MDS (multidimensional
scaling) plot to see how closely related those individuals are to the
individuals in reference set.

= Tutorial =

For a tutorial please see doc/TUTORIAL or
/usr/share/doc/bammds/TUTORIAL.

= Installation =

Global installation can be done by running the following as root:

   ./configure && sudo make install

Personal installation can be done by:

  ./configure --prefix=$HOME && make install

Mac users can install the precompiled Mac binary with:

  ./configure && make macinstall

or:

  ./configure --prefix=$HOME && make macinstall


= Required software to run BAMMDS =

To run BAMMDS you need the following software:

  R
  GNU Parallel (included in distribution)
  samtools
  vcftools (for reading vcf-files)
  p-link (for reading ped- and bed-files).

See the section 'Runtime requirements' below on how to install these.


= Running BAMMDS =

Run BAMMDS like this:

  bammds familyname.individualname.bam referenceset.vcf

This will generate these files:

  tmp/referenceset.log
  tmp/referenceset.tfam
  tmp/referenceset.tped
  tmp/familyname.individualname,referenceset.vcf.asd.gz
  tmp/familyname.individualname,referenceset.vcf.legend.csv
  referenceset.vcf.vcfidx
  familyname.individualname,referenceset.vcf.pdf

Anything in tmp/ can be generated again, so it can safely be removed.

The vcf-file is converted to .vcfidx, .log, .tfam, and .tped. The
.asd.gz contains the allele sharing distance. These can safely be
ignored.

The most important file is the .legend.csv. It determines how the
plotting is done: Which individuals and populations are included,
which colors are used, the legend of the points. It can be edited in a
spreadsheet.

The format of the .legend.csv-file is quite compact: Empty fields
inheirit their value from the field above. Fields with * get the
default value.

The .legend.filled.csv-file is generated from .legend.csv and is
simply the .legend.csv-file with all values filled in.

The .pdf-file contains the plots.


= If /tmp is limited in space =

BAMMDS generates temporary files only used internally. The can be big,
and are by default generated in /tmp.  If you want the temporary files
generated by bammds somewhere else than /tmp, do this by setting the
TMPDIR directory of your system, e.g.: export TMPDIR=$HOME/scratch


= Runtime requirements =

On Debian you will do:

  sudo apt-get install r-base-core samtools vcftools plink liblocal-lib-perl

On a Mac you will do:

  curl -L http://cpanmin.us | perl - --sudo App::cpanminus
  sudo cpan local::lib

If you have an old version of R, you may need to:

  wget http://cran.r-project.org/src/contrib/Archive/Rcpp/Rcpp_0.9.13.tar.gz
  R CMD INSTALL Rcpp_0.9.13.tar.gz 


= Compilation requirements -- for advanced users =

The distribution includes a pre-generated and pre-compiled version for
the x86_64 architecture, so if you do not have all the compilation
requirements, you may skip to Installation.

BAMDS requires this to compile:

* bammds_allelesharingsum bammds_allelesharing: C++-compiler
  On Debian:
    sudo apt-get install g++

* bammds.1: pod2man
  On Debian:
    sudo apt-get install perl

* bammds.html: pod2html
  On Debian:
    sudo apt-get install perl

* bammds.texi: pod2texi
  texinfo

* bammds.pdf: pod2pdf
  On Debian:
    sudo apt-get install pod2pdf

* bammds: Perl App::FatPacker
  On Debian:
    sudo perl -MCPAN -e 'install App::FatPacker'

* bammds: Either local::lib .packlist or installation of the Perl modules:
  Carp.pm Carp/Heavy.pm File/Path.pm File/Temp.pm File/Which.pm
  Getopt/Long.pm Pod/Usage.pm Text/CSV.pm Text/CSV_PP.pm Cwd.pm
  File/Spec.pm File/Spec/Cygwin.pm File/Spec/Epoc.pm
  File/Spec/Functions.pm File/Spec/Mac.pm File/Spec/OS2.pm
  File/Spec/Unix.pm File/Spec/VMS.pm File/Spec/Win32.pm
  On Debian:
    sudo apt-get install liblocal-lib-perl
    perl -MCPAN -Mlocal::lib -e 'CPAN::install(Carp)'
    perl -MCPAN -Mlocal::lib -e 'CPAN::install(Carp::Heavy)'
    perl -MCPAN -Mlocal::lib -e 'CPAN::install(File::Path)'
    perl -MCPAN -Mlocal::lib -e 'CPAN::install(File::Temp)'
    perl -MCPAN -Mlocal::lib -e 'CPAN::install(File::Which)'
    perl -MCPAN -Mlocal::lib -e 'CPAN::install(Getopt::Long)'
    perl -MCPAN -Mlocal::lib -e 'CPAN::install(Pod::Usage)'
    perl -MCPAN -Mlocal::lib -e 'CPAN::install(Text::CSV)'
    perl -MCPAN -Mlocal::lib -e 'CPAN::install(Text::CSV_PP)'
    perl -MCPAN -Mlocal::lib -e 'CPAN::install(Cwd)'
    perl -MCPAN -Mlocal::lib -e 'CPAN::install(File::Spec)'
    perl -MCPAN -Mlocal::lib -e 'CPAN::install(File::Spec::Cygwin)'
    perl -MCPAN -Mlocal::lib -e 'CPAN::install(File::Spec::Epoc)'
    perl -MCPAN -Mlocal::lib -e 'CPAN::install(File::Spec::Functions)'
    perl -MCPAN -Mlocal::lib -e 'CPAN::install(File::Spec::Mac)'
    perl -MCPAN -Mlocal::lib -e 'CPAN::install(File::Spec::OS2)'
    perl -MCPAN -Mlocal::lib -e 'CPAN::install(File::Spec::Unix)'
    perl -MCPAN -Mlocal::lib -e 'CPAN::install(File::Spec::VMS)'
    perl -MCPAN -Mlocal::lib -e 'CPAN::install(File::Spec::Win32)'

Compilation for global installation is:

  ./configure && make clean && make -j

Compilation for personal installation is:

  ./configure --prefix=$HOME && make clean && make -j
  

= New versions =

New versions will be released at: <<URL here>>


= Copyright and citation =

When using BAMMDS for a publication please cite:

<<INSERT ARTICLE HERE>>

Copyright (C) 2013 Ole Tange, Anna Sapfo, J. Victor Moreno-Mayar.

BAMMDS is released under GNU General Public License Version 3.

