Misc doc updates

Author: martijnvermaat

README.rst

@@ -58,7 +58,7 @@ a ``True`` value. Integers and floats are handled exactly as you'd expect::
     >>> print record.INFO['AF']
     [0.5]
 
-There are a number of convienience methods and properties for each ``Record`` allowing you to
+There are a number of convenience methods and properties for each ``Record`` allowing you to
 examine properties of interest::
 
     >>> print record.num_called, record.call_rate, record.num_unknown
@@ -142,19 +142,31 @@ ALT records are actually classes, so that you can interrogate them::
     >>> print bnd.withinMainAssembly, bnd.orientation, bnd.remoteOrientation, bnd.connectingSequence
     True False True T
 
-Random access is supported for files with tabix indexes. This requires the pysam module as a dependency.  Simply call fetch for the region you are interested in::
+The Reader supports retrieval of records within designated regions for files
+with tabix indexes via the fetch method. This requires the pysam module as a
+dependency. Pass in a chromosome, and, optionally, start and end coordinates,
+for the regions of interest::
 
     >>> vcf_reader = vcf.Reader(filename='vcf/test/tb.vcf.gz')
-    >>> for record in vcf_reader.fetch('20', 1110696, 1230237):  # doctest: +SKIP
+    >>> # fetch all records on chromosome 20 from base 1110696 through 1230237
+    >>> for record in vcf_reader.fetch('20', 1110695, 1230237):  # doctest: +SKIP
     ...     print record
     Record(CHROM=20, POS=1110696, REF=A, ALT=[G, T])
     Record(CHROM=20, POS=1230237, REF=T, ALT=[None])
 
-Or extract a single row::
+Note that the start and end coordinates are in the zero-based, half-open
+coordinate system, similar to ``_Record.start`` and ``_Record.end``. The very
+first base of a chromosome is index 0, and the the region includes bases up
+to, but not including the base at the end coordinate. For example::
 
-    >>> print vcf_reader.fetch('20', 1110696)  # doctest: +SKIP
-    Record(CHROM=20, POS=1110696, REF=A, ALT=[G, T])
+    >>> # fetch all records on chromosome 4 from base 11 through 20
+    >>> vcf_reader.fetch('4', 10, 20)   # doctest: +SKIP
 
+would include all records overlapping a 10 base pair region from the 11th base
+of through the 20th base (which is at index 19) of chromosome 4. It would not
+include the 21st base (at index 20). (See
+http://genomewiki.ucsc.edu/index.php/Coordinate_Transforms for more
+information on the zero-based, half-open coordinate system.)
 
 The ``Writer`` class provides a way of writing a VCF file.  Currently, you must specify a
 template ``Reader`` which provides the metadata::
@@ -164,8 +176,6 @@ template ``Reader`` which provides the metadata::
     >>> for record in vcf_reader:
     ...     vcf_writer.write_record(record)
 
-
 An extensible script is available to filter vcf files in vcf_filter.py.  VCF filters
 declared by other packages will be available for use in this script.  Please
 see :doc:`FILTERS` for full description.
-

docs/API.rst

@@ -14,43 +14,43 @@ vcf.Writer
    :members:
 
 vcf.model._Record
------------
+-----------------
 
 .. autoclass:: vcf.model._Record
    :members:
 
 vcf.model._Call
----------
+---------------
 
 .. autoclass:: vcf.model._Call
    :members:
 
 vcf.model._AltRecord
------------
+--------------------
 
 .. autoclass:: vcf.model._AltRecord
    :members:
 
 vcf.model._Substitution
------------
+-----------------------
 
 .. autoclass:: vcf.model._Substitution
    :members:
 
 vcf.model._SV
------------
+-------------
 
 .. autoclass:: vcf.model._SV
    :members:
 
 vcf.model._SingleBreakend
------------
+-------------------------
 
 .. autoclass:: vcf.model._SingleBreakend
    :members:
 
 vcf.model._Breakend
------------
+-------------------
 
 .. autoclass:: vcf.parser._Breakend
    :members:

docs/HISTORY.rst

@@ -2,15 +2,15 @@ Development
 ===========
 
 Please use the `PyVCF repository <https://github.com/jamescasbon/PyVCF/>`_.
-Pull requests gladly accepted. 
+Pull requests gladly accepted.
 Issues should be reported at the github issue tracker.
 
 Running tests
 -------------
 
 Please check the tests by running them with::
 
-    python setup.py test 
+    python setup.py test
 
 New features should have test code sent with them.
 
@@ -20,7 +20,7 @@ Changes
 0.6.7 Release
 -------------
 
-* Include missing .pyx files 
+* Include missing .pyx files
 
 0.6.6 Release
 -------------
@@ -56,17 +56,17 @@ Changes
 -------------
 
 * cython port of #79
-* correct writing of meta lines #84 
+* correct writing of meta lines #84
 
 0.6.2 Release
 -------------
 
-* issues #78, #79 (thanks Sean, Brad) 
+* issues #78, #79 (thanks Sean, Brad)
 
 0.6.1 Release
 -------------
 
-* Add strict whitespace mode for well formed VCFs with spaces 
+* Add strict whitespace mode for well formed VCFs with spaces
   in sample names (thanks Marco)
 * Ignore blank lines in files (thanks Martijn)
 * Tweaks for handling missing data (thanks Sean)
@@ -76,24 +76,24 @@ Changes
 0.6.0 Release
 -------------
 
-* Backwards incompatible change: _Call.data is now a 
+* Backwards incompatible change: _Call.data is now a
   namedtuple (previously it was a dict)
-* Optional cython version, much improved performance.  
+* Optional cython version, much improved performance.
 * Improvements to writer (thanks @cmclean)
 * Improvements to inheritance of classes (thanks @lennax)
 
 
 0.5.0 Release
 -------------
 
-VCF 4.1 support: 
- * support missing genotype #28 (thanks @martijnvermaat)
- * parseALT for svs #42, #48 (thanks @dzerbino)
+* VCF 4.1 support:
+  - support missing genotype #28 (thanks @martijnvermaat)
+  - parseALT for svs #42, #48 (thanks @dzerbino)
 * `trim_common_suffix` method #22 (thanks @martijnvermaat)
 * Multiple metadata with the same key is stored (#52)
-Writer improvements
- * A/G in Number INFO fields #53 (thanks @lennax) 
- * Better output #55 (thanks @cmclean)
+* Writer improvements:
+  - A/G in Number INFO fields #53 (thanks @lennax)
+  - Better output #55 (thanks @cmclean)
 * Allow malformed INFO fields #49 (thanks @ilyaminkin)
 * Added bayes factor error bias VCF filter
 * Added docs on vcf_melt
@@ -103,14 +103,14 @@ Writer improvements
 0.4.6 Release
 -------------
 
-* Performance improvements (#47) 
+* Performance improvements (#47)
 * Preserve order of INFO column (#46)
 
 0.4.5 Release
 -------------
 
-* Support exponent syntax qual values (#43, #44) (thanks @martijnvermaat) 
-* Preserve order of header lines (#45) 
+* Support exponent syntax qual values (#43, #44) (thanks @martijnvermaat)
+* Preserve order of header lines (#45)
 
 0.4.4 Release
 -------------
@@ -139,15 +139,15 @@ Writer improvements
 0.4.0 Release
 -------------
 
-* Package structure 
+* Package structure
 * add ``vcf.utils`` module with ``walk_together`` method
-* samtools tests 
+* samtools tests
 * support Freebayes' non standard '.' for no call
-* fix vcf_melt  
+* fix vcf_melt
 * support monomorphic sites, add ``is_monomorphic`` method, handle null QUALs
-* filter support for files with monomorphic calls 
+* filter support for files with monomorphic calls
 * Values declared as single are no-longer returned in lists
-* several performance improvements 
+* several performance improvements
 
 
 0.3.0 Release
@@ -170,14 +170,14 @@ Documentation release
 
 * Add shebang to vcf_filter.py
 
-0.2 Release 
+0.2 Release
 -----------
 
 * Replace genotype dictionary with a ``Call`` object
 * Methods on ``Record`` and ``Call`` (thanks @arq5x)
 * Shortcut parse_sample when genotype is None
 
-0.1 Release 
+0.1 Release
 -----------
 
 * Added test code
@@ -188,7 +188,7 @@ Documentation release
 * Allow opening by filename as well as filesocket
 * Support fetching rows for tabixed indexed files
 * Performance improvements (see ``test/prof.py``)
-* Added extensible filter script (see FILTERS.md), vcf_filter.py 
+* Added extensible filter script (see FILTERS.md), vcf_filter.py
 
 Contributions
 =============
@@ -197,4 +197,3 @@ Project started by @jdoughertyii and taken over by @jamescasbon on 12th January
 Contributions from @arq5x, @brentp, @martijnvermaat, @ian1roberts, @marcelm.
 
 This project was supported by `Population Genetics <http://www.populationgenetics.com/>`_.
-

docs/INTRO.rst

@@ -1,5 +1,4 @@
 Introduction
 ============
 
-.. automodule:: vcf
-
+.. include:: ../README.rst

vcf/__init__.py

@@ -1,4 +1,10 @@
 #!/usr/bin/env python
+"""
+A VCFv4.0 and 4.1 parser for Python.
+
+Online version of PyVCF documentation is available at http://pyvcf.rtfd.org/
+"""
+
 
 from vcf.parser import Reader, Writer
 from vcf.parser import VCFReader, VCFWriter

vcf/model.py

@@ -330,7 +330,7 @@ def nucl_diversity(self):
 
         Derived from:
         \"Population Genetics: A Concise Guide, 2nd ed., p.45\"
-          John Gillespie.
+        John Gillespie.
         """
         # skip if more than one alternate allele. assumes bi-allelic
         if len(self.ALT) > 1:
@@ -467,13 +467,14 @@ def var_type(self):
     def var_subtype(self):
         """
         Return the subtype of variant.
+
         - For SNPs and INDELs, yeild one of: [ts, tv, ins, del]
-        - For SVs yield either "complex" or the SV type defined
-          in the ALT fields (removing the brackets).
-          E.g.:
-               <DEL>       -> DEL
-               <INS:ME:L1> -> INS:ME:L1
-               <DUP>       -> DUP
+        - For SVs yield either "complex" or the SV type defined in the ALT
+          fields (removing the brackets). E.g.::
+
+              <DEL>       -> DEL
+              <INS:ME:L1> -> INS:ME:L1
+              <DUP>       -> DUP
 
         The logic is meant to follow the rules outlined in the following
         paragraph at: