A VCFv4.0 and 4.1 parser for Python.
Online version of PyVCF documentation is available at http://pyvcf.rtfd.org/
The intent of this module is to mimic the ``csv`` module in the Python stdlib,
as opposed to more flexible serialization formats like JSON or YAML. ``vcf``
will attempt to parse the content of each record based on the data types
specified in the meta-information lines -- specifically the ##INFO and
##FORMAT lines. If these lines are missing or incomplete, it will check
against the reserved types mentioned in the spec. Failing that, it will just
return strings.
There main interface is the class: ``Reader``. It takes a file-like
object and acts as a reader::
>>> import vcf
>>> vcf_reader = vcf.Reader(open('vcf/test/example-4.0.vcf', 'r'))
>>> for record in vcf_reader:
... print record
Record(CHROM=20, POS=14370, REF=G, ALT=[A])
Record(CHROM=20, POS=17330, REF=T, ALT=[A])
Record(CHROM=20, POS=1110696, REF=A, ALT=[G, T])
Record(CHROM=20, POS=1230237, REF=T, ALT=[None])
Record(CHROM=20, POS=1234567, REF=GTCT, ALT=[G, GTACT])
This produces a great deal of information, but it is conveniently accessed.
The attributes of a Record are the 8 fixed fields from the VCF spec::
* ``Record.CHROM``
* ``Record.POS``
* ``Record.ID``
* ``Record.REF``
* ``Record.ALT``
* ``Record.QUAL``
* ``Record.FILTER``
* ``Record.INFO``
plus attributes to handle genotype information:
* ``Record.FORMAT``
* ``Record.samples``
* ``Record.genotype``
``samples`` and ``genotype``, not being the title of any column, are left lowercase. The format
of the fixed fields is from the spec. Comma-separated lists in the VCF are
converted to lists. In particular, one-entry VCF lists are converted to
one-entry Python lists (see, e.g., ``Record.ALT``). Semicolon-delimited lists
of key=value pairs are converted to Python dictionaries, with flags being given
a ``True`` value. Integers and floats are handled exactly as you'd expect::
>>> vcf_reader = vcf.Reader(open('vcf/test/example-4.0.vcf', 'r'))
>>> record = next(vcf_reader)
>>> print record.POS
14370
>>> print record.ALT
[A]
>>> print record.INFO['AF']
[0.5]
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
3 1.0 0
>>> print record.num_hom_ref, record.num_het, record.num_hom_alt
1 1 1
>>> print record.nucl_diversity, record.aaf, record.heterozygosity
0.6 [0.5] 0.5
>>> print record.get_hets()
[Call(sample=NA00002, CallData(GT=1|0, GQ=48, DP=8, HQ=[51, 51]))]
>>> print record.is_snp, record.is_indel, record.is_transition, record.is_deletion
True False True False
>>> print record.var_type, record.var_subtype
snp ts
>>> print record.is_monomorphic
False
``record.FORMAT`` will be a string specifying the format of the genotype
fields. In case the FORMAT column does not exist, ``record.FORMAT`` is
``None``. Finally, ``record.samples`` is a list of dictionaries containing the
parsed sample column and ``record.genotype`` is a way of looking up genotypes
by sample name::
>>> record = next(vcf_reader)
>>> for sample in record.samples:
... print sample['GT']
0|0
0|1
0/0
>>> print record.genotype('NA00001')['GT']
0|0
The genotypes are represented by ``Call`` objects, which have three attributes: the
corresponding Record ``site``, the sample name in ``sample`` and a dictionary of
call data in ``data``::
>>> call = record.genotype('NA00001')
>>> print call.site
Record(CHROM=20, POS=17330, REF=T, ALT=[A])
>>> print call.sample
NA00001
>>> print call.data
CallData(GT=0|0, GQ=49, DP=3, HQ=[58, 50])
Please note that as of release 0.4.0, attributes known to have single values (such as
``DP`` and ``GQ`` above) are returned as values. Other attributes are returned
as lists (such as ``HQ`` above).
There are also a number of methods::
>>> print call.called, call.gt_type, call.gt_bases, call.phased
True 0 T|T True
Metadata regarding the VCF file itself can be investigated through the
following attributes:
* ``Reader.metadata``
* ``Reader.infos``
* ``Reader.filters``
* ``Reader.formats``
* ``Reader.samples``
For example::
>>> vcf_reader.metadata['fileDate']
'20090805'
>>> vcf_reader.samples
['NA00001', 'NA00002', 'NA00003']
>>> vcf_reader.filters
OrderedDict([('q10', Filter(id='q10', desc='Quality below 10')), ('s50', Filter(id='s50', desc='Less than 50% of samples have data'))])
>>> vcf_reader.infos['AA'].desc
'Ancestral Allele'
ALT records are actually classes, so that you can interrogate them::
>>> reader = vcf.Reader(open('vcf/test/example-4.1-bnd.vcf'))
>>> _ = next(reader); row = next(reader)
>>> print row
Record(CHROM=1, POS=2, REF=T, ALT=[T[2:3[])
>>> bnd = row.ALT[0]
>>> print bnd.withinMainAssembly, bnd.orientation, bnd.remoteOrientation, bnd.connectingSequence
True False True T
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')
>>> # 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])
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::
>>> # 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::
>>> vcf_reader = vcf.Reader(filename='vcf/test/tb.vcf.gz')
>>> vcf_writer = vcf.Writer(open('/dev/null', 'w'), vcf_reader)
>>> 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.
For detailed documentation, see `FILTERS`_.
.. _FILTERS: docs/FILTERS.rst
Raw data
{
"_id": null,
"home_page": "https://github.com/4dn-dcic/PyVCF",
"name": "dcicpyvcf",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.8.0",
"maintainer_email": null,
"keywords": "dcicpyvcf, pyvcf, vcf",
"author": "4DN-DCIC Team",
"author_email": "support@4dnucleome.org",
"download_url": "https://files.pythonhosted.org/packages/0a/ae/c1939479499691fe07ea3f9a327447b71f90bc4ddbc66ccccb2ba40dd1e1/dcicpyvcf-3.1.0.tar.gz",
"platform": null,
"description": "A VCFv4.0 and 4.1 parser for Python.\n\nOnline version of PyVCF documentation is available at http://pyvcf.rtfd.org/\n\nThe intent of this module is to mimic the ``csv`` module in the Python stdlib,\nas opposed to more flexible serialization formats like JSON or YAML. ``vcf``\nwill attempt to parse the content of each record based on the data types\nspecified in the meta-information lines -- specifically the ##INFO and\n##FORMAT lines. If these lines are missing or incomplete, it will check\nagainst the reserved types mentioned in the spec. Failing that, it will just\nreturn strings.\n\nThere main interface is the class: ``Reader``. It takes a file-like\nobject and acts as a reader::\n\n >>> import vcf\n >>> vcf_reader = vcf.Reader(open('vcf/test/example-4.0.vcf', 'r'))\n >>> for record in vcf_reader:\n ... print record\n Record(CHROM=20, POS=14370, REF=G, ALT=[A])\n Record(CHROM=20, POS=17330, REF=T, ALT=[A])\n Record(CHROM=20, POS=1110696, REF=A, ALT=[G, T])\n Record(CHROM=20, POS=1230237, REF=T, ALT=[None])\n Record(CHROM=20, POS=1234567, REF=GTCT, ALT=[G, GTACT])\n\n\nThis produces a great deal of information, but it is conveniently accessed.\nThe attributes of a Record are the 8 fixed fields from the VCF spec::\n\n * ``Record.CHROM``\n * ``Record.POS``\n * ``Record.ID``\n * ``Record.REF``\n * ``Record.ALT``\n * ``Record.QUAL``\n * ``Record.FILTER``\n * ``Record.INFO``\n\nplus attributes to handle genotype information:\n\n * ``Record.FORMAT``\n * ``Record.samples``\n * ``Record.genotype``\n\n``samples`` and ``genotype``, not being the title of any column, are left lowercase. The format\nof the fixed fields is from the spec. Comma-separated lists in the VCF are\nconverted to lists. In particular, one-entry VCF lists are converted to\none-entry Python lists (see, e.g., ``Record.ALT``). Semicolon-delimited lists\nof key=value pairs are converted to Python dictionaries, with flags being given\na ``True`` value. Integers and floats are handled exactly as you'd expect::\n\n >>> vcf_reader = vcf.Reader(open('vcf/test/example-4.0.vcf', 'r'))\n >>> record = next(vcf_reader)\n >>> print record.POS\n 14370\n >>> print record.ALT\n [A]\n >>> print record.INFO['AF']\n [0.5]\n\nThere are a number of convenience methods and properties for each ``Record`` allowing you to\nexamine properties of interest::\n\n >>> print record.num_called, record.call_rate, record.num_unknown\n 3 1.0 0\n >>> print record.num_hom_ref, record.num_het, record.num_hom_alt\n 1 1 1\n >>> print record.nucl_diversity, record.aaf, record.heterozygosity\n 0.6 [0.5] 0.5\n >>> print record.get_hets()\n [Call(sample=NA00002, CallData(GT=1|0, GQ=48, DP=8, HQ=[51, 51]))]\n >>> print record.is_snp, record.is_indel, record.is_transition, record.is_deletion\n True False True False\n >>> print record.var_type, record.var_subtype\n snp ts\n >>> print record.is_monomorphic\n False\n\n``record.FORMAT`` will be a string specifying the format of the genotype\nfields. In case the FORMAT column does not exist, ``record.FORMAT`` is\n``None``. Finally, ``record.samples`` is a list of dictionaries containing the\nparsed sample column and ``record.genotype`` is a way of looking up genotypes\nby sample name::\n\n >>> record = next(vcf_reader)\n >>> for sample in record.samples:\n ... print sample['GT']\n 0|0\n 0|1\n 0/0\n >>> print record.genotype('NA00001')['GT']\n 0|0\n\nThe genotypes are represented by ``Call`` objects, which have three attributes: the\ncorresponding Record ``site``, the sample name in ``sample`` and a dictionary of\ncall data in ``data``::\n\n >>> call = record.genotype('NA00001')\n >>> print call.site\n Record(CHROM=20, POS=17330, REF=T, ALT=[A])\n >>> print call.sample\n NA00001\n >>> print call.data\n CallData(GT=0|0, GQ=49, DP=3, HQ=[58, 50])\n\nPlease note that as of release 0.4.0, attributes known to have single values (such as\n``DP`` and ``GQ`` above) are returned as values. Other attributes are returned\nas lists (such as ``HQ`` above).\n\nThere are also a number of methods::\n\n >>> print call.called, call.gt_type, call.gt_bases, call.phased\n True 0 T|T True\n\nMetadata regarding the VCF file itself can be investigated through the\nfollowing attributes:\n\n * ``Reader.metadata``\n * ``Reader.infos``\n * ``Reader.filters``\n * ``Reader.formats``\n * ``Reader.samples``\n\nFor example::\n\n >>> vcf_reader.metadata['fileDate']\n '20090805'\n >>> vcf_reader.samples\n ['NA00001', 'NA00002', 'NA00003']\n >>> vcf_reader.filters\n OrderedDict([('q10', Filter(id='q10', desc='Quality below 10')), ('s50', Filter(id='s50', desc='Less than 50% of samples have data'))])\n >>> vcf_reader.infos['AA'].desc\n 'Ancestral Allele'\n\nALT records are actually classes, so that you can interrogate them::\n\n >>> reader = vcf.Reader(open('vcf/test/example-4.1-bnd.vcf'))\n >>> _ = next(reader); row = next(reader)\n >>> print row\n Record(CHROM=1, POS=2, REF=T, ALT=[T[2:3[])\n >>> bnd = row.ALT[0]\n >>> print bnd.withinMainAssembly, bnd.orientation, bnd.remoteOrientation, bnd.connectingSequence\n True False True T\n\nThe Reader supports retrieval of records within designated regions for files\nwith tabix indexes via the fetch method. This requires the pysam module as a\ndependency. Pass in a chromosome, and, optionally, start and end coordinates,\nfor the regions of interest::\n\n >>> vcf_reader = vcf.Reader(filename='vcf/test/tb.vcf.gz')\n >>> # fetch all records on chromosome 20 from base 1110696 through 1230237\n >>> for record in vcf_reader.fetch('20', 1110695, 1230237): # doctest: +SKIP\n ... print record\n Record(CHROM=20, POS=1110696, REF=A, ALT=[G, T])\n Record(CHROM=20, POS=1230237, REF=T, ALT=[None])\n\nNote that the start and end coordinates are in the zero-based, half-open\ncoordinate system, similar to ``_Record.start`` and ``_Record.end``. The very\nfirst base of a chromosome is index 0, and the the region includes bases up\nto, but not including the base at the end coordinate. For example::\n\n >>> # fetch all records on chromosome 4 from base 11 through 20\n >>> vcf_reader.fetch('4', 10, 20) # doctest: +SKIP\n\nwould include all records overlapping a 10 base pair region from the 11th base\nof through the 20th base (which is at index 19) of chromosome 4. It would not\ninclude the 21st base (at index 20). (See\nhttp://genomewiki.ucsc.edu/index.php/Coordinate_Transforms for more\ninformation on the zero-based, half-open coordinate system.)\n\nThe ``Writer`` class provides a way of writing a VCF file. Currently, you must specify a\ntemplate ``Reader`` which provides the metadata::\n\n >>> vcf_reader = vcf.Reader(filename='vcf/test/tb.vcf.gz')\n >>> vcf_writer = vcf.Writer(open('/dev/null', 'w'), vcf_reader)\n >>> for record in vcf_reader:\n ... vcf_writer.write_record(record)\n\nAn extensible script is available to filter vcf files in vcf_filter.py. VCF filters\ndeclared by other packages will be available for use in this script.\n\nFor detailed documentation, see `FILTERS`_.\n\n.. _FILTERS: docs/FILTERS.rst\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Variant Call Format (VCF) parser for Python",
"version": "3.1.0",
"project_urls": {
"Homepage": "https://github.com/4dn-dcic/PyVCF",
"Repository": "https://github.com/4dn-dcic/PyVCF.git"
},
"split_keywords": [
"dcicpyvcf",
" pyvcf",
" vcf"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bd6c7018d49f920347f19c3a3fe58c905cae7bf8437100ad83dca15292522570",
"md5": "2ec799c1041366284e7def8882528d02",
"sha256": "be42453cab4e4b64cb8ecb0fa8b49bc33a27aa541274a8becb264d7d6517def4"
},
"downloads": -1,
"filename": "dcicpyvcf-3.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2ec799c1041366284e7def8882528d02",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.8.0",
"size": 976540,
"upload_time": "2024-07-03T09:43:56",
"upload_time_iso_8601": "2024-07-03T09:43:56.038068Z",
"url": "https://files.pythonhosted.org/packages/bd/6c/7018d49f920347f19c3a3fe58c905cae7bf8437100ad83dca15292522570/dcicpyvcf-3.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0aaec1939479499691fe07ea3f9a327447b71f90bc4ddbc66ccccb2ba40dd1e1",
"md5": "cce60350b7c717177b7b31e8c4b6f700",
"sha256": "761312d5db5ebf415efa56edbdf2dc275b7e1827582702a48b9b8fa333cb8f48"
},
"downloads": -1,
"filename": "dcicpyvcf-3.1.0.tar.gz",
"has_sig": false,
"md5_digest": "cce60350b7c717177b7b31e8c4b6f700",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.8.0",
"size": 964887,
"upload_time": "2024-07-03T09:43:58",
"upload_time_iso_8601": "2024-07-03T09:43:58.106002Z",
"url": "https://files.pythonhosted.org/packages/0a/ae/c1939479499691fe07ea3f9a327447b71f90bc4ddbc66ccccb2ba40dd1e1/dcicpyvcf-3.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-03 09:43:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "4dn-dcic",
"github_project": "PyVCF",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"lcname": "dcicpyvcf"
}
JSON
