Plotting#

Data plots#

scpca.plots.data.data_matrix(array=None, num_rows=16, num_cols=4, num_states=2, right_add=0, cmaps=None, vmin=None, vmax=None, remove_ticklabels=False, title='D', xlabel=None, ylabel=None, ylabel_pos=None, xlabel_pos=None, hlinewidth=None, vlinewidth=None, ax=None)#

Create a Data Matrix Visualization with Multiple Colormaps.

Parameters

  • array (Optional[ndarray[Any, dtype[float32]]]) – Data array to visualize as a matrix. If None, random data is generated.

  • num_rows (int) – Number of rows in the data matrix. (Default: 16)

  • num_cols (int) – Number of columns in the data matrix. (Default: 4)

  • num_states (Union[int, List[int]]) – Number of categories to split the data matrix into. Must divide the array.shape[0] evenly. (Default: 2)

  • right_add (int) – Number of columns to add to the right of the data matrix. (Default: 0)

  • cmaps (Optional[List[str]]) – List of colormaps to use for different data categories. (Default: None)

  • vmin (Optional[float]) – Minimum value for color mapping. (Default: None)

  • vmax (Optional[float]) – Maximum value for color mapping. (Default: None)

  • remove_ticklabels (bool) – Whether to remove tick labels. (Default: False)

  • title (Optional[str]) – Title of the plot

  • xlabel (Optional[str]) – Label for the x-axis. (Default: None)

  • ylabel (Optional[str]) – Label for the y-axis. (Default: None)

  • ylabel_pos (Optional[Tuple[float, float]]) – Position coordinates for the y-axis label. (Default: None)

  • xlabel_pos (Optional[Tuple[float, float]]) – Position coordinates for the x-axis label. (Default: None)

  • hlinewidth (Optional[float]) – Line width for horizontal grid lines. (Default: None)

  • vlinewidth (Optional[float]) – Line width for vertical grid lines. (Default: None)

  • ax (Optional[Axes]) – Existing matplotlib axes to plot on. If None, a new figure is created.

Return type

Axes

Returns

Matplotlib axes containing the data matrix visualization.

Notes

This function creates a data matrix visualization with the option to use multiple colormaps for different data categories. It can be useful for visualizing structured data.

Example

>>> import matplotlib.pyplot as plt
>>> data_matrix(num_rows=12, num_cols=4, num_states=[2, 3, 1])
>>> plt.show()
scpca.plots.data.design_matrix(adata, formula, repeats=4, xticklabels=[], title='D', xlabel=None, ylabel=None, ylabel_pos=None, xlabel_pos=None, rotation=90, columns=None, ax=None)#

Create a Design Matrix Visualization.

Parameters

  • adata (AnnData) – Anndata object containing data for the design matrix.

  • formula (str) – Formula for creating the design matrix.

  • repeats (int) – Number of repeats for each category. (Default: 4)

  • xticklabels (List[str]) – Labels for the x-axis. (Default: [])

  • title (Optional[str]) – Title for the plot. (Default: “D”)

  • xlabel (Optional[str]) – Label for the x-axis. (Default: None)

  • ylabel (Optional[str]) – Label for the y-axis. (Default: None)

  • ylabel_pos (Optional[Tuple[float, float]]) – Position coordinates for the y-axis label. (Default: None)

  • xlabel_pos (Optional[Tuple[float, float]]) – Position coordinates for the x-axis label. (Default: None)

  • rotation (int) – Rotation angle for x-axis tick labels. (Default: 90)

  • columns (Union[int, List[int], None]) – Specify the columns to visualize from the design matrix. (Default: None)

  • ax (Optional[Axes]) – Existing matplotlib axes to plot on. If None, a new figure is created.

Return type

Axes

Returns

Matplotlib axes containing the design matrix visualization.

Notes

This function creates a design matrix visualization based on the provided formula and input data.

scpca.plots.data.heatmap(adata, model_key, states, factor, state_key, cluster_key, cluster_groups=None, dot=False, sign=1, var_names=None, highest=0, lowest=0, magnitude=1.96, **kwargs)#

Enrichment analysis of clusters based on differential gene expression.

Parameters

  • adata (AnnData) – Anndata object.

  • model_key (str) – Key to access the model in the adata object.

  • states (Union[str, List[str], Tuple[str, str]]) – States for comparison. If not pair of states is provided, “Intercept” is assumed to be the base state.

  • factor (int) – Factor index to consider for the differential calculation.

  • state_key (Union[str, List[str]]) – Key for state in adata.

  • cluster_key (str) – Key for cluster in adata.

  • cluster_groups (Union[str, List[str], None]) – Groups to consider for enrichment.

  • dot (bool) – If True, a dot plot is generated. Otherwise, a heatmap is generated. Default is False.

  • sign (Union[int, float]) – Sign to adjust the difference, by default 1.

  • highest (int) – Number of highest differential genes to retrieve, by default 0.

  • lowest (int) – Number of lowest differential genes to retrieve, by default 0.

  • magnitude (float) – Threshold for significance, by default 1.96.

  • **kwargs (Any) – Additional keyword arguments passed to the plotting function.

Return type

Axes

Returns

If return_var_names is True, returns a dictionary of variable names. Otherwise, returns the plot axes.

Notes

This function performs enrichment analysis of clusters based on differential gene expression. It first validates the sign and retrieves differential genes. Depending on the dot parameter, either a dot plot or a heatmap is generated to visualize the enrichment.

scpca.plots.data.triangle_overlay(array=None, num_rows=16, num_cols=4, rot=0, num_states=2, cmap=['Blues', 'Greens'], color=None, vmin=None, vmax=None, ax=None, **kwargs)#

Create a Triangle Overlay Plot.

Parameters

  • array (Optional[ndarray[Any, dtype[float32]]]) – Data array to overlay on the triangle plot. If None, random data is generated.

  • num_rows (int) – Number of rows in the triangle grid. (Default: 16)

  • num_cols (int) – Number of columns in the triangle grid. (Default: 4)

  • rot (int) – Rotation angle of the triangles in degrees. (Default: 0)

  • num_states (int) – Number of states or categories. (Default: 2)

  • cmap (List[str]) – List of colormaps to use for different states. (Default: [“Blues”, “Greens”])

  • color (Optional[str]) – Common color for all triangles if provided. (Default: None)

  • vmin (Optional[float]) – Minimum value for color mapping. (Default: None)

  • vmax (Optional[float]) – Maximum value for color mapping. (Default: None)

  • ax (Optional[Axes]) – Existing matplotlib axes to plot on. If None, a new figure is created.

  • **kwargs (Any) – Additional keyword arguments to pass to the PolyCollection.

Return type

Axes

Returns

Matplotlib axes containing the triangle overlay plot.

Notes

This function creates a triangle overlay plot with optional data values represented by colors. Triangles are arranged in a grid with specified rows and columns.

Fitting plots#

scpca.plots.qc.mean_var(adata, model_key=None, layers_key=None, β_rna_mean=3, β_rna_sd=1, alpha=1.0, margin=0.01, cmap='viridis', ax=None)#

Create a Scatter Plot of Mean vs. Variance in Single-Cell RNA-seq Data.

Parameters

  • adata (AnnData) – Anndata object containing single-cell RNA-seq data.

  • model_key (Optional[str]) – Key for the fitted model within the AnnData object. (Default: None)

  • layers_key (Optional[str]) – Key to extract counts from adata.layers. If None, raw counts are extracted from adata.X.

  • β_rna_mean (float) – Prior mean for RNA expression. (Default: 3.0)

  • β_rna_sd (float) – Prior standard deviation for RNA expression. (Default: 1.0)

  • alpha (float) – Transparency of data points in the scatter plot. (Default: 1.0)

  • margin (float) – Margin for the variance plot. (Default: 0.01)

  • cmap (str) – Colormap for the scatterplot. (Default: “viridis”)

  • ax (Optional[Axes]) – Existing matplotlib axes to plot on. If None, a new figure is created.

Return type

Axes

Returns

Matplotlib axes containing the scatter plot.

Notes

This function creates a scatter plot of the mean expression values against the variance for genes in single-cell RNA-seq data. It also visualizes a prior distribution for variance. The plot may include labeled genes with the highest deviations from the expected variance.

scpca.plots.qc.true_pred(adata, model_key, layers_key=None, cmap='viridis', colorbar_pos='right', colorbar_width='3%', orientation='vertical', ax=None)#

Create a 2D histogram plot of predicted vs. true counts of a scPCA model.

Parameters

  • adata (AnnData) – Anndata object containing single-cell RNA-seq data.

  • model_key (str) – Key for the fitted model within the AnnData object.

  • layers_key (Optional[str]) – Key to extract counts from adata.layers. If None, raw counts are extracted from adata.X.

  • cmap (str) – Colormap for the scatterplot. Default is “viridis”.

  • colorbar_pos (str) – Position of the colorbar (e.g., “right” or “left”). Default is “right”.

  • colorbar_width (str) – Width of the colorbar as a percentage of the figure. Default is “3%”.

  • orientation (str) – Orientation of the colorbar (“vertical” or “horizontal”). Default is “vertical”.

  • ax (Optional[Axes]) – Existing matplotlib axes to plot on. If None, a new figure is created.

Return type

Axes

Returns

Matplotlib axes containing the 2D scatter plot.

Notes

This function generates a 2D-histogram plot comparing predicted counts (from a fitted model) against true counts in single-cell RNA-seq data.

Factor Embedding#

scpca.plots.factor_embedding.factor_density(adata, model_key, cluster_key, factor=None, groups=[], sign=1.0, fill=True, lw=0.5, legend=True, ax=None, size=1, ncols=4, width=4, height=3)#

Plot Factor Density for Clusters in Single-Cell Analysis.

Parameters

  • adata (AnnData) – Anndata object containing single-cell data.

  • model_key (str) – Key for the fitted model.

  • factor (Union[int, List[int], None]) – Index of the factor to visualize.

  • cluster_key (str) – Key for the cluster annotations in adata.obs.

  • groups (Union[str, List[str]]) – Specific cluster groups to highlight in the plot. If empty, all clusters are used. (Default: [])

  • fill (bool) – Whether to fill the density plot. (Default: True)

  • lw (float) – Line width for the density plot. (Default: 0.5)

  • legend (bool) – Whether to display the legend. (Default: True)

  • ax (Optional[Axes]) – Matplotlib axes to plot on. If None, a new figure is created.

Return type

Axes

Returns

Matplotlib axes containing the factor density plot.

Notes

This function plots the density of a specific factor’s weights across clusters in single-cell analysis. The density plot shows the distribution of the factor weights for each cluster group.

scpca.plots.factor_embedding.factor_embedding(adata, model_key, factor=None, basis=None, sign=1.0, cmap='RdBu', colorbar_pos='right', colorbar_width='3%', orientation='vertical', pad=0.1, size=1, ncols=4, width=4, height=3, ax=None)#

Plot factor weights on a given basis such as UMAP/TSNE.

Parameters

  • adata (AnnData) – AnnData object.

  • model_key (str) – Key for the fitted model.

  • factor (Union[int, List[int], None]) – Factor(s) to plot. If None, then all factors are plotted.

  • basis (Optional[str]) – Key for the basis (e.g. UMAP, T-SNE). If basis is None factor embedding tries to retrieve “X_{model_key}_umap”.

  • sign (Union[float, int]) – Sign of the factor. Should be either 1.0 or -1.0.

  • cmap (str) – Colormap for the scatterplot.

  • colorbar_pos (str) – Position of the colorbar.

  • colorbar_width (str) – Width of the colorbar.

  • orientation (str) – Orientation of the colorbar. Should be either “vertical” or “horizontal”.

  • pad (float) – Padding between the plot and colorbar

  • size (float) – Marker/Dot size of the scatterplot.

  • ncols (int) – Number of columns for the subplots.

  • width (int) – Width of each subplot.

  • height (int) – Height of each subplot.

  • ax (Optional[Axes]) – Axes object to plot on. If None, then a new figure is created. Works only if one factor is plotted.

Return type

Axes

Returns

Axes object.

Loadings states#

scpca.plots.loadings_state.loadings_state(adata, model_key, states, factor=None, var_names=[], variable='W', highest=0, lowest=0, sign=1.0, highlight=True, cmap='RdBu', colorbar_pos='right', colorbar_width='3%', orientation='vertical', fontsize=10, pad=0.1, show_corr=False, show_diff=False, show_orthants=False, size_func=<function <lambda>>, sharey=False, sharex=False, ncols=4, width=4, height=3, text_kwargs={}, ax=None)#

Plot the loadings of two states.

Parameters

  • adata (AnnData) – AnnData object containing the scPCA model.

  • model_key (str) – Key to access the model information in adata.uns.

  • states (Union[List[str], Tuple[str, str], str]) – States to compare.

  • factor (Union[int, List[int], None]) – Factor or list of factors to plot. If None, all factors are plotted. Default is None.

  • var_names (Union[List[str], str]) – Variable names to highlight. Default is an empty list.

  • variable (str) – Variable to plot. Default is “W”.

  • highest (int) – Number of genes to plot with largest positve difference between two states. Default is 0.

  • lowest (int) – Number of genes to plot with largest negative difference between two states. Default is 0.

  • sign (Union[int, float]) – Sign of the loadings, either -1 or 1. Default is 1.0.

  • highlight (bool) – If true only var_names and highest/lowest genes are shown in color, all other genes in grey. Default is True.

  • cmap (str) – Colormap to use. Default is “RdBu”.

  • colorbar_pos (str) – Position of the colorbar. Default is “right”.

  • colorbar_width (str) – Width of the colorbar. Default is “3%”.

  • orientation (str) – Orientation of the colorbar. Default is “vertical”.

  • fontsize (int) – Font size for annotations. Default is 10.

  • pad (float) – Padding for the colorbar. Default is 0.1.

  • show_corr (bool) – Whether to show correlation. Default is False.

  • show_diff (bool) – Whether to show log differences. Default is False.

  • show_orthants (bool) – Whether to show orthants.

  • size_func (Callable[[float], float]) – Function to determine the size of the dots. Default is a lambda function that returns an array of 10.0.

  • sharey (bool) – Whether to share the y-axis across subplots. Default is False.

  • sharex (bool) – Whether to share the x-axis across subplots. Default is False.

  • ncols (int) – Number of columns in the subplot grid. Default is 4.

  • width (int) – Width of each subplot in inches. Default is 4.

  • height (int) – Height of each subplot in inches. Default is 3.

  • text_kwargs (Dict[str, Any]) – Additional keyword arguments for text annotations. Default is an empty dictionary.

  • ax (Optional[Axes]) – Matplotlib axes to use for plotting. If None, new subplots will be created. Default is None.

Returns

Matplotlib axes object containing the plotted instances or factors.

Return type

ax

Notes

  • The function sets up the plot environment and calls the internal function _loadings_state to do the actual plotting.

  • If var_names is provided, the arguments highest and lowest are ignored.

Examples

# Example usage loadings_state(adata, ‘model1’, [‘state1’, ‘state2’], factor=0)

scpca.plots.loadings_scatter.loadings_scatter(adata, model_key, states=[], factor=None, var_names=[], variable='W', highlight=True, size_func=<function <lambda>>, sign=1.0, jitter=0.01, fontsize=10, show_labels=0, annotation_linewidth=0.5, connection_linewidth=0.5, connection_alpha=1.0, cmap='RdBu', ncols=4, width=4, height=3, ax=None)#

Create a scatter plot of loading states for a given model and factors.

Parameters

  • adata (AnnData) – AnnData object.

  • model_key (str) – Key to access the model information in adata.uns.

  • states (Union[List[str], str]) – States to plot compare. Can be more than two.

  • factor (Union[int, List[int], None]) – Factor or list of factors to plot. If None, all factors are plotted. Default is None.

  • var_names (Union[List[str], str]) – Variable names to highlight. Default is an empty list.

  • variable (str) – Variable to plot. Default is “W”.

  • highlight (bool) – Whether to highlight specific variables. Default is True.

  • size_func (Callable[[float], float]) – Function to determine the size of the dots. Default is a lambda function that returns 10.0.

  • sign (Union[int, float]) – Sign of the loadings to consider. Default is 1.0.

  • jitter (float) – Amount of jitter to apply to the x-coordinates. Default is 0.01.

  • fontsize (int) – Font size for annotations. Default is 10.

  • show_labels (Union[List[int], int]) – Indices of states for which to show labels. Default is 0.

  • annotation_linewidth (float) – Line width for annotations. Default is 0.5.

  • cmap (str) – Colormap to use. Default is “RdBu”.

  • ncols (int) – Number of columns in the subplot grid. Default is 4.

  • width (int) – Width of each subplot in inches. Default is 4.

  • height (int) – Height of each subplot in inches. Default is 3.

  • ax (Optional[Axes]) – Matplotlib axes to use for plotting. Default is None.

Returns

Matplotlib axes object containing the plotted instances or factors.

Return type

ax

Notes

  • The function sets up the plot environment and calls the internal function _loadings_scatter to do the actual plotting.

Examples

# Example usage loadings_scatter(adata, ‘m0’, [‘state1’, ‘state2’], factor=0)