pl_scatter

Instructions

Implementation Reference

• src/scmcp/tool/pl.py:179-216 (handler)

  Handler function that executes pl_scatter by mapping to sc.pl.scatter, processing arguments, calling the function, saving figure, 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:219-265 (schema)

  Pydantic model defining the input schema for the pl_scatter tool, including fields like x, y, color, alpha, etc., inherited from BaseScatterModel.

  class EnhancedScatterModel(BaseScatterModel):
      """Input schema for the enhanced scatter plotting tool."""
      
      sort_order: bool = Field(
          default=True,
          description="For continuous annotations used as color parameter, plot data points with higher values on top of others."
      )
      
      alpha: Optional[float] = Field(
          default=None,
          description="Alpha value for the plot.",
          ge=0,
          le=1
      )
      
      groups: Optional[Union[str, List[str]]] = Field(
          default=None,
          description="Restrict to a few categories in categorical observation annotation."
      )
      
      components: Optional[Union[str, List[str]]] = Field(
          default=None,
          description="For instance, ['1,2', '2,3']. To plot all available components use components='all'."
      )
      
      projection: Literal['2d', '3d'] = Field(
          default='2d',
          description="Projection of plot."
      )
      
      right_margin: Optional[float] = Field(
          default=None,
          description="Adjust the width of the right margin."
      )
      
      left_margin: Optional[float] = Field(
          default=None,
          description="Adjust the width of the left margin."
      )
      
      @field_validator('alpha')
      def validate_alpha(cls, v: Optional[float]) -> Optional[float]:
          """Validate alpha is between 0 and 1"""
          if v is not None and (v < 0 or v > 1):
              raise ValueError("alpha must be between 0 and 1")
          return v

• src/scmcp/tool/pl.py:67-71 (registration)

  Creates and registers the pl_scatter Tool object with MCP types.Tool, specifying name, description, and input schema.

  pl_scatter = types.Tool(
      name="pl_scatter",
      description="Plot a scatter plot of two variables, Scatter plot along observations or variables axes.",
      inputSchema=EnhancedScatterModel.model_json_schema(),
  )

• src/scmcp/server.py:37-56 (registration)

  In list_tools MCP endpoint, includes pl_tools.values() (containing pl_scatter) when listing available tools.

  if MODULE == "io":
      tools = io_tools.values()
  elif MODULE == "pp":
      tools = pp_tools.values()
  elif MODULE == "tl":
      tools = tl_tools.values()
  elif MODULE == "pl":
      tools = pl_tools.values()
  elif MODULE == "util":
      tools = util_tools.values()
  else:
      tools = [
          *io_tools.values(),
          *pp_tools.values(),
          *tl_tools.values(),
          *pl_tools.values(),
          *util_tools.values(),
          *ccc_tools.values(),
      ]
  return tools

• src/scmcp/tool/pl.py:121-138 (helper)

  Mapping dictionary pl_func that associates 'pl_scatter' with scanpy's sc.pl.scatter function, 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,
  }