pl_embedding
Generate scatter plots for visualizing single-cell RNA sequencing embeddings like UMAP or t-SNE to analyze data patterns and clusters.
Instructions
Scatter plot for user specified embedding basis (e.g. umap, tsne, etc).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| figsize | No | Figure size. Format is (width, height). | |
| color_map | No | Color map to use for continuous variables. | |
| palette | No | Colors to use for plotting categorical annotation groups. | |
| vmax | No | The value representing the upper limit of the color scale. | |
| vmin | No | The value representing the lower limit of the color scale. | |
| vcenter | No | The value representing the center of the color scale. | |
| 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 |
| legend_fontoutline | No | Line width of the legend font outline in pt. | |
| color | No | Keys for annotations of observations/cells or variables/genes. | |
| gene_symbols | No | Column name in .var DataFrame that stores gene symbols. | |
| use_raw | No | Use .raw attribute of adata for coloring with gene expression. | |
| sort_order | No | For continuous annotations used as color parameter, plot data points with higher values on top of others. | |
| edges | No | Show edges between nodes. | |
| edges_width | No | Width of edges. | |
| edges_color | No | Color of edges. | grey |
| neighbors_key | No | Where to look for neighbors connectivities. | |
| arrows | No | Show arrows. | |
| groups | No | Restrict to a few categories in categorical observation annotation. | |
| components | No | For instance, ['1,2', '2,3']. To plot all available components use components='all'. | |
| dimensions | No | 0-indexed dimensions of the embedding to plot as integers. E.g. [(0, 1), (1, 2)]. | |
| layer | No | Name of the AnnData object layer that wants to be plotted. | |
| projection | No | Projection of plot. | 2d |
| size | No | Point size. If None, is automatically computed. | |
| frameon | No | Draw a frame around the scatter plot. | |
| add_outline | No | Add outline to scatter plot points. | |
| ncols | No | Number of columns for multiple plots. | |
| marker | No | Matplotlib marker style for points. | . |
| basis | Yes | Name of the obsm basis to use. | |
| mask_obs | No | A boolean array or a string mask expression to subset observations. | |
| arrows_kwds | No | Passed to matplotlib's quiver function for drawing arrows. | |
| scale_factor | No | Scale factor for the plot. | |
| cmap | No | Color map to use for continuous variables. Overrides color_map. | |
| na_color | No | Color to use for null or masked values. | lightgray |
| na_in_legend | No | Whether to include null values in the legend. | |
| outline_width | No | Width of the outline for highlighted points. | |
| outline_color | No | Color of the outline for highlighted points. | |
| colorbar_loc | No | Location of the colorbar. | right |
| hspace | No | Height space between panels. | |
| wspace | No | Width space between panels. | |
| title | No | Title for the plot. |
Implementation Reference
- src/scmcp/tool/pl.py:179-216 (handler)The run_pl_func executes the tool logic for pl_embedding by dispatching to sc.pl.embedding (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:874-942 (schema)Pydantic model defining the input schema for the pl_embedding tool, including basis, color, projection, and other scanpy.pl.embedding parameters.class EmbeddingModel(BaseEmbeddingModel): """Input schema for the embedding plotting tool.""" basis: str = Field( ..., # Required field description="Name of the obsm basis to use." ) mask_obs: Optional[str] = Field( default=None, description="A boolean array or a string mask expression to subset observations." ) arrows_kwds: Optional[dict] = Field( default=None, description="Passed to matplotlib's quiver function for drawing arrows." ) scale_factor: Optional[float] = Field( default=None, description="Scale factor for the plot." ) cmap: Optional[str] = Field( default=None, description="Color map to use for continuous variables. Overrides color_map." ) na_color: str = Field( default="lightgray", description="Color to use for null or masked values." ) na_in_legend: bool = Field( default=True, description="Whether to include null values in the legend." ) outline_width: Tuple[float, float] = Field( default=(0.3, 0.05), description="Width of the outline for highlighted points." ) outline_color: Tuple[str, str] = Field( default=("black", "white"), description="Color of the outline for highlighted points." ) colorbar_loc: Optional[str] = Field( default="right", description="Location of the colorbar." ) hspace: float = Field( default=0.25, description="Height space between panels." ) wspace: Optional[float] = Field( default=None, description="Width space between panels." ) title: Optional[Union[str, List[str]]] = Field( default=None, description="Title for the plot." )
- src/scmcp/tool/pl.py:73-77 (registration)Creates the MCP Tool object for pl_embedding with name, description, and input schema.pl_embedding = types.Tool( name="pl_embedding", description="Scatter plot for user specified embedding basis (e.g. umap, tsne, etc).", inputSchema=EmbeddingModel.model_json_schema(), )
- src/scmcp/tool/pl.py:141-159 (registration)Adds the pl_embedding tool to the pl_tools dictionary, which is used by the server to list and dispatch tools.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, }
- src/scmcp/tool/pl.py:121-138 (helper)Maps 'pl_embedding' to the underlying scanpy function sc.pl.embedding 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, }