Implementation¶
Logo class¶

class
logomaker.
Logo
(**kwargs)¶ 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 builtin 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 builtin 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 xaxis in order of increasing absolute value. If ‘small_on_top’, stack glyphs away from xaxis 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 yaxis.
 flip_below: (bool)
If True, characters below the xaxis (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 xaxis. 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 xaxis. 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 xaxis. 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 xaxis. 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 xaxis. 
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 xaxis.
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

fade_glyphs_in_probability_logo
(*args, **kwargs)¶ 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 yaxis extent of highlight box. If None, is set to ymin of the Axes object.
 ceiling: (None or number)
Highest yaxis 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 builtin 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 builtin 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 xaxis.
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 xaxis.
 fade: (number in [0,1])
The amount to fade characters below the xaxis.
 flip: (bool)
If True, characters below the xaxis will be flipped upside down.
 **kwargs:
Keyword arguments to pass to Glyph.set_attributes(), but only for characters below the xaxis.
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 xaxis.
Parameters:  anchor: (int)
Anchors tick marks at a specific number. Even if this number is not within the xaxis 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)
xcoordinate value on which to center the Glyph.
 c: (str)
The character represented by the Glyph.
 floor: (number)
ycoordinate value where the bottom of the Glyph extends to. Must be < ceiling.
 ceiling: (number)
ycoordinate 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)
xcoordinate 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 = ceilingfloor, 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 01000 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 zstack 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:
 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.
 Normalize values:
 Divides each row by the sum of the row. This is needed for probability matrices. To do this, set normalize_values=True.
 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 1step transformations, 2step 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 onehotencoded 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 arraylike 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 nonzero (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 arraylike list of single characters)
sequence for which values matrix is constructed
 values: (arraylike list of numbers)
array of values values for each character in sequence
 cols: (str or arraylike 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 cleanedup 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