Implementation

Logo class

Logo represents a basic logo, drawn on a specified axes object using a specified matrix, which is supplied as a pandas dataframe.

Attributes:
df: (pd.DataFrame)

A matrix specifying character heights and positions. Rows correspond to positions while columns correspond to characters. Column names must be single characters and row indices must be integers.

color_scheme: (str, dict, or array with length 3)

Specification of logo colors. Default is ‘gray’. Can take a variety of forms.

  • (str) A built-in Logomaker color scheme in which the color of each
character is determined that character’s identity. Options are,
  • For DNA/RNA: ‘classic’, ‘grays’, or ‘base_paring’.
  • For protein: ‘hydrophobicity’, ‘chemistry’, or ‘charge’.
  • (str) A built-in matplotlib color name such as ‘k’ or ‘tomato’
  • (list) An RGB array, i.e., 3 floats with values in the interval [0,1]
  • (dict) A dictionary that maps characters to colors, E.g.,
    {‘A’: ‘blue’,
    ‘C’: ‘yellow’, ‘G’: ‘green’, ‘T’: ‘red’}
font_name: (str)

The character font to use when rendering the logo. For a list of valid font names, run logomaker.list_font_names().

stack_order: (str)

Must be ‘big_on_top’, ‘small_on_top’, or ‘fixed’. If ‘big_on_top’, stack characters away from x-axis in order of increasing absolute value. If ‘small_on_top’, stack glyphs away from x-axis in order of decreasing absolute value. If ‘fixed’, stack glyphs from top to bottom in the order that characters appear in the data frame.

center_values: (bool)

If True, the stack of characters at each position will be centered around zero. This is accomplished by subtracting the mean value in each row of the matrix from each element in that row.

baseline_width: (float >= 0.0)

Width of the logo baseline, drawn at value 0.0 on the y-axis.

flip_below: (bool)

If True, characters below the x-axis (which correspond to negative values in the matrix) will be flipped upside down.

shade_below: (float in [0,1])

The amount of shading to use for characters drawn below the x-axis. Larger numbers correspond to more shading (i.e., darker characters).

fade_below: (float in [0,1])

The amount of fading to use for characters drawn below the x-axis. Larger numbers correspond to more fading (i.e., more transparent characters).

fade_probabilities: (bool)

If True, the characters in each stack will be assigned an alpha value equal to their height. This option only makes sense if df is a probability matrix. For additional customization, use Logo.fade_glyphs_in_probability_logo().

vpad: (float in [0,1])

The whitespace to leave above and below each character within that character’s bounding box. Note that, if vpad > 0, the height of the character’s bounding box (and not of the character itself) will correspond to values in df.

vsep: (float >= 0)

Amount of whitespace to leave between the bounding boxes of rendered characters. Unlike vpad, vsep is NOT relative to character height.

alpha: (float in [0,1])

Opacity to use when rendering characters. Note that, if this is used together with fade_below or fade_probabilities, alpha will multiply existing opacity values.

show_spines: (None or bool)

Whether a box should be drawn around the logo. For additional customization of spines, use Logo.style_spines().

ax: (matplotlib Axes object)

The matplotlb Axes object on which the logo is drawn.

zorder: (int >=0)

This governs what other objects drawn on ax will appear in front or behind the rendered logo.

figsize: ([float, float]):

The default figure size for the rendered logo; only used if ax is not supplied by the user.

**kwargs:

Additional key word arguments to send to the Glyph constructor.

Methods

draw(self[, clear]) Draws characters in Logo.
draw_baseline(\*args, \*\*kwargs) Draws a horizontal line along the x-axis.
fade_glyphs_in_probability_logo(\*args, …) Fades glyphs in probability logo according to value.
highlight_position(\*args, \*\*kwargs) Draws a rectangular box highlighting a specific position.
highlight_position_range(\*args, \*\*kwargs) Draws a rectangular box highlighting multiple positions within the Logo
style_glyphs(\*args, \*\*kwargs) Modifies the properties of all characters in a Logo.
style_glyphs_below(\*args, \*\*kwargs) Modifies the properties of all characters drawn below the x-axis.
style_glyphs_in_sequence(\*args, \*\*kwargs) Restyles the glyphs in a specific sequence.
style_single_glyph(\*args, \*\*kwargs) Modifies the properties of a single character in Logo.
style_spines(\*args, \*\*kwargs) Styles the spines of the Axes object in which the logo is drawn.
style_xticks(\*args, \*\*kwargs) Formats and styles tick marks along the x-axis.
draw(self, clear=False)

Draws characters in Logo.

Parameters:
clear: (bool)

If True, Axes will be cleared before logo is drawn.
Returns:
None
draw_baseline(*args, **kwargs)

Draws a horizontal line along the x-axis.

Parameters:
zorder: (number)

This governs what other objects drawn on ax will appear in front or behind the baseline. Logo characters are, by default, drawn in front of the baseline.

color: (matplotlib color)

Color to use for the baseline. Can be a named matplotlib color or an RGB array.

linewidth: (number >= 0)

Width of the baseline.

**kwargs:

Additional keyword arguments to be passed to ax.axhline()
Returns:
None

Fades glyphs in probability logo according to value.

Parameters:
v_alpha0, v_alpha1: (number in [0,1])

Matrix values marking values that are rendered using alpha=0 and alpha=1, respectively. These values must satisfy v_alpha0 < v_alpha1.
Returns:
None
highlight_position(*args, **kwargs)

Draws a rectangular box highlighting a specific position.

Parameters:
p: (int)

Single position to highlight.

**kwargs:

Other parameters to pass to highlight_position_range()
Returns:
None
highlight_position_range(*args, **kwargs)

Draws a rectangular box highlighting multiple positions within the Logo

Parameters:
pmin: (int)

Lowest position to highlight.

pmax: (int)

Highest position to highlight.

padding: (number >= -0.5)

Amount of padding to add on the left and right sides of highlight.

color: (None or matplotlib color)

Color to use for highlight. Can be a named matplotlib color or an RGB array.

edgecolor: (None or matplotlib color)

Color to use for highlight box edges. Can be a named matplotlib color or an RGB array.

floor: (None number)

Lowest y-axis extent of highlight box. If None, is set to ymin of the Axes object.

ceiling: (None or number)

Highest y-axis extent of highlight box. If None, is set to ymax of the Axes object.

zorder: (number)

This governs which other objects drawn on ax will appear in front or behind of the highlight. Logo characters are, by default, drawn in front of the highlight box.
Returns:
None
style_glyphs(*args, **kwargs)

Modifies the properties of all characters in a Logo.

Parameters:
color_scheme: (str, dict, or array with length 3)

Specification of logo colors. Default is ‘gray’. Can take a variety of forms.

  • (str) A built-in Logomaker color scheme in which the color of each
character is determined that character’s identity. Options are,
  • For DNA/RNA: ‘classic’, ‘grays’, or ‘base_paring’.
  • For protein: ‘hydrophobicity’, ‘chemistry’, or ‘charge’.
  • (str) A built-in matplotlib color name such as ‘k’ or ‘tomato’
  • (list) An RGB array, i.e., 3 floats with values in the interval [0,1]
  • (dict) A dictionary that maps characters to colors, E.g.,
    {‘A’: ‘blue’,
    ‘C’: ‘yellow’, ‘G’: ‘green’, ‘T’: ‘red’}
**kwargs:

Keyword arguments to pass to Glyph.set_attributes()
Returns:
None
style_glyphs_below(*args, **kwargs)

Modifies the properties of all characters drawn below the x-axis.

Parameters:
color: (color specification)

Color to use before shade is applied.

alpha: (number in [0,1])

Opacity to use when rendering characters, before fade is applied.

shade: (number in [0,1])

The amount to shade characters below the x-axis.

fade: (number in [0,1])

The amount to fade characters below the x-axis.

flip: (bool)

If True, characters below the x-axis will be flipped upside down.

**kwargs:

Keyword arguments to pass to Glyph.set_attributes(), but only for characters below the x-axis.
Returns:
None
style_glyphs_in_sequence(*args, **kwargs)

Restyles the glyphs in a specific sequence.

Parameters:
sequence: (str)

A string the same length as the logo, specifying which character to restyle at each position. Characters in sequence that are not in the columns of the Logo’s df are ignored.

**kwargs:

Keyword arguments to pass to Glyph.set_attributes()
Returns:
None
style_single_glyph(*args, **kwargs)

Modifies the properties of a single character in Logo.

Parameters:
p: (int)

Position of modified glyph. Must index a row in the matrix df passed to the Logo constructor.

c: (str of length 1)

Character to modify. Must be the name of a column in the matrix df passed to the Logo constructor.

**kwargs:

Keyword arguments to pass to Glyph.set_attributes()
Returns:
None
style_spines(*args, **kwargs)

Styles the spines of the Axes object in which the logo is drawn. Note: “spines” refers to the edges of the Axes bounding box.

Parameters:
spines: (tuple of str)

Specifies which of the four spines to modify. The default value for this parameter lists all four spines.

visible: (bool)

Whether to show or not show the spines listed in the parameter spines.

color: (matplotlib color)

Color of the spines. Can be a named matplotlib color or an RGB array.

linewidth: (float >= 0)

Width of lines used to draw the spines.

bounds: (None or [float, float])

If not None, specifies the values between which a spine (or spines) will be drawn.
Returns:
None
style_xticks(*args, **kwargs)

Formats and styles tick marks along the x-axis.

Parameters:
anchor: (int)

Anchors tick marks at a specific number. Even if this number is not within the x-axis limits, it fixes the register for tick marks.

spacing: (int > 0)

The spacing between adjacent tick marks

fmt: (str)

String used to format tick labels.

rotation: (number)

Angle, in degrees, with which to draw tick mark labels.

**kwargs:

Additional keyword arguments to be passed to ax.set_xticklabels()
Returns:
None

Glyph class

class logomaker.Glyph(**kwargs)

A Glyph represents a character, drawn on a specified axes at a specified position, rendered using specified styling such as color and font_name.

Attributes:
p: (number)

x-coordinate value on which to center the Glyph.

c: (str)

The character represented by the Glyph.

floor: (number)

y-coordinate value where the bottom of the Glyph extends to. Must be < ceiling.

ceiling: (number)

y-coordinate value where the top of the Glyph extends to. Must be > floor.

ax: (matplotlib Axes object)

The axes object on which to draw the Glyph.

width: (number > 0)

x-coordinate span of the Glyph.

vpad: (number in [0,1])

Amount of whitespace to leave within the Glyph bounding box above and below the actual Glyph. Specifically, in a glyph with height h = ceiling-floor, a margin of size h*vpad/2 will be left blank both above and below the rendered character.

font_name: (str)

The name of the font to use when rendering the Glyph. This is the value passed as the ‘family’ parameter when calling the matplotlib.font_manager.FontProperties constructor.

font_weight: (str or number)

The font weight to use when rendering the Glyph. Specifically, this is the value passed as the ‘weight’ parameter in the matplotlib.font_manager.FontProperties constructor. From matplotlib documentation: “weight: A numeric value in the range 0-1000 or one of ‘ultralight’, ‘light’, ‘normal’, ‘regular’, ‘book’, ‘medium’, ‘roman’, ‘semibold’, ‘demibold’, ‘demi’, ‘bold’, ‘heavy’, ‘extra bold’, ‘black’.”

color: (matplotlib color)

Color to use for Glyph face.

edgecolor: (matplotlib color)

Color to use for Glyph edge.

edgewidth: (number >= 0)

Width of Glyph edge.

dont_stretch_more_than: (str)

This parameter limits the amount that a character will be horizontally stretched when rendering the Glyph. Specifying a wide character such as ‘W’ corresponds to less potential stretching, while specifying a narrow character such as ‘.’ corresponds to more stretching.

flip: (bool)

If True, the Glyph will be rendered upside down.

mirror: (bool)

If True, a mirror image of the Glyph will be rendered.

zorder: (number)

Placement of Glyph within the z-stack of ax.

alpha: (number in [0,1])

Opacity of the rendered Glyph.

figsize: ([float, float]):

The default figure size for the rendered glyph; only used if ax is not supplied by the user.

Methods

draw(self) Draws Glyph given current parameters.
set_attributes(self, \*\*kwargs) Safe way to set the attributes of a Glyph object
draw(self)

Draws Glyph given current parameters.

Parameters:
None.
Returns:
None.
set_attributes(self, **kwargs)

Safe way to set the attributes of a Glyph object

Parameters:
**kwargs:

Attributes and their values.

matrix functions

logomaker.transform_matrix(*args, **kwargs)

Performs transformations on a matrix. There are three types of transformations that can be performed:

  1. Center values:
    Subtracts the mean from each row in df. This is common for weight matrices or energy matrices. To do this, set center_values=True.
  2. Normalize values:
    Divides each row by the sum of the row. This is needed for probability matrices. To do this, set normalize_values=True.
  3. From/To transformations:
    Transforms from one type of matrix (e.g. ‘counts’) to another type of matrix (e.g. ‘information’). To do this, set from_type and to_type arguments.

Here are the mathematical formulas invoked by From/To transformations:

from_type=’counts’ -> to_type=’probability’:
P_ic = (N_ic + l)/(N_i + C*l), N_i = sum_c(N_ic)
from_type=’probability’ -> to_type=’weight’:
W_ic = log_2(P_ic / Q_ic)
from_type=’weight’ -> to_type=’probability’:
P_ic = Q_ic * 2^(W_ic)
from_type=’probability’ -> to_type=’information’:
I_ic = P_ic * sum_d(P_id * log2(P_id / W_id))
from_type=’information’ -> to_type=’probability’:
P_ic = I_ic / sum_d(I_id)
notation:
i = position c, d = character l = pseudocount C = number of characters N_ic = counts matrix element P_ic = probability matrix element Q_ic = background probability matrix element W_ic = weight matrix element I_ic = information matrix element

Using these five 1-step transformations, 2-step transformations are also enabled, e.g., from_type=’counts’ -> to_type=’information’.

Parameters:
df: (dataframe)

The matrix to be transformed.

center_values: (bool)

Whether to center matrix values, i.e., subtract the mean from each row.

normalize_values: (bool)

Whether to normalize each row, i.e., divide each row by the sum of that row.

from_type: (str)

Type of input matrix. Must be one of ‘counts’, ‘probability’, ‘weight’, or ‘information’.

to_type: (str)

Type of output matrix. Must be one of ‘probability’, ‘weight’, or ‘information’. Can be ‘counts’ ONLY if from_type is ‘counts’ too.

background: (array, or df)

Specification of background probabilities. If array, should be the same length as df.columns and correspond to the probability of each column’s character. If df, should be a probability matrix the same shape as df.

pseudocount: (number >= 0)

Pseudocount to use when transforming from a counts matrix to a probability matrix.
Returns:
out_df: (dataframe)

Transformed matrix
logomaker.sequence_to_matrix(*args, **kwargs)

Generates a matrix from a sequence. With default keyword arguments, this is a one-hot-encoded version of the sequence provided. Alternatively, is_iupac=True allows users to get matrix models based in IUPAC motifs.

Parameters:
seq: (str)

Sequence from which to construct matrix.

cols: (str or array-like or None)

The characters to use for the matrix columns. If None, cols is constructed from the unqiue characters in seq. Overriden by alphabet and is_iupac.

alphabet: (str or None)

The alphabet used to determine the columns of the matrix. Options are: ‘dna’, ‘rna’, ‘protein’. Ignored if None. Overrides cols.

is_iupac: (bool)

If True, it is assumed that the sequence represents an IUPAC DNA string. In this case, cols is overridden, and alphabet must be None.

to_type: (str)

The type of matrix to output. Must be ‘probability’, ‘weight’, or ‘information’

center_weights: (bool)

Whether to subtract the mean of each row, but only if to_type=’weight’.
Returns:
seq_df: (dataframe)

the matrix returned to the user.
logomaker.alignment_to_matrix(*args, **kwargs)

Generates matrix from a sequence alignment

Parameters:
sequences: (list of strings)

A list of sequences, all of which must be the same length

counts: (None or list of numbers)

If not None, must be a list of numbers the same length os sequences, containing the (nonnegative) number of times that each sequence was observed. If None, defaults to 1.

to_type: (str)

The type of matrix to output. Must be ‘counts’, ‘probability’, ‘weight’, or ‘information’

background: (array, or df)

Specification of background probabilities. If array, should be the same length as df.columns and correspond to the probability of each column’s character. If df, should be a probability matrix the same shape as df.

characters_to_ignore: (str)

Characters to ignore within sequences. This is often needed when creating matrices from gapped alignments.

center_weights: (bool)

Whether to subtract the mean of each row, but only if to_type==’weight’.

pseudocount: (number >= 0.0)

Pseudocount to use when converting from counts to probabilities.
Returns:
out_df: (dataframe)

A matrix of the requested type.
logomaker.saliency_to_matrix(*args, **kwargs)

Takes a sequence string and an array of values values and outputs a values dataframe. The returned dataframe is a L by C matrix where C is the number ofcharacters and L is sequence length. If matrix is denoted as S, i indexes positions and c indexes characters, then S_ic will be non-zero (equal to the value in the values array at position p) only if character c occurs at position p in sequence. All other elements of S are zero.

example usage:

saliency_mat = logomaker.saliency_to_matrix(sequence,values) logomaker.Logo(saliency_mat)

Parameters:
seq: (str or array-like list of single characters)

sequence for which values matrix is constructed

values: (array-like list of numbers)

array of values values for each character in sequence

cols: (str or array-like or None)

The characters to use for the matrix columns. If None, cols is constructed from the unqiue characters in seq. Overridden by alphabet and is_iupac.

alphabet: (str or None)

The alphabet used to determine the columns of the matrix. Options are: ‘dna’, ‘rna’, ‘protein’. Ignored if None. Overrides cols.
Returns:
saliency_df: (dataframe)

values matrix in the form of a dataframe
logomaker.validate_matrix(*args, **kwargs)

Checks to make sure that the input dataframe, df, represents a valid matrix, i.e., an object that can be displayed as a logo.

Parameters:
df: (dataframe)

A pandas dataframe where each row represents an (integer) position and each column represents to a (single) character.

matrix_type: (None or str)

If ‘probability’, validates df as a probability matrix, i.e., all elements are in [0,1] and rows are normalized). If ‘information’, validates df as an information matrix, i.e., all elements >= 0.

allow_nan: (bool)

Whether to allow NaN entries in the matrix.
Returns:
out_df: (dataframe)

A cleaned-up version of df (if possible).

dataset functions

logomaker.demo(*args, **kwargs)

Performs a demonstration of the Logomaker software.

Parameters:
name: (str)

Must be one of {‘fig1b’, ‘fig1c’, ‘fig1d’, ‘fig1e’, ‘fig1f’, ‘logo’}.
Returns:
None.
logomaker.list_example_matrices(*args, **kwargs)

Return list of available matrices.

logomaker.get_example_matrix(*args, **kwargs)

Returns an example matrix from which a logo can be made.

Parameters:
name: (None or str)

Name of example matrix.

print_description: (bool)

If true, a description of the example matrix will be printed
Returns:
df: (data frame)

A data frame containing an example matrix.
logomaker.list_example_datafiles(*args, **kwargs)

Return list of available data files.

logomaker.open_example_datafile(*args, **kwargs)

Returns a file handle to an example dataset

Parameters:
name: (None or str)

Name of example matrix.

print_description: (bool)

If true, a description of the example matrix will be printed
Returns:
f: (file handle)

A handle to the requested file

functional tests

logomaker.run_tests()

Run all Logomaker functional tests. There are 547 tests as of 14 May 2019.

Parameters:
None.