Merge pull request #78 from pysam-developers/pysam-0.8.2

Pysam 0.8.2

.gitignore

@@ -12,9 +12,7 @@ tests/*.c
 tests/*.pyxbldc
 tests/*.sam
 tests/*.fai
-tests/pysam_data/*.bam
-tests/pysam_data/*.bam.bai
-tests/pysam_test_work
+tests/pysam_data
 
 # cython files
 pysam/TabProxies.c

AUTHORS

@@ -1,10 +1,12 @@
 List of contributors:
 
-Andreas Heger, Tildon Grant Belgard, Kevin B. Jacobs, Florian
-Finkernagel, Leo Goodstadt, Martin Goodson all contributed code
-to pysam.
+Andreas Heger, Tildon Grant Belgard, Florian Finkernagel, Leo
+Goodstadt, Martin Goodson all contributed code to pysam.
 
-Gerton Lunter provided a VCF parser.
+Kevin B. Jacobs implemented a Cython wrapper for the VCF/BCF
+reader/writer in htslib.
+
+Gerton Lunter provided a validating VCF parser.
 
 Marcel Martin implemented python 3 compatibility.
 Ben Schiller contributed a Windows compatible clone.

doc/faq.rst

@@ -84,6 +84,24 @@ Note that re-opening files incurs a performance penalty which can
 become severe when calling :meth:`~pysam.AlignmentFile.fetch` often.
 Thus, ``multiple_iterators`` is set to ``False`` by default.
 
+AlignmentFile.fetch does not show unmapped reads
+================================================
+
+:meth:`~pysam.AlignmentFile.fetch` will only iterate over alignments
+in the SAM/BAM file. The following thus always works::
+
+    bf = pysam.AlignemFile(fname, "rb")
+    for r in bf.fetch():
+        assert not r.is_unmapped
+
+If the SAM/BAM file contains unaligned reads, they can be included
+in the iteration by adding the ``until_eof=True`` flag::
+
+    bf = pysam.AlignemFile(fname, "rb")
+    for r in bf.fetch(until_eof=True):
+        if r.is_unmapped:
+	    print "read is unmapped"
+	
 BAM files with a large number of reference sequences is slow
 ============================================================
 
@@ -100,7 +118,7 @@ header. This might require a lot of jumping around in the file. To
 avoid this, use::
 
       track = pysam.AlignmentFile(fname, "rb")
-      for aln in track.fetch(until_eof = True):
+      for aln in track.fetch(until_eof=True):
       	  pass
  
 This will iterate through reads as they appear in the file.

doc/release.rst

@@ -3,11 +3,23 @@ Release notes
 =============
 
 Release 0.8.2
+=============
 
+* Pysam now wraps htslib 1.2.1 and samtools version 1.2
+* Added CRAM file support to pysam
+* New alignment info interface.
+   * opt() and setTag are deprecated, use get_tag() and set_tag()
+     instead.
+   * added has_tag()
+   * tags is deprecated, use get_tags() and set_tags() instead.
 * FastqFile is now FastxFile to reflect that the latter permits
   iteration over both fastq- and fasta-formatted files.
+* A Cython wrapper for htslib VCF/BCF reader/writer. The wrapper
+  provides a nearly complete Pythonic interface to VCF/BCF metadata
+  with reading and writing capability. However, the interface is still
+  incomplete and preliminary and lacks capability to mutate the
+  resulting data.
 
-
 Release 0.8.1
 =============
 

htslib/INSTALL

@@ -1,25 +1,79 @@
-System Requirements
-===================
+Basic Installation
+==================
 
-HTSlib depends on the zlib library <http://zlib.net>.  Building HTSlib requires
-zlib development files to be installed on the build machine; you may need to
-ensure a package such as zlib1g-dev (on Debian or Ubuntu Linux) or zlib-devel
-(on RPM/yum-based distributions) is installed.
+To build and install HTSlib, 'cd' to the htslib-1.x directory containing
+the package's source and type the following commands:
 
+    ./configure
+    make
+    make install
 
-Compilation
-===========
+The './configure' command checks your build environment and allows various
+optional functionality to be enabled (see Configuration below).  If you
+don't want to select any optional functionality, you may wish to omit
+configure and just type 'make; make install' as for previous versions
+of HTSlib.  However if the build fails you should run './configure' as
+it can diagnose the common reasons for build failures.
 
-'cd' to the htslib-1.x directory containing the package's source and type
-'make' to compile HTSlib.
+The 'make' command builds the HTSlib library and and various useful
+utilities: bgzip, htsfile, and tabix.  If compilation fails you should
+run './configure' as it can diagnose problems with your build environment
+that cause build failures.
 
+The 'make install' command installs the libraries, library header files,
+utilities, several manual pages, and a pkgconfig file to /usr/local.
+The installation location can be changed by configuring with --prefix=DIR
+or via 'make prefix=DIR install' (see Installation Locations below).
 
-Installation
-============
 
-Type 'make install' to install the bgzip and tabix utilities, library headers,
-library archives, several manual pages, and a pkgconfig file to /usr/local.
+Configuration
+=============
 
-Type 'make prefix=/path/to/dir install' to install everything under your
-choice of installation directory.  The install target also understands
-DESTDIR and the other usual installation directory variables.
+By default, './configure' examines your build environment, checking for
+requirements such as the zlib development files, and arranges for a plain
+HTSlib build.  The following configure options can be used to enable
+various features and specify further optional external requirements:
+
+--with-irods[=DIR]
+    Specifies the location of the iRODS client library to use to enable
+    access to data objects stored in iRODS (<http://irods.org/>) via file
+    paths like 'irods:DATAOBJ'.  DIR is the base of an iRODS source tree
+    such that the library is present as DIR/lib/core/obj/libRodsAPI.* and
+    headers are present under DIR/lib/api/include and so on.  If '=DIR' is
+    omitted, $IRODS_HOME will be used as a base directory.
+
+The configure script also accepts the usual options and environment variables
+for tuning installation locations and compilers: type './configure --help'
+for details.  For example,
+
+    ./configure CC=icc --prefix=/opt/icc-compiled
+
+would specify that HTSlib is to be built with icc and installed into bin,
+lib, etc subdirectories under /opt/icc-compiled.
+
+
+Installation Locations
+======================
+
+By default, 'make install' installs HTSlib libraries under /usr/local/lib,
+HTSlib header files under /usr/local/include, utility programs under
+/usr/local/bin, etc.  (To be precise, the header files are installed within
+a fixed 'htslib' subdirectory under the specified .../include location.)
+
+You can specify a different location to install HTSlib by configuring
+with --prefix=DIR or specify locations for particular parts of HTSlib by
+configuring with --libdir=DIR and so on.  Type './configure --help' for
+the full list of such install directory options.
+
+Alternatively you can specify different locations at install time by
+typing 'make prefix=DIR install' or 'make libdir=DIR install' and so on.
+Consult the list of prefix/exec_prefix/etc variables near the top of the
+Makefile for the full list of such variables that can be overridden.
+
+You can also specify a staging area by typing 'make DESTDIR=DIR install',
+possibly in conjunction with other --prefix or prefix=DIR settings.
+For example,
+
+    make DESTDIR=/tmp/staging prefix=/opt
+
+would install into bin, lib, etc subdirectories under /tmp/staging/opt.