samscope Files

== Description ==

Samscope is a lightweight SAM/BAM file viewer that makes visually
exploring next generation sequencing data intuitive and maybe even
fun!

Samscope uses multiple layers so simultaneously (or sequentially) view
SAM/BAM related features like coverage or allele frequency, or
ChIP-SEQ features like polarity. Individual reads will be drawn if BAM
indexes are available.

== Building ==

To build samscope from source, there's a few requirements:
  C++ compiler of your choice (tested with gcc 4.2, 4.3, 4.4)
  scons ( http://www.scons.org/ )
  boost >= 1.34 ( http://www.boost.org )
  GLUT and OpenGL libraries appropriate for your distribution (we strongly recommend freeglut ( http://freeglut.sourceforge.net/ )
  CMake (for building bamtools. http://www.cmake.org )

 *Optional, but Recommended:
  libxmu-dev (for clipboard support (part of Xorg))
  libdevil-dev (for screenshots http://openil.sourceforge.net/ )
  zlib-dev for handling compressed files
  perl (for viewing/compiling the POD documentation) 

Bamtools and Samtools libraries are also required, but we include them in our
distribution, so we encourage you to use the copies in our distribution.

Once you have all the required packages, building should consist of:
 scons

That's it. If you have multiple cores with which to compile, you may
want to use something like:
 scons -j8

If you're vehemently opposed to installing perl, you can skip the
manpage generation and just build samscope:
 scons samscope
See 'scons -h' for a complete list of build options.

You can install to /usr/local/bin/ (or whatever you set with BINDIR)
using:
 scons install
or
 scons install BINDIR=~/bin
to install to your home directory.

== Running ==

Running samscope can be as simple as

 ./samscope test1.bam

This would run all the preprocessing to do a basic coverage display of
test1.sam.  Samscope can generate a wide variety of data layers such
as polarity (very helpful for ChIP-SEQ data). To generate these other
layers use options such as:

 ./samscope --buildpolarity test1.bam

A full set of options can be viewed via

 ./samscope --help

Some layers (such as the base specific layers like baseA/baseC and
major/minor allele frequencies) require bam inputs, due to differences
in the bamtools/samtools libraries. We recommend using BAM for
everything when possible, so we've included a sam2bam converter which
can be used as:

 ./sam2bam test1.sam

This will generate test1.bam.

== Controls ==

Samscope uses keyboard+mouse style interface without any GUI buttons
to click. The control scheme tries to borrow from classic X window manager
styles. The important parts to remember include:

 * Middle mouse button pans the screen.
 * Right mouse button zooms.
 ** The point you click at is used as an origin around which to zoom, so it
    will stay in a fixed position.
 * Left mouse button is for "tools" like Zoom or Ruler.
 ** Clicking on a peak will automatically zoom to the extents of the peak.
 * Mouse actions ignore the vertical axis unless Shift is held while moving.
 * 'h' toggles help display with a detailed list of controls.
 * 'n' toggles display of navigational state (where you are, what's being
   displayed right now).
 * 'q' quits.

Keyboard commands (like 'c' (color-mode) or ']' (next layer)) are used
to modify the current display state.

== Documentation ==

Consult "perldoc samscope" or "man samscope" if available.  Also,
http://samscope.dna.bio.keio.ac.jp/wiki/ has more detailed
explainations and extra information for the curious.

== Questions ==

Feel free to contact the authors at samscope@dna.bio.keio.ac.jp if you
have questions.