barplot

barplot ¶

barplot(
    data,
    xAxis: str = "imageid",
    yAxis: str = "phenotype",
    groupBy: Optional[str] = None,
    subsetGroupBy: Optional[List[str]] = None,
    orderGroupBy: Optional[List[str]] = None,
    subsetXAxis: Optional[List[str]] = None,
    subsetYAxis: Optional[List[str]] = None,
    orderXAxis: Optional[List[str]] = None,
    orderYAxis: Optional[List[str]] = None,
    method: str = "percent",
    plottingMode: str = "standard",
    figSize: Optional[Tuple[float, float]] = None,
    fontSize: Optional[int] = None,
    color: Optional[Union[str, List[str], dict]] = None,
    palette: Optional[str] = None,
    alpha: float = 1.0,
    barWidth: Optional[float] = None,
    groupGap: float = 1.0,
    streamData: bool = False,
    maxWorkers: Optional[int] = None,
    verbose: bool = False,
    outputDir: Optional[str] = None,
    show: bool = True,
    returnData: bool = False,
    returnFig: bool = False,
    dpi: int = 300,
    transparent: bool = False,
    watermark: bool = True,
    matplotlib_bbox_to_anchor=(1, 1.02),
    matplotlib_legend_loc=2,
    ax: Optional[Axes] = None,
    sdataTable: Optional[str] = None,
    **kwargs
)

Stacked or grouped composition bars.

Cross-tabulates yAxis (usually the cell type) within xAxis (usually the image), optionally nested inside groupBy, and draws the result as stacked bars. method='percent' normalises each bar to 100%, which is what you want when images differ in cell count; method='absolute' keeps raw counts.

Only obs is needed, so this is one of the few plotting functions that supports streamData=True — it reads the two or three columns it needs from the .h5ad without loading the expression matrix.

outputDir is interpreted two ways: a string with a file suffix (.pdf, .html, …) that is not an existing directory is treated as the full output path; anything else is treated as a directory and a default file name is appended based on the plotting mode.

Parameters:

Name	Type	Description	Default
`data`	`(AnnData \| SpatialData \| str, required)`	The cell table. An `AnnData`, a path to an `.h5ad` file, a `SpatialData` object, or a path to a `.zarr` SpatialData store.	required
`xAxis`	`str`	Column in `obs` that supplies the bars.	`'imageid'`
`yAxis`	`str`	Column in `obs` that supplies the segments within each bar.	`'phenotype'`
`groupBy`	`str`	Extra `obs` column used to group the bars — e.g. treatment arm, with images inside it.	`None`
`subsetGroupBy`	`list`	Keep only these `groupBy` values.	`None`
`orderGroupBy`	`list`	Explicit order for the `groupBy` values.	`None`
`subsetXAxis`	`list`	Keep only these `xAxis` values.	`None`
`subsetYAxis`	`list`	Keep only these `yAxis` values.	`None`
`orderXAxis`	`list`	Explicit bar order.	`None`
`orderYAxis`	`list`	Explicit segment order within each bar.	`None`
`method`	`str`	`'percent'` normalises each bar to 100%; `'absolute'` plots raw counts.	`'percent'`
`plottingMode`	`str`	`'standard'` for Matplotlib, `'interactive'` for a Plotly figure saved as HTML.	`'standard'`
`figSize`	`tuple`	Figure size in inches.	`None`
`fontSize`	`int`	Tick and legend font size.	`None`
`color`	`str \| list \| dict`	Segment colours: one colour for all, a list in segment order, or a `{segment: colour}` mapping.	`None`
`palette`	`str`	Named colormap used to generate colours when `color` is not given.	`None`
`alpha`	`float`	Bar opacity.	`1.0`
`barWidth`	`float`	Width of each bar.	`None`
`groupGap`	`float`	Extra spacing between `groupBy` groups.	`1.0`
`streamData`	`bool`	Read the required `obs` columns straight from an `.h5ad` path with CAP-AnnData instead of loading the whole object. Needs `data` to be a path.	`False`
`maxWorkers`	`int`	Cap on parallel workers. Defaults to `max(1, cpu_count() - 1)`.	`None`
`verbose`	`bool`	Print progress messages.	`False`
`outputDir`	`str`	Output directory, or a full output file path when it carries a suffix. See above.	`None`
`show`	`bool`	Display the figure before returning.	`True`
`returnData`	`bool`	Return the pivot table behind the plot instead of drawing it.	`False`
`returnFig`	`bool`	Return the figure object.	`False`
`dpi`	`int`	Resolution of the saved figure.	`300`
`transparent`	`bool`	Save with a transparent background.	`False`
`watermark`	`bool`	Draw the scimappro watermark on the figure.	`True`
`matplotlib_bbox_to_anchor`	`tuple`	Legend anchor, passed to Matplotlib.	`(1, 1.02)`
`matplotlib_legend_loc`	`int \| str`	Legend location, passed to Matplotlib.	`2`
`ax`	`Axes`	Draw onto this axis instead of creating a figure.	`None`
`sdataTable`	`str`	Which `SpatialData` table to read.	`None`
`**kwargs`	`dict`	Extra options forwarded to the plotting backend.	`{}`

Returns:

Name	Type	Description
`result`	`None \| DataFrame \| Figure`	`None` by default and always in streaming mode; the pivot table with `returnData=True`; the figure with `returnFig=True`.

Example

# Cell-type composition of every image, as percentages.
sp.pl.barplot(adata, xAxis="imageid", yAxis="phenotype")

# Absolute counts, images grouped by treatment, saved as one file.
sp.pl.barplot(
    adata,
    xAxis="imageid",
    yAxis="phenotype",
    groupBy="treatment",
    method="absolute",
    outputDir="figures/composition.pdf",
    show=False,
)

# An interactive Plotly version.
sp.pl.barplot(adata, plottingMode="interactive", outputDir="figures")

# Straight off disk, without loading the matrix.
sp.pl.barplot("big.h5ad", streamData=True, outputDir="figures")