pl_violin
Generate violin plots for visualizing data distribution, with options for grouping, scaling, and customizing color maps, legend placement, and axis labels.
Instructions
Plot violin plot of one or more variables.
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). | |
| keys | Yes | Keys for accessing variables of .var_names or fields of .obs. | |
| 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. | |
| multi_panel | No | Display keys in multiple panels also when groupby is not None. | |
| order | No | Order in which to show the categories. | |
| palette | No | Colors to use for plotting categorical annotation groups. | |
| rotation | No | Rotation of xtick labels. | |
| 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. | |
| 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. | |
| xlabel | No | Label of the x axis. Defaults to groupby if rotation is None, otherwise, no label is shown. | |
| ylabel | No | Label of the y axis. |
Implementation Reference
- src/scmcp/tool/pl.py:179-217 (handler)Generic handler function that executes the tool logic for 'pl_violin' by retrieving sc.pl.violin from pl_func mapping, validating parameters, calling it on the active AnnData, saving the figure, and logging the operation.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:426-478 (schema)Pydantic model defining the input schema and validation for the 'pl_violin' tool parameters.class ViolinModel(BaseStatPlotModel): """Input schema for the violin plotting tool.""" keys: Union[str, List[str]] = Field( ..., # Required field description="Keys for accessing variables of .var_names or fields of .obs." ) 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 ) scale: Literal['area', 'count', 'width'] = Field( default='width', description="The method used to scale the width of each violin." ) order: Optional[List[str]] = Field( default=None, description="Order in which to show the categories." ) multi_panel: Optional[bool] = Field( default=None, description="Display keys in multiple panels also when groupby is not None." ) xlabel: str = Field( default='', description="Label of the x axis. Defaults to groupby if rotation is None, otherwise, no label is shown." ) ylabel: Optional[Union[str, List[str]]] = Field( default=None, description="Label of the y axis." ) rotation: Optional[float] = Field( default=None, description="Rotation of xtick labels." ) @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:29-33 (registration)Registers the 'pl_violin' tool with MCP types.Tool, specifying name, description, and linking to ViolinModel schema.pl_violin = types.Tool( name="pl_violin", description="Plot violin plot of one or more variables.", inputSchema=ViolinModel.model_json_schema(), )
- src/scmcp/tool/pl.py:121-138 (registration)Maps the 'pl_violin' tool name to the underlying scanpy function sc.pl.violin for execution.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_violin tool object in the pl_tools dictionary for lookup during tool invocation.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, }