pl_rank_genes_groups_dotplot

Instructions

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