alphapepttools.pl.plot_pca

Contents

alphapepttools.pl.plot_pca#

alphapepttools.pl.plot_pca(data, x_column=1, y_column=2, color='blue', color_map_column=None, color_column=None, dim_space='obs', embeddings_name=None, method='pca', label=False, label_column=None, ax=None, palette=None, color_dict=None, legend=None, scatter_kwargs=None)#

PCA scatter plot showing principal component projections.

Visualizes PCA results by plotting two principal components against each other. The function retrieves PCA embeddings from the AnnData object based on the dim_space parameter: use “obs” for sample projections (most common, shows how samples relate) or “var” for feature projections (shows how features/genes relate). Axes are automatically labeled with explained variance percentages.

Parameters:

  • data (AnnData) – AnnData object containing PCA results (must have run PCA first).

  • x_column (int (default: 1)) – Principal component number for x-axis (1-indexed, so 1 = PC1, 2 = PC2, etc.).

  • y_column (int (default: 2)) – Principal component number for y-axis (1-indexed).

  • color (str (default: 'blue')) – Single color for all points. Overridden by color_map_column or color_column.

  • color_map_column (str | None (default: None)) – Column in data.obs (for dim_space=”obs”) or data.var (for dim_space=”var”) to use for color encoding. Values are mapped to colors using palette or color_dict. Overrides the color parameter.

  • color_column (str | None (default: None)) – Column containing actual color values (hex, RGBA, etc.). Overrides both color and color_map_column parameters.

  • dim_space (str (default: 'obs')) – PCA space to visualize: - “obs”: Sample projections (default) - shows samples in PC space - “var”: Feature projections - shows features/genes in PC space

  • embeddings_name (str | None (default: None)) – Custom embeddings name if non-default name was used in the PCA function. If None, uses default naming convention (“X_pca_obs” or “X_pca_var”).

  • method (Literal['pca', 'bpca'] (default: 'pca')) – The method used for dimensionality reduction. Options are “pca” or “bpca” with “pca” as the default. This is used to construct the default keys if embeddings_name is None.

  • label (bool (default: False)) – Whether to add text labels to points in the scatter plot.

  • label_column (str | None (default: None)) – Column to use for point labels. If None and label=True, uses the index (data.obs.index for dim_space=”obs”, data.var.index for dim_space=”var”).

  • ax (Axes | None (default: None)) – Matplotlib axes to plot on. If None, a new figure is created.

  • palette (list[str | tuple] | None (default: None)) – List of colors for color encoding. If None, uses default qualitative palette.

  • color_dict (dict[str, str | tuple] | None (default: None)) – Dictionary mapping category values to specific colors. Overrides palette.

  • legend (str | Legend | None (default: None)) – Legend specification. Use “auto” to create legend from color_map_column.

  • scatter_kwargs (dict | None (default: None)) – Additional keyword arguments passed to matplotlib scatter (e.g., s, alpha).

Return type:

None

Examples

Basic PCA plot with sample coloring:

fig, ax = plt.subplots()
Plots.plot_pca(
    data=adata,
    ax=ax,
    x_column=1,
    y_column=2,
    color_map_column="replicate",
    legend="auto",
)

PCA with custom PC axes and labels:

fig, ax = plt.subplots()
Plots.plot_pca(
    data=adata,
    ax=ax,
    x_column=2,  # PC2
    y_column=3,  # PC3
    label=True,
    label_column="sample_id",
    color_map_column="treatment",
    color_dict={"Control": "gray", "Drug": "red"},
)

Feature space PCA (var projection):

# Show how proteins/genes relate to each other in PC space
fig, ax = plt.subplots()
Plots.plot_pca(
    data=adata,
    ax=ax,
    x_column=1,
    y_column=2,
    dim_space="var",  # Feature projection instead of sample
    color_map_column="protein_type",
    scatter_kwargs={"s": 20, "alpha": 0.6},
)

Notes

  • PCA must be run on the AnnData object before calling this function

  • Axis labels automatically include explained variance percentages (e.g., “PC1 (45.2%)”)

  • dim_space=”obs” retrieves sample projections from obsm (most common usage)

  • dim_space=”var” retrieves feature projections from varm (less common)

  • PC numbers are 1-indexed: x_column=1 corresponds to the first principal component

  • This is a convenience wrapper around scatter() with automatic PCA data extraction

Contents