API

Plotting

geneviz.tracks.plot_tracks(tracks, region, figsize=None, height_ratios=None, tick_top=False, padding=(0, 0), reverse=False, despine=False)[source]

Plots given tracks over the specified range on shared axes.

Parameters:
  • tracks (List[Track]) – List of tracks to draw.
  • region (Tuple[str, int, int]) – Genomic region to draw.
  • figsize (Tuple[int, int]) – Size of resulting figure, specified as a tuple of (width, height). Height may be omitted (by passing None), in which case the height of the figure will be scaled depending on the heights of the tracks.
  • height_ratios (List[int]) – Relative heights of each track.
  • tick_top (bool) – Whether xticks should be plotted along top.
  • padding (Tuple[int, int]) – Amount of padding to add on the x-axis (in genomic space).
  • reverse (bool) – Whether the x-axis should be reversed, useful for drawing features on the reverse strand from left to right.
Returns:

Figure and axes on which was drawn.
Return type:

Tuple[matplotlib.Figure, matplotlib.Axes]

Base tracks

class geneviz.tracks.Track[source]

Abstract base class representing a Geneviz track.

Specifies two methods, draw and get_height, that form the main interface of a track and should be overridden in each subclass. The method get_height is used to determine the height of a given track, which determine the (relative) amount of vertical space the track is given when drawn. The draw method called by plot_tracks to draw the track on a given axis for a given region.

draw(region, ax)[source]

Draws the track on the given axis.

Parameters:
  • region (Tuple[str, int, int]) – Genomic region to draw.
  • ax (matplotlib.Axes) – Axis to draw track on.
get_height(region, ax)[source]

Returns the height of the track within the plotting region.

Parameters:
  • region (Tuple[str, int, int]) – The genomic region that will be drawn. Specified as a tuple of (chromosome, start, end).
  • ax (matplotlib.Axes) – Axis that the track will be drawn on. Used to determine the size of some features that may be dependent on the axis (such as the space required to draw labels etc.).
Returns:

height – Height of the track within the given region.
Return type:

int
class geneviz.tracks.DummyTrack(height=1)[source]

Dummy track that doesn’t draw anything.

This track can be used to create a blank axis that can be drawn on manually at a later time point.

Parameters:height (int) – Height of the dummy track.
draw(region, ax)[source]

Draws the track on the given axis.

This is effectively a no-op for the dummy track.

Parameters:
  • region (Tuple[str, int, int]) – Genomic region to draw.
  • ax (matplotlib.Axes) – Axis to draw track on.
get_height(region, ax)[source]

Returns the (fixed) height of the dummy track.

Parameters:
  • region (Tuple[str, int, int]) – The genomic region that will be drawn. Specified as a tuple of (chromosome, start, end).
  • ax (matplotlib.Axes) – Axis that the track will be drawn on.
Returns:

height – Height of the dummy track.
Return type:

int

Feature tracks

class geneviz.tracks.FeatureTrack(data, group=None, label=None, hue=None, hue_order=None, palette=None, strand_junctions=False, height=1.0, spacing=0.05, color='dimgrey', patch_kws=None, line_kws=None, label_kws=None)[source]

Track for plotting generic genomic features in a stacked fashion.

The FeatureTrack is the main track that is used to plot genomic features. Overlapping features are plotted in a stacked fashion to avoid overplotting. Optionally, features can be grouped together if they belong to the same group, such as exons for a given gene/transcript. Grouped features are connected by junctions to indicate that they belong to a single group. Features can also be colored by their properties, using the hue and palette arugments.

Parameters:
  • data (pandas.Dataframe) – Dataset for plotting. Each row in the DataFrame is expected to correspond with a single feature. The DataFrame should have the following columns: seqname, start, end, strand; which together specify the location and orientation of the corresponding feature.
  • group (str) – Column (categorical) by which features should be grouped. Grouped features are drawn together (at the same height) and are visually connected by junctions.
  • label (str) – Column containing text labels that should be used to name features in the plot. If group is specified, the label of the first feature in the group is used for the group.
  • hue (str) – Column (categorical) that should be used to determine the color of a given feature.
  • hue_order (List[str]) – Order to plot the categorical hue levels in, otherwise the levels are inferred from the data objects.
  • palette (List[Union[str, Tuple[float, float, float]]]) – Colors to use for the different levels of the hue variable. Should be specified as a list of colors (strs) or a list of tuples with RGB values (similar to Seaborn color palettes).
  • strand_junctions (bool) – Boolean that indicates if group junctions should be drawn in a stranded fashion for groups. If False, the features are drawn with their own respective strands. If True, the strand of a group is determined from the first element of the group and the junctions are drawn upwards (for groups on the forward strand) or downwards (for groups on the reverse strand).
  • height (float) – The height of an individual feature.
  • spacing (float) – The (vertical) spacing to use between features.
  • color (str) – Color for all of the elements. Overridded by hue.
  • patch_kws (dict[str, Any]) – Dict of keyword arguments to pass to RectangleCollection or FancyArrow collection when drawing feature patches. Used to precisely specify the aesthetics of features.
  • line_kws (dict[str, Any]) – Dict of keyword arguments to pass to LineCollection when drawing the junctions between groups. Used to specify modify the aesthetics of the junctions.
  • label_kws (dict[str, Any]) – Dict of keyword arguments to pass to ax.annotate when drawing feature/group labels. Used to precisely specify the aesthetics of the labels.
draw(region, ax)[source]

Draws the track on the given axis.

Parameters:
  • region (Tuple[str, int, int]) – Genomic region to draw.
  • ax (matplotlib.Axes) – Axis to draw track on.
classmethod from_position(data, width, **kwargs)[source]

Constructs instance from frame with positions instead of start/ends.

Assumes that the DataFrame contains a ‘position’ column, which defines the exact position of the given feature. This function expands features so that the width of the plotted feature is equal to the given width and features are centered around their position.

Parameters:
  • data (pandas.Dataframe) – Dataset for plotting. Assumed to be the same format as for the main constructor, apart from containing a ‘position’ column, rather than start/end columns.
  • width (int) – The width to use for the expanded features.
  • **kwargs – Any kwargs are passed to the main constructor.
get_height(region, ax)[source]

Returns the height of the dummy track.

Parameters:
  • region (Tuple[str, int, int]) – The genomic region that will be drawn. Specified as a tuple of (chromosome, start, end).
  • ax (matplotlib.Axes) – Axis that the track will be drawn on.
Returns:

height – Height of the track.
Return type:

int
class geneviz.tracks.RugTrack(data, hue=None, hue_order=None, palette=None, height=1.0, line_kws=None)[source]

Track that plots density ticks for features.

Parameters:
  • data (pandas.Dataframe) – Dataset for plotting. Each row in the DataFrame is expected to correspond with a single feature. The DataFrame should have the following columns: seqname, position, strand; which together specify the location and orientation of the corresponding feature.
  • hue (str) – Column (categorical) that should be used to determine the color of a given feature.
  • hue_order (List[str]) – Order to plot the categorical hue levels in, otherwise the levels are inferred from the data objects.
  • palette (List[Union[str, Tuple[float, float, float]]]) – Colors to use for the different levels of the hue variable. Should be specified as a list of colors (strs) or a list of tuples with RGB values (similar to Seaborn color palettes).
  • height (float) – The height of the track.
  • line_kws (dict[str, Any]) – Dict of keyword arguments to pass to LineCollection when drawing the ticks. Used to specify modify the aesthetics of the ticks.
draw(region, ax)[source]

Draws the track on the given axis.

Parameters:
  • region (Tuple[str, int, int]) – Genomic region to draw.
  • ax (matplotlib.Axes) – Axis to draw track on.
get_height(region, ax)[source]

Returns the height of the track.

Parameters:
  • region (Tuple[str, int, int]) – The genomic region that will be drawn. Specified as a tuple of (chromosome, start, end).
  • ax (matplotlib.Axes) – Axis that the track will be drawn on.
Returns:

height – Height of the track.
Return type:

int

Gene tracks

class geneviz.tracks.BiomartTrack(host='http://www.ensembl.org', mart='ENSEMBL_MART_ENSEMBL', dataset='hsapiens_gene_ensembl', gene_id='gene_id', transcript_id='transcript_id', bm_gene_name='external_gene_name', collapse=None, filter=None, hue=None, hue_order=None, palette=None, height=0.9, spacing=0.05, label_kws=None, patch_kws=None, line_kws=None)[source]

Track for plotting gene/transcript annotations from Biomart.

Gene draws genes/transcripts on a genomic axis, in a stacked fashion if transcripts/genes are overlapping. Gene annotations are queried directly from Biomart.

Parameters:
  • host (str) – Biomart host address.
  • mart (str) – Biomart mart name.
  • dataset (str) – Biomart dataset name.
  • **kwargs – Keywords are passed to the GeneTrack constructor, which is used internally to draw transcripts/genes.
class geneviz.tracks.GtfTrack(gtf_path, gene_id='gene_id', transcript_id='transcript_id', collapse=None, filter=None, hue=None, hue_order=None, palette=None, height=0.9, spacing=0.05, label_kws=None, patch_kws=None, line_kws=None)[source]

NGS tracks

class geneviz.tracks.SpliceTrack(data, height=1, color=None, patch_kws=None)[source]