aaanalysis.AAlogoPlot.single_logo

AAlogoPlot.single_logo(df_logo=None, df_logo_info=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 TMD/JMD annotations.

Parameters:

• df_logo (pd.DataFrame, shape (n_positions, n_amino_acids)) – Logo matrix as returned by AAlogo.get_df_logo(). Rows are residue positions, columns are amino acids.

• 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.

• 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 (plt.Figure) – Figure object.

• axes (plt.Axes or tuple of plt.Axes) – Single Axes when df_logo_info is None; tuple (ax_logo, ax_info) when df_logo_info is provided.

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()

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()

Without df_logo_info: axes type = Axes
With df_logo_info:    axes type = tuple, ax_logo ylabel='Probability [%]', ax_info ylabel='Bits'

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()

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()

height_ratio=(1, 6): logo/bar height ratio = 6.0

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()

name_data_pos='top': label placed on ax_info
name_data_pos='right': label placed on ax_logo
name_data_pos='left': label placed on ax_logo
name_data_pos='bottom': label placed on ax_logo

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)
    plot = aa.AAlogoPlot(logo_type=logo_type, jmd_n_len=10, jmd_c_len=10)
    fig, ax = plot.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 plot call
assert df_logo.values.max() == max_before, "df_logo was mutated!"
print(f"df_logo.max() unchanged after all plot calls: {max_before:.4f}")

logo_type='probability': ylabel='Probability [%]'
logo_type='counts': ylabel='Counts'
logo_type='weight': ylabel='Weight'
logo_type='information': ylabel='Bits'
df_logo.max() unchanged after all plot 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)]:
    plot = 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 = plot.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()

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()

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()

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()

start=1: first x-tick label = '1'
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()

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()

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()

figsize=(8, 3): actual fig size = (np.float64(8.0), np.float64(3.0))
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()