MEA bubble maps label NES values as log2(FF)

[SuhasSrinivasan]

Summary

In Kinase Library 1.7.1, the natural MEA-to-bubble-map workflow can display normalized enrichment scores (NES) while labeling the color scale log2(FF).

combine_mea_enrichment_results() defaults lff_col_name to NES:

kinase-library/src/kinase_library/modules/enrichment.py

Lines 299 to 300 in dd1ba35

	def combine_mea_enrichment_results(enrichment_results_dict, data_type='kl_object',
	lff_col_name='NES', pval_col_name=None, adj_pval=True):

It copies that column into the returned lff_data matrix:

kinase-library/src/kinase_library/modules/enrichment.py

Lines 354 to 361 in dd1ba35

	lff_data = pd.DataFrame(index=kinases, columns=conds_list)
	pval_data = pd.DataFrame(index=kinases, columns=conds_list)
	for res,cond in zip(enrichment_results_tables,conds_list):
	lff_data[cond] = res[lff_col_name]
	pval_data[cond] = res[pval_col_name]
	return(lff_data,pval_data)

However, plot_bubblemap() documents lff_data as log-frequency-factor data and does not expose a color-bar title parameter:

kinase-library/src/kinase_library/modules/enrichment.py

Lines 684 to 703 in dd1ba35

	def plot_bubblemap(lff_data, pval_data, cont_kins=None, sig_lff=0, sig_pval=0.1, kinases=None,
	plot_cont_kins=True, highlight_cont_kins=True, sort_kins_by='family',
	cond_order=None, only_sig_kins=False, only_sig_conds = False,
	kin_clust=False, condition_clust=False, cluster_by=None,
	cluster_by_matrix=None, cluster_method='average',
	color_kins_by='family', kin_categories_colors=None, cond_colors=None,
	title=None, family_legned=True, pval_legend=True, lff_cbar=True,
	pval_legend_spacing=None, save_fig=False, max_window=True,
	lff_clim=(-2,2), max_pval_size=4, bubblesize_range=(10,100),
	num_panels=6, vertical=True, constrained_layout=True,
	xaxis_label='Condition', yaxis_label='Kinase',
	xlabel=True, xlabels_size=8, ylabel=True, ylabels_size=10,
	font_family=None):
	"""
	Function to display a bubblemap with Kinase Library enrichment results inputted as log frequency factor and p-value matrices.
	Parameters
	----------
	lff_data : pd.DataFrame
	Matrix containing Kinase Library enrichment log frequency factor data with kinases as index and conditions as columns.

The color-bar title is unconditionally set to log2(FF):

kinase-library/src/kinase_library/modules/enrichment.py

Lines 1039 to 1044 in dd1ba35

	if lff_cbar:
	axes[2].set(aspect=10)
	sm = plt.cm.ScalarMappable(cmap='coolwarm', norm=cnorm)
	sm.set_array([])
	cbar = fig.colorbar(sm, cax=axes[2])
	cbar.ax.set_title('log2(FF)')

No transformation from NES to log2 frequency factor occurs between the combiner and plotting function.

Minimal reproducer

import pandas as pd
import kinase_library as kl

kinases = ["AKT1", "ERK1"]
mea_results = {
    "condition_a": pd.DataFrame(
        {"NES": [1.5, -1.2], "FDR": [0.01, 0.02]}, index=kinases
    ),
    "condition_b": pd.DataFrame(
        {"NES": [1.1, -1.4], "FDR": [0.03, 0.01]}, index=kinases
    ),
}

nes_data, pval_data = kl.combine_mea_enrichment_results(
    mea_results,
    data_type="data_frame",
)

kl.plot_bubblemap(
    lff_data=nes_data,
    pval_data=pval_data,
    num_panels=1,
    max_window=False,
)

The bubble colors represent the supplied NES values, but the color bar is titled log2(FF).

Expected behavior

MEA bubble maps should identify the color statistic as NES, or plot_bubblemap() should expose a parameter such as lff_cbar_title / colorbar_title so callers can label the supplied statistic accurately. A configurable title with a backward-compatible default would also support non-MEA uses of the generic plotting function.

The MEA combiner documentation could also be updated to describe its default NES input and return value rather than log frequency factor.

Environment

• kinase-library==1.7.1
• Python 3.12