README.html

<link href="style.css" media="screen" rel="stylesheet" type="text/css" />

<p><a href="https://travis-ci.org/armbrustlab/SEAStAR"><img src="https://travis-ci.org/armbrustlab/SEAStAR.svg?branch=master" alt="Build Status"></a></p>
<h2 id="seastar---a-framework-for-the-analysis-of-next-generation-metagenomes">SEAStAR - A framework for the analysis of next-generation metagenomes</h2>
<h3 id="the-basics">The Basics</h3>
<h4 id="seastar-is-a-package-of-tools-supporting-the-construction-of-complete-analysis-pipelines-for-next-generation-illumina-solid-sequencing-data-generated-from-environmental-samples">SEAStAR is a package of tools supporting the construction of complete analysis pipelines for next-generation (Illumina&reg;, SOLiD&trade;) sequencing data generated from environmental samples.</h4>
<h5 id="it-includes-high-performance-tools-for-dealing-with">It includes high-performance tools for dealing with:</h5>
<ul>
<li>Converting between file formats (CSFASTA -&gt; FASTQ)</li>
<li>Trimming raw reads for quality (with tuning support)</li>
<li>PCR de-duplication of paired reads (without reference sequences)</li>
<li>Selecting and estimating the relative abundance of sequences from large reference databases (e.g. 16S rDNA)</li>
<li>Sub-sampling paired FASTQ files randomly, or based on reads included in (or excluded from) reference alignments</li>
<li>Converting assembled color-space (SOLiD) contigs to nucleotide-space</li>
<li>Connecting assembled contigs together via paired reads (constructing an assembly graph)</li>
<li>Splitting complicated metagenomic assembly graphs into well-supported scaffolds</li>
<li>Binning scaffolds by organism using tetra-nucleotide statistics</li>
<li>Identifying small circular scaffolds that are likely virus or plasmid genomes</li>
</ul>
<h5 id="seastar-works-with-but-does-not-supply">SEAStAR works with, but does not supply:</h5>
<ul>
<li>Short-read sequence aligners (e.g. <a href="http://bio-bwa.sourceforge.net">BWA</a>, <a href="http://bowtie-bio.sourceforge.net/index.shtml">Bowtie</a>)</li>
<li>De novo contig assemblers (e.g. <a href="http://www.ebi.ac.uk/~zerbino/velvet/">Velvet</a>)</li>
<li>Tools for visualizing assembly graphs (e.g. <a href="http://www.graphviz.org/">GraphViz</a>, <a href="http://zvtm.sourceforge.net/zgrviewer.html">ZGRViewer</a>)</li>
<li>16S Taxonomic classifiers (e.g. <a href="http://sourceforge.net/projects/rdp-classifier/">RDP Classifier</a>)</li>
</ul>
<p>You can find out more about SEAStAR on its <a href="http://armbrustlab.ocean.washington.edu/SEAStAR">Armbrust Lab Homepage</a> and obtain news regarding updates and related info by following <a href="https://twitter.com/SEAStAR_meta">@SEAStAR_meta</a> on Twitter.</p>
<p>This file contains information on how to build and install the SEAStAR tools. For information on using the tools themselves, please see the included SEAStAR User Guide file.</p>
<h3 id="license">License</h3>
<p>SEAStAR is released under the GPLv3 license, a copy of which is provided in the included file &quot;COPYING&quot;. By using this software, you are agreeing to be bound by the terms of this license.</p>
<h3 id="installation">Installation</h3>
<p>The instructions that follow are for building the SEAStAR tools from source code.</p>
<p>SEAStAR is designed to build and run on any 64-bit Unix-like system, including Linux and Mac OS X version 10.7 or later. Many components of SEAStAR are optimized for multiple CPU cores and require substantial memory. We recommend a machine with a minimum of 4 CPU cores and 32 GB of RAM to run these tools.  Depending on your datasets and what you are trying to do (e.g. de novo assembly) you may require a substantially more powerful machine than this minimum recommendation.</p>
<p>The SEAStAR package has dependencies on a small number of software packages that you (or your system administrator) may need to install or update. The process described in the next section will notify you if your system is missing any of these components.</p>
<h4 id="required-tools">Required Tools:</h4>
<ul>
<li><a href="http://gcc.gnu.org">gcc</a> -- version 4.2 or newer, supporting <a href="http://openmp.org">OpenMP</a> (version 4.7 recommended)</li>
<li><a href="http://www.cmake.org">cmake</a> -- version 2.8.5 or newer</li>
<li><a href="http://nodejs.org">node.js</a> -- version 0.10 or newer</li>
<li><a href="http://www.gnu.org/software/gawk/">gawk</a> -- version 3.1.5 or newer (version 4.0.2 recommended)</li>
</ul>
<p>Additional instructions are available below for fulfilling these requirements for Mac OS X, and for programmers wishing to make modifications to the included source code.</p>
<p>Once you have the above packages: To build SEAStAR using Unix style command line tools, run the following commands from the directory where all files generated in the build process should be placed (including executables). This is your &quot;destination tree&quot;.</p>
<pre><code>cmake [dir]
make</code></pre><p>Where [dir] is the path to the root of the SEASTAR source tree (where this README file is found).</p>
<p>If the path &quot;.&quot; is used for [dir] above (run from the &quot;source tree&quot;), then the binary and source tree will be the same (an &quot;in-source build&quot;). After a successful make, executables will be found in the bin/ subdirectory.</p>
<p>This directory (the bin subdirectory of the destination tree) should be added to your PATH environment variable, so that newly built tools can be found from your data analysis directories:</p>
<pre><code>export PATH=$PATH:[dest_dir]/bin   # Where [dest_dir] is the fully qualified path to your destination tree directory</code></pre><p>To test the newly built components:</p>
<pre><code>make test</code></pre><p>If any tests fail, do not use the executables!</p>
<p>To clean all files generated in the source directory for an in-source build (this will only work for git checked-out repositories):</p>
<pre><code>git clean -fxd</code></pre><p>For an out-of-source build you can simply delete the destination tree directory and start again.</p>
<h3 id="additional-installation-details-for-mac-os-x">Additional installation details for Mac OS X</h3>
<p>For Mac OS X users: To fulfill the above requirements, you will first need to download and install Apple&#39;s &quot;Command Line Developer Tools&quot;.</p>
<pre><code>xcode-select --install</code></pre><p>And then we recommend installing the other required packages using <a href="https://brew.sh/">HomeBrew</a> or <a href="http://www.macports.org/">MacPorts</a>.</p>
<h4 id="homebrew-preferred">HomeBrew (preferred)</h4>
<p>Visit the link below to download and install HomeBrew.</p>
<blockquote>
<p><a href="https://brew.sh/">https://brew.sh/</a></p>
</blockquote>
<p>Then run the following commands to install the required packages:</p>
<pre><code>brew update
brew install cmake
brew install node   # Node may also optionally be installed using nvm
brew install gawk
brew install gcc@8</code></pre><h4 id="macports">MacPorts</h4>
<p>Visit the link below to download and install MacPorts.</p>
<blockquote>
<p><a href="http://www.macports.org/install.php">http://www.macports.org/install.php</a></p>
</blockquote>
<p>Then run the following commands to install the required packages:</p>
<pre><code>sudo port selfupdate
sudo port install cmake
sudo port install node  # Node may also optionally be installed using nvm
sudo port install gawk
sudo port install gcc8  # or whatever version you may prefer</code></pre><h3 id="an-important-note-about-compilers-on-mac-os-x-">An important note about compilers on Mac OS X :</h3>
<p>Xcode&#39;s default Clang-based compiler does not support OpenMP (a standard for writing efficiently parallelized C code); this is why we specify above that you must install the gcc compiler. The cmake script provided checks OS X systems to see if the OpenMP support is working correctly with the default (or specified) C compiler. If you receive an error when trying to build that says &quot;You need to install gcc (version 4.4 or later)&quot; it is because our build system is attempting to use the Xcode compiler, and not the one you installed using HomeBrew or MacPorts.</p>
<p>You will need to define an environment variable to explicitly tell cmake which compiler to use. Note that this must be done each time you start a command line session where you wish to run cmake again (or add it to your shell startup file, e.g. .bash_profile in your home directory).  For example:</p>
<pre><code>export CC=/usr/local/bin/gcc-8  # Homebrew</code></pre><p>or</p>
<pre><code>export CC=/opt/local/bin/gcc-8  # MacPorts</code></pre><p>Change the numbers above if you are using a different version!</p>
<p>Note: It may also be possible, with some more work, to use a newer version of clang than provided by Apple to compile with OpenMP support, but we mave not tested this. Both HomeBrew and MacPorts enable installation of LLVM 7 (which includes the clang C compiler). Have fun with that!</p>
<h3 id="for-developers">For Developers</h3>
<p>Some of the included JavaScript (.js) files are automatically generated from <a href="http://coffeescript.org">CoffeeScript</a> source files (CoffeeScript is a <a href="http://en.wikipedia.org/wiki/Source-to-source_compiler">transcompiled</a> dialect of JavaScript with Python-like syntax.) If you wish to modify these components, please edit the .coffee files in the scripts/ subdirectory of the source tree. The make system will automatically regenerate the .js files in the bin/ subdirectory of the destination tree. To successfully transcompile these files, you will need the to install the CoffeeScript package for node.js:</p>
<pre><code>sudo npm install -g coffee-script</code></pre><p>It is sometimes useful to build with GCC debug flags turned on.  To achieve this follow the normal cmake build procedure with one additional user defined cmake cache entry:</p>
<pre><code>cmake -D DEBUG=ON [dir]</code></pre>