pl_rank_genes_groups_dotplot
Visualize differentially expressed genes across cell groups using dot plots to identify expression patterns and statistical significance.
Instructions
Plot ranking of genes(DEGs) using dotplot visualization. Defualt plot DEGs for rank_genes_groups tool
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. | |
| var_names | No | Genes to plot. Sometimes is useful to pass a specific list of var names (e.g. genes) to check their fold changes or p-values | |
| groupby | Yes | The key of the observation grouping to consider. | |
| use_raw | No | Use raw attribute of adata if present. | |
| log | No | Plot on logarithmic axis. | |
| dendrogram | No | If True or a valid dendrogram key, a dendrogram based on the hierarchical clustering between the groupby categories is added. | |
| gene_symbols | No | Column name in .var DataFrame that stores gene symbols. | |
| var_group_positions | No | Use this parameter to highlight groups of var_names with brackets or color blocks between the given start and end positions. | |
| var_group_labels | No | Labels for each of the var_group_positions that want to be highlighted. | |
| layer | No | Name of the AnnData object layer that wants to be plotted. | |
| groups | No | The groups for which to show the gene ranking. | |
| n_genes | No | Number of genes to show. This can be a negative number to show down regulated genes. Ignored if var_names is passed. | |
| values_to_plot | No | Instead of the mean gene value, plot the values computed by sc.rank_genes_groups. | |
| min_logfoldchange | No | Value to filter genes in groups if their logfoldchange is less than the min_logfoldchange. | |
| key | No | Key used to store the ranking results in adata.uns. |
Implementation Reference
- src/scmcp/schema/pl.py:839-871 (schema)Pydantic model (RankGenesGroupsDotplotModel) defining the input schema, fields, and validation for the pl_rank_genes_groups_dotplot tool.class RankGenesGroupsDotplotModel(BaseMatrixModel): """Input schema for the rank_genes_groups_dotplot plotting tool.""" groups: Optional[Union[str, List[str]]] = Field( default=None, description="The groups for which to show the gene ranking." ) n_genes: Optional[int] = Field( default=None, description="Number of genes to show. This can be a negative number to show down regulated genes. Ignored if var_names is passed." ) values_to_plot: Optional[Literal['scores', 'logfoldchanges', 'pvals', 'pvals_adj', 'log10_pvals', 'log10_pvals_adj']] = Field( default=None, description="Instead of the mean gene value, plot the values computed by sc.rank_genes_groups." ) min_logfoldchange: Optional[float] = Field( default=None, description="Value to filter genes in groups if their logfoldchange is less than the min_logfoldchange." ) key: Optional[str] = Field( default=None, description="Key used to store the ranking results in adata.uns." ) var_names: Union[List[str], Mapping[str, List[str]]] = Field( default=None, description="Genes to plot. Sometimes is useful to pass a specific list of var names (e.g. genes) to check their fold changes or p-values" ) @field_validator('n_genes') def validate_n_genes(cls, v: Optional[int]) -> Optional[int]: """Validate n_genes""" # n_genes can be positive or negative, so no validation needed return v
- src/scmcp/tool/pl.py:93-97 (registration)Definition and registration of the pl_rank_genes_groups_dotplot Tool object with name, description, and input schema.pl_rank_genes_groups_dotplot = types.Tool( name="pl_rank_genes_groups_dotplot", description="Plot ranking of genes(DEGs) using dotplot visualization. Defualt plot DEGs for rank_genes_groups tool", inputSchema=RankGenesGroupsDotplotModel.model_json_schema(), )
- src/scmcp/tool/pl.py:121-138 (registration)Mapping (pl_func dict) of tool name 'pl_rank_genes_groups_dotplot' to the underlying Scanpy function sc.pl.rank_genes_groups_dotplot.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)Addition of the tool object to pl_tools dict, which is exposed via server.list_tools() for MCP tool listing.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:179-217 (handler)Core handler function for all pl_ tools, including pl_rank_genes_groups_dotplot: dispatches to mapped Scanpy function, prepares arguments, executes plot, saves figure via set_fig_path, logs 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