feat: shared fontsize constants, display_label, and xlabel on 1D panels

- Add FS_TICK/FS_AXLABEL/FS_AXTITLE/FS_TITLE/FS_LEGEND and use them in the
  1D scatter and genome-axis decoration.
- Add AXIS_LABELS and display_label() so log2RDR is shown as "RDR" on 1D and
  2D axes, matching the heatmap colorbar.
- plot_scatter_1d and plot_scatter_1d_multisample take an xlabel; the
  multisample figure draws it above the profile's top chromosome ticks.
- 1D legend moves to the lower right.
- plot_heatmap_cnp scales profile_hspace with figure height so the
  chromosome-label band keeps its size on short pages.

Author: RunpengLuo

src/cnplot/__init__.py

@@ -50,9 +50,15 @@
 from .cnplot_intcnp import plot_cnv_profile
 from .cnplot_io_utils import read_bed, read_chr_sizes
 from .cnplot_utils import (
+    AXIS_LABELS,
     BAF_LIM,
     CN_PREFIX,
     EXP_PREFIX,
+    FS_AXLABEL,
+    FS_AXTITLE,
+    FS_LEGEND,
+    FS_TICK,
+    FS_TITLE,
     MARKER_SIZE_LARGE,
     MARKER_SIZE_SMALL,
     MAX_NDOTS,
@@ -63,6 +69,7 @@
     FigureSaver,
     adaptive_dot_size,
     decorate_genome_axis,
+    display_label,
     draw_chr_boundaries,
     draw_segment_boundaries,
     get_clone_ylabels,
@@ -97,13 +104,19 @@ def _read_version() -> str:
 __version__ = _read_version()
 
 __all__ = [
+    "AXIS_LABELS",
     "BAF_COLORS",
     "BAF_LIM",
     "CELLTYPE_CMAP",
     "CN_PREFIX",
     "DATASET_CMAP",
     "DEFAULT_EXCLUDED_CHROMS",
     "EXP_PREFIX",
+    "FS_AXLABEL",
+    "FS_AXTITLE",
+    "FS_LEGEND",
+    "FS_TICK",
+    "FS_TITLE",
     "MARKER_SIZE_LARGE",
     "MARKER_SIZE_SMALL",
     "MAX_NDOTS",
@@ -126,6 +139,7 @@ def _read_version() -> str:
     "adaptive_dot_size",
     "annotate_landmarks",
     "decorate_genome_axis",
+    "display_label",
     "draw_chr_boundaries",
     "draw_segment_boundaries",
     "get_ascn_cmap",

src/cnplot/cnplot_1d.py

@@ -24,7 +24,11 @@
 from .cnplot_genome_axis import GenomeAxis
 from .cnplot_utils import (
     EXP_PREFIX,
+    FS_AXLABEL,
+    FS_AXTITLE,
+    FS_LEGEND,
     decorate_genome_axis,
+    display_label,
     draw_chr_boundaries,
     draw_segment_boundaries,
     resolve_colors,
@@ -168,6 +172,7 @@ def plot_scatter_1d(
     edgewidth: float = 0.0,
     ylim: tuple | None = None,
     ylabel: str | None = None,
+    xlabel: str | None = None,
     title: str | None = None,
     href: float | None = None,
     reverse_y: bool = False,
@@ -210,8 +215,13 @@ def plot_scatter_1d(
         edgecolor: Marker edge color.
         edgewidth: Marker edge width.
         ylim: Fixed (lo, hi), or None to leave the autoscale alone.
-        ylabel: Y-axis label.
-        title: Axes title, drawn left-aligned.
+        ylabel: Y-axis label, passed through
+            :func:`~cnplot.cnplot_utils.display_label`.
+        xlabel: X-axis label, drawn under the chromosome ticks and passed through
+            :func:`~cnplot.cnplot_utils.display_label`. None leaves the axis
+            unnamed, which suits a stacked panel whose bottom row carries it.
+        title: Axes title, drawn left-aligned at FS_AXTITLE -- it labels one row
+            of a stack, so it stays below the y-axis label that names the quantity.
         href: Y value for a dotted grey reference line, e.g. 0.5 on a BAF row.
         reverse_y: Invert the y-axis.
         plot_chrname: Draw chromosome labels under the axes.
@@ -273,7 +283,8 @@ def plot_scatter_1d(
             label=label,
         )
     if keep_col is not None and show_legend:
-        ax.legend(loc="upper right", fontsize=8, markerscale=2, framealpha=0.7)
+        # NB: lower right -- a legend at the top is the first thing the eye reaches.
+        ax.legend(loc="lower right", fontsize=FS_LEGEND, markerscale=2, framealpha=0.7)
     if rasterized:
         for coll in ax.collections:
             coll.set_rasterized(True)
@@ -295,15 +306,17 @@ def plot_scatter_1d(
     if ylim is not None:
         ax.set_ylim(*ylim)
     if ylabel is not None:
-        ax.set_ylabel(ylabel, fontsize=12, fontweight="bold")
+        ax.set_ylabel(display_label(ylabel), fontsize=FS_AXLABEL)
     if title is not None:
-        ax.set_title(title, fontsize=12, fontweight="bold", loc="left")
+        ax.set_title(title, fontsize=FS_AXTITLE, fontweight="bold", loc="left", pad=4.0)
     decorate_genome_axis(
         ax,
         genome_axis,
         plot_chrname=plot_chrname,
         mb_ticks=mb_ticks,
         mb_tick_step=mb_tick_step,
     )
+    if xlabel is not None:
+        ax.set_xlabel(display_label(xlabel), fontsize=FS_AXLABEL)
     if reverse_y:
         ax.invert_yaxis()

src/cnplot/cnplot_2d.py

@@ -32,6 +32,7 @@
     EXP_PREFIX,
     NORMAL_CLONE,
     SAMPLE_COL,
+    display_label,
     resolve_colors,
     resolve_marker_size,
 )
@@ -418,8 +419,8 @@ def plot_scatter_2d(
                 )
 
     grid.set_axis_labels(
-        xlabel=xcol if xlabel is None else xlabel,
-        ylabel=ycol if ylabel is None else ylabel,
+        xlabel=display_label(xcol if xlabel is None else xlabel),
+        ylabel=display_label(ycol if ylabel is None else ylabel),
         fontsize=12,
     )
     if title is not None:

src/cnplot/cnplot_figures.py

@@ -30,8 +30,10 @@
     select_sample,
 )
 from .cnplot_utils import (
+    FS_AXLABEL,
     NORMAL_CLONE,
     SAMPLE_COL,
+    display_label,
     resolve_marker_size,
 )
 
@@ -158,6 +160,7 @@ def plot_scatter_1d_multisample(
     markersize: float | None = None,
     mb_ticks: bool = False,
     mb_tick_step: float = 50_000_000,
+    xlabel: str | None = None,
     intra_group_hspace: float = 0.25,
     inter_group_hspace: float = 0.15,
     profile_hspace: float = 0.2,
@@ -212,7 +215,9 @@ def plot_scatter_1d_multisample(
         inter_group_hspace: Space between groups, as a fraction of a group's
             height; a group is several rows tall, so keep this small.
         profile_hspace: Space between the last row and the profile, which needs
-            room for the chromosome labels it draws along its top.
+            room for the chromosome labels it draws along its top. Raised to a
+            floor of 0.2 when ``xlabel`` is set, since the name is drawn above
+            those labels.
         rasterized: Rasterize the point collections.
         **profile_kwargs: Passed to
             :func:`~cnplot.cnplot_intcnp.plot_cnv_profile`.
@@ -263,13 +268,15 @@ def plot_scatter_1d_multisample(
 
     # Nested so the three gaps stay independent: rows within a group, group to
     # group, and rows to profile. One flat grid would tie the last two together.
+    # NB: a top-side xlabel sits in the rows-to-profile gap; 0.2 clears the row above.
+    gap = max(profile_hspace, 0.2) if xlabel is not None else profile_hspace
     if has_profile:
         outer = GridSpec(
             2,
             1,
             figure=fig,
             height_ratios=[rows_h, profile_h],
-            hspace=profile_hspace,
+            hspace=gap,
             top=0.97,
         )
         groups_gs = GridSpecFromSubplotSpec(
@@ -323,6 +330,9 @@ def plot_scatter_1d_multisample(
                 href=spec["href"],
                 reverse_y=spec["reverse_y"],
                 plot_chrname=last_row and last_group and not has_profile,
+                xlabel=(
+                    xlabel if (last_row and last_group and not has_profile) else None
+                ),
                 mb_ticks=mb_ticks,
                 mb_tick_step=mb_tick_step,
                 rasterized=rasterized,
@@ -342,6 +352,10 @@ def plot_scatter_1d_multisample(
         plot_cnv_profile(
             ax_profile, seg_df, genome_axis, ax_leg=ax_legend, **profile_kwargs
         )
+        if xlabel is not None:
+            # NB: the profile ticks its chromosomes on top, so the name goes there too.
+            ax_profile.set_xlabel(display_label(xlabel), fontsize=FS_AXLABEL)
+            ax_profile.xaxis.set_label_position("top")
     return fig
 
 
@@ -388,7 +402,8 @@ def plot_heatmap_cnp(
         profile_hspace: Space between the heatmap and the profile below it; holds
             the chromosome labels drawn on top of the profile. None picks 0.35,
             or 0.45 under ``mb_ticks``, whose rotated Mb labels take the same
-            band.
+            band, and raises that floor on a short page so the fixed-size labels
+            keep the same gap in inches however tall the figure is.
         top: Top of the axes block in figure fraction; the space above holds the
             title.
         profile: "cnv" draws the joint integer-CN profile
@@ -409,7 +424,10 @@ def plot_heatmap_cnp(
     if profile not in ("cnv", "ascn"):
         raise ValueError("profile must be 'cnv' or 'ascn'")
     if profile_hspace is None:
-        profile_hspace = 0.45 if heatmap_kwargs.get("mb_ticks") else 0.35
+        base = 0.45 if heatmap_kwargs.get("mb_ticks") else 0.35
+        # NB: hspace is a fraction of axes height; the labels are not, so short pages
+        # need a larger fraction to hold the same band.
+        profile_hspace = max(base, 4.5 / figsize[1])
     heatmap_kwargs.setdefault("show_colorbar", True)
     heatmap_kwargs.setdefault("show_block_labels", False)
     heatmap_kwargs["plot_chrname"] = False

src/cnplot/cnplot_utils.py

@@ -72,6 +72,31 @@
 # off the spine; ticks still run 0.0 to 1.0, the pad being too small to label.
 BAF_LIM = (-0.01, 1.01)
 
+# Fontsizes
+FS_TICK = 14
+FS_AXLABEL = 18
+FS_AXTITLE = 16
+FS_TITLE = 20
+FS_LEGEND = 12
+
+# Display names for plotted quantities. A log2 ratio still reads as "RDR" on an
+# axis, which is how the heatmap already labels its colorbar; the 1D rows follow
+# so the two figures name the same quantity the same way.
+AXIS_LABELS = {"log2RDR": "RDR"}
+
+
+def display_label(name: str | None) -> str | None:
+    """Canonical axis text for a quantity name.
+
+    Args:
+        name: Column or label name, or None.
+
+    Returns:
+        The display name from :data:`AXIS_LABELS`, or ``name`` unchanged when it
+        has no canonical form. None passes through.
+    """
+    return name if name is None else AXIS_LABELS.get(name, name)
+
 
 # =============================================================================
 # Axis decoration
@@ -192,7 +217,7 @@ def decorate_genome_axis(
     plot_chrname: bool = True,
     label_pos: str = "bottom",
     rotation: float = 60,
-    fontsize: int = 8,
+    fontsize: int = FS_TICK,
     hide_spines: bool = False,
     pad_axis: bool = False,
     mb_ticks: bool = False,
@@ -215,7 +240,7 @@ def decorate_genome_axis(
         rotation: Tick label rotation in degrees, applied to the chromosome names
             or, with ``mb_ticks``, to the Mb labels; rotating keeps the dense Mb
             labels from overlapping. Chromosome names stay upright in that mode.
-        fontsize: Label font size.
+        fontsize: Label font size; defaults to the module-level FS_TICK.
         hide_spines: Hide all four spines.
         pad_axis: Use the padded limits instead of tight genome ends.
         mb_ticks: Mark position in Mb every ``mb_tick_step`` bp within each