ccc_circle_plot

Instructions

Implementation Reference

• src/scmcp/tool/ccc.py:64-72 (handler)

  Handler function that implements the ccc_circle_plot tool logic: filters results by specificity cutoff, prepares parameters, and calls liana's circle_plot.

  def plot_circleplot(adata, **kwargs):
      pval = kwargs.pop("specificity_cutoff", 0.05)
      res_key = kwargs.get("uns_key", "liana_res")
      pval_col = adata.uns[res_key].columns[-1]
      kwargs["filter_fun"] = lambda x: x[pval_col] <= pval
      parameters = inspect.signature( li.pl.circle_plot).parameters
      kwargs = {k: kwargs.get(k) for k in parameters if k in kwargs}    
      ax = li.pl.circle_plot(adata, **kwargs)
      return ax

• src/scmcp/schema/ccc.py:181-313 (schema)

  Pydantic model defining the input schema and parameters for the ccc_circle_plot tool.

  class CirclePlotModel(JSONParsingModel):
      """Input schema for LIANA's circle_plot visualization for cell-cell communication networks."""
      
      uns_key: Optional[str] = Field(
          default="liana_res",
          description="Key in adata.uns that contains the LIANA results."
      )
      
      groupby: Optional[str] = Field(
          default=None,
          description="Key to be used for grouping or clustering cells."
      )
      
      source_key: str = Field(
          default="source",
          description="Column name of the sender/source cell types in liana_res."
      )
      
      target_key: str = Field(
          default="target",
          description="Column name of the receiver/target cell types in liana_res."
      )
      
      score_key: Optional[str] = Field(
          default=None,
          description="Column name of the score in liana_res. If None, the score is inferred from the method."
      )
      
      inverse_score: bool = Field(
          default=False,
          description="Whether to invert the score. If True, the score will be -log10(score)."
      )
      
      top_n: Optional[int] = Field(
          default=None,
          description="Top N entities to plot."
      )
      
      orderby: Optional[str] = Field(
          default=None,
          description="If top_n is not None, order the interactions by this column."
      )
      
      orderby_ascending: Optional[bool] = Field(
          default=None,
          description="If top_n is not None, specify how to order the interactions."
      )
      
      orderby_absolute: bool = Field(
          default=False,
          description="If top_n is not None, whether to order by the absolute value of the orderby column."
      )
      
      source_labels: Optional[Union[List[str], str]] = Field(
          default=None,
          description="List of labels to use as source, the rest are filtered out."
      )
      
      target_labels: Optional[Union[List[str], str]] = Field(
          default=None,
          description="List of labels to use as target, the rest are filtered out."
      )
      
      ligand_complex: Optional[Union[List[str], str]] = Field(
          default=None,
          description="List of ligand complexes to filter the interactions to be plotted."
      )
      
      receptor_complex: Optional[Union[List[str], str]] = Field(
          default=None,
          description="List of receptor complexes to filter the interactions to be plotted."
      )
      
      pivot_mode: Literal["counts", "mean"] = Field(
          default="counts",
          description="The mode of the pivot table: 'counts' for number of connections, 'mean' for mean of score values."
      )
      
      mask_mode: Literal["and", "or"] = Field(
          default="or",
          description="The mode of the mask: 'or' to include source or target, 'and' to include source and target."
      )
      
      specificity_cutoff: float = Field(
          default=0.05,
          description="specificity or pval threshold for filtering results. "
      )
      
      figure_size: Tuple[float, float] = Field(
          default=(5, 5),
          description="Figure x,y size."
      )
      
      edge_alpha: float = Field(
          default=0.5,
          description="The transparency of the edges."
      )
      
      edge_arrow_size: int = Field(
          default=10,
          description="The size of the arrow."
      )
      
      edge_width_scale: Tuple[float, float] = Field(
          default=(1, 5),
          description="The scale of the edge width."
      )
      
      node_alpha: float = Field(
          default=1.0,
          description="The transparency of the nodes."
      )
      
      node_size_scale: Tuple[float, float] = Field(
          default=(100, 400),
          description="The scale of the node size."
      )
      
      node_label_offset: Tuple[float, float] = Field(
          default=(0.1, -0.2),
          description="The offset of the node label."
      )
      
      node_label_size: int = Field(
          default=8,
          description="The size of the node label."
      )
      
      node_label_alpha: float = Field(
          default=0.7,
          description="The transparency of the node label."
      )

• src/scmcp/tool/ccc.py:29-33 (registration)

  MCP Tool object registration with name, description, and schema for ccc_circle_plot.

  circle_plot_tool = types.Tool(
      name="ccc_circle_plot",
      description="Visualize cell-cell communication network using a circular plot.",
      inputSchema=CirclePlotModel.model_json_schema(),
  )

• src/scmcp/tool/ccc.py:100-106 (registration)

  ccc_tools dictionary that maps tool name to Tool object, including ccc_circle_plot.

  ccc_tools = {
      "ls_ccc_method": ls_ccc_method_tool,
      "ccc_rank_aggregate": rank_aggregate_tool,
      "ccc_circle_plot": circle_plot_tool,
      "ccc_dot_plot": dot_plot_tool,
      "ccc": ccc_tool,
  }

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

  In list_tools(), includes ccc_tools.values() to register ccc_circle_plot among available tools.

      tools = [
          *io_tools.values(),
          *pp_tools.values(),
          *tl_tools.values(),
          *pl_tools.values(),
          *util_tools.values(),
          *ccc_tools.values(),
      ]
  return tools