AAlogoPlot.single_logo

AAlogoPlot.single_logo(df_logo=None, df_logo_info=None, aal_kws=None, df_parts=None, labels=None, label_test=1, tmd_len=None, info_bar_color='gray', info_bar_ylim=None, target_p1_site=None, figsize=(8, 4), height_ratio=(1, 6), fontsize_labels=None, name_data=None, name_data_pos='top', 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)

Plot a single sequence logo with optional bit-score bar and target middle domain (TMD) / juxta middle domain (JMD) annotations.

Renders a pre-computed logo matrix from AAlogo as a letter-stack sequence logo using logomaker [Tareen20], and draws colored TMD/JMD part annotations beneath the x-axis. An optional bit-score bar panel can be shown above the logo when df_logo_info is provided. See AAlogoPlot.multi_logo() for stacking multiple logos for group comparison.

Added in version 1.1.0.

Parameters:

• df_logo (pd.DataFrame, shape (n_positions, n_amino_acids), optional) – Logo matrix as returned by AAlogo.get_df_logo(). Rows are residue positions, columns are amino acids. Required unless aal_kws is given, in which case it is computed internally and must be None.

• df_logo_info (pd.Series, shape (n_positions,), optional) – Per-position information content as returned by AAlogo.get_df_logo_info(). If provided, a bit-score bar is rendered above the main logo. Must be None when aal_kws is given (it is then computed internally and the bar is shown).

• aal_kws (dict, optional) – AAlogo.get_df_logo() / AAlogo.get_df_logo_info() keyword arguments. If given, df_logo and df_logo_info are computed internally and both must be None. Mutually exclusive with df_logo and df_logo_info (see Notes).

• df_parts (pd.DataFrame, shape (n_samples, n_parts), optional) – Sequence parts DataFrame with at least one of the standard part columns (jmd_n, tmd, jmd_c), as passed to AAlogo.get_df_logo(). If given, df_logo and df_logo_info are computed internally (so the bit-score bar is shown). Mutually exclusive with df_logo / df_logo_info and with aal_kws (see Notes).

• labels (array-like, shape (n_samples,), optional) – Class labels for the samples in df_parts. If provided, only samples with label_test are included in the logo computation. Only used together with df_parts.

• label_test (int, default=1) – Class label of the test group to select from labels. Only used together with df_parts.

• tmd_len (int, optional) – Fixed length (>=1) to align all target middle domain (TMD) sequences before computing the logo. If None, the maximum TMD length in df_parts is used. Only used together with df_parts.

• info_bar_color (str, default='gray') – Color of the bit-score bars in the optional top panel.

• info_bar_ylim (tuple of float, optional) – Y-axis limits (min, max) for the bit-score bar. If None, set automatically.

• target_p1_site (int, optional) – If set, replaces the standard JMD/TMD x-axis with P-site notation (P1, P2, …, P1’, P2’, …) anchored at this position index.

• figsize (tuple of (int or float), default=(8, 4)) – Figure size (width, height) in inches.

• height_ratio (tuple of (int or float), default=(1, 6)) – Height ratio (info_bar, logo) when df_logo_info is provided.

• fontsize_labels (int or float, optional) – Font size for axis labels. If None, uses the package default.

• name_data (str, optional) – Dataset name to annotate on the plot.

• name_data_pos ({'top', 'right', 'bottom', 'left'}, default='top') – Position of the name_data annotation.

• name_data_color (str, default='black') – Color of the name_data annotation.

• name_data_fontsize (int or float, optional) – Font size of the name_data annotation.

• 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 x-tick marks, part bar, and highlight.

• jmd_color (str, default='blue') – Color for JMD x-tick marks and part bar.

• fontsize_tmd_jmd (int or float, optional) – Font size for the ‘JMD-N’, ‘TMD’, ‘JMD-C’ part labels. If None, auto-sized.

• weight_tmd_jmd ({'normal', 'bold'}, default='normal') – Font weight for the ‘JMD-N’, ‘TMD’, ‘JMD-C’ part labels.

• highlight_tmd_area (bool, default=True) – If True, shades the TMD region with a semi-transparent rectangle.

• highlight_alpha (float, default=0.15) – Opacity of the TMD highlight (0 = fully transparent, 1 = opaque).

• xtick_size (int or float, optional) – Font size for x-tick labels. If None, uses the package default.

• 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 (Axes or tuple of (Axes, Axes)) – When df_logo_info is None: a single Axes for the logo panel. When df_logo_info is provided: a tuple (ax_logo, ax_info) where ax_info is the bit-score bar above the logo.

Notes

• There are three ways to supply the logo data, and exactly one must be used:

  1. precomputed df_logo (optionally with df_logo_info);

  2. the raw inputs df_parts (with labels, label_test, tmd_len);

  3. an aal_kws dict bundling the AAlogo getter arguments.

  Mixing sources (e.g. df_parts together with df_logo or aal_kws) raises ValueError.

• df_parts is the most direct shortcut: when given (and df_logo is None), 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()) from df_parts/labels/label_test/tmd_len, then renders the logo with the bit-score bar.

• aal_kws is the equivalent shortcut as a single dict, useful when the getter arguments are assembled programmatically. It holds the arguments shared by both methods, e.g. df_parts, labels, label_test, tmd_len, start_n, characters_to_ignore, and pseudocount. Unknown keys raise ValueError. Example: aal_kws=dict(df_parts=df_parts, labels=labels, label_test=1, tmd_len=20).

See also

• AAlogoPlot.multi_logo(): for stacked multi-group comparison.

• AAlogo: to compute df_logo and df_logo_info.

Examples

AAlogoPlot.single_logo renders a single sequence logo with optional TMD/JMD part annotations. When df_logo_info is provided, a bit-score bar is added above the logo in a second panel.

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 = aal.get_df_logo(df_parts=df_parts, labels=labels, label_test=1)
df_logo_info = aal.get_df_logo_info(df_parts=df_parts, labels=labels, label_test=1)

aal_plot = aa.AAlogoPlot(logo_type='probability', jmd_n_len=10, jmd_c_len=10)
print(f"df_logo shape: {df_logo.shape}, positions = {len(df_logo)}")

df_logo shape: (43, 20), positions = 43

The logo matrix returned by AAlogo.get_df_logo. Rows are residue positions, columns are amino acids. tmd_len is derived as len(df_logo) - jmd_n_len - jmd_c_len using the lengths set at initialization.

fig, ax = aal_plot.single_logo(df_logo=df_logo)
plt.show()

Plotting single logo (TMD length=23, JMD-N=10, JMD-C=10)

When provided, a second panel is added above the logo showing per-position information content as a bar chart (y-axis label: ‘Bits’). The return value changes from a single Axes to a tuple (ax_logo, ax_info).

# Without df_logo_info: returns single Axes
fig, ax = aal_plot.single_logo(df_logo=df_logo)
print(f"Without df_logo_info: axes type = {type(ax).__name__}")
plt.close()

# With df_logo_info: returns tuple (ax_logo, ax_info)
fig, axes = aal_plot.single_logo(df_logo=df_logo, df_logo_info=df_logo_info)
ax_logo, ax_info = axes
print(f"With df_logo_info:    axes type = {type(axes).__name__}, "
      f"ax_logo ylabel='{ax_logo.get_ylabel()}', ax_info ylabel='{ax_info.get_ylabel()}'")
plt.show()

Plotting single logo (TMD length=23, JMD-N=10, JMD-C=10)
Without df_logo_info: axes type = Axes
Plotting single logo (TMD length=23, JMD-N=10, JMD-C=10)
With df_logo_info:    axes type = tuple, ax_logo ylabel='Probability [%]', ax_info ylabel='Bits'

aal_kws is a convenience shortcut that skips the manual AAlogo step. Instead of building an AAlogo and calling get_df_logo / get_df_logo_info yourself, pass their shared arguments (df_parts, labels, label_test, tmd_len, start_n, characters_to_ignore, pseudocount) as a single dict. AAlogoPlot then instantiates AAlogo internally (using this plot’s logo_type), computes both df_logo and df_logo_info, and renders the logo together with the bit-score bar. It is mutually exclusive with df_logo / df_logo_info.

# One-shot: skip the manual AAlogo step -- aal_kws computes df_logo + df_logo_info internally
aal_plot = aa.AAlogoPlot(logo_type='probability', jmd_n_len=10, jmd_c_len=10)
fig, axes = aal_plot.single_logo(
    aal_kws=dict(df_parts=df_parts, labels=labels, label_test=1),
    name_data='DOM_GSEC positive',
)
print(f"Returned axes type = {type(axes).__name__} (logo panel + info bar)")
plt.show()

Plotting single logo (TMD length=23, JMD-N=10, JMD-C=10)
Returned axes type = tuple (logo panel + info bar)

The most direct shortcut: pass the raw inputs instead of precomputed frames. When df_parts is given (and df_logo is None), AAlogoPlot instantiates AAlogo internally (using this plot’s logo_type) and computes both df_logo and df_logo_info from df_parts / labels / label_test / tmd_len, then renders the logo together with the bit-score bar. This is equivalent to the aal_kws dict form and is mutually exclusive with df_logo / df_logo_info and with aal_kws. The result is identical to the manual two-getter path.

# Direct inputs: skip BOTH the manual AAlogo step and the aal_kws dict
aal_plot = aa.AAlogoPlot(logo_type='probability', jmd_n_len=10, jmd_c_len=10)
fig, axes = aal_plot.single_logo(
    df_parts=df_parts, labels=labels, label_test=1,
    name_data='DOM_GSEC positive',
)
print(f"Returned axes type = {type(axes).__name__} (logo panel + info bar)")

# Internally this recomputes the very same frames as the manual two-getter path
df_logo_direct = aa.AAlogo(logo_type='probability').get_df_logo(
    df_parts=df_parts, labels=labels, label_test=1)
print(f"df_logo recomputed identically: {df_logo_direct.equals(df_logo)}")
plt.show()

Plotting single logo (TMD length=23, JMD-N=10, JMD-C=10)
Returned axes type = tuple (logo panel + info bar)
df_logo recomputed identically: True

info_bar_color sets the bar color in the top panel. info_bar_ylim fixes the y-axis of the top panel to (min, max) — useful for comparing multiple plots on the same scale.

fig, axes = aal_plot.single_logo(
    df_logo=df_logo,
    df_logo_info=df_logo_info,
    info_bar_color='steelblue',
    info_bar_ylim=(0, 2.0),   # fix y-axis of the top panel
)
ax_logo, ax_info = axes
print(f"ax_info ylim: {ax_info.get_ylim()}")
plt.show()

Plotting single logo (TMD length=23, JMD-N=10, JMD-C=10)
ax_info ylim: (np.float64(0.0), np.float64(2.0))

Controls the relative height of (info_bar_panel, logo_panel) when df_logo_info is provided. Default is (1, 6) — logo is 6× taller than the bar.

for ratio in [(1, 6), (1, 1)]:
    fig, axes = aal_plot.single_logo(
        df_logo=df_logo,
        df_logo_info=df_logo_info,
        height_ratio=ratio,
    )
    ax_logo, ax_info = axes
    h_logo = ax_logo.get_position().height
    h_info = ax_info.get_position().height
    print(f"height_ratio={ratio}: logo/bar height ratio = {h_logo/h_info:.1f}")
    plt.show()

Plotting single logo (TMD length=23, JMD-N=10, JMD-C=10)
height_ratio=(1, 6): logo/bar height ratio = 6.0

Plotting single logo (TMD length=23, JMD-N=10, JMD-C=10)
height_ratio=(1, 1): logo/bar height ratio = 1.0

name_data annotates the plot with a text label.

Routing rule: when df_logo_info is provided and name_data_pos='top', the label is placed on ax_info (the top panel). For all other positions, it is placed on ax_logo.

# With df_logo_info: 'top' goes to ax_info, other positions go to ax_logo
for pos in ['top', 'right', 'left', 'bottom']:
    fig, axes = aal_plot.single_logo(
        df_logo=df_logo,
        df_logo_info=df_logo_info,
        name_data='DOM_GSEC positive',
        name_data_pos=pos,
    )
    ax_logo, ax_info = axes
    expected_ax = 'ax_info' if pos == 'top' else 'ax_logo'
    print(f"name_data_pos='{pos}': label placed on {expected_ax}")
    plt.close()

# Show the 'top' case
fig, axes = aal_plot.single_logo(
    df_logo=df_logo, df_logo_info=df_logo_info,
    name_data='DOM_GSEC positive', name_data_pos='top',
)
plt.show()

Plotting single logo (TMD length=23, JMD-N=10, JMD-C=10)
name_data_pos='top': label placed on ax_info
Plotting single logo (TMD length=23, JMD-N=10, JMD-C=10)
name_data_pos='right': label placed on ax_logo
Plotting single logo (TMD length=23, JMD-N=10, JMD-C=10)
name_data_pos='left': label placed on ax_logo
Plotting single logo (TMD length=23, JMD-N=10, JMD-C=10)
name_data_pos='bottom': label placed on ax_logo
Plotting single logo (TMD length=23, JMD-N=10, JMD-C=10)

logo_type at init controls the y-axis label only. For 'probability', the backend also scales values ×100 and fixes yticks to [0, 25, 50, 75, 100]. The input df_logo is not mutated — scaling is applied to an internal copy.

max_before = df_logo.values.max()

for logo_type in ['probability', 'counts', 'weight', 'information']:
    df_logo_t = aa.AAlogo(logo_type=logo_type).get_df_logo(
        df_parts=df_parts, labels=labels, label_test=1)
    aal_plot_t = aa.AAlogoPlot(logo_type=logo_type, jmd_n_len=10, jmd_c_len=10)
    fig, ax = aal_plot_t.single_logo(df_logo=df_logo_t)
    print(f"logo_type='{logo_type}': ylabel='{ax.get_ylabel()}'")
    plt.close()

# Confirm df_logo not mutated by any aal_plot_t call
assert df_logo.values.max() == max_before, "df_logo was mutated!"
print(f"df_logo.max() unchanged after all aal_plot_t calls: {max_before:.4f}")

Plotting single logo (TMD length=23, JMD-N=10, JMD-C=10)
logo_type='probability': ylabel='Probability [%]'
Plotting single logo (TMD length=23, JMD-N=10, JMD-C=10)
logo_type='counts': ylabel='Counts'
Plotting single logo (TMD length=23, JMD-N=10, JMD-C=10)
logo_type='weight': ylabel='Weight'
Plotting single logo (TMD length=23, JMD-N=10, JMD-C=10)
logo_type='information': ylabel='Bits'
df_logo.max() unchanged after all aal_plot_t calls: 0.4444

These derive tmd_len = len(df_logo) - jmd_n_len - jmd_c_len, which sets the extent of the TMD region in the part bar, x-tick coloring, and highlight. Here df_logo has 40 positions (10 + 20 + 10).

# Same df_logo, different jmd lengths -> different TMD region highlighted
for jmd_n, jmd_c in [(10, 10), (5, 5), (0, 0)]:
    aal_plot_t = aa.AAlogoPlot(logo_type='probability', jmd_n_len=jmd_n, jmd_c_len=jmd_c)
    tmd_len = len(df_logo) - jmd_n - jmd_c
    fig, ax = aal_plot_t.single_logo(df_logo=df_logo)
    fig.suptitle(f"jmd_n_len={jmd_n}, jmd_c_len={jmd_c} → tmd_len={tmd_len}", y=1.01)
    plt.show()

Plotting single logo (TMD length=23, JMD-N=10, JMD-C=10)

Plotting single logo (TMD length=33, JMD-N=5, JMD-C=5)

Plotting single logo (TMD length=43, JMD-N=0, JMD-C=0)

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

fig, ax = aal_plot.single_logo(
    df_logo=df_logo,
    tmd_color='darkorange',
    jmd_color='steelblue',
)
plt.show()

Plotting single logo (TMD length=23, JMD-N=10, JMD-C=10)

highlight_tmd_area=True (default) draws a shaded rectangle over the TMD region. highlight_alpha sets its opacity.

for alpha in [0.0, 0.15, 0.5]:
    fig, ax = aal_plot.single_logo(
        df_logo=df_logo,
        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()

Plotting single logo (TMD length=23, JMD-N=10, JMD-C=10)

Plotting single logo (TMD length=23, JMD-N=10, JMD-C=10)

Plotting single logo (TMD length=23, JMD-N=10, JMD-C=10)

Shifts the x-tick label numbers — the first position of JMD-N gets this number. Does not move the highlight or part bar.

for start in [1, 10]:
    fig, ax = aal_plot.single_logo(df_logo=df_logo, start=start)
    xtick_labels = [t.get_text() for t in ax.get_xticklabels() if t.get_text()]
    print(f"start={start}: first x-tick label = '{xtick_labels[0]}'")
    plt.close()

Plotting single logo (TMD length=23, JMD-N=10, JMD-C=10)
start=1: first x-tick label = '1'
Plotting single logo (TMD length=23, JMD-N=10, JMD-C=10)
start=10: first x-tick label = '10'

Control the font weight and size of the ‘JMD-N’, ‘TMD’, ‘JMD-C’ text labels drawn below the x-axis.

fig, ax = aal_plot.single_logo(
    df_logo=df_logo,
    weight_tmd_jmd='bold',
    fontsize_tmd_jmd=14,
)
plt.show()

Plotting single logo (TMD length=23, JMD-N=10, JMD-C=10)

When set, replaces the entire TMD/JMD x-axis with P-site notation (P2, P1, P1’, P2’, …). The value is the 0-based position index of the P1 site. All of start, fontsize_tmd_jmd, weight_tmd_jmd, xtick_width, xtick_length are ignored when target_p1_site is set.

# P1 at position index 10 (JMD-N/TMD boundary in a 10+20+10 layout)
fig, ax = aal_plot.single_logo(df_logo=df_logo, target_p1_site=10, figsize=(10,4), xtick_size=7)
xtick_labels = [t.get_text() for t in ax.get_xticklabels()]
print(f"x-tick labels: {xtick_labels[:6]} ...")
plt.show()

Plotting single logo (TMD length=23, JMD-N=10, JMD-C=10)
x-tick labels: ['P10', 'P9', 'P8', 'P7', 'P6', 'P5'] ...

Sets the (width, height) of the whole figure in inches. When df_logo_info is provided, both panels share this total height, split by height_ratio.

for figsize in [(8, 3), (14, 5)]:
    fig, ax = aal_plot.single_logo(df_logo=df_logo, figsize=figsize)
    actual = tuple(round(x, 1) for x in fig.get_size_inches())
    print(f"figsize={figsize}: actual fig size = {actual}")
    plt.close()

Plotting single logo (TMD length=23, JMD-N=10, JMD-C=10)
figsize=(8, 3): actual fig size = (np.float64(8.0), np.float64(3.0))
Plotting single logo (TMD length=23, JMD-N=10, JMD-C=10)
figsize=(14, 5): actual fig size = (np.float64(14.0), np.float64(5.0))

logo_color_scheme is passed directly to logomaker.Logo. logo_stack_order controls letter stacking: 'big_on_top' (default), 'small_on_top', or 'fixed'.

for scheme, order in [('weblogo_protein', 'big_on_top'), ('chemistry', 'small_on_top')]:
    fig, ax = aal_plot.single_logo(
        df_logo=df_logo,
        logo_color_scheme=scheme,
        logo_stack_order=order,
    )
    fig.suptitle(f"color_scheme='{scheme}', stack_order='{order}'", y=1.01)
    plt.show()

Plotting single logo (TMD length=23, JMD-N=10, JMD-C=10)

Plotting single logo (TMD length=23, JMD-N=10, JMD-C=10)

Further parameters. AAlogoPlot.single_logo also accepts: fontsize_labels — Font size for axis labels; name_data_color — Color of the name_data annotation; name_data_fontsize — Font size of the name_data annotation; 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.