plot-misc 2.2.1__py3-none-any.whl → 2.3.0__py3-none-any.whl

plot_misc/__init__.py

@@ -1 +1,12 @@
+"""
+plot-misc: matplotlib-based plotting archetypes for scientific figures.
+
+A curated collection of user-oriented plotting functions and
+classes built on top of `matplotlib`. Each function returns standard
+matplotlib `Figure`/`Axes` objects, so results can be further customised
+with familiar matplotlib methods. Per the package design callables are limited
+to creating illustrations, and should data be internally calculated this is
+done with options for user overwrites, while making the derived data available
+for inspection and re-use.
+"""
 from ._version import __version__

plot_misc/_version.py

@@ -1 +1 @@
-__version__ = '2.2.1'
+__version__ = '2.3.0'

plot_misc/constants.py

@@ -58,6 +58,8 @@ class UtilsNames(object):
     annot_pval         = 'matrix_pvalue'
     annot_effect       = 'matrix_point_estimate'
     value_point        = 'curated_matrix_point_estimate_value'
+    value_unsigned_log = 'curated_matrix_value_unsigned_log'
+    value_raw          = 'curated_matrix_value_raw'
     value_original     = 'crude_point_estimate'
     source_data        = 'source_data'
     mat_point          = 'point'
@@ -67,8 +69,12 @@ class UtilsNames(object):
     mat_outcome        = 'outcome'
     mat_exposure_list  = ['IL2ra', 'IP10', 'SCF', 'TRAIL']
     mat_outcome_list   = ['HDL-C', 'LDL-C']
+    mat_annot_symbol   = 'symbol'
     mat_annot_star     = 'star'
     mat_annot_pval     = 'pvalues'
+    mat_annot_pval_signed   = 'pvalues_signed'
+    mat_annot_pval_unsigned = 'pvalues_unsigned'
+    mat_annot_pval_raw      = 'pvalues_raw'
     mat_annot_point    = 'point_estimates'
     mat_annot_none     = '`NoneType`'
     roc_false_positive = 'false_positive'

plot_misc/example_data/examples.py

@@ -508,6 +508,54 @@ def heatmap_pvalue_matrix(**kwargs):
     data.index.name = UtilsNames.mat_outcome
     return data
 
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+@dataset
+def qc_matrix(seed=2026):
+    """
+    Creates a dummy quality-control (QC) data set to showcase
+    `plot_misc.heatmap.masked_heatmap`.
+    
+    The values are signed, standardised QC deviations for a set of samples
+    (rows) across several QC metrics (columns). The accompanying indicator
+    flags the cells that failed QC (an absolute deviation above 2), i.e. the
+    cells `masked_heatmap` should highlight; the passing cells are left to the
+    background layer.
+    
+    Parameters
+    ----------
+    seed : `int`, default 2026
+        Seed for the random number generator, ensuring a reproducible matrix.
+    
+    Returns
+    -------
+    values : `pd.DataFrame`
+        Signed standardised QC deviations of shape (12, 6).
+    indicator : `pd.DataFrame`
+        A binary (0/1) table of the same shape as `values`, equal to 1 where
+        the metric failed QC and 0 otherwise.
+    """
+    rng = np.random.default_rng(seed)
+    samples = ['Sample_{:02d}'.format(i) for i in range(1, 13)]
+    metrics = [
+        'CallRate', 'Heterozygosity', 'Contamination', 'MeanDepth',
+        'DuplicationRate', 'InsertSize',
+    ]
+    values = pd.DataFrame(
+        rng.normal(loc=0.0, scale=1.3, size=(len(samples), len(metrics))),
+        index=samples, columns=metrics,
+    )
+    # inject a handful of unambiguous QC failures so the showcase always has
+    # highlighted cells regardless of the random draw
+    values.iloc[0, 2] = 3.4
+    values.iloc[3, 0] = -3.1
+    values.iloc[5, 4] = 2.8
+    values.iloc[7, 1] = -2.6
+    values.iloc[9, 5] = 3.0
+    values.iloc[11, 3] = -2.9
+    values = values.round(3)
+    indicator = (values.abs() > 2).astype(int)
+    return values, indicator
+
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 @dataset
 def load_calibration_data(**kwargs):

plot_misc/forest.py

@@ -982,20 +982,6 @@ class EmpiricalSupport(object):
     results_ : `EmpiricalSupportResults`
         An EmpiricalSupportResults instance.
     
-    Methods
-    -------
-    calc_empirical_support(estimate, standard_error, alpha)
-        Computes the range of confidence intervals and compatibility metrics
-        over the supplied alpha values.
-    
-    plot_tree(...)
-        Creates a 'tree plot' summarising the parameter space supported by
-        the data, with options for CI and estimate annotations.
-    
-    _plot_empirical_support(...)
-        Generates a visualisation of confidence intervals and their overlap
-        across varying alpha values.
-    
     Notes
     -----
     This implementation is based on the concept of compatibility (or

plot_misc/heatmap.py

@@ -11,6 +11,10 @@ heatmap(data, row_labels, col_labels, ...)
     Draws a standard heatmap using matplotlib's `imshow`, with options for
     gridlines, tick formatting, and embedded colourbars.
 
+masked_heatmap(data, indicator, row_labels, col_labels, ...)
+    Draws a two-layer heatmap: a single-colour background and, on top of it,
+    the heatmap restricted to the cells flagged by a binary indicator table.
+
 annotate_heatmap(im, data=None, valfmt=None, ...)
     Adds text annotations to an existing heatmap image (AxesImage object),
     with configurable formatting and colour thresholding.
@@ -22,9 +26,8 @@ from the example published in the official matplotlib gallery [1]_.
 
 References
 ----------
-.. [1] Matplotlib contributors. "Creating annotated heatmaps."
-Matplotlib Gallery.
-https://matplotlib.org/stable/gallery/images_contours_and_fields/image_annotated_heatmap.html
+.. [1] Matplotlib contributors. "Creating annotated heatmaps." Matplotlib
+   Gallery. https://matplotlib.org/stable/gallery/images_contours_and_fields/image_annotated_heatmap.html
 """
 
 # modules
@@ -32,9 +35,13 @@ import numpy as np
 import pandas as pd
 import matplotlib
 import matplotlib.pyplot as plt
+from matplotlib.colors import ListedColormap
+from matplotlib.patches import Rectangle
 from plot_misc.utils.utils import _update_kwargs
 from plot_misc.errors import (
     is_type,
+    is_df,
+    InputValidationError,
 )
 from plot_misc.constants import Real
 from typing import Any
@@ -45,6 +52,7 @@ def heatmap(data:pd.DataFrame | np.ndarray, row_labels:list[str] | np.ndarray,
             grid_linestyle:str='-', grid_linewidth:float=3,
             cbar_bool:bool=False, cbar_label:str="",
             ax:plt.Axes | None = None,
+            figsize:tuple[float,float] | None = None,
             grid_kw:dict[Any,Any] | None = None,
             cbar_kw:dict[Any,Any] | None = None,
             **kwargs:Any,
@@ -78,6 +86,8 @@ def heatmap(data:pd.DataFrame | np.ndarray, row_labels:list[str] | np.ndarray,
     ax : `plt.Axes` or `None`, default None
         A `matplotlib.axes.Axes` instance to which the heatmap is plotted. If
         not provided, use current axes or create a new one.
+    figsize : `tuple` [`float`, `float`] or `None`, default `None`
+        Figure size in inches (width, height). Ignored if `ax` is provided.
     grid_kw : `dict` [`str`,`any`] or `None`, default None
         A dictionary with arguments to `matplotlib.Axes.grid`.
     cbar_kw : `dict` [`str`, `any`] or `None`, default `None`
@@ -105,10 +115,20 @@ def heatmap(data:pd.DataFrame | np.ndarray, row_labels:list[str] | np.ndarray,
             Matplotlib Gallery.
             https://matplotlib.org/stable/gallery/images_contours_and_fields/image_annotated_heatmap.html
     """
-    
+    # check in put
+    is_type(data, (pd.DataFrame, np.ndarray))
+    is_type(row_labels, (list, np.ndarray))
+    is_type(col_labels, (list, np.ndarray))
+    is_type(grid_col, str)
+    is_type(grid_linestyle, str)
+    is_type(grid_linewidth, Real)
+    is_type(cbar_bool, bool)
+    is_type(cbar_label, str)
     # create a axes if needed
-    if not ax:
-        ax = plt.gca()
+    if ax is None:
+        _, ax = plt.subplots(figsize=figsize)
+    else:
+        f = ax.figure
     # check input
     if isinstance(data, pd.DataFrame):
         matrix = data.copy().to_numpy()
@@ -117,10 +137,6 @@ def heatmap(data:pd.DataFrame | np.ndarray, row_labels:list[str] | np.ndarray,
     # copy
     row_lab = row_labels
     col_lab = col_labels
-    # check additional input
-    is_type(row_lab, (list, np.array))
-    is_type(col_lab, (list, np.array))
-    is_type(cbar_label, str)
     # map None to dict
     grid_kw = grid_kw or {}
     cbar_kw = cbar_kw or {}
@@ -156,12 +172,201 @@ def heatmap(data:pd.DataFrame | np.ndarray, row_labels:list[str] | np.ndarray,
     new_grid_kwargs = _update_kwargs(
         update_dict=grid_kw, which="minor", color=grid_col,
                      linestyle=grid_linestyle, linewidth=grid_linewidth,
-                     )
+                     clip_on=False,)
     ax.grid(**new_grid_kwargs)
     ax.tick_params(which="minor", bottom=False, left=False)
     # return stuff
     return im, cbar
 
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+def masked_heatmap(data:pd.DataFrame | np.ndarray,
+                   indicator:pd.DataFrame | np.ndarray,
+                   row_labels:list[str] | np.ndarray,
+                   col_labels:list[str] | np.ndarray,
+                   background_col:str='white', background_gridcol:str='white',
+                   background_linestyle:str='-', background_linewidth:float=0.5,
+                   background_zorder:Real = 1,
+                   outline_col:str='black', outline_linestyle:str='-',
+                   outline_linewidth:float=1.5, outline_zorder:Real = 2,
+                   frame: bool=False,
+                   cbar_bool:bool=False, cbar_label:str="",
+                   ax:plt.Axes | None = None,
+                   figsize:tuple[float,float] | None = None,
+                   grid_kw:dict[Any,Any] | None = None,
+                   cbar_kw:dict[Any,Any] | None = None,
+                   background_kw:dict[Any,Any] | None = None,
+                   outline_kw:dict[Any,Any] | None = None,
+                   **kwargs: Any,
+                   ) -> tuple[matplotlib.image.AxesImage,
+                              matplotlib.colorbar.Colorbar]:
+    """
+    Plot a two-layer heatmap masked by a binary indicator table.
+    
+    The function draws two layers. First a single-colour background covering
+    every cell (carrying an optional grid lattice). Second, the heatmap of
+    `data`, restricted to the cells where `indicator` equals 1.
+    
+    Parameters
+    ----------
+    data : `pd.DataFrame` or `np.ndarray`
+        A 2D array of shape (M, N) containing the values to plot.
+    indicator : `pd.DataFrame` or `np.ndarray`
+        A binary (0/1, booleans accepted) array of the same shape as `data`.
+        Only cells equal to 1 are drawn and outlined.
+    row_labels : `list` [`str`] or `np.ndarray`
+        A list or array of length M with the labels for the rows.
+    col_labels : `list` [`str`] or `np.ndarray`
+        A list or array of length N with the labels for the columns.
+    background_col : `str`, default 'white'
+        The fill colour of the background layer.
+    background_gridcol : `str`, default 'white'
+        The colour of the background grid lattice lines.
+    background_linestyle : `str`, default '-'
+        The linestyle of the background grid lattice.
+    background_linewidth : `float`, default 0.5
+        The width of the background grid lattice. Set to 0 to suppress it.
+    background_zorder : `int`, `float` default `1`
+        The draw order of the background grid lattice.
+    outline_col : `str`, default 'black'
+        The edge colour of the per-cell outlines drawn on `indicator == 1`
+        cells.
+    outline_linestyle : `str`, default '-'
+        The linestyle of the per-cell outlines.
+    outline_linewidth : `float`, default 1.5
+        The width of the per-cell outlines. Set to 0 to suppress them.
+    outline_zorder : `int`, `float`, default `2`
+        The draw order of the per-cell outlines.
+    frame : `bool`, default `False`
+        Whether to plot the spines.
+    cbar_bool : `bool`, default `False`
+        If `True`, add a colourbar (built from the masked heatmap layer).
+    cbar_label : `str`, default ""
+        The label for the colourbar.
+    ax : `plt.Axes` or `None`, default `None`
+        A `matplotlib.axes.Axes` instance to draw on. If `None`, a new figure
+        and axes are created.
+    figsize : `tuple` [`float`, `float`] or `None`, default `None`
+        Figure size in inches (width, height). Ignored if `ax` is provided.
+    grid_kw : `dict` [`str`, `any`] or `None`, default `None`
+        Additional arguments forwarded to `matplotlib.Axes.grid` for the
+        background lattice.
+    outline_kw : `dict` [`str`, `any`] or `None`, default `None`
+        Additional arguments forwarded to each `matplotlib.patches.Rectangle`
+        outline. Outlines default to `clip_on=False` so the borders of cells on
+        the matrix boundary are not clipped by the axes edge; pass
+        `{'clip_on': True}` to restore clipping.
+    cbar_kw : `dict` [`str`, `any`] or `None`, default `None`
+        A dictionary with arguments to `matplotlib.Figure.colorbar`.
+    background_kw : `dict` [`str`, `any`] or `None`, default `None`,
+        A dictionary with arguments to `heatmap.heatmap`.
+    **kwargs : `any`,
+        All other arguments passed to `masking ax.imshow`.
+    
+    Returns
+    -------
+    im : `matplotlib.image.AxesImage`
+        The masked (foreground) heatmap image object.
+    cbar : `matplotlib.colorbar.Colorbar` or `None`
+        The colourbar object if `cbar_bool` is `True`, otherwise `None`.
+    
+    Notes
+    -----
+    The masking is achieved by a separate imshow call setting the cells to
+    transparent, revealing the background.
+    
+    The returned `im` mirrors the contract of `heatmap` and can therefore be
+    annotated using `annotate_heatmap`.
+    """
+    # create an axes if needed
+    if ax is None:
+        _, ax = plt.subplots(figsize=figsize)
+    else:
+        f = ax.figure
+    # check input types
+    is_type(data, (pd.DataFrame, np.ndarray))
+    is_type(indicator, (pd.DataFrame, np.ndarray))
+    _ = [is_type(k, (dict, type(None))) for k in\
+         (grid_kw, cbar_kw, outline_kw, background_kw)]
+    # the indicator must match the data shape exactly (full 2D shape, not just
+    # the row count)
+    if np.shape(data) != np.shape(indicator):
+        raise InputValidationError(
+            f"`indicator` shape {np.shape(indicator)} does not match `data` "
+            f"shape {np.shape(data)}."
+        )
+    # coerce the data and indicator to numpy arrays
+    if isinstance(data, pd.DataFrame):
+        matrix = data.copy().to_numpy()
+    else:
+        matrix = data
+    if isinstance(indicator, pd.DataFrame):
+        flag = indicator.copy().to_numpy()
+    else:
+        flag = indicator
+    # flag should only contain 0 and 1
+    unique_flags = set(np.unique(flag).tolist())
+    if not unique_flags.issubset({0, 1}):
+        raise InputValidationError(
+            f"`indicator` must only contain binary (0/1) values, got "
+            f"{sorted(unique_flags)}."
+        )
+    # setup the kwargs None to dict
+    background_kw = background_kw or {}
+    # masking_kw = masking_kw or {}
+    grid_kw = grid_kw or {}
+    cbar_kw = cbar_kw or {}
+    outline_kw = outline_kw or {}
+    outline_kw = _update_kwargs(update_dict=outline_kw,
+                                zorder=outline_zorder)
+    # the background grid lattice carries the background draw order
+    grid_kw = _update_kwargs(update_dict=grid_kw, zorder=background_zorder)
+    # ### Layer 1: a single-colour background covering every cell. Reusing
+    # `heatmap` keeps a single source of truth for the tick, label, spine and
+    # grid (lattice) cosmetics.
+    background = np.zeros_like(matrix, dtype=float)
+    layer1_kwargs = _update_kwargs(
+         update_dict=background_kw,
+         data=background, row_labels=row_labels, col_labels=col_labels,
+         grid_col=background_gridcol, grid_linestyle=background_linestyle,
+         grid_linewidth=background_linewidth, cbar_bool=False, ax=ax,
+         grid_kw=grid_kw, cmap=ListedColormap([background_col]),
+    )
+    heatmap(**layer1_kwargs, )
+    # ### Layer 2: the heatmap, masked so only `indicator == 1` cells are drawn.
+    masked = np.ma.masked_where(flag == 0, matrix)
+    # creating an alpha matrix.
+    # user_alpha = masking_kw.pop('alpha', 1.0)
+    user_alpha = kwargs.pop('alpha', 1.0)
+    alpha = (flag == 1).astype(float) * np.asarray(user_alpha, dtype=float)
+    layer2_kwargs = _update_kwargs(
+        update_dict=kwargs, alpha=alpha,
+    )
+    im = ax.imshow(masked, **layer2_kwargs)
+    # Create colorbar from the foreground (masked) layer
+    if cbar_bool:
+        cbar = ax.figure.colorbar(im, ax=ax, **cbar_kw)
+        cbar.ax.set_ylabel(cbar_label, rotation=-90, va="bottom")
+    else:
+        cbar = None
+    # ### Outline each `indicator == 1` cell. Zero cells get no patch, so they
+    # carry no outline; a zero `outline_linewidth` hides the borders.
+    rect_kw = _update_kwargs(update_dict=outline_kw, facecolor='none',
+                             edgecolor=outline_col,
+                             linestyle=outline_linestyle,
+                             linewidth=outline_linewidth,
+                             clip_on=False,
+                             )
+    rows, cols = np.where(flag == 1)
+    # NOTE the 0.5 and 1.0 are imshow fixed convention and should be hardcoded
+    for i, j in zip(rows, cols):
+        ax.add_patch(Rectangle((j-.5, i-.5), 1, 1, **rect_kw))
+    # Show the spines
+    if frame:
+        for spine in ax.spines.values():
+            spine.set_visible(True)
+    # return stuff
+    return im, cbar
+
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 def annotate_heatmap(
     im:plt.Axes.imshow,
@@ -210,6 +415,10 @@ def annotate_heatmap(
     
     # mapping data to matrix
     values = im.get_array()
+    # masked cells (e.g. from `masked_heatmap`) are not drawn and must not be
+    # annotated; `getmaskarray` yields a full boolean mask for masked arrays and
+    # an all-False mask for plain arrays, leaving the unmasked path unchanged
+    mask = np.ma.getmaskarray(values)
     if data is None:
         matrix = im.get_array()
     elif isinstance(data, pd.DataFrame):
@@ -239,6 +448,9 @@ def annotate_heatmap(
     texts = []
     for i in range(matrix.shape[0]):
         for j in range(matrix.shape[1]):
+            # skip masked cells, which carry no drawn value to annotate
+            if mask[i, j]:
+                continue
             # only run if threshold exists
             if threshold is not None:
                 kw.update(color=textcolors[int(abs(values[i, j]) >= threshold)])

plot_misc/machine_learning.py

@@ -55,8 +55,13 @@ from typing import (
     Any,
     Callable,
     Union,
-    Self,
 )
+# `typing.Self` was added in Python 3.11; fall back to typing_extensions on 3.10
+# (the minimum supported version per pyproject `requires-python`).
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
 from statsmodels.nonparametric.smoothers_lowess import lowess
 # from packaging import version
 # if version.parse('3.4.0') < version.parse(mpl._version.version):
@@ -665,15 +670,6 @@ class DecisionCurve(object):
         include at least one predicted risk score (between 0 and 1) and a
         binary outcome variable.
     
-    Methods
-    -------
-    calc_net_benefit(...)
-        Computes the net benefit across a range of thresholds for one or more
-        models.
-    plot(...)
-        Visualises the decision curves, with optional smoothing and style
-        customisation.
-    
     Notes
     -----
     This implementation is adapted from the `dcurves` Python package
@@ -763,8 +759,8 @@ class DecisionCurve(object):
         These rates are scaled by the assumed prevalence to allow valid
         comparisons across populations with different case/control ratios.
         
-        Code adapted from
-        `here <https://github.com/MSKCC-Epi-Bio/dcurves/blob/main/dcurves/dca.py>`_.
+        Code adapted from the
+        `dcurves true/false rate calculation <https://github.com/MSKCC-Epi-Bio/dcurves/blob/main/dcurves/dca.py>`_.
         
         Hash: 007c64b
         """
@@ -861,8 +857,8 @@ class DecisionCurve(object):
         
         The resulting table can be visualised using the `plot()` method.
         
-        Code adapted from:
-        `here <https://github.com/MSKCC-Epi-Bio/dcurves/blob/main/dcurves/dca.py>`_
+        Code adapted from the
+        `dcurves net benefit calculation <https://github.com/MSKCC-Epi-Bio/dcurves/blob/main/dcurves/dca.py>`_
         
         Hash: 007c64b
         """

plot_misc/survival.py

@@ -292,6 +292,7 @@ def extract_follow_up(data: pd.DataFrame,
     -------
     pd.DataFrame
         DataFrame with the following columns:
+    
         - 'time': Requested time points (as integers)
         - '{output_col}_at_risk': Number at risk at each time point
         - '{output_col}_at_risk_format': Formatted at-risk numbers with

plot_misc/utils/formatting.py

@@ -16,7 +16,7 @@ format_estimates(point, se=None, lower=None, upper=None, alpha=0.05, ...)
 sci_notation(number, sig_fig=2, ...)
     Converts a float into scientific notation with superscript exponents.
 
-format_roc(observed, predicted, **kwargs)
+format_roc(observed, predicted, ...)
     Computes ROC curve data and returns it as a tidy DataFrame.
 
 string_interval(limits, int_notation, middle, lower_lim, inq_space, sep)