Specifying genomes

This section illustrates the use of genome files for use with BEDTools programs that need to know chromosome limits to prevent out-of-range coordinates.

Using BEDTools programs like slopBed or shuffleBed from the command line requires “genome” or “chromsizes” files. pybedtools comes with common genome assemblies already set up as a dictionary with chromosomes as keys and zero-based (start, stop) tuples as values:

>>> from pybedtools import genome_registry
>>> genome_registry.dm3['chr2L']
(0, 23011544)

The rules for specifying a genome for methods that require a genome are as follows (use whatever is most convenient):

  • Use g to specify either a filename or a dictionary
  • Use genome to specify either an assembly name or a dictionary

Below are examples of each.

As a file

This is the typical way of using BEDTools programs, by specifying an existing genome file with g:

>>> a = pybedtools.example_bedtool('a.bed')
>>> b = a.slop(b=100, g='hg19.genome')

As a string

This is probably the most convenient way of specifying a genome. If the genome exists in the genome registry it will be used directly; otherwise it will automatically be downloaded from UCSC. You must use the genome kwarg for this; if you use g a string will be interpreted as a filename:

>>> c = a.slop(b=100, genome='hg19')

As a dictionary

This is a good way of providing custom coordinates; either g or genome will accept a dictionary:

>>> d = a.slop(b=100, g={'chr1':(1, 10000)})
>>> e = a.slop(b=100, genome={'chr1':(1,100000)})

Make sure that all these different methods return the same results

>>> b == c == d == e
True

Converting to a file

Since BEDTools programs operate on files, the fastest choice will be to use an existing file. While the time to convert a dictionary to a file is extremely small, over 1000’s of files (e.g., for Monte Carlo simulations), the time may add up. The function pybedtools.chromsizes_to_file() will create a file from a dictionary or string:

>>> # with no filename specified, a tempfile will be created
>>> pybedtools.chromsizes_to_file(pybedtools.chromsizes('dm3'), 'dm3.genome')
'dm3.genome'
>>> print(open('dm3.genome').read())
chr2L       23011544
chr2LHet    368872
chr2R       21146708
chr2RHet    3288761
chr3L       24543557
chr3LHet    2555491
chr3R       27905053
chr3RHet    2517507
chr4        1351857
chrM        19517
chrU        10049037
chrUextra   29004656
chrX        22422827
chrXHet     204112
chrYHet     347038