alphapepttools.pl.plot_pca_loadings

alphapepttools.pl.plot_pca_loadings#

alphapepttools.pl.plot_pca_loadings(data, ax, dim_space='obs', embeddings_name=None, method='pca', dim=1, nfeatures=20, scatter_kwargs=None)#

1D loadings plot showing top features contributing to a principal component.

Creates a scatter plot displaying the loadings (weights) of the top contributing features for a single principal component. Loadings indicate how much each feature (gene/protein) contributes to the PC. The plot shows the top N features ranked by absolute loading value.

Parameters:

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

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

  • dim_space (str (default: 'obs')) – PCA space to retrieve loadings from: - “obs”: Sample space PCA (default) - shows which features drive sample separation - “var”: Feature space PCA - shows which samples drive feature separation

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

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

  • dim (int (default: 1)) – Principal component number to show loadings for (1-indexed, so 1 = PC1, 2 = PC2, etc.).

  • nfeatures (int (default: 20)) – Number of top features (by absolute loading value) to display.

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

Return type:

None

Examples

Basic loadings plot for PC1:

fig, ax = plt.subplots()
Plots.plot_pca_loadings(
    data=adata,
    ax=ax,
    dim=1,
    nfeatures=20,
)

Loadings plot for PC3 with more features:

fig, ax = plt.subplots()
Plots.plot_pca_loadings(data=adata, ax=ax, dim=3, nfeatures=30, scatter_kwargs={"s": 50, "alpha": 0.8})

Feature space loadings (var projection):

# Show which samples most influence feature PC1
fig, ax = plt.subplots()
Plots.plot_pca_loadings(
    data=adata,
    ax=ax,
    dim=1,
    dim_space="var",
    nfeatures=15,
)

Notes

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

  • Features are ranked by absolute loading value (magnitude, not sign)

  • Y-axis shows feature names, X-axis shows loading values

  • dim_space=”obs” shows feature loadings (most common - which proteins/genes matter)

  • dim_space=”var” shows sample loadings (which samples matter)

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