AAlogoPlot.multi_logo

AAlogoPlot.multi_logo(list_df_logo=None, list_df_logo_info=None, list_aal_kws=None, info_bar_color='gray', info_bar_ylim=None, height_ratio=(1, 6), target_p1_site=None, figsize_per_logo=(8, 3), fontsize_labels=None, list_name_data=None, name_data_pos='top', list_name_data_color='black', name_data_fontsize=None, logo_font_name='Verdana', logo_color_scheme='weblogo_protein', logo_stack_order='big_on_top', logo_width=0.96, logo_vpad=0.05, logo_vsep=0.0, start=1, tmd_color='mediumspringgreen', jmd_color='blue', fontsize_tmd_jmd=None, weight_tmd_jmd='normal', highlight_tmd_area=True, highlight_alpha=0.15, xtick_size=None, xtick_width=2.0, xtick_length=11.0)[source]

Plot multiple sequence logos stacked vertically for group comparison, each with an optional bit-score bar on top.

All logos share the same y-axis scale, and (when shown) all bit-score bars share a common scale so they are comparable across groups. Target middle domain (TMD) / juxta middle domain (JMD) annotations are shown only on the bottom subplot to avoid repetition.

Added in version 1.1.0.

Parameters:

list_df_logo (list of pd.DataFrame, each shape (n_positions, n_amino_acids), optional) – List of logo matrices, one per group. All must have the same number of positions. Required unless list_aal_kws is given, in which case it is computed internally and must be None.
list_df_logo_info (list of pd.Series, each shape (n_positions,), optional) – Per-position information content, one per group, as returned by AAlogo.get_df_logo_info(). If provided, a bit-score bar is rendered above each logo. Length and per-group positions must match list_df_logo. Must be None when list_aal_kws is given (it is then computed internally and the bars are shown).
list_aal_kws (list of dict, optional) – Per-group AAlogo.get_df_logo() keyword arguments, one dict per group. If given, list_df_logo and list_df_logo_info are computed internally and must be None. Mutually exclusive with list_df_logo (see Notes).
info_bar_color (str, default='gray') – Color of the bit-score bars in the optional top panels.
info_bar_ylim (tuple of float, optional) – Shared y-axis limits (min, max) for all bit-score bars. If None, set automatically from the global maximum so bars stay comparable across groups.
height_ratio (tuple of (int or float), default=(1, 6)) – Height ratio (info_bar, logo) of each group when list_df_logo_info is provided.
target_p1_site (int, optional) – If set, replaces the standard JMD/TMD x-axis with P-site notation.
figsize_per_logo (tuple of (int or float), default=(8, 3)) – Figure size (width, height) per subplot in inches. Total figure height is figsize_per_logo[1] * len(list_df_logo).
fontsize_labels (int or float, optional) – Font size for axis labels.
list_name_data (list of str, optional) – Dataset names, one per logo. Length must match list_df_logo.
name_data_pos ({'top', 'right', 'bottom', 'left'}, default='top') – Position of the name annotation on each subplot.
list_name_data_color (str or list of str, default='black') – Color(s) for name annotations. A single string applies to all; a list must match list_df_logo in length.
name_data_fontsize (int or float, optional) – Font size for name annotations.
logo_font_name (str, default='Verdana') – Font name for amino acid letter rendering.
logo_color_scheme (str, default='weblogo_protein') – Color scheme for amino acid letters (passed to logomaker).
logo_stack_order ({'big_on_top', 'small_on_top', 'fixed'}, default='big_on_top') – Stacking order of letters within each position column.
logo_width (float, default=0.96) – Relative width of each letter column (0 to 1).
logo_vpad (float, default=0.05) – Vertical padding between stacked letters.
logo_vsep (float, default=0.0) – Vertical separation between stacked letters.
start (int, default=1) – Residue number assigned to the first position of JMD-N.
tmd_color (str, default='mediumspringgreen') – Color for TMD annotations.
jmd_color (str, default='blue') – Color for JMD annotations.
fontsize_tmd_jmd (int or float, optional) – Font size for part labels. If None, auto-sized.
weight_tmd_jmd ({'normal', 'bold'}, default='normal') – Font weight for part labels.
highlight_tmd_area (bool, default=True) – If True, shades the TMD region in each subplot.
highlight_alpha (float, default=0.15) – Opacity of the TMD highlight.
xtick_size (int or float, optional) – Font size for x-tick labels (bottom subplot only).
xtick_width (int or float, default=2.0) – Line width of x-tick marks.
xtick_length (int or float, default=11.0) – Length of x-tick marks in points.

Returns:

fig (Figure) – Figure object.
ax (list of Axes or list of tuple of (Axes, Axes)) – When no bit-score bars are shown: one Axes per logo. When list_df_logo_info (or list_aal_kws) is given: one (ax_logo, ax_info) tuple per group, where ax_info is the bar above.

Notes

list_aal_kws is a convenience shortcut that skips the manual AAlogo step for each group: AAlogoPlot instantiates AAlogo with this plot’s logo_type and computes both df_logo (via AAlogo.get_df_logo()) and df_logo_info (via AAlogo.get_df_logo_info()) per dict, so the bit-score bars appear automatically. Each dict holds that group’s arguments, e.g. df_parts, labels, label_test, tmd_len, start_n, characters_to_ignore, and pseudocount (typically the same df_parts with a different label_test per group). Passing both list_aal_kws and list_df_logo / list_df_logo_info raises ValueError, as do unknown keys. Example: list_aal_kws=[dict(df_parts=df_parts, labels=labels, label_test=1), dict(df_parts=df_parts, labels=labels, label_test=0)].

See also

AAlogoPlot.single_logo(): for a single-group visualization.
AAlogo: to compute df_logo for each group.

Examples

AAlogoPlot.multi_logo stacks multiple sequence logos vertically in one figure, one subplot per logo. All subplots share the same y-axis scale. Part annotations (JMD-N, TMD, JMD-C bar and text) are shown only on the bottom subplot.

import warnings
warnings.filterwarnings('ignore')
import aaanalysis as aa
import matplotlib.pyplot as plt

aa.plot_settings()

sf = aa.SequenceFeature()
df_seq = aa.load_dataset(name='DOM_GSEC', n=100)
labels = df_seq['label'].to_list()
df_parts = sf.get_df_parts(df_seq=df_seq, list_parts=['jmd_n', 'tmd', 'jmd_c'])

aal = aa.AAlogo(logo_type='probability')
df_logo_pos = aal.get_df_logo(df_parts=df_parts, labels=labels, label_test=1)
df_logo_neg = aal.get_df_logo(df_parts=df_parts, labels=labels, label_test=0)

aal_plot = aa.AAlogoPlot(logo_type='probability', jmd_n_len=10, jmd_c_len=10)
df_info_pos = aal.get_df_logo_info(df_parts=df_parts, labels=labels, label_test=1)
df_info_neg = aal.get_df_logo_info(df_parts=df_parts, labels=labels, label_test=0)

A list of logo DataFrames — one per subplot. All must have the same number of positions. The number of subplots equals len(list_df_logo).

# Two logos: one subplot per group
fig, axes = aal_plot.multi_logo(list_df_logo=[df_logo_pos, df_logo_neg])
print(f"n_subplots: {len(axes)}, positions per logo: {len(df_logo_pos)}")
plt.show()

[94mPlotting 2 logos (TMD length=23, JMD-N=10, JMD-C=10)[0m
n_subplots: 2, positions per logo: 43

list_aal_kws is a convenience shortcut that skips the manual AAlogo step for every group. Pass a list of dicts – one per subplot – each holding the AAlogo.get_df_logo arguments for that group (often the same df_parts with a different label_test). AAlogoPlot instantiates AAlogo internally (using this plot’s logo_type) and computes both list_df_logo and list_df_logo_info for you, so each logo is drawn with its bit-score bar on top. It is mutually exclusive with list_df_logo.

# One-shot: build both logos from df_parts via label_test, no manual AAlogo step
fig, axes = aal_plot.multi_logo(
    list_aal_kws=[
        dict(df_parts=df_parts, labels=labels, label_test=1),
        dict(df_parts=df_parts, labels=labels, label_test=0),
    ],
    list_name_data=['Positive (label=1)', 'Negative (label=0)'],
)
print(f"n_subplots: {len(axes)}")
plt.show()

[94mPlotting 2 logos (TMD length=23, JMD-N=10, JMD-C=10)[0m
n_subplots: 2

Pass a list of per-position information-content Series (from AAlogo.get_df_logo_info), one per group, to render a bit-score bar above each logo – the stacked counterpart of single_logo’s bar. info_bar_color sets the bar color. The method then returns one (ax_logo, ax_info) tuple per group.

# Precomputed bit-score bars, one per logo
fig, axes = aal_plot.multi_logo(
    list_df_logo=[df_logo_pos, df_logo_neg],
    list_df_logo_info=[df_info_pos, df_info_neg],
    list_name_data=['Positive (label=1)', 'Negative (label=0)'],
    info_bar_color='gray',
)
print(f"returns {len(axes)} (ax_logo, ax_info) pairs")
plt.tight_layout()
plt.show()

[94mPlotting 2 logos (TMD length=23, JMD-N=10, JMD-C=10)[0m
returns 2 (ax_logo, ax_info) pairs

info_bar_ylim sets a shared (min, max) for every bit-score bar so heights stay comparable across groups (auto-scaled to the global maximum when None). height_ratio sets the (info_bar, logo) height proportion of each group.

fig, axes = aal_plot.multi_logo(
    list_df_logo=[df_logo_pos, df_logo_neg],
    list_df_logo_info=[df_info_pos, df_info_neg],
    list_name_data=['Positive', 'Negative'],
    info_bar_ylim=(0, 4),
    height_ratio=(1, 5),
)
plt.tight_layout()
plt.show()

[94mPlotting 2 logos (TMD length=23, JMD-N=10, JMD-C=10)[0m

list_name_data annotates each subplot with a label. Length must match list_df_logo. list_name_data_color sets the color — either a single string (applies to all) or a list with one color per subplot.

fig, axes = aal_plot.multi_logo(
    list_df_logo=[df_logo_pos, df_logo_neg],
    list_name_data=['Positive (label=1)', 'Negative (label=0)'],
    list_name_data_color=['tab:green', 'tab:gray'],
)
plt.show()

[94mPlotting 2 logos (TMD length=23, JMD-N=10, JMD-C=10)[0m

Controls where the label is placed on each subplot’s axes. Uses ax.transAxes coordinates, so the same position applies to every subplot.

for pos in ['top', 'right', 'left']:
    fig, axes = aal_plot.multi_logo(
        list_df_logo=[df_logo_pos, df_logo_neg],
        list_name_data=['Positive', 'Negative'],
        name_data_pos=pos,
    )
    fig.suptitle(f"name_data_pos='{pos}'", y=1.01)
    plt.show()

[94mPlotting 2 logos (TMD length=23, JMD-N=10, JMD-C=10)[0m

[94mPlotting 2 logos (TMD length=23, JMD-N=10, JMD-C=10)[0m

[94mPlotting 2 logos (TMD length=23, JMD-N=10, JMD-C=10)[0m

Sets the (width, height) of each individual subplot in inches. Total figure height = figsize_per_logo[1] * len(list_df_logo).

for h in [2, 4]:
    fig, axes = aal_plot.multi_logo(
        list_df_logo=[df_logo_pos, df_logo_neg],
        list_name_data=['Positive', 'Negative'],
        figsize_per_logo=(10, h),
    )
    print(f"figsize_per_logo height={h}: total fig height = {fig.get_size_inches()[1]:.1f} in")
    plt.show()

[94mPlotting 2 logos (TMD length=23, JMD-N=10, JMD-C=10)[0m
figsize_per_logo height=2: total fig height = 4.0 in

[94mPlotting 2 logos (TMD length=23, JMD-N=10, JMD-C=10)[0m
figsize_per_logo height=4: total fig height = 8.0 in

logo_color_scheme is passed directly to logomaker.Logo. Common options: 'weblogo_protein' (default), 'chemistry', 'hydrophobicity'.

logo_stack_order controls letter stacking within each column: 'big_on_top' (default), 'small_on_top', 'fixed'.

for scheme in ['weblogo_protein', 'chemistry']:
    fig, axes = aal_plot.multi_logo(
        list_df_logo=[df_logo_pos, df_logo_neg],
        list_name_data=['Positive', 'Negative'],
        logo_color_scheme=scheme,
    )
    fig.suptitle(f"logo_color_scheme='{scheme}'", y=1.01)
    plt.show()

[94mPlotting 2 logos (TMD length=23, JMD-N=10, JMD-C=10)[0m

[94mPlotting 2 logos (TMD length=23, JMD-N=10, JMD-C=10)[0m

highlight_tmd_area=True (default) shades the TMD region in every subplot. highlight_alpha controls the opacity of the shading (0 = invisible, 1 = opaque).

for alpha in [0.0, 0.15, 0.4]:
    fig, axes = aal_plot.multi_logo(
        list_df_logo=[df_logo_pos, df_logo_neg],
        list_name_data=['Positive', 'Negative'],
        highlight_tmd_area=alpha > 0,
        highlight_alpha=alpha if alpha > 0 else 0.15,
    )
    fig.suptitle(f"highlight_tmd_area={alpha > 0}, highlight_alpha={alpha}", y=1.01)
    plt.show()

[94mPlotting 2 logos (TMD length=23, JMD-N=10, JMD-C=10)[0m

[94mPlotting 2 logos (TMD length=23, JMD-N=10, JMD-C=10)[0m

[94mPlotting 2 logos (TMD length=23, JMD-N=10, JMD-C=10)[0m

Set the color of the TMD and JMD part bar, x-tick marks, and TMD highlight rectangle across all subplots.

fig, axes = aal_plot.multi_logo(
    list_df_logo=[df_logo_pos, df_logo_neg],
    list_name_data=['Positive', 'Negative'],
    tmd_color='darkorange',
    jmd_color='steelblue',
)
plt.show()

[94mPlotting 2 logos (TMD length=23, JMD-N=10, JMD-C=10)[0m

Sets the residue number of the first position. Shifts x-tick labels on the bottom subplot only — does not affect positions or highlight coordinates.

for start in [1, 5]:
    fig, axes = aal_plot.multi_logo(
        list_df_logo=[df_logo_pos, df_logo_neg],
        list_name_data=['Positive', 'Negative'],
        start=start,
    )
    fig.suptitle(f"start={start}", y=1.01)
    plt.show()

[94mPlotting 2 logos (TMD length=23, JMD-N=10, JMD-C=10)[0m

[94mPlotting 2 logos (TMD length=23, JMD-N=10, JMD-C=10)[0m

These control the appearance of the ‘JMD-N’, ‘TMD’, ‘JMD-C’ text labels, which are drawn only on the bottom subplot.

fig, axes = aal_plot.multi_logo(
    list_df_logo=[df_logo_pos, df_logo_neg],
    list_name_data=['Positive', 'Negative'],
    weight_tmd_jmd='bold',
    fontsize_tmd_jmd=14,
)
plt.show()

[94mPlotting 2 logos (TMD length=23, JMD-N=10, JMD-C=10)[0m

When set, replaces the standard JMD/TMD x-axis on every subplot with P-site notation (P2, P1, P1’, P2’, …). The value is the 0-based position index of the P1 cleavage site.

# P1 site at position index 10 (start of TMD in a 10+20+10 layout)
fig, axes = aal_plot.multi_logo(
    list_df_logo=[df_logo_pos, df_logo_neg],
    list_name_data=['Positive', 'Negative'],
    target_p1_site=10,
)
plt.show()

[94mPlotting 2 logos (TMD length=23, JMD-N=10, JMD-C=10)[0m

All subplots automatically share the same y-axis maximum, computed from the maximum per-position sum across all logos. This makes group comparisons visually fair.

fig, axes = aal_plot.multi_logo(
    list_df_logo=[df_logo_pos, df_logo_neg],
    list_name_data=['Positive', 'Negative'],
)
ylims = [ax.get_ylim() for ax in axes]
print(f"y-axis limits per subplot: {ylims}")
print(f"All equal: {len(set(ylims)) == 1}")
plt.show()

[94mPlotting 2 logos (TMD length=23, JMD-N=10, JMD-C=10)[0m
y-axis limits per subplot: [(np.float64(0.0), np.float64(100.00000000000003)), (np.float64(0.0), np.float64(100.00000000000003))]
All equal: True

Further parameters. AAlogoPlot.multi_logo also accepts: fontsize_labels — Font size for axis labels; name_data_fontsize — Font size for name annotations; logo_font_name — Font name for amino acid letter rendering; logo_width — Relative width of each letter column (0 to 1); logo_vpad — Vertical padding between stacked letters; logo_vsep — Vertical separation between stacked letters; xtick_size — Font size for x-tick labels (bottom subplot only); xtick_width — Line width of x-tick marks; xtick_length — Length of x-tick marks in points.