# ===========================================================================
#
#                            PUBLIC DOMAIN NOTICE
#               National Center for Biotechnology Information
#
#  This software/database is a "United States Government Work" under the
#  terms of the United States Copyright Act.  It was written as part of
#  the author's official duties as a United States Government employee and
#  thus cannot be copyrighted.  This software/database is freely available
#  to the public for use. The National Library of Medicine and the U.S.
#  Government have not placed any restriction on its use or reproduction.
#
#  Although all reasonable efforts have been taken to ensure the accuracy
#  and reliability of the software and data, the NLM and the U.S.
#  Government do not and cannot warrant the performance or results that
#  may be obtained by using this software or data. The NLM and the U.S.
#  Government disclaim all warranties, express or implied, including
#  warranties of performance, merchantability or fitness for any particular
#  purpose.
#
#  Please cite the author in any work or product based on this material.
#
# ===========================================================================


The NCBI SRA ( Sequence Read Archive ) Toolkit
29 April 2011
2.0.1 RELEASE


Contact: sra-tools@ncbi.nlm.nih.gov


For preliminary documentation on tool usage, consult the files within
the "help" directory. THIS DOCUMENTATION IS SUBJECT TO CHANGE.


DESCRIPTION:

 This release includes tools for reading the SRA archive, generally
 by converting individual runs into some commonly used format such as
 fastq. There are minor changes over the rc5 release.


 "Linux" binaries have been created on CentOS and SuSE Linux
 distributions. They are not guaranteed to work on other
 distributions. In particular, the version of libc.so should be
 compatible. They are specific to the x86-family architectures.

 "Windows" binaries have been created using MSVC's (not Cygwin)
 tools. This release includes Win32 binaries.

 "Mac OS X" binaries are available for the x86-family
 architectures. They will NOT run on PPC Macs. The 64-bit binaries
 will run only on OS 10.6. The 32-bit binaries should run on either
 10.5 or later.


CONTENTS:

 "abi-dump"            - dump ABI color-space runs into their native format
 "abi-load"            - load ABI color-space runs
 "fastq-dump"          - dump any run of any platform in FASTQ format
 "fastq-load"          - load FASTQ runs
 "helicos-load"        - load HELICOS runs
 "illumina-dump"       - dump Illumina runs into their native format
 "illumina-load"       - load Illumina native runs
 "kar"                 - an archive extraction tool for .sra files
 "kdbmeta"             - display the contents of one or more metadata stores
 "rcexplain"           - print out error string for return codes (RC)
 "sff-dump"            - dump 454 runs into SFF format
 "sff-load"            - load 454 SFF runs
 "sra-dbcc"            - check SRA runs
 "sra-dump"            - dump any run in a textual format [see note below]
 "sra-kar"             - creates a single file archive from an SRA run
 "sra-stat"            - display run column statistics
 "srf-load"            - load SRF runs
 "vdb-copy"            - dump any run in a textual format [see note below]
 "vdb-dump"            - copy SRA runs


NOTES:

 The textual dumpers "sra-dump" and "vdb-dump" are provided in this
 release as an aid in visual inspection. It is likely that their
 actual output formatting will be changed in the near future to a
 stricter, more formalized representation[s]. PLEASE DO NOT RELY UPON
 THE OUTPUT FORMAT SEEN IN THIS RELEASE.

 The "help" information will be improved in near future releases, and
 the tool options will become standardized across the set. We will
 also be providing documentation on our web site.

 Tool options may change in the next release. Version 1 tool options
 will remain supported wherever possible in order to preserve
 operation of any existing scripts.


CAVEATS:

 SRA tools are designed to handle very large amounts of data, and are
 not currently oriented toward desktop use. They work well within any
 Unix-like environment, such as Linux or MacOS's BSD shell.

 Windows operation presents a few challenges. We have tested our
 binaries under the MS "cmd.exe" shell and Cygwin's bash. Our tools
 know how to accept paths in Windows, Cygwin, POSIX and MinGW
 formats. Internally, all paths are treated as MinGW-style POSIX
 paths, so any information appearing in output will reflect this
 conversion:

   # simple file names
   SRR012345.sra                   => [NO CHANGE]

   # relative paths
   win\SRR012345.sra               => win/SRR012345.sra

   # full or drive-relative paths
   C:\sra\win\SRR012345.sra        => /C/sra/win/SRR012345.sra

   # network paths
   \\server\sra\SRR012345.sra      => //server/sra/SRR012345.sra

   # POSIX paths
   /sra/posix/SRR012345.sra        => [NO CHANGE]

   # Cygwin full paths
   /cygdrive/C/sra/SRR012345.sra   => /C/sra/SRR012345.sra

 There are some situations where the software may behave unexpectedly
 due to path conversions. In particular, since Windows does not
 conform to POSIX path conventions, there may be difficulties
 combining network paths with non-network paths, explicitly or
 implicitly. IF YOU HAVE PROBLEMS, we recommend mounting file servers
 as network drives.

 If you run the software under Cygwin, you should take care to use
 either relative paths (those that do not begin with '/') or full
 paths that start with "/cygdrive/". The reason is that Cygwin
 provides its own path manipulation, but our tools are not aware of
 which shell they are running under.
