pl_heatmap
Visualize gene expression patterns with customizable heatmaps for single-cell RNA sequencing data. Configure figure size, color scales, annotations, and group comparisons.
Instructions
Heatmap of the expression values of genes.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| color_map | No | Color map to use for continuous variables. | |
| dendrogram | No | If True or a valid dendrogram key, a dendrogram based on the hierarchical clustering between the groupby categories is added. | |
| figsize | No | Figure size. Format is (width, height). | |
| gene_symbols | No | Column name in .var DataFrame that stores gene symbols. | |
| groupby | Yes | The key of the observation grouping to consider. | |
| layer | No | Name of the AnnData object layer that wants to be plotted. | |
| legend_fontoutline | No | Line width of the legend font outline in pt. | |
| 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 |
| log | No | Plot on logarithmic axis. | |
| num_categories | No | Only used if groupby observation is not categorical. This value determines the number of groups into which the groupby observation should be subdivided. | |
| palette | No | Colors to use for plotting categorical annotation groups. | |
| show_gene_labels | No | By default gene labels are shown when there are 50 or less genes. Otherwise the labels are removed. | |
| standard_scale | No | Whether or not to standardize that dimension between 0 and 1. | |
| swap_axes | No | By default, the x axis contains var_names and the y axis the groupby categories. By setting swap_axes then x are the groupby categories and y the var_names. | |
| use_raw | No | Use raw attribute of adata if present. | |
| var_group_labels | No | Labels for each of the var_group_positions that want to be highlighted. | |
| 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_rotation | No | Label rotation degrees. By default, labels larger than 4 characters are rotated 90 degrees. | |
| var_names | No | var_names should be a valid subset of adata.var_names or a mapping where the key is used as label to group the values. | |
| vcenter | No | The value representing the center of the color scale. | |
| vmax | No | The value representing the upper limit of the color scale. | |
| vmin | No | The value representing the lower limit of the color scale. |
Implementation Reference
- src/scmcp/tool/pl.py:179-217 (handler)Generic handler function that implements the core logic for the 'pl_heatmap' tool by mapping to sc.pl.heatmap and executing it with validated arguments on the active AnnData.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:382-417 (schema)Pydantic model defining the input schema and validation for the pl_heatmap tool, extending BaseMatrixModel with heatmap-specific parameters.class HeatmapModel(BaseMatrixModel): """Input schema for the heatmap plotting tool.""" num_categories: int = Field( default=7, description="Only used if groupby observation is not categorical. This value determines the number of groups into which the groupby observation should be subdivided.", gt=0 ) var_group_rotation: Optional[float] = Field( default=None, description="Label rotation degrees. By default, labels larger than 4 characters are rotated 90 degrees." ) standard_scale: Optional[Literal['var', 'obs']] = Field( default=None, description="Whether or not to standardize that dimension between 0 and 1." ) swap_axes: bool = Field( default=False, description="By default, the x axis contains var_names and the y axis the groupby categories. By setting swap_axes then x are the groupby categories and y the var_names." ) show_gene_labels: Optional[bool] = Field( default=None, description="By default gene labels are shown when there are 50 or less genes. Otherwise the labels are removed." ) @field_validator('num_categories') def validate_num_categories(cls, v: int) -> int: """Validate num_categories is positive""" if v <= 0: raise ValueError("num_categories must be a positive integer") return v
- src/scmcp/tool/pl.py:42-46 (registration)Registers the pl_heatmap tool as an MCP Tool instance with name, description, and reference to HeatmapModel schema.pl_heatmap = types.Tool( name="pl_heatmap", description="Heatmap of the expression values of genes.", inputSchema=HeatmapModel.model_json_schema(), )
- src/scmcp/tool/pl.py:127-127 (registration)Maps the 'pl_heatmap' tool name to the underlying Scanpy function sc.pl.heatmap in the pl_func dictionary used by the handler."pl_heatmap": sc.pl.heatmap,
- src/scmcp/tool/pl.py:147-147 (registration)Adds the pl_heatmap tool instance to the pl_tools dictionary for aggregation and server registration."pl_heatmap": pl_heatmap,