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

plot_misc/_version.py

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

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/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.
@@ -32,9 +36,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 +53,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 +87,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 +116,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 +138,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 +173,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 +416,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 +449,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/utils/utils.py

@@ -201,12 +201,19 @@ class MatrixHeatmapResults(Results):
         (unlogged) point estimates, masked where needed.
     curated_matrix_value : `pd.DataFrame`
         The final heatmap matrix with signed -log10(p-values), possibly NA-masked
-        and suitable for plotting (numeric).
+        and suitable for plotting (numeric). This is the default colour matrix.
+    curated_matrix_value_unsigned_log : `pd.DataFrame`
+        The unsigned -log10(p-value) matrix, NA-masked with 0 (numeric).
+    curated_matrix_value_raw : `pd.DataFrame`
+        The raw (untransformed) p-value matrix, NA-masked with 1 (numeric).
     matrix_point_estimate : `pd.DataFrame`
         A matrix of formatted point estimates as strings, with non-significant
         values masked.
     matrix_pvalue : `pd.DataFrame`
-      A matrix of signed -log10(p-values), unmasked (floats).
+      The p-value annotation matrix (strings). Its representation follows the
+      `annotate` argument of `calc_matrices`: signed -log10(p-values) for
+      'pvalues'/'pvalues_signed', unsigned -log10(p-values) for
+      'pvalues_unsigned', or the raw p-values for 'pvalues_raw'.
     matrix_star : `pd.DataFrame`
       A matrix showing stars for significant values and empty strings otherwise.
     source_data : `pd.DataFrame`
@@ -219,6 +226,8 @@ class MatrixHeatmapResults(Results):
         UtilsNames.annot_star,
         UtilsNames.annot_pval,
         UtilsNames.annot_effect,
+        UtilsNames.value_unsigned_log,
+        UtilsNames.value_raw,
         UtilsNames.value_original,
         UtilsNames.value_point,
         UtilsNames.source_data,
@@ -530,98 +539,123 @@ def _extract(data:pd.DataFrame, exposure_col:str, outcome_col:str,
 
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 def _format_matrices(effect:pd.DataFrame, pval:pd.DataFrame, sig:float,
-                     log:bool=True, ptrun:Real=16, digits:str='3',
-                     symbol:str='★') -> tuple[pd.DataFrame,
-                                                pd.DataFrame,
-                                                pd.DataFrame,
-                                                pd.DataFrame,
-                                                pd.DataFrame,
-                                                ]:
+                     ptrun:Real=16, digits:str='3',
+                     symbol:str='★',
+                     pval_mode:Literal['signed_log',
+                                       'unsigned_log',
+                                       'raw']='signed_log',
+                     ) -> tuple[pd.DataFrame,
+                                pd.DataFrame,
+                                pd.DataFrame,
+                                pd.DataFrame,
+                                pd.DataFrame,
+                                pd.DataFrame,
+                                pd.DataFrame,
+                                ]:
     """
     Format effect and p-value matrices for heatmap visualisation.
-
-    Applies masking, rounding, annotation, and -log10 transformation to p-values,
-    returning both numeric and string matrices for plotting.
+    
+    P-values are always -log10 transformed. Three numeric p-value tables are
+    returned (signed -log10, unsigned -log10, and the raw p-value), together
+    with the string annotation matrices used to overlay the heatmap.
     
     Parameters
     ----------
     effect : `pd.DataFrame`
         Matrix of effect estimates as floats.
     pval : `pd.DataFrame`
-        Matrix of p-values as floats.
+        Matrix of p-values as floats (in [0, 1]).
     sig : `float`
-        The significance p-value cut-off either bounded between 0 and 1,
-        or -log10 transformed.
-    log : `bool`, default is `True`
-        should the `pval` matrix be -log10 transformed.
+        Significance cut-off expressed as a `-log10` threshold (a cell is
+        significant when `-log10(p) >= sig`).
     ptrun : `float` or `int`, default 16
-        Truncation threshold for p-values.
+        P-values smaller than `10^(-ptrun)` are truncated.
     digits : `str`, default `3`
-        the number of significant digits the effect matrix should be rounded.
+        Number of decimals the numeric tables and effect strings are rounded
+        to (a single integer character).
     symbol : `str`, default `★`
-        the unicode symbol used to flag significant findings.
+        The glyph used to flag significant findings in the `star` matrix.
+    pval_mode : {'signed_log', 'unsigned_log', 'raw'}, default 'signed_log'
+        Representation used for the `pvalstring` annotation matrix only:
+        - 'signed_log': signed -log10(p-value).
+        - 'unsigned_log': unsigned -log10(p-value).
+        - 'raw': the untransformed p-value (in [0, 1]).
+        This affects *only* the annotation string; it never changes the numeric
+        tables or the significance mask.
     
     Returns
     -------
-    pval : pd.DataFrame
-        Signed p-value matrix (numeric).
-    effect : pd.DataFrame
-        Masked effect matrix with rounded string entries.
-    star : pd.DataFrame
-        Star annotation matrix for significant results.
-    pvalstring : pd.DataFrame
-        Masked p-value string matrix for annotation.
-    effect_float : pd.DataFrame
-        Raw effect matrix without masking.
-    """
+    pval_signed : `pd.DataFrame`
+        Signed -log10(p-value) matrix (`sign(effect) * -log10 p`). This is the
+        default heatmap colour matrix.
+    pval_unsigned : `pd.DataFrame`
+        Unsigned -log10(p-value) matrix.
+    pval_raw : `pd.DataFrame`
+        Raw (untransformed) p-value matrix, rounded to `digits`.
+    effect : `pd.DataFrame`
+        Effect matrix as strings, masked to `'.'` where non-significant.
+    star : `pd.DataFrame`
+        Star annotation matrix (`symbol` for significant cells).
+    pvalstring : `pd.DataFrame`
+        P-value annotation matrix (strings), rendered per `pval_mode`.
+    effect_float : `pd.DataFrame`
+        Unmasked effect matrix (numeric).
     
-    # checking input
+    Raises
+    ------
+    ValueError
+        If `digits` is not a single character, or `pval_mode` is not one of
+        the supported values.
+    
+    Notes
+    -----
+    The numeric matrices are signed by the effect direction (`sign(effect)`) so
+    a diverging colour map encodes both significance magnitude and effect
+    direction on one scale. The significance mask is unaffected by the choice of
+    numeric representation: because `-log10` is monotonic, `p <= alpha` and
+    `-log10(p) >= -log10(alpha)` select the same cells.
+    """
+    # Validate inputs.
     if len(digits) > 1:
         raise ValueError("`digits` must be interpretable as a single integer, "
                          f"got: {digits}.")
-    # taking the log10
-    if log:
-        pval_full = _nlog10_func(pval, ptrun)
-    else:
-        pval_full = pval.copy()
-    # rounding
+    if pval_mode not in ('signed_log', 'unsigned_log', 'raw'):
+        raise ValueError("`pval_mode` must be one of 'signed_log', "
+                         f"'unsigned_log', 'raw', got: {pval_mode}.")
+    # ### Compute the three numeric p-value tables (signed/unsigned -log10, raw).
+    ndig = int(float(digits))
     dig = '{:.'+digits+'f}'
-    pval = pval_full.round(int(float(digits)))
+    pval_raw = pval.round(ndig)
+    nlog10 = _nlog10_func(pval, ptrun)
+    pval_unsigned = nlog10.round(ndig)
     dir = np.sign(effect)
-    # simply stoaring the float matrix
+    pval_signed = dir * pval_unsigned
+    # ### Keep the unmasked effect matrix and format the effect estimates.
     effect_float = effect.copy()
-    # formatting
     if pd.__version__ < '2.1.0':
         effect = effect.applymap(dig.format).copy()
     else:
         effect = effect.map(dig.format).copy()
-    # scaling
-    pval = dir * pval
-    # if log use larger than
-    if log:
-        # if not significant set to empty
-        effect[pval_full < sig] = '.'
-        effect = effect.astype('str')
-        # adding stars
-        star = effect.copy()
-        star[pval_full >= sig] = symbol
-        # pvalues
-        pvalstring = effect.copy()
-        pvalstring[pval_full >= sig] = pval[pval_full >= sig].astype('str')
-        # if log != True use smaller than
+    # Derive the significance mask (-log10 space; NaN cells fall through both).
+    significant = nlog10 >= sig
+    not_significant = nlog10 < sig
+    # #### Select the annotation representation (`pval_mode` axis).
+    if pval_mode == 'raw':
+        pval_annot = pval_raw
+    elif pval_mode == 'unsigned_log':
+        pval_annot = pval_unsigned
     else:
-        # if not significant set to empty
-        effect[pval_full > sig] = '.'
-        effect = effect.astype('str')
-        # adding stars
-        star = effect.copy()
-        star[pval_full <= sig] = symbol
-        # pvalues
-        pvalstring = effect.copy()
-        pvalstring[pval_full <= sig] = pval[pval_full <= sig].astype('str')
-    
-    # returning
-    return pval, effect, star, pvalstring, effect_float
+        pval_annot = pval_signed
+    # #### Mask non-significant cells and build the star / p-value annotations.
+    effect[not_significant] = '.'
+    effect = effect.astype('str')
+    star = effect.copy()
+    star[significant] = symbol
+    pvalstring = effect.copy()
+    pvalstring[significant] = pval_annot[significant].astype('str')
+    # Return the tables
+    return (pval_signed, pval_unsigned, pval_raw, effect, star, pvalstring,
+            effect_float)
 
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 def calc_matrices(data:pd.DataFrame,
@@ -629,10 +663,17 @@ def calc_matrices(data:pd.DataFrame,
                   outcome_col:str,
                   point_col:str='point',
                   pvalue_col:str='pvalue',
-                  alpha:Real=-1*np.log10(0.05),
+                  alpha:Real=0.05,
                   sig_numbers:int=2,
-                  ptrun:Real=16,
-                  annotate:str | None='star',
+                  ptrun:Real=1e-16,
+                  annotate:Literal['symbol',
+                                   'star',
+                                   'pvalues',
+                                   'pvalues_signed',
+                                   'pvalues_unsigned',
+                                   'pvalues_raw',
+                                   'point_estimates']|None='symbol',
+                  symbol:str='★',
                   without_log:bool=False,
                   mask_na:bool=True,
                   **kwargs:Any,
@@ -659,20 +700,35 @@ def calc_matrices(data:pd.DataFrame,
     pvalue_col : `str`, default 'pvalue'
         Column name with p-values. Note p-values are expected to range between
         0 and 1.
-    alpha : `float` or `int`, default `-1*np.log(0.05)`
-        The significance cut-off.
+    alpha : `float`, default `0.05`
+        The significance cut-off as a raw p-value in (0, 1] (consistent with
+        `volcano`). Converted internally to a -log10 threshold. Values outside
+        (0, 1] raise `InputValidationError`.
     sig_numbers : `int`, default 2
         The number of significant numbers the cell annotations should have.
-    ptrun : `float` or `int`, default 16
-        P-values smaller than 10^(-ptrun) are truncated.
-    annotate : `str`, default 'star'
+    ptrun : `float` or `int`, default 1e-16
+        The truncation threshold as a raw p-value in (0, 1]: p-values smaller
+        than `ptrun` are floored to `ptrun` before the -log10 transform.
+    annotate : `str`, default 'symbol'
         Annotation style to return. Options:
-        - 'star': significance stars
-        - 'pvalues': raw or transformed p-values
-        - 'pointestimates': formatted effect estimates
+        - 'symbol': significance markers using `symbol`.
+        - 'star': **Deprecated** alias for 'symbol' — use 'symbol' instead.
+        - 'pvalues': signed -log10(p-values). **Deprecated** — use
+          'pvalues_signed' instead.
+        - 'pvalues_signed': signed -log10(p-values).
+        - 'pvalues_unsigned': unsigned -log10(p-values).
+        - 'pvalues_raw': the untransformed p-values (in [0, 1]).
+        - 'point_estimates': formatted effect estimates
         - None: returns only numeric matrix without annotations
+        The numeric value matrix is always signed -log10(p-values); only the
+        annotation representation changes with the 'pvalues*' options.
+    symbol : `str`, default `★`
+        The text/unicode glyph used to flag significant findings when
+        `annotate='symbol'` (e.g. `'●'`, `'◆'`, `'*'`).
     without_log : `bool`, default `False`
-        If the p-value should `NOT` be -log10 converted.
+        **Deprecated** and no longer changes behaviour: p-values are always
+        -log10 transformed. Setting it to `True` emits a `DeprecationWarning`.
+        Use the `curated_matrix_value_raw` table for raw p-values.
     mask_na : `bool`, default `True`
         If you want to mask missing results (e.g., replacing NAs by 0 or 1)
     **kwargs
@@ -686,6 +742,8 @@ def calc_matrices(data:pd.DataFrame,
     ------
     ValueError
         If `annotate` is not one of the supported values.
+    InputValidationError
+        If `alpha` is not a raw p-value in (0, 1].
     """
     #### check input
     is_type(data, pd.DataFrame)
@@ -694,9 +752,51 @@ def calc_matrices(data:pd.DataFrame,
     is_type(point_col, str)
     is_type(pvalue_col, str)
     is_type(alpha, (int, float))
+    is_type(ptrun, (int, float))
     is_type(sig_numbers, int)
+    is_type(symbol, str)
     is_type(without_log, bool)
     is_type(mask_na, bool)
+    ### `alpha` is a raw p-value threshold in (0, 1]
+    if not (0 < alpha <= 1):
+        raise InputValidationError(
+            "`alpha` must be a raw p-value in (0, 1] (e.g. 0.05); got: "
+            f"{alpha}. The -log10 convention was removed in v2.3."
+        )
+    ### `ptrun` is a raw p-value truncation threshold in (0, 1]
+    if not (0 < ptrun <= 1):
+        raise InputValidationError(
+            "`ptrun` must be a raw p-value in (0, 1] (e.g. 1e-16); got: "
+            f"{ptrun}. The exponent convention was removed in v2.3."
+        )
+    ### `without_log` is deprecated and no longer changes behaviour
+    if without_log:
+        warnings.warn(
+            "`without_log` is deprecated and will be removed in a future "
+            "release; p-values are now always -log10 transformed. Use the "
+            "`curated_matrix_value_raw` table for raw p-values.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+    ### warn on deprecated annotation aliases
+    deprecated_annot = {
+        UtilsNames.mat_annot_star: UtilsNames.mat_annot_symbol,
+        UtilsNames.mat_annot_pval: UtilsNames.mat_annot_pval_signed,
+    }
+    if annotate in deprecated_annot:
+        warnings.warn(
+            f"`annotate={annotate!r}` is deprecated and will be removed in a "
+            f"future release; use {deprecated_annot[annotate]!r} instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+    ### map the requested annotation onto a p-value representation mode
+    if annotate == UtilsNames.mat_annot_pval_unsigned:
+        pval_mode = 'unsigned_log'
+    elif annotate == UtilsNames.mat_annot_pval_raw:
+        pval_mode = 'raw'
+    else:
+        pval_mode = 'signed_log'
     ### subsetting data
     point_mat, pvalue_mat = _extract(data,
                                      exposure_col=exposure_col,
@@ -705,17 +805,22 @@ def calc_matrices(data:pd.DataFrame,
                                      pvalue_col=pvalue_col,
                                      **kwargs,
                                      )
-    ### formatting data
-    values, annot_effect, annot_star, annot_pval, values_point =\
+    ### formatting data (convert the raw-p `alpha` to a -log10 threshold)
+    sig = -1 * np.log10(alpha)
+    (values, values_unsigned, values_raw, annot_effect, annot_star,
+     annot_pval, values_point) =\
         _format_matrices(
-            point_mat, pvalue_mat, sig=alpha,
-            ptrun=ptrun, digits=str(sig_numbers),
-            log=not without_log,
+            point_mat, pvalue_mat, sig=sig,
+            ptrun=-np.log10(ptrun), digits=str(sig_numbers),
+            symbol=symbol, pval_mode=pval_mode,
         )
     ### selecting the annotation to use
-    if annotate == UtilsNames.mat_annot_star:
+    if annotate in (UtilsNames.mat_annot_symbol, UtilsNames.mat_annot_star):
         annot = annot_star
-    elif annotate == UtilsNames.mat_annot_pval:
+    elif annotate in (UtilsNames.mat_annot_pval,
+                      UtilsNames.mat_annot_pval_signed,
+                      UtilsNames.mat_annot_pval_unsigned,
+                      UtilsNames.mat_annot_pval_raw):
         annot = annot_pval
     elif annotate == UtilsNames.mat_annot_point:
         annot = annot_effect
@@ -725,26 +830,30 @@ def calc_matrices(data:pd.DataFrame,
     else:
         raise ValueError('Incorrect `annotate` value supplied '
                          'Please use: {}'.\
-                         format([UtilsNames.mat_annot_star,
+                         format([UtilsNames.mat_annot_symbol,
+                                 UtilsNames.mat_annot_star,
                                  UtilsNames.mat_annot_pval,
+                                 UtilsNames.mat_annot_pval_signed,
+                                 UtilsNames.mat_annot_pval_unsigned,
+                                 UtilsNames.mat_annot_pval_raw,
                                  UtilsNames.mat_annot_point,
                                  UtilsNames.mat_annot_none,
                                  ]
                                 ))
     ### drop or mask NAs
     if not mask_na:
+        # drop rows/columns containing any missing value
         drop_c = ~values.isna().any(axis=0)
         drop_r = ~values.isna().any(axis=1)
         values_input = values.loc[drop_r, drop_c]
+        values_unsigned_input = values_unsigned.loc[drop_r, drop_c]
+        values_raw_input = values_raw.loc[drop_r, drop_c]
         annot_input = annot.loc[drop_r, drop_c]
-        # Mask with zero if logged
-    elif not without_log:
-        values_input = values.fillna(0, inplace=False)
-        annot_input = annot.fillna('.', inplace=False)
-        annot_input[annot_input == 'nan'] = '.'
-        # Mask with one if not
     else:
-        values_input = values.fillna(1, inplace=False)
+        # fill missing -log10 values with 0 and raw p-values with 1
+        values_input = values.fillna(0, inplace=False)
+        values_unsigned_input = values_unsigned.fillna(0, inplace=False)
+        values_raw_input = values_raw.fillna(1, inplace=False)
         annot_input = annot.fillna('.', inplace=False)
         annot_input[annot_input == 'nan'] = '.'
     ### Return
@@ -753,6 +862,8 @@ def calc_matrices(data:pd.DataFrame,
            UtilsNames.annot_star: annot_star,
            UtilsNames.annot_pval: annot_pval,
            UtilsNames.annot_effect: annot_effect,
+           UtilsNames.value_unsigned_log: values_unsigned_input,
+           UtilsNames.value_raw: values_raw_input,
            UtilsNames.value_original: values,
            UtilsNames.value_point: values_point,
            UtilsNames.source_data: data,
@@ -979,7 +1090,7 @@ def segment_labelled(
         # do we need to apply a transformation first
         if calc_angle_after_trans:
             p1 = list(ax.transData.transform_point((x[0], y[0])))
-            p2 = list(ax.transData.transform_point((y[0], y[1])))
+            p2 = list(ax.transData.transform_point((x[1], y[1])))
             x_trans=[p1[0], p2[0]]
             y_trans=[p1[1], p2[1]]
         else:

plot_misc/volcano.py

@@ -39,8 +39,7 @@ from typing import Any
 
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 def plot_volcano(data:DataFrame, y_column:str, x_column:str,
-                 point_label:str | None = None,
-                 fsize:tuple[float,float] | None = None, adjust:bool=False,
+                 point_label:str | None = None, adjust:bool=False,
                  lim:int=1000, vline:Real=0, alpha:float=1e-5,
                  col_sgnd: str = 'orangered', col_nsgnd: str = 'dimgrey',
                  col_vline: str = 'lightcoral',
@@ -50,6 +49,7 @@ def plot_volcano(data:DataFrame, y_column:str, x_column:str,
                  index_label:list[str] | None = None,
                  font_label: str | None = None,
                  ax:plt.Axes | None = None,
+                 figsize:tuple[float,float] | None = None,
                  label_kwargs_dict:dict[Any,Any] | None = None,
                  scatter_sig_kwargs_dict:dict[Any,Any] | None = None,
                  scatter_nonsig_kwargs_dict:dict[Any,Any] | None = None,
@@ -70,8 +70,6 @@ def plot_volcano(data:DataFrame, y_column:str, x_column:str,
     point_label : `str` or `None`, default `None`
         Column name in `data` to use for point labels. If `None`, no labels
         are added.
-    fsize : `tuple` [`float`, `float`] or `None`, default `None`
-        Figure size in inches (width, height). Ignored if `ax` is provided.
     adjust : `bool`, default `False`
         Whether to apply label de-overlapping using `adjustText`.
     lim : `int`, default 1000
@@ -106,6 +104,8 @@ def plot_volcano(data:DataFrame, y_column:str, x_column:str,
         Font family to use for point labels (e.g. 'monospace', 'Arial').
     ax : `plt.axes` or `None`, default `None`
         Axis object to plot on. If `None`, a new figure and axis are created.
+    figsize : `tuple` [`float`, `float`] or `None`, default `None`
+        Figure size in inches (width, height). Ignored if `ax` is provided.
     label_kwargs_dict : `dict` or `None`, default `None`
         Optional keyword arguments passed to `adjust_text`.
     scatter_sig_kwargs_dict : `dict` or `None`, default `None`
@@ -155,7 +155,7 @@ def plot_volcano(data:DataFrame, y_column:str, x_column:str,
     ### getting figure
     # should we create a figure and axis
     if ax is None:
-        f, ax = plt.subplots(figsize=fsize)
+        f, ax = plt.subplots(figsize=figsize)
     else:
         f = ax.figure
     ### significance level

{plot_misc-2.2.1.dist-info → plot_misc-2.2.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plot-misc
-Version: 2.2.1
+Version: 2.2.2
 Summary: Various plotting templates built on top of matplotlib
 Author-email: A Floriaan Schmidt <floriaanschmidt@gmail.com>
 License-Expression: GPL-3.0-or-later
@@ -48,15 +48,29 @@ Dynamic: license-file
 <img src="https://schmidtaf.gitlab.io/plot-misc/_images/icon.png" alt="plot-misc icon" width="250"/>
 
 # A collection of plotting functions
-__version__: `2.2.1`
+__version__: `2.2.2`
 
 This repository collects plotting modules written on top of `matplotlib`.
-The functions are intended to set up light-touch, basic illustrations that
-can be customised using the standard matplotlib interface via axes and figures.
-Functionality is included to create illustrations commonly used in medical research,
-covering forest plots, volcano plots, incidence matrices/bubble charts,
-illustrations to evaluate prediction models (e.g. feature importance, net benefit, calibration plots),
-and more.
+The functions describe plotting archetypes intended to set up light-touch,
+illustrations that can be customised using the standard matplotlib interface
+via axes and figures.
+Because the implementation is matplotlib-first, the API is consistent with
+matplotlib conventions, and users already familiar with the library will find 
+the learning curve minimal.
+
+The functionality is geared towards illustrations commonly used in biomedical 
+research:
+
+* Bar charts
+* Bubble charts
+* Forest plots (with optional side-tables)
+* Heatmaps (with optional annotations)
+* Incidence matrix plots
+* Machine learning plots (calibration, feature importance, net benefit)
+* Pie charts
+* Survival plots (with optional survival table)
+* Tree/compatibility plots
+* Volcano plots
 
 Please consult the **[documentation](https://SchmidtAF.gitlab.io/plot-misc/)** 
 for plot-misc.

{plot_misc-2.2.1.dist-info → plot_misc-2.2.2.dist-info}/RECORD

@@ -1,17 +1,17 @@
 plot_misc/__init__.py,sha256=ZygAIkX6Nbjag1czWdQa-yP-GM1mBE_9ss21Xh__JFc,34
-plot_misc/_version.py,sha256=-7agX4LcQ0956RU4mY0EYyxYQU9llH7JklZOsqoujdU,22
+plot_misc/_version.py,sha256=jsJ9CNIuUt8dDFB4i0PiBf07nzBU0RtG1CVRQ7TdoQ0,22
 plot_misc/barchart.py,sha256=_4Fj8ypYi6Aehgv4b13Lh1zS1ee4z7OXrGo1P5QBshw,21925
-plot_misc/constants.py,sha256=5DO2NyJUsuHTmjfAU9_TjhXF4FnU09OnfjQ6Dk2R64I,4243
+plot_misc/constants.py,sha256=SABaNQpTRXm4pMF_F6sdsBUvNVyb-WXQLT_YAmUgtuo,4530
 plot_misc/errors.py,sha256=ZbOZg1TbY-7dtPAsJNxIRsjlUfJg0vrx8kRPFsMClaQ,9637
 plot_misc/forest.py,sha256=suIeIY-eGHjzrEb3uargKXLXbSR4kIJ3jhdslaE977I,62508
-plot_misc/heatmap.py,sha256=AQZGDsw9voiI8KBmKGkXT_Rn1w01OI3YcUns0AnwNHI,9887
+plot_misc/heatmap.py,sha256=mON3VNdYZOKsUWARPapepcz3G8_6iCp9_9ZChx2Wcgc,19852
 plot_misc/incidencematrix.py,sha256=BFDLQZT0nEhd8XzCtVVo7mR3s70DwzAMG4-ut7zLal8,18832
 plot_misc/machine_learning.py,sha256=R60w12PxLnEWQ9CNwgQKTF3S1K9JXkC68TgAzr-ib2s,48631
 plot_misc/piechart.py,sha256=nKT9Xr-rP9t8hv6ITb_0594AlzgfnAEdqkyCslLriLc,8613
 plot_misc/survival.py,sha256=-C3s54qfxmIIaMp8ertaNjEiOMraoe0ZpP_5wYUqgKs,25405
-plot_misc/volcano.py,sha256=2FjWvTBR1Jg7Dw8gMbCvAOZ8CBDHwVsUwBhXmzogolM,9341
+plot_misc/volcano.py,sha256=gEUOBYUqOE6fzjrS-2asgxi30EPv_Qjfk23lwCx2Cv4,9347
 plot_misc/example_data/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-plot_misc/example_data/examples.py,sha256=O4shXvWovdPmawHH2dGxBHMQx2hoOioYd0kVrt2zLKk,29727
+plot_misc/example_data/examples.py,sha256=T9jBdtQEbZKEWVoT0SJt8sJ5fTSdXpTqfDA6Y898s0g,31498
 plot_misc/example_data/example_datasets/bar_points.tsv.gz,sha256=ppYQY01DXz77GzSANpwZ9N4zZvxQN5AiHmLsOhZ6cbk,255
 plot_misc/example_data/example_datasets/barchart.tsv.gz,sha256=9TVBaC7yuDuNzOQivTm-UxjmB_jyCfbv1twiL13WpOs,123
 plot_misc/example_data/example_datasets/calibration_bins.tsv.gz,sha256=7BQdx7Tx5zF6wSyyCTwjkSaELKywoykUpelWvxe5pxA,332
@@ -27,9 +27,9 @@ plot_misc/example_data/example_datasets/volcano.tsv.gz,sha256=Cd0J-VeiVPruUqdbPo
 plot_misc/utils/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
 plot_misc/utils/colour.py,sha256=SfhjFcnvTQ-_zfstMqb0vMPyW3-pdPO4G3KJ7-BtQ4E,7715
 plot_misc/utils/formatting.py,sha256=1sGd3d1C5UCtYkeK6RNfJf9joaGbBOfJ8y0lFT5sXD8,14023
-plot_misc/utils/utils.py,sha256=wffVkE0uGPpQX-erEtm4ox_93VlYuBcZfHIdWn-kK6g,44326
-plot_misc-2.2.1.dist-info/licenses/LICENSE,sha256=TAKLZop-WRQ03q1liEZVOMPZOrVwR2ndHSdxC7j1YeU,779
-plot_misc-2.2.1.dist-info/METADATA,sha256=5aI-7qZNl7E7ZC1C1lKjnrZrkKXoPP3jXn10EAlHrIk,5366
-plot_misc-2.2.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-plot_misc-2.2.1.dist-info/top_level.txt,sha256=WyOYx7sloAXvlDvWfFf57ZAf9PnKTWb0zqenkcZKkAE,10
-plot_misc-2.2.1.dist-info/RECORD,,
+plot_misc/utils/utils.py,sha256=5q9-h9OowWVSyas-GS2NSKTakH0kE0A5GM8nfXt6qiA,50779
+plot_misc-2.2.2.dist-info/licenses/LICENSE,sha256=TAKLZop-WRQ03q1liEZVOMPZOrVwR2ndHSdxC7j1YeU,779
+plot_misc-2.2.2.dist-info/METADATA,sha256=Zd_W6_Cc1ZOzGFAe-L5yc4MKUkqvl3GUhX-3DQ-9oDs,5700
+plot_misc-2.2.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+plot_misc-2.2.2.dist-info/top_level.txt,sha256=WyOYx7sloAXvlDvWfFf57ZAf9PnKTWb0zqenkcZKkAE,10
+plot_misc-2.2.2.dist-info/RECORD,,