Skip to content

Plotting

Mixin for convenient plots/visualization of pAnnData object. Typically a wrapper of functions from the scpviz.plotting module.

PlotMixin

Source code in src/scpviz/pAnnData/plot.py 
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
class PlotMixin:
    def plot_counts(self, classes=None, y='protein_count', **kwargs):
        import seaborn as sns

        df = self.summary # type: ignore #, in base
        if classes is None:
            df=df.reset_index()
            classes = 'index'
        sns.violinplot(data=df, x=classes, y=y, **kwargs)

    def plot_rs(self, figsize=(10, 4)):
        """
        Visualize connectivity in the RS (protein × peptide) matrix.

        Generates side-by-side histograms:

        - Left: Number of peptides mapped to each protein
        - Right: Number of proteins associated with each peptide

        Args:
            figsize (tuple): Size of the matplotlib figure (default: (10, 4)).

        Returns:
            None
        """
        import matplotlib
        import matplotlib.pyplot as plt

        if self.rs is None:
            print("⚠️ No RS matrix to plot.")
            return

        rs = self.rs
        prot_links = rs.getnnz(axis=1)
        pep_links = rs.getnnz(axis=0)

        fig, axes = plt.subplots(1, 2, figsize=figsize)

        axes[0].hist(prot_links, bins=50, color='gray')
        axes[0].set_title("Peptides per Protein")
        axes[0].set_xlabel("Peptide Count")
        axes[0].set_ylabel("Protein Frequency")

        axes[1].hist(pep_links, bins=50, color='gray')
        axes[1].set_title("Proteins per Peptide")
        axes[1].set_xlabel("Protein Count")
        axes[1].set_ylabel("Peptide Frequency")

        plt.tight_layout()
        backend = matplotlib.get_backend()
        if "agg" in backend.lower():
            # Running headless (e.g. pytest, CI)
            plt.close(fig)
        else:
            plt.show(block=False)

    def plot_abundance(self, ax=None, namelist=None, layer="X",
        on="protein", classes=None, return_df=False, order=None,
        palette=None, log=True, facet=None, height=4,
        aspect=0.5, plot_points=True, x_label="gene", kind="auto", **kwargs,):
        """
        Wrapper for `scpviz.plotting.plot_abundance`.

        Plot abundance of proteins or peptides across samples.

        This function visualizes expression values for selected proteins or peptides
        using violin + box + strip plots, or bar plots when the number of replicates
        per group is small. Supports grouping, faceting, and custom ordering.

        Args:
            ax (matplotlib.axes.Axes): Axis to plot on. Ignored if `facet` is used.
            pdata (pAnnData): Input pAnnData object.
            namelist (list of str, optional): List of accessions or gene names to plot.
                If None, all available features are considered.
            layer (str): Data layer to use for abundance values. Default is `'X'`.
            on (str): Data level to plot, either `'protein'` or `'peptide'`.
            classes (str or list of str, optional): `.obs` column(s) to use for grouping
                samples. Determines coloring and grouping structure.
            return_df (bool): If True, returns the DataFrame of replicate and summary values.
            order (dict or list, optional): Custom order of classes. For dictionary input,
                keys are class names and values are the ordered categories.  
                Example: `order = {"condition": ["sc", "kd"]}`.
            palette (list or dict, optional): Color palette mapping groups to colors.
            log (bool): If True, apply log2 transformation to abundance values. Default is True.
            facet (str, optional): `.obs` column to facet by, creating multiple subplots.
            height (float): Height of each facet plot. Default is 4.
            aspect (float): Aspect ratio of each facet plot. Default is 0.5.
            plot_points (bool): Whether to overlay stripplot of individual samples.
            x_label (str): Label for the x-axis, either `'gene'` or `'accession'`.
            kind (str): Type of plot. Options:

                - `'auto'`: Default; uses barplot if groups have ≤ 3 samples, otherwise violin.
                - `'violin'`: Always use violin + box + strip.
                - `'bar'`: Always use barplot.

            **kwargs: Additional keyword arguments passed to seaborn plotting functions.

        Returns:
            ax (matplotlib.axes.Axes or seaborn.FacetGrid):
                The axis or facet grid containing the plot.
            df (pandas.DataFrame, optional): Returned if `return_df=True`.

        !!! example
            Plot abundance of two selected proteins:
                ```python
                pdata.plot_abundance(ax, namelist=['Slc12a2','Septin6'])
                ```            

        """
        return plotting.plot_abundance(ax=ax,pdata=self,namelist=namelist,
            layer=layer,on=on,classes=classes,return_df=return_df,
            order=order,palette=palette,log=log,facet=facet,
            height=height,aspect=aspect,plot_points=plot_points,x_label=x_label,
            kind=kind,**kwargs,
        )

    def plot_abundance_boxgrid(self, namelist=None, ax=None, layer="X", on="protein", classes="Grouping", return_df=False, 
        order=None, plot_type="box", log_scale=False, figsize=(2,2), palette=None, y_min=None, y_max=None,
        label_x=True, show_n=False, global_legend=True, box_kwargs=None, hline_kwargs=None, bar_kwargs=None, bar_error="sd", violin_kwargs=None,
        text_kwargs=None, strip_kwargs=None,):
        """
    Plot abundance values in a one-row panel of boxplots, mean-lines, bars, or violins.

    This function generates a clean horizontal panel, with one subplot per gene,
    using ``plot_type`` to select boxplots (default), mean-lines, bar plots, or
    violin plots. If ``log_scale=True``, abundance values are visualized in log10
    units (with zero or negative values clipped to 0 before transformation). The
    layout is optimized for compact manuscript figure panels and supports custom
    global legends, count annotations, and flexible formatting via keyword
    dictionaries.

    Args:
        namelist (list of str, optional): List of accessions or gene names to plot.
            If None, all available features are considered.
        ax (matplotlib.axes.Axes): Axis to plot on. Generates a new axis if None.
        layer (str): Data layer to use for abundance values. Default is ``"X"``.
        on (str): Data level to plot, either ``"protein"`` or ``"peptide"``.
        classes (str or None): Column in the returned abundance DataFrame to use for
            grouping samples. Defaults to ``"Grouping"``. If None, samples are not
            grouped.
        return_df (bool): If True, returns the DataFrame of replicate and summary values.
        order (list of str, optional): Ordered list to plot by (class order). If None,
            uses the order present in the data.
        plot_type (str): Type of plot, select from one of ``{"box", "line", "bar", "violin"}``.
            Defaults to ``"box"``.
        log_scale (bool): If True, plot log10-transformed abundances on a linear axis.
            If False (default), plot raw abundance values on a linear axis.
        figsize (tuple): Figure size as (width, height) in inches.
        palette (dict or list, optional): Color palette for grouping categories.
            Defaults to ``scplt.get_color("colors", n_classes)``.
        y_min (float or None): Lower y-axis limit in plotting units. If ``log_scale=True``,
            this is in log10 units (e.g., 2 → 10²). If ``log_scale=False``, this is in
            raw abundance units. If None, inferred.
        y_max (float or None): Upper y-axis limit in plotting units. If ``log_scale=True``,
            this is in log10 units (e.g., 6 → 10⁶). If ``log_scale=False``, this is in
            raw abundance units. If None, inferred.
        label_x (bool): Whether to display x tick labels inside each subplot.
        show_n (bool): Whether to annotate each subplot with sample counts.
        global_legend (bool): Whether to display a single global legend.
        box_kwargs (dict, optional): Additional arguments passed to ``sns.boxplot``
            (used when ``plot_type="box"``).
        hline_kwargs (dict, optional): Keyword arguments for mean-lines
            (used when ``plot_type="line"``). Note that ``half_width`` sets the length
            of the mean line.
        bar_kwargs (dict, optional): Additional arguments passed to bar plotting
            (used when ``plot_type="bar"``).
        bar_error (str, optional): Error bar for bar plot. Select from one of
            ``{"sd", "sem", None, <callable>}``, where callable takes a 1D array and
            returns a scalar error. Defaults to ``"sd"``.
        violin_kwargs (dict, optional): Additional arguments passed to ``sns.violinplot``
            (used when ``plot_type="violin"``).
        text_kwargs (dict, optional): Keyword arguments for count labels
            (e.g., fontsize, offset).
        strip_kwargs (dict, optional): Keyword arguments for strip (raw points),
            e.g. ``{"darken_factor": 0.65}``.

    Returns:
        fig (matplotlib.figure.Figure): The generated figure.
        axes (list of matplotlib.axes.Axes): One axis per gene.
        df (pandas.DataFrame, optional): Returned if ``return_df=True``.

        Default customizations for keyword dictionaries:

        Boxplot styling (used when ``plot_type="box"``):
        ```python
        box_kwargs = {
            "showcaps": False,
            "whiskerprops": {"visible": False},
            "showfliers": False,
            "boxprops": {"alpha": 0.6, "linewidth": 1},
            "linewidth": 1,
            "dodge": True,
        }
        ```

        Mean-line styling (used when ``plot_type="line"``):
        ```python
        hline_kwargs = {
            "color": "k",
            "linewidth": 2.0,
            "zorder": 5,
            "half_width": 0.15,
        }
        ```
        Note: ``half_width`` sets the half-length of the mean line.

        Bar styling (used when ``plot_type="bar"``):
        ```python
        bar_kwargs = {
            "alpha": 0.8,
            "edgecolor": "black",
            "linewidth": 0.6,
            "width": 0.3,
            "capsize": 2,
            "zorder": 3,
        }
        ```

        Violin styling (used when ``plot_type="violin"``):
        ```python
        violin_kwargs = {
            "inner": "quartile",
            "dodge": True,
            "zorder": 5,
        }
        ```

        Strip styling (raw points; used for all plot types):
        ```python
        strip_kwargs = {
            "jitter": True,
            "alpha": 0.4,
            "size": 3,
            "zorder": 7,
            "darken_factor": 0.65,
        }
        ```

        Text annotation styling (used when ``show_n=True``):
        ```python
        text_kwargs = {
            "fontsize": 7,
            "color": "black",
            "ha": "center",
            "va": "bottom",
            "zorder": 10,
            "offset": 0.1,
        }
        ```

    !!! example
        Basic usage (grouped boxplots):
        ```python
        fig, axes = pdata.plot_abundance_boxgrid(
            namelist=["Gapdh", "Vcp", "Ahnak"],
            classes="condition",
            plot_type="box",
            figsize=(2,2.5),
        )
        plt.show()
        ```

        Bar plots with error bars:
        ```python
        fig, axes = pdata.plot_abundance_boxgrid(
            namelist=["Gapdh", "Vcp", "Ahnak"],
            classes="condition",
            plot_type="bar",
            bar_error="sd",  # "sd", "sem", None, or callable
            figsize=(2,2.5),
        )
        plt.show()
        ```

        Mean-lines with count annotations:
        ```python
        fig, axes = pdata.plot_abundance_boxgrid(
            namelist=["Gapdh", "Vcp", "Ahnak"],
            classes="condition",
            plot_type="line",
            show_n=True,
            figsize=(2,2.5),
        )
        plt.show()
        ```

        Violin plots (distribution-focused):
        ```python
        fig, axes = pdata.plot_abundance_boxgrid(
            namelist=["Gapdh", "Vcp", "Ahnak"],
            classes="condition",
            plot_type="violin",
            figsize=(2,2.5),
        )
        plt.show()
        ```

        Customizing appearance (palette, order, and styling):
        ```python
        palette = {"Control": "#4C72B0", "Treatment": "#DD8452"}

        fig, axes = pdata.plot_abundance_boxgrid(
            namelist=["Gapdh", "Vcp", "Ahnak"],
            classes="condition",
            order=["Control", "Treatment"],
            palette=palette,
            plot_type="box",
            box_kwargs={"boxprops": {"alpha": 0.45}, "linewidth": 1.2},
            strip_kwargs={"size": 4, "alpha": 0.6},
            y_min=2,
            y_max=10,
            log_scale=True,
            figsize=(2,2.5),
        )
        plt.show()
        ```

        Return the plotting DataFrame for downstream checks:
        ```python
        fig, axes, df = pdata.plot_abundance_boxgrid(
            namelist=["Gapdh", "Vcp"],
            classes="condition",
            plot_type="box",
            return_df=True,
        )

        display(df.head())
        plt.show()
        ```
    """
        return plotting.plot_abundance_boxgrid(pdata=self, namelist=namelist, ax=ax, layer=layer, on=on,
            classes=classes, return_df=return_df, order=order, plot_type=plot_type, log_scale=log_scale,
            figsize=figsize, palette=palette, y_min=y_min, y_max=y_max,
            label_x=label_x, show_n=show_n, global_legend=global_legend,
            box_kwargs=box_kwargs, hline_kwargs=hline_kwargs, bar_kwargs=bar_kwargs, bar_error=bar_error,
            violin_kwargs=violin_kwargs, text_kwargs=text_kwargs, strip_kwargs=strip_kwargs,
        )

plot_abundance 

plot_abundance(ax=None, namelist=None, layer='X', on='protein', classes=None, return_df=False, order=None, palette=None, log=True, facet=None, height=4, aspect=0.5, plot_points=True, x_label='gene', kind='auto', **kwargs)

Wrapper for scpviz.plotting.plot_abundance.

Plot abundance of proteins or peptides across samples.

This function visualizes expression values for selected proteins or peptides using violin + box + strip plots, or bar plots when the number of replicates per group is small. Supports grouping, faceting, and custom ordering.

Parameters:

Name Type Description Default
ax Axes

Axis to plot on. Ignored if facet is used.

 None
pdata pAnnData

Input pAnnData object.

 required
namelist list of str

List of accessions or gene names to plot. If None, all available features are considered.

 None
layer str

Data layer to use for abundance values. Default is 'X'.

 'X'
on str

Data level to plot, either 'protein' or 'peptide'.

 'protein'
classes str or list of str

.obs column(s) to use for grouping samples. Determines coloring and grouping structure.

 None
return_df bool

If True, returns the DataFrame of replicate and summary values.

 False
order dict or list

Custom order of classes. For dictionary input, keys are class names and values are the ordered categories.
Example: order = {"condition": ["sc", "kd"]}.

 None
palette list or dict

Color palette mapping groups to colors.

 None
log bool

If True, apply log2 transformation to abundance values. Default is True.

 True
facet str

.obs column to facet by, creating multiple subplots.

 None
height float

Height of each facet plot. Default is 4.

 4
aspect float

Aspect ratio of each facet plot. Default is 0.5.

 0.5
plot_points bool

Whether to overlay stripplot of individual samples.

 True
x_label str

Label for the x-axis, either 'gene' or 'accession'.

 'gene'
kind str

Type of plot. Options:

  • 'auto': Default; uses barplot if groups have ≤ 3 samples, otherwise violin.
  • 'violin': Always use violin + box + strip.
  • 'bar': Always use barplot.
 'auto'
**kwargs

Additional keyword arguments passed to seaborn plotting functions.

 {}

Returns:

Name Type Description
ax Axes or FacetGrid

The axis or facet grid containing the plot.
df (DataFrame, optional)

Returned if return_df=True.

Example

Plot abundance of two selected proteins: 

pdata.plot_abundance(ax, namelist=['Slc12a2','Septin6'])

Source code in src/scpviz/pAnnData/plot.py 
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
def plot_abundance(self, ax=None, namelist=None, layer="X",
    on="protein", classes=None, return_df=False, order=None,
    palette=None, log=True, facet=None, height=4,
    aspect=0.5, plot_points=True, x_label="gene", kind="auto", **kwargs,):
    """
    Wrapper for `scpviz.plotting.plot_abundance`.

    Plot abundance of proteins or peptides across samples.

    This function visualizes expression values for selected proteins or peptides
    using violin + box + strip plots, or bar plots when the number of replicates
    per group is small. Supports grouping, faceting, and custom ordering.

    Args:
        ax (matplotlib.axes.Axes): Axis to plot on. Ignored if `facet` is used.
        pdata (pAnnData): Input pAnnData object.
        namelist (list of str, optional): List of accessions or gene names to plot.
            If None, all available features are considered.
        layer (str): Data layer to use for abundance values. Default is `'X'`.
        on (str): Data level to plot, either `'protein'` or `'peptide'`.
        classes (str or list of str, optional): `.obs` column(s) to use for grouping
            samples. Determines coloring and grouping structure.
        return_df (bool): If True, returns the DataFrame of replicate and summary values.
        order (dict or list, optional): Custom order of classes. For dictionary input,
            keys are class names and values are the ordered categories.  
            Example: `order = {"condition": ["sc", "kd"]}`.
        palette (list or dict, optional): Color palette mapping groups to colors.
        log (bool): If True, apply log2 transformation to abundance values. Default is True.
        facet (str, optional): `.obs` column to facet by, creating multiple subplots.
        height (float): Height of each facet plot. Default is 4.
        aspect (float): Aspect ratio of each facet plot. Default is 0.5.
        plot_points (bool): Whether to overlay stripplot of individual samples.
        x_label (str): Label for the x-axis, either `'gene'` or `'accession'`.
        kind (str): Type of plot. Options:

            - `'auto'`: Default; uses barplot if groups have ≤ 3 samples, otherwise violin.
            - `'violin'`: Always use violin + box + strip.
            - `'bar'`: Always use barplot.

        **kwargs: Additional keyword arguments passed to seaborn plotting functions.

    Returns:
        ax (matplotlib.axes.Axes or seaborn.FacetGrid):
            The axis or facet grid containing the plot.
        df (pandas.DataFrame, optional): Returned if `return_df=True`.

    !!! example
        Plot abundance of two selected proteins:
            ```python
            pdata.plot_abundance(ax, namelist=['Slc12a2','Septin6'])
            ```            

    """
    return plotting.plot_abundance(ax=ax,pdata=self,namelist=namelist,
        layer=layer,on=on,classes=classes,return_df=return_df,
        order=order,palette=palette,log=log,facet=facet,
        height=height,aspect=aspect,plot_points=plot_points,x_label=x_label,
        kind=kind,**kwargs,
    )

plot_abundance_boxgrid 

plot_abundance_boxgrid(namelist=None, ax=None, layer='X', on='protein', classes='Grouping', return_df=False, order=None, plot_type='box', log_scale=False, figsize=(2, 2), palette=None, y_min=None, y_max=None, label_x=True, show_n=False, global_legend=True, box_kwargs=None, hline_kwargs=None, bar_kwargs=None, bar_error='sd', violin_kwargs=None, text_kwargs=None, strip_kwargs=None)

Plot abundance values in a one-row panel of boxplots, mean-lines, bars, or violins.

This function generates a clean horizontal panel, with one subplot per gene, using plot_type to select boxplots (default), mean-lines, bar plots, or violin plots. If log_scale=True, abundance values are visualized in log10 units (with zero or negative values clipped to 0 before transformation). The layout is optimized for compact manuscript figure panels and supports custom global legends, count annotations, and flexible formatting via keyword dictionaries.

Parameters:

Name Type Description Default
namelist list of str

List of accessions or gene names to plot. If None, all available features are considered.

 None
ax Axes

Axis to plot on. Generates a new axis if None.

 None
layer str

Data layer to use for abundance values. Default is "X".

 'X'
on str

Data level to plot, either "protein" or "peptide".

 'protein'
classes str or None

Column in the returned abundance DataFrame to use for grouping samples. Defaults to "Grouping". If None, samples are not grouped.

 'Grouping'
return_df bool

If True, returns the DataFrame of replicate and summary values.

 False
order list of str

Ordered list to plot by (class order). If None, uses the order present in the data.

 None
plot_type str

Type of plot, select from one of {"box", "line", "bar", "violin"}. Defaults to "box".

 'box'
log_scale bool

If True, plot log10-transformed abundances on a linear axis. If False (default), plot raw abundance values on a linear axis.

 False
figsize tuple

Figure size as (width, height) in inches.

 (2, 2)
palette dict or list

Color palette for grouping categories. Defaults to scplt.get_color("colors", n_classes).

 None
y_min float or None

Lower y-axis limit in plotting units. If log_scale=True, this is in log10 units (e.g., 2 → 10²). If log_scale=False, this is in raw abundance units. If None, inferred.

 None
y_max float or None

Upper y-axis limit in plotting units. If log_scale=True, this is in log10 units (e.g., 6 → 10⁶). If log_scale=False, this is in raw abundance units. If None, inferred.

 None
label_x bool

Whether to display x tick labels inside each subplot.

 True
show_n bool

Whether to annotate each subplot with sample counts.

 False
global_legend bool

Whether to display a single global legend.

 True
box_kwargs dict

Additional arguments passed to sns.boxplot (used when plot_type="box").

 None
hline_kwargs dict

Keyword arguments for mean-lines (used when plot_type="line"). Note that half_width sets the length of the mean line.

 None
bar_kwargs dict

Additional arguments passed to bar plotting (used when plot_type="bar").

 None
bar_error str

Error bar for bar plot. Select from one of {"sd", "sem", None, <callable>}, where callable takes a 1D array and returns a scalar error. Defaults to "sd".

 'sd'
violin_kwargs dict

Additional arguments passed to sns.violinplot (used when plot_type="violin").

 None
text_kwargs dict

Keyword arguments for count labels (e.g., fontsize, offset).

 None
strip_kwargs dict

Keyword arguments for strip (raw points), e.g. {"darken_factor": 0.65}.

 None

Returns:

Name Type Description
fig Figure

The generated figure.
axes list of matplotlib.axes.Axes

One axis per gene.
df (DataFrame, optional)

Returned if return_df=True.

Default customizations for keyword dictionaries:

Boxplot styling (used when plot_type="box"):

```python

box_kwargs = { "showcaps": False, "whiskerprops": {"visible": False}, "showfliers": False, "boxprops": {"alpha": 0.6, "linewidth": 1}, "linewidth": 1, "dodge": True,

}

```

Mean-line styling (used when plot_type="line"):

```python

hline_kwargs = { "color": "k", "linewidth": 2.0, "zorder": 5, "half_width": 0.15,

}

```
Note

half_width sets the half-length of the mean line.

Bar styling (used when plot_type="bar"):

```python

bar_kwargs = { "alpha": 0.8, "edgecolor": "black", "linewidth": 0.6, "width": 0.3, "capsize": 2, "zorder": 3,

}

```

Violin styling (used when plot_type="violin"):

```python

violin_kwargs = { "inner": "quartile", "dodge": True, "zorder": 5,

}

```

Strip styling (raw points; used for all plot types):

```python

strip_kwargs = { "jitter": True, "alpha": 0.4, "size": 3, "zorder": 7, "darken_factor": 0.65,

}

```

Text annotation styling (used when show_n=True):

```python

text_kwargs = { "fontsize": 7, "color": "black", "ha": "center", "va": "bottom", "zorder": 10, "offset": 0.1,

}

```

Example

Basic usage (grouped boxplots): 

fig, axes = pdata.plot_abundance_boxgrid(
    namelist=["Gapdh", "Vcp", "Ahnak"],
    classes="condition",
    plot_type="box",
    figsize=(2,2.5),
)
plt.show()

Bar plots with error bars: 

fig, axes = pdata.plot_abundance_boxgrid(
    namelist=["Gapdh", "Vcp", "Ahnak"],
    classes="condition",
    plot_type="bar",
    bar_error="sd",  # "sd", "sem", None, or callable
    figsize=(2,2.5),
)
plt.show()

Mean-lines with count annotations: 

fig, axes = pdata.plot_abundance_boxgrid(
    namelist=["Gapdh", "Vcp", "Ahnak"],
    classes="condition",
    plot_type="line",
    show_n=True,
    figsize=(2,2.5),
)
plt.show()

Violin plots (distribution-focused): 

fig, axes = pdata.plot_abundance_boxgrid(
    namelist=["Gapdh", "Vcp", "Ahnak"],
    classes="condition",
    plot_type="violin",
    figsize=(2,2.5),
)
plt.show()

Customizing appearance (palette, order, and styling): 

palette = {"Control": "#4C72B0", "Treatment": "#DD8452"}

fig, axes = pdata.plot_abundance_boxgrid(
    namelist=["Gapdh", "Vcp", "Ahnak"],
    classes="condition",
    order=["Control", "Treatment"],
    palette=palette,
    plot_type="box",
    box_kwargs={"boxprops": {"alpha": 0.45}, "linewidth": 1.2},
    strip_kwargs={"size": 4, "alpha": 0.6},
    y_min=2,
    y_max=10,
    log_scale=True,
    figsize=(2,2.5),
)
plt.show()

Return the plotting DataFrame for downstream checks: 

fig, axes, df = pdata.plot_abundance_boxgrid(
    namelist=["Gapdh", "Vcp"],
    classes="condition",
    plot_type="box",
    return_df=True,
)

display(df.head())
plt.show()

Source code in src/scpviz/pAnnData/plot.py 
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
def plot_abundance_boxgrid(self, namelist=None, ax=None, layer="X", on="protein", classes="Grouping", return_df=False, 
    order=None, plot_type="box", log_scale=False, figsize=(2,2), palette=None, y_min=None, y_max=None,
    label_x=True, show_n=False, global_legend=True, box_kwargs=None, hline_kwargs=None, bar_kwargs=None, bar_error="sd", violin_kwargs=None,
    text_kwargs=None, strip_kwargs=None,):
    """
Plot abundance values in a one-row panel of boxplots, mean-lines, bars, or violins.

This function generates a clean horizontal panel, with one subplot per gene,
using ``plot_type`` to select boxplots (default), mean-lines, bar plots, or
violin plots. If ``log_scale=True``, abundance values are visualized in log10
units (with zero or negative values clipped to 0 before transformation). The
layout is optimized for compact manuscript figure panels and supports custom
global legends, count annotations, and flexible formatting via keyword
dictionaries.

Args:
    namelist (list of str, optional): List of accessions or gene names to plot.
        If None, all available features are considered.
    ax (matplotlib.axes.Axes): Axis to plot on. Generates a new axis if None.
    layer (str): Data layer to use for abundance values. Default is ``"X"``.
    on (str): Data level to plot, either ``"protein"`` or ``"peptide"``.
    classes (str or None): Column in the returned abundance DataFrame to use for
        grouping samples. Defaults to ``"Grouping"``. If None, samples are not
        grouped.
    return_df (bool): If True, returns the DataFrame of replicate and summary values.
    order (list of str, optional): Ordered list to plot by (class order). If None,
        uses the order present in the data.
    plot_type (str): Type of plot, select from one of ``{"box", "line", "bar", "violin"}``.
        Defaults to ``"box"``.
    log_scale (bool): If True, plot log10-transformed abundances on a linear axis.
        If False (default), plot raw abundance values on a linear axis.
    figsize (tuple): Figure size as (width, height) in inches.
    palette (dict or list, optional): Color palette for grouping categories.
        Defaults to ``scplt.get_color("colors", n_classes)``.
    y_min (float or None): Lower y-axis limit in plotting units. If ``log_scale=True``,
        this is in log10 units (e.g., 2 → 10²). If ``log_scale=False``, this is in
        raw abundance units. If None, inferred.
    y_max (float or None): Upper y-axis limit in plotting units. If ``log_scale=True``,
        this is in log10 units (e.g., 6 → 10⁶). If ``log_scale=False``, this is in
        raw abundance units. If None, inferred.
    label_x (bool): Whether to display x tick labels inside each subplot.
    show_n (bool): Whether to annotate each subplot with sample counts.
    global_legend (bool): Whether to display a single global legend.
    box_kwargs (dict, optional): Additional arguments passed to ``sns.boxplot``
        (used when ``plot_type="box"``).
    hline_kwargs (dict, optional): Keyword arguments for mean-lines
        (used when ``plot_type="line"``). Note that ``half_width`` sets the length
        of the mean line.
    bar_kwargs (dict, optional): Additional arguments passed to bar plotting
        (used when ``plot_type="bar"``).
    bar_error (str, optional): Error bar for bar plot. Select from one of
        ``{"sd", "sem", None, <callable>}``, where callable takes a 1D array and
        returns a scalar error. Defaults to ``"sd"``.
    violin_kwargs (dict, optional): Additional arguments passed to ``sns.violinplot``
        (used when ``plot_type="violin"``).
    text_kwargs (dict, optional): Keyword arguments for count labels
        (e.g., fontsize, offset).
    strip_kwargs (dict, optional): Keyword arguments for strip (raw points),
        e.g. ``{"darken_factor": 0.65}``.

Returns:
    fig (matplotlib.figure.Figure): The generated figure.
    axes (list of matplotlib.axes.Axes): One axis per gene.
    df (pandas.DataFrame, optional): Returned if ``return_df=True``.

    Default customizations for keyword dictionaries:

    Boxplot styling (used when ``plot_type="box"``):
    ```python
    box_kwargs = {
        "showcaps": False,
        "whiskerprops": {"visible": False},
        "showfliers": False,
        "boxprops": {"alpha": 0.6, "linewidth": 1},
        "linewidth": 1,
        "dodge": True,
    }
    ```

    Mean-line styling (used when ``plot_type="line"``):
    ```python
    hline_kwargs = {
        "color": "k",
        "linewidth": 2.0,
        "zorder": 5,
        "half_width": 0.15,
    }
    ```
    Note: ``half_width`` sets the half-length of the mean line.

    Bar styling (used when ``plot_type="bar"``):
    ```python
    bar_kwargs = {
        "alpha": 0.8,
        "edgecolor": "black",
        "linewidth": 0.6,
        "width": 0.3,
        "capsize": 2,
        "zorder": 3,
    }
    ```

    Violin styling (used when ``plot_type="violin"``):
    ```python
    violin_kwargs = {
        "inner": "quartile",
        "dodge": True,
        "zorder": 5,
    }
    ```

    Strip styling (raw points; used for all plot types):
    ```python
    strip_kwargs = {
        "jitter": True,
        "alpha": 0.4,
        "size": 3,
        "zorder": 7,
        "darken_factor": 0.65,
    }
    ```

    Text annotation styling (used when ``show_n=True``):
    ```python
    text_kwargs = {
        "fontsize": 7,
        "color": "black",
        "ha": "center",
        "va": "bottom",
        "zorder": 10,
        "offset": 0.1,
    }
    ```

!!! example
    Basic usage (grouped boxplots):
    ```python
    fig, axes = pdata.plot_abundance_boxgrid(
        namelist=["Gapdh", "Vcp", "Ahnak"],
        classes="condition",
        plot_type="box",
        figsize=(2,2.5),
    )
    plt.show()
    ```

    Bar plots with error bars:
    ```python
    fig, axes = pdata.plot_abundance_boxgrid(
        namelist=["Gapdh", "Vcp", "Ahnak"],
        classes="condition",
        plot_type="bar",
        bar_error="sd",  # "sd", "sem", None, or callable
        figsize=(2,2.5),
    )
    plt.show()
    ```

    Mean-lines with count annotations:
    ```python
    fig, axes = pdata.plot_abundance_boxgrid(
        namelist=["Gapdh", "Vcp", "Ahnak"],
        classes="condition",
        plot_type="line",
        show_n=True,
        figsize=(2,2.5),
    )
    plt.show()
    ```

    Violin plots (distribution-focused):
    ```python
    fig, axes = pdata.plot_abundance_boxgrid(
        namelist=["Gapdh", "Vcp", "Ahnak"],
        classes="condition",
        plot_type="violin",
        figsize=(2,2.5),
    )
    plt.show()
    ```

    Customizing appearance (palette, order, and styling):
    ```python
    palette = {"Control": "#4C72B0", "Treatment": "#DD8452"}

    fig, axes = pdata.plot_abundance_boxgrid(
        namelist=["Gapdh", "Vcp", "Ahnak"],
        classes="condition",
        order=["Control", "Treatment"],
        palette=palette,
        plot_type="box",
        box_kwargs={"boxprops": {"alpha": 0.45}, "linewidth": 1.2},
        strip_kwargs={"size": 4, "alpha": 0.6},
        y_min=2,
        y_max=10,
        log_scale=True,
        figsize=(2,2.5),
    )
    plt.show()
    ```

    Return the plotting DataFrame for downstream checks:
    ```python
    fig, axes, df = pdata.plot_abundance_boxgrid(
        namelist=["Gapdh", "Vcp"],
        classes="condition",
        plot_type="box",
        return_df=True,
    )

    display(df.head())
    plt.show()
    ```
"""
    return plotting.plot_abundance_boxgrid(pdata=self, namelist=namelist, ax=ax, layer=layer, on=on,
        classes=classes, return_df=return_df, order=order, plot_type=plot_type, log_scale=log_scale,
        figsize=figsize, palette=palette, y_min=y_min, y_max=y_max,
        label_x=label_x, show_n=show_n, global_legend=global_legend,
        box_kwargs=box_kwargs, hline_kwargs=hline_kwargs, bar_kwargs=bar_kwargs, bar_error=bar_error,
        violin_kwargs=violin_kwargs, text_kwargs=text_kwargs, strip_kwargs=strip_kwargs,
    )

plot_rs 

plot_rs(figsize=(10, 4))

Visualize connectivity in the RS (protein × peptide) matrix.

Generates side-by-side histograms:

  • Left: Number of peptides mapped to each protein
  • Right: Number of proteins associated with each peptide

Parameters:

Name Type Description Default
figsize tuple

Size of the matplotlib figure (default: (10, 4)).

 (10, 4)

Returns:

Type Description

None
Source code in src/scpviz/pAnnData/plot.py 
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
def plot_rs(self, figsize=(10, 4)):
    """
    Visualize connectivity in the RS (protein × peptide) matrix.

    Generates side-by-side histograms:

    - Left: Number of peptides mapped to each protein
    - Right: Number of proteins associated with each peptide

    Args:
        figsize (tuple): Size of the matplotlib figure (default: (10, 4)).

    Returns:
        None
    """
    import matplotlib
    import matplotlib.pyplot as plt

    if self.rs is None:
        print("⚠️ No RS matrix to plot.")
        return

    rs = self.rs
    prot_links = rs.getnnz(axis=1)
    pep_links = rs.getnnz(axis=0)

    fig, axes = plt.subplots(1, 2, figsize=figsize)

    axes[0].hist(prot_links, bins=50, color='gray')
    axes[0].set_title("Peptides per Protein")
    axes[0].set_xlabel("Peptide Count")
    axes[0].set_ylabel("Protein Frequency")

    axes[1].hist(pep_links, bins=50, color='gray')
    axes[1].set_title("Proteins per Peptide")
    axes[1].set_xlabel("Protein Count")
    axes[1].set_ylabel("Peptide Frequency")

    plt.tight_layout()
    backend = matplotlib.get_backend()
    if "agg" in backend.lower():
        # Running headless (e.g. pytest, CI)
        plt.close(fig)
    else:
        plt.show(block=False)