pl_stacked_violin
Create compact stacked violin plots for visualizing single-cell RNA sequencing data, enabling detailed comparison of gene expression across groups with customizable color maps, scales, and annotations.
Instructions
Plot stacked violin plots. Makes a compact image composed of individual violin plots stacked on top of each other.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| color_map | No | Color map to use for continuous variables. | |
| figsize | No | Figure size. Format is (width, height). | |
| gene_symbols | No | Column name in .var DataFrame that stores gene symbols. | |
| groupby | No | The key of the observation grouping to consider. | |
| jitter | No | Add jitter to the stripplot (only when stripplot is True). | |
| layer | No | Name of the AnnData object layer that wants to be plotted. | |
| legend_fontoutline | No | Line width of the legend font outline in pt. | |
| legend_fontsize | No | Numeric size in pt or string describing the size. | |
| legend_fontweight | No | Legend font weight. A numeric value in range 0-1000 or a string. | bold |
| legend_loc | No | Location of legend, either 'on data', 'right margin' or a valid keyword for the loc parameter. | right margin |
| log | No | Plot on logarithmic axis. | |
| order | No | Order in which to show the categories. | |
| palette | No | Colors to use for plotting categorical annotation groups. | |
| scale | No | The method used to scale the width of each violin. | width |
| size | No | Size of the jitter points. | |
| stripplot | No | Add a stripplot on top of the violin plot. | |
| swap_axes | No | Swap axes such that observations are on the x-axis. | |
| use_raw | No | Use raw attribute of adata if present. | |
| var_names | No | var_names should be a valid subset of adata.var_names. | |
| vcenter | No | The value representing the center of the color scale. | |
| vmax | No | The value representing the upper limit of the color scale. | |
| vmin | No | The value representing the lower limit of the color scale. |
Implementation Reference
- src/scmcp/tool/pl.py:179-216 (handler)Generic handler function that dispatches to sc.pl.stacked_violin (via pl_func mapping) with validated arguments and handles figure saving and logging.def run_pl_func(ads, func, arguments): """ Execute a Scanpy plotting function with the given arguments. Parameters ---------- adata : AnnData Annotated data matrix. func : str Name of the plotting function to execute. arguments : dict Arguments to pass to the plotting function. Returns ------- The result of the plotting function. """ adata = ads.adata_dic[ads.active] if func not in pl_func: raise ValueError(f"Unsupported function: {func}") run_func = pl_func[func] parameters = inspect.signature(run_func).parameters kwargs = {k: arguments.get(k) for k in parameters if k in arguments} if "title" not in parameters: kwargs.pop("title", False) kwargs.pop("return_fig", True) kwargs["show"] = False kwargs["save"] = ".png" try: fig = run_func(adata, **kwargs) fig_path = set_fig_path(func, **kwargs) add_op_log(adata, run_func, kwargs) return fig_path except Exception as e: raise e return fig_path
- src/scmcp/schema/pl.py:646-686 (schema)Pydantic model defining the input schema for the pl_stacked_violin tool, extending BaseStatPlotModel with specific parameters like stripplot, jitter, size, order, scale, swap_axes.class StackedViolinModel(BaseStatPlotModel): """Input schema for the stacked_violin plotting tool.""" stripplot: bool = Field( default=True, description="Add a stripplot on top of the violin plot." ) jitter: Union[float, bool] = Field( default=True, description="Add jitter to the stripplot (only when stripplot is True)." ) size: int = Field( default=1, description="Size of the jitter points.", gt=0 ) order: Optional[List[str]] = Field( default=None, description="Order in which to show the categories." ) scale: Literal['area', 'count', 'width'] = Field( default='width', description="The method used to scale the width of each violin." ) swap_axes: bool = Field( default=False, description="Swap axes such that observations are on the x-axis." ) @field_validator('size') def validate_size(cls, v: int) -> int: """Validate size is positive""" if v <= 0: raise ValueError("size must be a positive integer") return v
- src/scmcp/tool/pl.py:35-39 (registration)Creates the MCP Tool object for pl_stacked_violin with name, description, and input schema.pl_stacked_violin = types.Tool( name="pl_stacked_violin", description="Plot stacked violin plots. Makes a compact image composed of individual violin plots stacked on top of each other.", inputSchema=StackedViolinModel.model_json_schema(), )
- src/scmcp/tool/pl.py:121-138 (registration)Maps the tool name 'pl_stacked_violin' to the underlying scanpy function sc.pl.stacked_violin, used by the handler.pl_func = { "pl_pca": sc.pl.pca, "pl_embedding": sc.pl.embedding, # Add the new embedding function "diffmap": sc.pl.diffmap, "pl_violin": sc.pl.violin, "pl_stacked_violin": sc.pl.stacked_violin, "pl_heatmap": sc.pl.heatmap, "pl_dotplot": sc.pl.dotplot, "pl_matrixplot": sc.pl.matrixplot, "pl_tracksplot": sc.pl.tracksplot, "pl_scatter": sc.pl.scatter, "embedding_density": sc.pl.embedding_density, "rank_genes_groups": sc.pl.rank_genes_groups, "pl_rank_genes_groups_dotplot": sc.pl.rank_genes_groups_dotplot, # Add function mapping "pl_clustermap": sc.pl.clustermap, "pl_highly_variable_genes": sc.pl.highly_variable_genes, "pl_pca_variance_ratio": sc.pl.pca_variance_ratio, }
- src/scmcp/tool/pl.py:141-159 (registration)Registers the pl_stacked_violin Tool object in the pl_tools dictionary for higher-level tool collection.pl_tools = { "pl_pca": pl_pca_tool, "pl_embedding": pl_embedding, # Add the new embedding tool # "diffmap": diffmap, "pl_violin": pl_violin, "pl_stacked_violin": pl_stacked_violin, "pl_heatmap": pl_heatmap, "pl_dotplot": pl_dotplot, "pl_matrixplot": pl_matrixplot, "pl_tracksplot": pl_tracksplot, "pl_scatter": pl_scatter, # "embedding_density": embedding_density, # "spatial": spatial, # "rank_genes_groups": rank_genes_groups, "pl_rank_genes_groups_dotplot": pl_rank_genes_groups_dotplot, # Add tool mapping # "pl_clustermap": pl_clustermap, "pl_highly_variable_genes": pl_highly_variable_genes, "pl_pca_variance_ratio": pl_pca_variance_ratio, }