Genomedata 1.3 documentation¶

Command-line interface¶

Genomedata archives can be created and loaded from the command line with the genomedata-load command.

Python API¶

The Genomedata package is designed to be used from a variety of scripting languages, but currently only exports the following Python API.

class genomedata.Genome(filename, *args, **kwargs)[source]¶

The root level of the genomedata object hierarchy.

If you use this as a context manager, it will keep track of any open Chromosomes and close them (and the Genome object) for you later when the context is left:

with Genome("/path/to/genomedata") as genome:
  chromosome = genome["chr1"]
  [...]

If not used as a context manager, you are responsible for closing the Genomedata archive once you are done:

>>> genome = Genome("/path/to/genomedata")
>>> chromosome = genome["chr1"]
[...]
>>> genome.close()

__init__(filename, *args, **kwargs)[source]¶

Create a Genome object from a genomdata archive.

Parameters:	filename (string) – the root of the Genomedata object hierarchy. This can either be a .genomedata file that contains the entire genome or a directory containing multiple chromosome files. *args – args passed on to open_file if single file or to Chromosome if directory **kwargs – keyword args passed on to open_file if single file or to Chromosome if directory

Example:

>>> genome = Genome("./genomedata.ctcf.pol2b/")
>>> genome
Genome("./genomedata.ctcf.pol2b/")
    [...]
>>> genome.close()
>>> genome = Genome("./cat_chipseq.genomedata", mode="r")
    [...]
>>> genome.close()

__iter__()[source]¶

Return next chromosome, in sorted order, with memoization.

Example:

for chromosome in genome:
  print chromosome.name
  for supercontig, continuous in chromosome.itercontinuous():
    [...]

__getitem__(name)[source]¶

Return a reference to a chromosome of the given name.

Parameters:	name (string) – name of the chromosome (e.g. “chr1” if chr1.genomedata is a file in the Genomedata archive or chr1 is a top-level group in the single-file Genomedata archive)
Returns:	Chromosome

Example:

>>> genome["chrX"]
<Chromosome 'chrX', file='/path/to/genomedata/chrX.genomedata'>
>>> genome["chrZ"]
KeyError: 'Could not find chromosome: chrZ'

add_track_continuous(trackname)[source]¶

Add a new track

The Genome object must have been created with :param mode:=”r+”. Behavior is undefined if this is not the case.

Currently sets the dirty bit, which can only be erased with genomedata-close-data

close()[source]¶

Close this Genomedata archive and any open chromosomes

If the Genomedata archive is a directory, this closes all open chromosomes. If it is a single file, this closes that file. This should only be used if Genome is not a context manager (see Genome). The behavior is undefined if this is called while Genome is being used as a context manager.

erase_data(trackname)[source]¶

Erase all data for the given track across all chromosomes

The Genome object must have been created with :param mode:=”r+”. Behavior is undefined if this is not the case.

Currently sets the dirty bit, which can only be erased with genomedata-close-data

format_version¶

Genomedata format version

None means there are no chromosomes in it already.

index_continuous(trackname)[source]¶

Return the column index of the trackname in the continuous data.

Parameters:	trackname (string) – name of data track
Returns:	integer

This is used for efficient indexing into continuous data:

>>> col_index = genome.index_continuous("sample_track")
>>> data = genome["chr3"][100:150, col_index]

although for typical use, the track can be indexed directly:

>>> data = genome["chr3"][100:150, "sample_track"]

isopen¶

Return a boolean indicating if the Genome is still open

maxs¶

Return a vector of the maximum value for each track.

Returns:	numpy.array

means¶

Return a vector of the mean value of each track.

Returns:	numpy.array

mins¶

Return the minimum value for each track.

Returns:	numpy.array

num_datapoints¶

Return the number of datapoints in each track.

Returns:	a numpy.array vector with an entry for each track.

num_tracks_continuous¶

Returns the number of continuous data tracks.

sums¶

Return a vector of the sum of the values for each track.

Returns:	numpy.array

sums_squares¶

Return a vector of the sum of squared values for each track’s data.

Returns:	numpy.array

tracknames_continuous¶

Return a list of the names of all data tracks stored.

vars¶

Return a vector of the variance in the data for each track.

Returns:	numpy.array

class genomedata.Chromosome(h5file, where='/', name=None)[source]¶

The Genomedata object corresponding to data for a given chromosome.

Usually created by keying into a Genome object with the name of a chromosome, as in:

>>> with Genome("/path/to/genomedata") as genome:
...     chromosome = genome["chrX"]
...     chromosome
...
<Chromosome 'chrX', file='/path/to/genomedata/chrX.genomedata'>

__iter__()[source]¶

Return next supercontig in chromosome.

New in version 1.2: Supercontigs are ordered by start index

Seldom used in favor of the more direct: Chromosome.itercontinuous()

Example:

>>> for supercontig in chromosome:
...     supercontig  # calls repr()
...
<Supercontig 'supercontig_0', [0:66115833]>
<Supercontig 'supercontig_1', [66375833:90587544]>
<Supercontig 'supercontig_2', [94987544:199501827]>

__getitem__(key)[source]¶

Return the continuous data corresponding to this bp slice

Parameters:	key – base_key must index or slice bases track_key specify data tracks with index, slice, string, list of strings, list of indexes, or array of indexes

but can also index, slice,

or directly specify (string or list of strings) the data tracks.

Returns:	numpy.array

If slice is taken over or outside a supercontig boundary, missing data is filled in with NaN’s automatically and a warning is printed.

Typical use:

>>> chromosome = genome["chr4"]
>>> chromosome[0:5]  # Get all data for the first five bases of chr4
>>> chromosome[0, 0:2]  # Get data for first two tracks at chr4:0
>>> chromosome[100, "ctcf"]  # Get "ctcf" track value at chr4:100

exception ChromosomeDirtyError[source]¶

Chromosome.attrs¶

Return the attributes for this Chromosome.

This may also include Genome-wide attributes if the archive is implemented as a directory.

Chromosome.close()[source]¶

Close the current chromosome file.

This only needs to be called when Genomedata files are manually opened as Chromosomes. Otherwise, Genome.close() should be called to close any open chromosomes or Genomedata files. The behavior is undefined if this is called on a Chromosome accessed through a Genome object. Using Genomedata as a context manager makes life easy by memoizing chromosome access and guaranteeing the proper cleanup. See Genome.

Chromosome.default_mode = 'r'¶

Chromosome.default_where = '/'¶

Chromosome.end¶

Return the index past the last base in this chromosome.

For Genome.format_version > 0, this will be the number of bases of sequence in the chromosome. For == 0, this will be the end of the last supercontig.

This is the end in half-open coordinates, making slicing simple:

>>> chromosome.seq[chromosome.start:chromosome.end]

Chromosome.index_continuous(trackname)[source]¶

Return the column index of the trackname in the continuous data.

Parameters:	trackname (string) – name of data track
Returns:	integer

This is used for efficient indexing into continuous data:

>>> chromosome = genome["chr3"]
>>> col_index = chromosome.index_continuous("sample_track")
>>> data = chromosome[100:150, col_index]

although for typical use, the track can be indexed directly:

>>> data = chromosome[100:150, "sample_track"]

Chromosome.isopen¶

Return a boolean indicating if the Chromosome is still open

Chromosome.itercontinuous()[source]¶

Return a generator over all supercontig, continuous pairs.

New in version 1.2: Supercontigs are ordered by increasing supercontig.start.

This is the best way to efficiently iterate over the data since all specified data is in supercontigs:

for supercontig, continuous in chromosome.itercontinuous():
    print supercontig, supercontig.start, supercontig.end
    [...]

Chromosome.maxs¶

See Genome.maxs

Chromosome.mins¶

See Genome.mins

Chromosome.name¶

Return the name of this chromosome (same as __str__()).

Chromosome.num_datapoints¶

See Genome.num_datapoints

Chromosome.num_tracks_continuous¶

Return the number of tracks in this chromosome

Chromosome.seq¶

Return the genomic sequence of this chromosome.

If the index or slice spans a non-supercontig range, N’s are inserted in place of the missing data and a warning is issued.

Example:

>>> chromosome = genome["chr1"]
>>> for supercontig in chromosome:
...     print repr(supercontig)
...
<Supercontig 'supercontig_0', [0:121186957]>
<Supercontig 'supercontig_1', [141476957:143422081]>
<Supercontig 'supercontig_2', [143522081:247249719]>
>>> chromosome.seq[0:10].tostring()  # Inside supercontig
'taaccctaac'
>>> chromosome.seq[121186950:121186970].tostring()  # supercontig boundary
'agAATTCNNNNNNNNNNNNN'
>>> chromosome.seq[121186957:121186960].tostring()  # not in supercontig
UserWarning: slice of chromosome sequence does not overlap any supercontig (filling with 'N')
'NNN'

The entire sequence for a chromosome can be retrieved with:

>>> chromosome.seq[chromosome.start:chromosome.end]

Chromosome.start¶

Return the index of the first base in this chromosome.

For Genome.format_version > 0, this will always be 0. For == 0, this will be the start of the first supercontig.

Chromosome.sums¶

See Genome.sums

Chromosome.sums_squares¶

See Genome.sums_squares

Chromosome.supercontigs¶

Return the supercontig that contains this range if possible.

Returns:	Supercontig

Indexable with a slice or simple index:

>>> chromosome.supercontigs[100]
[<Supercontig 'supercontig_0', [0:66115833]>]
>>> chromosome.supercontigs[1:100000000]
[<Supercontig 'supercontig_0', [0:66115833]>, <Supercontig 'supercontig_1', [66375833:90587544]>, <Supercontig 'supercontig_2', [94987544:199501827]>]
>>> chromosome.supercontigs[66115833:66375833]  # Between two supercontigs
[]

Chromosome.tracknames_continuous¶

Return a list of the data track names in this Chromosome.

class genomedata.Supercontig(h5group)[source]¶

A container for a segment of data in one chromosome.

Implemented via a HDF5 Group

attrs¶

Return the attributes of this supercontig.

continuous¶

Return the underlying continuous data in this supercontig. To read the whole dataset into memory as a numpy.array, use continuous.read()

Returns:	tables.EArray

end¶

Return the index past the last base in this supercontig.

This is the end in half-open coordinates, making slicing simpler:

>>> supercontig.seq[supercontig.start:supercontig:end]

name¶

Return the name of this supercontig.

project(pos, bound=False)[source]¶

Project chromsomal coordinates to supercontig coordinates.

Parameters:	pos (integer) – chromosome coordinate bound (boolean) – bound result to valid supercontig coordinates
Returns:	integer

seq¶

See Chromosome.seq.

start¶

Return the index of the first base in this supercontig.

The first base is index 0.