embedding_density

Instructions

Implementation Reference

• src/scmcp/tool/tl.py:164-177 (handler)

  Generic handler function for tl tools, including embedding_density, that dispatches to sc.tl.embedding_density with inspected parameters and logs the operation.

  def run_tl_func(ads, func, arguments):
      adata = ads.adata_dic[ads.active]
      if func not in tl_func:
          raise ValueError(f"Unsupported function: {func}")
      run_func = tl_func[func]
      parameters = inspect.signature(run_func).parameters
      kwargs = {k: arguments.get(k) for k in parameters if k in arguments}    
      try:
          res = run_func(adata, **kwargs)
          add_op_log(adata, run_func, kwargs)
      except Exception as e:
          logger.error(f"Error running function {func}: {e}")
          raise
      return 

• src/scmcp/schema/tl.py:239-265 (schema)

  Pydantic input schema model for the embedding_density computation tool (sc.tl.embedding_density).

  class EmbeddingDensityModel(JSONParsingModel):
      """Input schema for the embedding density calculation tool."""
      
      basis: str = Field(
          default='umap',
          description="The embedding over which the density will be calculated. This embedded representation should be found in `adata.obsm['X_[basis]']`."
      )
      groupby: Optional[str] = Field(
          default=None,
          description="Key for categorical observation/cell annotation for which densities are calculated per category."
      )
      key_added: Optional[str] = Field(
          default=None,
          description="Name of the `.obs` covariate that will be added with the density estimates."
      )
      components: Optional[Union[str, List[str]]] = Field(
          default=None,
          description="The embedding dimensions over which the density should be calculated. This is limited to two components."
      )
      
      @field_validator('components')
      def validate_components(cls, v: Optional[Union[str, List[str]]]) -> Optional[Union[str, List[str]]]:
          """Validate that components are limited to two dimensions"""
          if v is not None and isinstance(v, list) and len(v) > 2:
              raise ValueError("components is limited to two dimensions")
          return v

• src/scmcp/tool/tl.py:40-150 (registration)

  Registration of the embedding_density tool for computation (tl), including tool object creation, function mapping in tl_func, and inclusion in tl_tools dictionary.

  # Add embedding_density tool
  embedding_density_tool = types.Tool(
      name="embedding_density",
      description="Calculate the density of cells in an embedding",
      inputSchema=EmbeddingDensityModel.model_json_schema(),
  )
  
  # Add leiden tool
  leiden_tool = types.Tool(
      name="leiden",
      description="Leiden clustering algorithm for community detection",
      inputSchema=LeidenModel.model_json_schema(),
  )
  
  # Add louvain tool
  louvain_tool = types.Tool(
      name="louvain",
      description="Louvain clustering algorithm for community detection",
      inputSchema=LouvainModel.model_json_schema(),
  )
  
  # Add dendrogram tool
  dendrogram_tool = types.Tool(
      name="dendrogram",
      description="Hierarchical clustering dendrogram",
      inputSchema=DendrogramModel.model_json_schema(),
  )
  
  # Add dpt tool
  dpt_tool = types.Tool(
      name="dpt",
      description="Diffusion Pseudotime (DPT) analysis",
      inputSchema=DPTModel.model_json_schema(),
  )
  
  # Add paga tool
  paga_tool = types.Tool(
      name="paga",
      description="Partition-based graph abstraction",
      inputSchema=PAGAModel.model_json_schema(),
  )
  
  # Add ingest tool
  ingest_tool = types.Tool(
      name="ingest",
      description="Map labels and embeddings from reference data to new data",
      inputSchema=IngestModel.model_json_schema(),
  )
  
  # Add rank_genes_groups tool
  rank_genes_groups_tool = types.Tool(
      name="rank_genes_groups",
      description="Rank genes for characterizing groups, perform differentially expressison analysis",
      inputSchema=RankGenesGroupsModel.model_json_schema(),
  )
  
  # Add filter_rank_genes_groups tool
  filter_rank_genes_groups_tool = types.Tool(
      name="filter_rank_genes_groups",
      description="Filter out genes based on fold change and fraction of genes",
      inputSchema=FilterRankGenesGroupsModel.model_json_schema(),
  )
  
  # Add marker_gene_overlap tool
  marker_gene_overlap_tool = types.Tool(
      name="marker_gene_overlap",
      description="Calculate overlap between data-derived marker genes and reference markers",
      inputSchema=MarkerGeneOverlapModel.model_json_schema(),
  )
  
  # Add score_genes tool
  score_genes_tool = types.Tool(
      name="score_genes",
      description="Score a set of genes based on their average expression",
      inputSchema=ScoreGenesModel.model_json_schema(),
  )
  
  # Add score_genes_cell_cycle tool
  score_genes_cell_cycle_tool = types.Tool(
      name="score_genes_cell_cycle",
      description="Score cell cycle genes and assign cell cycle phases",
      inputSchema=ScoreGenesCellCycleModel.model_json_schema(),
  )
  
  # Dictionary mapping tool names to scanpy functions
  tl_func = {
      "tsne": sc.tl.tsne,
      "umap": sc.tl.umap,
      "draw_graph": sc.tl.draw_graph,
      "diffmap": sc.tl.diffmap,
      "embedding_density": sc.tl.embedding_density,
      "leiden": sc.tl.leiden,
      "louvain": sc.tl.louvain,
      "dendrogram": sc.tl.dendrogram,
      "dpt": sc.tl.dpt,
      "paga": sc.tl.paga,
      "ingest": sc.tl.ingest,
      "rank_genes_groups": sc.tl.rank_genes_groups,
      "filter_rank_genes_groups": sc.tl.filter_rank_genes_groups,
      "marker_gene_overlap": sc.tl.marker_gene_overlap,
      "score_genes": sc.tl.score_genes,
      "score_genes_cell_cycle": sc.tl.score_genes_cell_cycle,
  }
  
  # Dictionary mapping tool names to tool objects
  tl_tools = {
      "tsne": tsne_tool,
      "umap": umap_tool,
      "draw_graph": draw_graph_tool,
      "diffmap": diffmap_tool,
      "embedding_density": embedding_density_tool,

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

  Generic handler function for pl tools, including embedding_density plot, that calls sc.pl.embedding_density, saves figure, and logs.

  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:718-749 (schema)

  Pydantic input schema model for the embedding_density plotting tool (sc.pl.embedding_density), extending BaseEmbeddingModel.

  class EmbeddingDensityModel(BaseEmbeddingModel):
      """Input schema for the embedding_density plotting tool."""
      
      basis: str = Field(
          ...,  # Required field
          description="Basis to use for embedding."
      )
      
      key: Optional[str] = Field(
          default=None,
          description="Key for annotation of observations/cells or variables/genes."
      )
      
      convolve: Optional[float] = Field(
          default=None,
          description="Sigma for Gaussian kernel used for convolution."
      )
      
      alpha: float = Field(
          default=0.5,
          description="Alpha value for the plot.",
          ge=0,
          le=1
      )
      
      @field_validator('alpha')
      def validate_alpha(cls, v: float) -> float:
          """Validate alpha is between 0 and 1"""
          if v < 0 or v > 1:
              raise ValueError("alpha must be between 0 and 1")
          return v