alphapepttools.pl.layered_plot

Contents

alphapepttools.pl.layered_plot#

alphapepttools.pl.layered_plot(ax, base_config, layers=None, color_dict=None, default_layer_column='__data', default_layer_val='__all', default_color_key='__default_color', default_color=(np.float64(0.21299500192233756), np.float64(0.5114186851211072), np.float64(0.730795847750865), np.float64(1.0)), default_layer_kwargs=None, lim_padding_factor=1.1, xlims=None, ylims=None, plotting_callable=None, return_glob_layer_indices=False)#

Plot multiple layers with defined hierarchy and without datapoint reuse.

In order to layer multiple levels of plotting layers onto each other (e.g. color points by differential expression, and then highlight extra points on top of that), this function allows for defining multiple plotting layers. The purpose of this is to avoid repetitive specification of shared parameters in the layers list. Points which are not assigned to any layer are plotted in the default layer in the background. A shared color_dict is used by all layers to lookup colors by key.

Parameters:

  • ax (Axes) – Matplotlib axes object to plot on.

  • base_config (PlotConfig) – Base configuration for the plot layers containing data and plot parameters.

  • layers (list[tuple] | None (default: None)) – List of layer specifications, each a tuple of (layer_column, layer_val, color_key, layer_kwargs). - layer_column (str): Column name to filter on for this layer - layer_val (str|int|list): Value(s) to match in the layer_column (i.e. this layer will only contain points where data[layer_column] is in layer_val) - color_key (str): Color key in color_dict for this layer - layer_kwargs (dict, optional): Additional parameters for this layer By default None, which results in a single default layer containing all points.

  • color_dict (dict[str, str | tuple] | None (default: None)) – Dictionary mapping color keys to colors. By default None, which results in a single default color.

  • default_layer_column (str (default: '__data')) – Column name to use for the default layer. By default “__data”.

  • default_layer_val (str (default: '__all')) – Value to use for the default layer. By default “__all”.

  • default_color_key (str (default: '__default_color')) – Color key to use for the default color. By default “__default_color”.

  • default_color (str | tuple (default: (np.float64(0.21299500192233756), np.float64(0.5114186851211072), np.float64(0.730795847750865), np.float64(1.0)))) – Color to use for the default color. By default BaseColors.get(“blue”).

  • default_layer_kwargs (dict | None (default: None)) – Default scatterplot keyword arguments for the default layer. By default None.

  • lim_padding_factor (float (default: 1.1)) – Factor to pad the x and y limits of the plot. By default 1.1.

  • xlims (tuple[float, float] | None (default: None)) – x-axis limits for the plot. If None, limits are calculated from the data with padding. By default None.

  • ylims (tuple[float, float] | None (default: None)) – y-axis limits for the plot. If None, limits are calculated from the data with padding. By default None.

  • plotting_callable (Callable | None (default: None)) – Custom plotting function to use instead of scatter. Should accept ax, data, and other parameters. By default None, which uses scatter.

  • return_glob_layer_indices (bool (default: False)) – If True, returns a list of (indices, color, color_key, scatter_kwargs) tuples for each layer. Useful for debugging or further processing of layer assignments. By default False.

Return type:

None | list

Returns:

None | list If return_glob_layer_indices is False, returns None. Otherwise, returns a list of tuples containing (layer_indices, layer_color, color_key, scatter_kwargs) for each layer.

Example

import numpy as np
import pandas as pd
import anndata as ad
from alphapepttools import pl
import alphapepttools as apt
from alphapepttools.pl import BaseColors, create_figure, label_axes

rng = np.random.default_rng(seed=42)

# example data
testx = rng.normal(0, 1, 300)
testy = -np.cos(testx) + rng.normal(0, 0.2, 300)
testp = 10 ** -(testy - min(testy))
vp_data = pd.DataFrame(
    {
        "id": [f"P{10000 + i}" for i in range(300)],
        "gene": [f"gene_{i}" for i in range(300)],
        "log2fc": testx,
        "pval": testp,
        "neg_log10pval": -np.log10(testp),
    }
)
vp_data.index = vp_data["id"].astype(str)

example_adata_diff = ad.AnnData(
    X=vp_data[["log2fc", "pval", "neg_log10pval"]].values,
    obs=vp_data[["id", "gene"]],
    var=vp_data[["log2fc", "pval", "neg_log10pval"]].columns.to_frame(),
)

# Add some example categorical and point-of-interest annotations
example_adata_diff.obs["diff_exp_status"] = example_adata_diff.to_df()["log2fc"].apply(
    lambda x: "upregulated" if x > 1 else ("downregulated" if x < -1 else "unchanged")
)

example_adata_diff.obs["pathway"] = rng.choice(
    ["pathway_A", "pathway_B", "pathway_C", "pathway_D", "pathway_E"], size=example_adata_diff.n_obs
)
example_adata_diff.obs["poi_status"] = rng.choice(
    ["poi", "background"], size=example_adata_diff.n_obs, p=[0.01, 0.99]
)

# Specify a custom color dictionary for the categories we want to color
color_dict = {
    "upregulated": BaseColors.get("red"),
    "downregulated": BaseColors.get("blue"),
    "unchanged": BaseColors.get("grey"),
    "poi": BaseColors.get("black"),
    "pathway_A": BaseColors.get("purple", lighten=0.5),
}

# In order to avoid repeating instructions for each layer, we can summarize the parameters for the whole plot in a configuration
layered_plot_config = pl.make_scatter_config(
    data=example_adata_diff,  # all layers use the same data and numeric columns
    x_column="log2fc",
    y_column="neg_log10pval",
    scatter_kwargs={"alpha": 0.7, "s": 30},  # make the points slightly transparent and set a good size
)

# Define layers: each layer is a tuple of (column to filter on, value to select, color key, optional plotting kwargs)
plot_layers = [
    (
        "poi_status",
        "poi",
        "poi",
        {"scatter_kwargs": {"marker": "^", "s": 200}},
    ),  # this layer gets custom scatterplot settings kwargs
    ("pathway", "pathway_A", "pathway_A"),
    ("diff_exp_status", "upregulated", "upregulated"),
    ("diff_exp_status", "downregulated", "downregulated"),
    ("diff_exp_status", "unchanged", "unchanged"),
]

# Visualize the plot with layers
fig, axm = create_figure(1, 1, figsize=(6, 6))
ax = axm.next()
apt.pl.layered_plot(
    ax=ax,
    base_config=layered_plot_config,
    layers=plot_layers,
    color_dict=color_dict,
    ylims=(0, 3),
    xlims=(-3, 4.5),  # leave some space for labels on the right side
)

# Label axes
label_axes(
    ax,
    xlabel="log2 Fold Change",
    ylabel="-log10 p-value",
    title="Layered Volcano Plot of Differential Expression with Custom Colors and Highlighting",
)
Contents