Bio.Graphics.GenomeDiagram package

Module contents

GenomeDiagram module integrated into Biopython.

class Bio.Graphics.GenomeDiagram.Diagram(name=None, format='circular', pagesize='A3', orientation='landscape', x=0.05, y=0.05, xl=None, xr=None, yt=None, yb=None, start=None, end=None, tracklines=False, fragments=10, fragment_size=None, track_size=0.75, circular=True, circle_core=0.0)

Bases: object

Diagram container.

Arguments:

  • name - a string, identifier for the diagram.

  • tracks - a list of Track objects comprising the diagram.

  • format - a string, format of the diagram ‘circular’ or ‘linear’, depending on the sort of diagram required.

  • pagesize - a string, the pagesize of output describing the ISO size of the image, or a tuple of pixels.

  • orientation - a string describing the required orientation of the final drawing (‘landscape’ or ‘portrait’).

  • x - a float (0->1), the proportion of the page to take up with even X margins t the page.

  • y - a float (0->1), the proportion of the page to take up with even Y margins to the page.

  • xl - a float (0->1), the proportion of the page to take up with the left X margin to the page (overrides x).

  • xr - a float (0->1), the proportion of the page to take up with the right X margin to the page (overrides x).

  • yt - a float (0->1), the proportion of the page to take up with the top Y margin to the page (overrides y).

  • yb - a float (0->1), the proportion of the page to take up with the bottom Y margin to the page (overrides y).

  • circle_core - a float, the proportion of the available radius to leave empty at the center of a circular diagram (0 to 1).

  • start - an integer, the base/aa position to start the diagram at.

  • end - an integer, the base/aa position to end the diagram at.

  • tracklines - a boolean, True if track guidelines are to be drawn.

  • fragments - and integer, for a linear diagram, the number of equal divisions into which the sequence is divided.

  • fragment_size - a float (0->1), the proportion of the space available to each fragment that should be used in drawing.

  • track_size - a float (0->1), the proportion of the space available to each track that should be used in drawing with sigils.

  • circular - a boolean, True if the genome/sequence to be drawn is, in reality, circular.

__init__(name=None, format='circular', pagesize='A3', orientation='landscape', x=0.05, y=0.05, xl=None, xr=None, yt=None, yb=None, start=None, end=None, tracklines=False, fragments=10, fragment_size=None, track_size=0.75, circular=True, circle_core=0.0)

Initialize.

gdd = Diagram(name=None)

set_all_tracks(attr, value)

Set the passed attribute of all tracks in the set to the passed value.

Arguments:

  • attr - An attribute of the Track class.

  • value - The value to set that attribute.

set_all_tracks(self, attr, value)

draw(format=None, pagesize=None, orientation=None, x=None, y=None, xl=None, xr=None, yt=None, yb=None, start=None, end=None, tracklines=None, fragments=None, fragment_size=None, track_size=None, circular=None, circle_core=None, cross_track_links=None)

Draw the diagram, with passed parameters overriding existing attributes.

gdd.draw(format=’circular’)

write(filename='test1.ps', output='PS', dpi=72)

Write the drawn diagram to a specified file, in a specified format.

Arguments:

  • filename - a string indicating the name of the output file, or a handle to write to.

  • output - a string indicating output format, one of PS, PDF, SVG, or provided the ReportLab renderPM module is installed, one of the bitmap formats JPG, BMP, GIF, PNG, TIFF or TIFF. The format can be given in upper or lower case.

  • dpi - an integer. Resolution (dots per inch) for bitmap formats.

Returns:

No return value.

write(self, filename=’test1.ps’, output=’PS’, dpi=72)

write_to_string(output='PS', dpi=72)

Return a byte string containing the diagram in the requested format.

Arguments:

  • output - a string indicating output format, one of PS, PDF, SVG, JPG, BMP, GIF, PNG, TIFF or TIFF (as specified for the write method).

  • dpi - Resolution (dots per inch) for bitmap formats.

Returns:

Return the completed drawing as a bytes string in a prescribed format.

add_track(track, track_level)

Add a Track object to the diagram.

It also accepts instructions to place it at a particular level on the diagram.

Arguments:

  • track - Track object to draw.

  • track_level - an integer. The level at which the track will be drawn (above an arbitrary baseline).

add_track(self, track, track_level)

new_track(track_level, **args)

Add a new Track to the diagram at a given level.

The track is returned for further user manipulation.

Arguments:

  • track_level - an integer. The level at which the track will be drawn (above an arbitrary baseline).

new_track(self, track_level)

del_track(track_level)

Remove the track to be drawn at a particular level on the diagram.

Arguments:

  • track_level - an integer. The level of the track on the diagram to delete.

del_track(self, track_level)

get_tracks()

Return a list of the tracks contained in the diagram.

move_track(from_level, to_level)

Move a track from one level on the diagram to another.

Arguments:

  • from_level - an integer. The level at which the track to be moved is found.

  • to_level - an integer. The level to move the track to.

renumber_tracks(low=1, step=1)

Renumber all tracks consecutively.

Optionally from a passed lowest number.

Arguments:

  • low - an integer. The track number to start from.

  • step - an integer. The track interval for separation of tracks.

get_levels()

Return a sorted list of levels occupied by tracks in the diagram.

get_drawn_levels()

Return a sorted list of levels occupied by tracks.

These tracks are not explicitly hidden.

range()

Return lowest and highest base numbers from track features.

Returned type is a tuple.

__getitem__(key)

Return the track contained at the level of the passed key.

__str__()

Return a formatted string describing the diagram.

class Bio.Graphics.GenomeDiagram.Track(name=None, height=1, hide=0, greytrack=0, greytrack_labels=5, greytrack_fontsize=8, greytrack_font='Helvetica', greytrack_font_rotation=0, greytrack_font_color=_grey, scale=1, scale_format=None, scale_color=colors.black, scale_font='Helvetica', scale_fontsize=6, scale_fontangle=45, scale_largeticks=0.5, scale_ticks=1, scale_smallticks=0.3, scale_largetick_interval=1e6, scale_smalltick_interval=1e4, scale_largetick_labels=1, scale_smalltick_labels=0, axis_labels=1, start=None, end=None, greytrack_font_colour=None, scale_colour=None)

Bases: object

Track.

Attributes:

  • height Int describing the relative height to other trackscale_fontsizes in the diagram

  • name String describing the track

  • hide Boolean, 0 if the track is not to be drawn

  • start, end Integers (or None) specifying start/end to draw just a partial track.

  • greytrack Boolean, 1 if a grey background to the track is to be drawn

  • greytrack_labels Int describing how many track-identifying labels should be placed on the track at regular intervals

  • greytrack_font String describing the font to use for the greytrack labels

  • greytrack_fontsize Int describing the font size to display the labels on the grey track

  • greytrack_font_rotation Int describing the angle through which to rotate the grey track labels (Linear only)

  • greytrack_font_color colors.Color describing the color to draw the grey track labels

  • scale Boolean, 1 if a scale is to be drawn on the track

  • scale_format String, defaults to None, when scale values are written as numerals. Setting this to ‘SInt’ invokes SI unit-like multiples, such as Mbp, Kbp and so on.

  • scale_color colors.Color to draw the elements of the scale

  • scale_font String describing the font to use for the scale labels

  • scale_fontsize Int describing the size of the scale label font

  • scale_fontangle Int describing the angle at which to draw the scale labels (linear only)

  • scale_ticks Boolean, 1 if ticks should be drawn at all on the scale

  • scale_largeticks Float (0->1) describing the height of large scale ticks relative to the track height.

  • scale_smallticks Float (0->1) describing the height of large scale ticks relative to the track height.

  • scale_largetick_interval Int, describing the number of bases that should separate large ticks

  • scale_smalltick_interval Int, describing the number of bases that should separate small ticks

  • scale_largetick_labels Boolean describing whether position labels should be written over large ticks

  • scale_smalltick_labels Boolean describing whether position labels should be written over small ticks

  • axis_labels Boolean describing whether the value labels should be placed on the Y axes

__init__(name=None, height=1, hide=0, greytrack=0, greytrack_labels=5, greytrack_fontsize=8, greytrack_font='Helvetica', greytrack_font_rotation=0, greytrack_font_color=_grey, scale=1, scale_format=None, scale_color=colors.black, scale_font='Helvetica', scale_fontsize=6, scale_fontangle=45, scale_largeticks=0.5, scale_ticks=1, scale_smallticks=0.3, scale_largetick_interval=1e6, scale_smalltick_interval=1e4, scale_largetick_labels=1, scale_smalltick_labels=0, axis_labels=1, start=None, end=None, greytrack_font_colour=None, scale_colour=None)

Initialize.

Arguments:

  • height Int describing the relative height to other tracks in the diagram

  • name String describing the track

  • hide Boolean, 0 if the track is not to be drawn

  • greytrack Boolean, 1 if a grey background to the track is to be drawn

  • greytrack_labels Int describing how many track-identifying labels should be placed on the track at regular intervals

  • greytrack_font String describing the font to use for the greytrack labels

  • greytrack_fontsize Int describing the font size to display the labels on the grey track

  • greytrack_font_rotation Int describing the angle through which to rotate the grey track labels (Linear only)

  • greytrack_font_color colors.Color describing the color to draw the grey track labels (overridden by backwards compatible argument with UK spelling, colour).

  • scale Boolean, 1 if a scale is to be drawn on the track

  • scale_color colors.Color to draw the elements of the scale (overridden by backwards compatible argument with UK spelling, colour).

  • scale_font String describing the font to use for the scale labels

  • scale_fontsize Int describing the size of the scale label font

  • scale_fontangle Int describing the angle at which to draw the scale labels (linear only)

  • scale_ticks Boolean, 1 if ticks should be drawn at all on the scale

  • scale_largeticks Float (0->1) describing the height of large scale ticks relative to the track height.

  • scale_smallticks Float (0->1) describing the height of large scale ticks relative to the track height.

  • scale_largetick_interval Int, describing the number of bases that should separate large ticks

  • scale_smalltick_interval Int, describing the number of bases that should separate small ticks

  • scale_largetick_labels Boolean describing whether position labels should be written over large ticks

  • scale_smalltick_labels Boolean describing whether position labels should be written over small ticks

  • name String to help identify the track

  • height Relative height to draw the track

  • axis_labels Boolean describing whether the value labels should be placed on the Y axes

add_set(set)

Add a preexisting FeatureSet or GraphSet object to the track.

new_set(type='feature', **args)

Create a new FeatureSet or GraphSet object.

Create a new FeatureSet or GraphSet object, add it to the track, and return for user manipulation

del_set(set_id)

Remove the set with the passed id from the track.

get_sets()

Return the sets contained in this track.

get_ids()

Return the ids of all sets contained in this track.

range()

Return the lowest and highest base (or mark) numbers as a tuple.

to_string(verbose=0)

Return a formatted string with information about the track.

Arguments:

  • verbose - Boolean indicating whether a short or complete account of the track is required

__getitem__(key)

Return the set with the passed id.

__str__()

Return a formatted string with information about the Track.

class Bio.Graphics.GenomeDiagram.FeatureSet(set_id=None, name=None, parent=None)

Bases: object

FeatureSet object.

__init__(set_id=None, name=None, parent=None)

Create the object.

Arguments:

  • set_id: Unique id for the set

  • name: String identifying the feature set

add_feature(feature, **kwargs)

Add a new feature.

Arguments:

  • feature: Bio.SeqFeature object

  • kwargs: Keyword arguments for Feature. Named attributes of the Feature

Add a Bio.SeqFeature object to the diagram (will be stored internally in a Feature wrapper).

del_feature(feature_id)

Delete a feature.

Arguments:

  • feature_id: Unique id of the feature to delete

Remove a feature from the set, indicated by its id.

set_all_features(attr, value)

Set an attribute of all the features.

Arguments:

  • attr: An attribute of the Feature class

  • value: The value to set that attribute to

Set the passed attribute of all features in the set to the passed value.

get_features(attribute=None, value=None, comparator=None)

Retrieve features.

Arguments:

  • attribute: String, attribute of a Feature object

  • value: The value desired of the attribute

  • comparator: String, how to compare the Feature attribute to the passed value

If no attribute or value is given, return a list of all features in the feature set. If both an attribute and value are given, then depending on the comparator, then a list of all features in the FeatureSet matching (or not) the passed value will be returned. Allowed comparators are: ‘startswith’, ‘not’, ‘like’.

The user is expected to make a responsible decision about which feature attributes to use with which passed values and comparator settings.

get_ids()

Return a list of all ids for the feature set.

range()

Return the lowest and highest base (or mark) numbers as a tuple.

to_string(verbose=0)

Return a formatted string with information about the set.

Arguments:

  • verbose: Boolean indicating whether a short (default) or complete account of the set is required

__len__()

Return the number of features in the set.

__getitem__(key)

Return a feature, keyed by id.

__str__()

Return a formatted string with information about the feature set.

class Bio.Graphics.GenomeDiagram.Feature(parent=None, feature_id=None, feature=None, color=colors.lightgreen, label=0, border=None, colour=None)

Bases: object

Class to wrap Bio.SeqFeature objects for GenomeDiagram.

Attributes:

  • parent FeatureSet, container for the object

  • id Unique id

  • color color.Color, color to draw the feature

  • hide Boolean for whether the feature will be drawn or not

  • sigil String denoting the type of sigil to use for the feature. Currently either “BOX” or “ARROW” are supported.

  • arrowhead_length Float denoting length of the arrow head to be drawn, relative to the bounding box height. The arrow shaft takes up the remainder of the bounding box’s length.

  • arrowshaft_height Float denoting length of the representative arrow shaft to be drawn, relative to the bounding box height. The arrow head takes the full height of the bound box.

  • name_qualifiers List of Strings, describes the qualifiers that may contain feature names in the wrapped Bio.SeqFeature object

  • label Boolean, 1 if the label should be shown

  • label_font String describing the font to use for the feature label

  • label_size Int describing the feature label font size

  • label_color color.Color describing the feature label color

  • label_angle Float describing the angle through which to rotate the feature label in degrees (default = 45, linear only)

  • label_position String, ‘start’, ‘end’ or ‘middle’ denoting where to place the feature label. Leave as None for the default which is ‘start’ for linear diagrams, and at the bottom of the feature as drawn on circular diagrams.

  • label_strand Integer -1 or +1 to explicitly place the label on the forward or reverse strand. Default (None) follows th feature’s strand. Use -1 to put labels under (linear) or inside (circular) the track, +1 to put them above (linear) or outside (circular) the track.

  • locations List of tuples of (start, end) ints describing where the feature and any subfeatures start and end

  • type String denoting the feature type

  • name String denoting the feature name

  • strand Int describing the strand on which the feature is found

__init__(parent=None, feature_id=None, feature=None, color=colors.lightgreen, label=0, border=None, colour=None)

Initialize.

Arguments:

  • parent FeatureSet containing the feature

  • feature_id Unique id for the feature

  • feature Bio.SeqFeature object to be wrapped

  • color color.Color Color to draw the feature (overridden by backwards compatible argument with UK spelling, colour). Either argument is overridden if ‘color’ is found in feature qualifiers

  • border color.Color Color to draw the feature border, use None for the same as the fill color, False for no border.

  • label Boolean, 1 if the label should be shown

set_feature(feature)

Define the Bio.SeqFeature object to be wrapped.

get_feature()

Return the unwrapped Bio.SeqFeature object.

set_colour(colour)

Backwards compatible variant of set_color(self, color) using UK spelling.

set_color(color)

Set the color in which the feature will be drawn.

Arguments:

  • color The color to draw the feature - either a colors.Color object, an RGB tuple of floats, or an integer corresponding a colors in colors.txt

__getattr__(name)

Get attribute by name.

If the Feature class doesn’t have the attribute called for, check in self._feature for it.

class Bio.Graphics.GenomeDiagram.GraphSet(name=None)

Bases: object

Graph Set.

Attributes:

  • id Unique identifier for the set

  • name String describing the set

__init__(name=None)

Initialize.

Arguments:

  • name String identifying the graph set sensibly

new_graph(data, name=None, style='bar', color=colors.lightgreen, altcolor=colors.darkseagreen, linewidth=1, center=None, colour=None, altcolour=None, centre=None)

Add a GraphData object to the diagram.

Arguments:

  • data List of (position, value) int tuples

  • name String, description of the graph

  • style String (‘bar’, ‘heat’, ‘line’) describing how the graph will be drawn

  • color colors.Color describing the color to draw all or ‘high’ (some styles) data (overridden by backwards compatible argument with UK spelling, colour).

  • altcolor colors.Color describing the color to draw ‘low’ (some styles) data (overridden by backwards compatible argument with UK spelling, colour).

  • linewidth Float describing linewidth for graph

  • center Float setting the value at which the x-axis crosses the y-axis (overridden by backwards compatible argument with UK spelling, centre)

Add a GraphData object to the diagram (will be stored internally).

del_graph(graph_id)

Remove a graph from the set, indicated by its id.

get_graphs()

Return list of all graphs in the graph set, sorted by id.

Sorting is to ensure reliable stacking.

get_ids()

Return a list of all ids for the graph set.

range()

Return the lowest and highest base (or mark) numbers as a tuple.

data_quartiles()

Return (minimum, lowerQ, medianQ, upperQ, maximum) values as a tuple.

to_string(verbose=0)

Return a formatted string with information about the set.

Arguments:

  • verbose - Flag indicating whether a short or complete account of the set is required

__len__()

Return the number of graphs in the set.

__getitem__(key)

Return a graph, keyed by id.

__str__()

Return a formatted string with information about the feature set.

class Bio.Graphics.GenomeDiagram.GraphData(id=None, data=None, name=None, style='bar', color=colors.lightgreen, altcolor=colors.darkseagreen, center=None, colour=None, altcolour=None)

Bases: object

Graph Data.

Attributes:

  • id Unique identifier for the data

  • data Dictionary of describing the data, keyed by position

  • name String describing the data

  • style String (‘bar’, ‘heat’, ‘line’) describing how to draw the data

  • poscolor colors.Color for drawing high (some styles) or all values

  • negcolor colors.Color for drawing low values (some styles)

  • linewidth Int, thickness to draw the line in ‘line’ styles

__init__(id=None, data=None, name=None, style='bar', color=colors.lightgreen, altcolor=colors.darkseagreen, center=None, colour=None, altcolour=None)

Initialize.

Arguments:

  • id Unique ID for the graph

  • data List of (position, value) tuples

  • name String describing the graph

  • style String describing the presentation style (‘bar’, ‘line’, ‘heat’)

  • color colors.Color describing the color to draw all or the ‘high’ (some styles) values (overridden by backwards compatible argument with UK spelling, colour).

  • altcolor colors.Color describing the color to draw the ‘low’ values (some styles only) (overridden by backwards compatible argument with UK spelling, colour).

  • center Value at which x-axis crosses y-axis.

set_data(data)

Add data as a list of (position, value) tuples.

get_data()

Return data as a list of sorted (position, value) tuples.

add_point(point)

Add a single point to the set of data as a (position, value) tuple.

quartiles()

Return (minimum, lowerQ, medianQ, upperQ, maximum) values as tuple.

range()

Return range of data as (start, end) tuple.

Returns the range of the data, i.e. its start and end points on the genome as a (start, end) tuple.

mean()

Return the mean value for the data points (float).

stdev()

Return the sample standard deviation for the data (float).

__len__()

Return the number of points in the data set.

__getitem__(index)

Return data value(s) at the given position.

Given an integer representing position on the sequence returns a float - the data value at the passed position.

If a slice, returns graph data from the region as a list or (position, value) tuples. Slices with step are not supported.

__str__()

Return a string describing the graph data.

Bases: object

Hold information for drawing a cross link between features.

__init__(featureA, featureB, color=colors.lightgreen, border=None, flip=False)

Create a new cross link.

Arguments featureA and featureB should GenomeDiagram feature objects, or 3-tuples (track object, start, end), and currently must be on different tracks.

The color and border arguments should be ReportLab colour objects, or for border use a boolean False for no border, otherwise it defaults to the same as the main colour.

The flip argument draws an inverted cross link, useful for showing a mapping where one sequence has been reversed. It is conventional to also use a different colour (e.g. red for simple links, blue for any flipped links).

property startA

Start position of Feature A.

property endA

End position of Feature A.

property startB

Start position of Feature B.

property endB

End position of Feature B.

class Bio.Graphics.GenomeDiagram.ColorTranslator(filename=None)

Bases: object

Class providing methods for translating representations of color into.

Examples

>>> from Bio.Graphics import GenomeDiagram
>>> gdct=GenomeDiagram._Colors.ColorTranslator()
>>> print(gdct.float1_color((0.5, 0.5, 0.5)))
Color(.5,.5,.5,1)
>>> print(gdct.int255_color((1, 75, 240)))
Color(.003922,.294118,.941176,1)
>>> print(gdct.artemis_color(7))
Color(1,1,0,1)
>>> print(gdct.scheme_color(2))
Color(1,0,0,1)
>>> gdct.get_artemis_colorscheme()
{0: (Color(1,1,1,1), 'pathogenicity, adaptation, chaperones'), 1: (Color(.39,.39,.39,1), 'energy metabolism'), 2: (Color(1,0,0,1), 'information transfer'), 3: (Color(0,1,0,1), 'surface'), 4: (Color(0,0,1,1), 'stable RNA'), 5: (Color(0,1,1,1), 'degradation of large molecules'), 6: (Color(1,0,1,1), 'degradation of small molecules'), 7: (Color(1,1,0,1), 'central/intermediary/miscellaneous metabolism'), 8: (Color(.6,.98,.6,1), 'unknown'), 9: (Color(.53,.81,.98,1), 'regulators'), 10: (Color(1,.65,0,1), 'conserved hypotheticals'), 11: (Color(.78,.59,.39,1), 'pseudogenes and partial genes'), 12: (Color(1,.78,.78,1), 'phage/IS elements'), 13: (Color(.7,.7,.7,1), 'some miscellaneous information'), 14: (Color(0,0,0,1), ''), 15: (Color(1,.25,.25,1), 'secondary metabolism'), 16: (Color(1,.5,.5,1), ''), 17: (Color(1,.75,.75,1), '')}

>>> print(gdct.translate((0.5, 0.5, 0.5)))
Color(.5,.5,.5,1)
>>> print(gdct.translate((1, 75, 240)))
Color(.003922,.294118,.941176,1)
>>> print(gdct.translate(7))
Color(1,1,0,1)
>>> print(gdct.translate(2))
Color(1,0,0,1)
__init__(filename=None)

Initialize.

Argument filename is the location of a file containing colorscheme information.

translate(color=None, colour=None)

Translate a color into a ReportLab Color object.

Arguments:

  • color - Color defined as an int, a tuple of three ints 0->255 or a tuple of three floats 0 -> 1, or a string giving one of the named colors defined by ReportLab, or a ReportLab color object (returned as is).

  • colour - Backwards compatible alias using UK spelling (which will over-ride any color argument).

Returns a colors.Color object, determined semi-intelligently depending on the input values

read_colorscheme(filename)

Load colour scheme from file.

Reads information from a file containing color information and stores it internally.

Argument filename is the location of a file defining colors in tab-separated format plaintext as:

INT \t RED \t GREEN \t BLUE \t Comment

Where RED, GREEN and BLUE are intensities in the range 0 -> 255, e.g.:

2 \t 255 \t 0 \t 0 \t Red: Information transfer
get_artemis_colorscheme()

Return the Artemis color scheme as a dictionary.

artemis_color(value)

Artemis color (integer) to ReportLab Color object.

Arguments:

  • value: An int representing a functional class in the Artemis color scheme (see www.sanger.ac.uk for a description), or a string from a GenBank feature annotation for the color which may be dot delimited (in which case the first value is used).

Takes an int representing a functional class in the Artemis color scheme, and returns the appropriate colors.Color object

get_colorscheme()

Return the user-defined color scheme as a dictionary.

scheme_color(value)

Map a user-defined color integer to a ReportLab Color object.

  • value: An int representing a single color in the user-defined color scheme

Takes an int representing a user-defined color and returns the appropriate colors.Color object.

int255_color(values)

Map integer (red, green, blue) tuple to a ReportLab Color object.

  • values: A tuple of (red, green, blue) intensities as integers in the range 0->255

Takes a tuple of (red, green, blue) intensity values in the range 0 -> 255 and returns an appropriate colors.Color object.

float1_color(values)

Map float (red, green, blue) tuple to a ReportLab Color object.

  • values: A tuple of (red, green, blue) intensities as floats in the range 0 -> 1

Takes a tuple of (red, green, blue) intensity values in the range 0 -> 1 and returns an appropriate colors.Color object.