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

plot_misc/__init__.py

@@ -1 +1,18 @@
+"""
+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 reuse.
+"""
 from ._version import __version__
+
+__citation__ = (
+    "Schmidt AF, Hukerikar N, Finan C, van Vugt M. Effective visualization "
+    "of biomedical data using plot-misc. Bioinformatics Advances. "
+    "2026;6(1):vbag184. https://doi.org/10.1093/bioadv/vbag184"
+)

plot_misc/_version.py

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

plot_misc/example_data/example_datasets/string_data.txt

@@ -0,0 +1 @@
+hi!

plot_misc/example_data/examples.py

@@ -229,12 +229,12 @@ def help(name):
 @dataset
 def dummy_data():
     """A dummy dataset function that returns a small list.
-
+    
     Returns
     -------
     data : `list`
         A list of length 3 with ``['A', 'B', 'C']``
-
+    
     Notes
     -----
     This function is called ``dummy_data`` and has been decorated with a
@@ -253,7 +253,7 @@ def dummy_load_data():
     -------
     str_data : `str`
         A string of data loaded from an example data file.
-
+    
     Notes
     -----
     This function is called ``dummy_data`` and has been decorated with a
@@ -774,34 +774,34 @@ def load_survival_table(**kwargs):
     return table
 
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-@dataset
-def load_forest_preprocessed(**kwargs):
-    """
-    Loads the forest example data with subgroup colour and model shape
-    columns attached, ready for direct use by the forest plot.
+# @dataset
+# def load_forest_preprocessed(**kwargs):
+#     """
+#     Loads the forest example data with subgroup colour and model shape
+#     columns attached, ready for direct use by the forest plot.
     
-    Returns
-    -------
-    pd.DataFrame
-    """
-    # mapping literals (mirrors resources/examples/forestplot.ipynb cell 2)
-    col_dict = {
-        'wo T2DM/CVD': 'orangered',
-        'w T2DM': 'blueviolet',
-        'w T2DM & CVD': 'limegreen',
-    }
-    shape_dict = {
-        'PGS only': 'o',
-        'PGS plus': 's',
-        'PGS extended': 'H',
-    }
-    # base data (already carries the hardcoded ForestNames.y_col)
-    df = load_forest_data(**kwargs)
-    # attach colour and shape columns
-    df['col'] = df['subgroup_name'].map(col_dict)
-    df['shape'] = df['model'].map(shape_dict)
-    # return
-    return df
+#     Returns
+#     -------
+#     pd.DataFrame
+#     """
+#     # mapping literals (mirrors resources/examples/forestplot.ipynb cell 2)
+#     col_dict = {
+#         'wo T2DM/CVD': 'orangered',
+#         'w T2DM': 'blueviolet',
+#         'w T2DM & CVD': 'limegreen',
+#     }
+#     shape_dict = {
+#         'PGS only': 'o',
+#         'PGS plus': 's',
+#         'PGS extended': 'H',
+#     }
+#     # base data (already carries the hardcoded ForestNames.y_col)
+#     df = load_forest_data(**kwargs)
+#     # attach colour and shape columns
+#     df['col'] = df['subgroup_name'].map(col_dict)
+#     df['shape'] = df['model'].map(shape_dict)
+#     # return
+#     return df
 
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 @dataset

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

@@ -26,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

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)

plot_misc/utils/utils.py

@@ -24,7 +24,7 @@ annotate_axis_midpoints(ax, labels, axis='y', gap=6, offset=None, ...)
 calc_angle_points(x, y, radians=False)
     Calculates the angle between two points in degrees or radians.
     
-calc_matrices(data, exposure_col, outcome_col, point_col='point',
+calc_matrices(data, columns, rows, point_col='point',
     pvalue_col='pvalue', ...)
     Creates effect and p-value matrices for heatmap plotting, including
     optional annotation styles and NA masking.
@@ -38,7 +38,7 @@ change_ticks(ax, ticks, labels=None, axis='x', log=False)
 adjust_labels(annotations, axis, min_distance=0.1)
     Adjusts overlapping annotation text to improve legibility.
     
-plot_span(start_span, stop_span, ax, horizontal=True, **kwargs)
+plot_span(start_span, stop_span, ax, horizontal=True, ...)
     Adds a vertical or horizontal span to a matplotlib axis.
     
 segment_labelled(x, y, ax, label=None, ...)
@@ -261,12 +261,6 @@ class MidpointNormalize(mpl.colors.Normalize):
         Central value that maps to 0.5 on the colour scale.
     clip : `bool`, default False
         If True, data outside vmin/vmax is clipped to the endpoints.
-    
-    Methods
-    -------
-    inverse(value)
-        Inverts a normalised value from the [0, 1] scale back to the original
-        data scale.
     """
     def __init__(self, vmin:float | None = None, vmax:float | None = None,
                  vcenter:float | None = None, clip:bool=False):
@@ -284,8 +278,12 @@ class MidpointNormalize(mpl.colors.Normalize):
         else:
             value = np.clip(value, self.vmin, self.vmax)
         x, y = [self.vmin, self.vcenter, self.vmax], [0, 0.5, 1.]
-        return np.ma.masked_array(np.interp(value, x, y,
-                                            left=-np.inf, right=np.inf))
+        # capturing potential mask, and applying to interp
+        value = np.ma.asarray(value, dtype=float)
+        mask = np.ma.getmaskarray(value)
+        result = np.interp(value.filled(np.nan), x, y,
+                           left=-np.inf, right=np.inf)
+        return np.ma.masked_array(result, mask=mask)
     # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     def inverse(self, value):
         y, x = [self.vmin, self.vcenter, self.vmax], [0, 0.5, 1]
@@ -326,6 +324,7 @@ def _update_kwargs(update_dict:dict[Any, Any], **kwargs:Any,
     return new_dict
 
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# NOTE this is not used anymore can be removed
 def _dict_string_argument(partial_match:str, dict_string:dict[Any, str],
                           context:dict[Any,Any],
                           ) -> dict[Any,Any]:
@@ -364,7 +363,11 @@ def _dict_string_argument(partial_match:str, dict_string:dict[Any, str],
     # evaluating object
     for key, value in dict_string.items():
         if isinstance(value, str) and re.match(partial_match, value):
-            dict_string[key] = eval(value, context)
+            dict_string[key] = eval(
+                value,
+                {"__builtins__": {}},
+                context,
+            )
     # return stuff
     return dict_string
 
@@ -473,7 +476,7 @@ def change_ticks(ax:plt.Axes, ticks:list[str], labels:list[str] | None = None,
     # done
 
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-def _extract(data:pd.DataFrame, exposure_col:str, outcome_col:str,
+def _extract(data:pd.DataFrame, columns:str, rows:str,
             point_col:str, pvalue_col:str, dropna:bool=False,
             **kwargs:Any,
             ) -> tuple[pd.DataFrame, pd.DataFrame]:
@@ -481,17 +484,16 @@ def _extract(data:pd.DataFrame, exposure_col:str, outcome_col:str,
     Extract point estimate and p-value matrices from long-format data.
     
     This function takes a long-format DataFrame and returns two pivot tables:
-    one for point estimates and one for p-values. These are indexed by
-    outcome and columned by exposure.
+    one for point estimates and one for p-values.
     
     Parameters
     ----------
     data : `pd.DataFrame`
         Input data in long format with the required columns.
-    exposure_col : `str`
-        Name of the column representing exposure variables.
-    outcome_col : `str`
-        Name of the column representing outcome variables.
+    columns : `str`
+        Name of the column representing column labels.
+    rows : `str`
+        Name of the column representing row labels.
     point_col : `str`
         Name of the column containing point estimates.
     pvalue_col : `str`
@@ -510,22 +512,28 @@ def _extract(data:pd.DataFrame, exposure_col:str, outcome_col:str,
     ------
     ValueError
         If the point and p-value matrices have mismatched shapes.
+    
+    Notes
+    -----
+    Both matrices are sorted alphabetically on the index and on the columns.
+    To retain input order instead, pass ``sort=False``, which is forwarded
+    through `**kwargs` to `pd.DataFrame.pivot_table`
     """
     ### subsetting
     # making sure we do not change the original `data`
     data = data.copy()
     ### getting estimates
-    point = data[[point_col, exposure_col, outcome_col]].copy()
-    pvalue = data[[pvalue_col, exposure_col, outcome_col]].copy()
+    point = data[[point_col, columns, rows]].copy()
+    pvalue = data[[pvalue_col, columns, rows]].copy()
     ### matrix
-    point_mat = point.pivot_table(index=[outcome_col],
-                      columns = exposure_col,
+    point_mat = point.pivot_table(index=[rows],
+                      columns = columns,
                       values = point_col,
                       dropna=dropna,
                       **kwargs,
                       )
-    pvalue_mat = pvalue.pivot_table(index=[outcome_col],
-                      columns = exposure_col,
+    pvalue_mat = pvalue.pivot_table(index=[rows],
+                      columns = columns,
                       values = pvalue_col,
                       dropna=dropna,
                       **kwargs,
@@ -567,9 +575,11 @@ def _format_matrices(effect:pd.DataFrame, pval:pd.DataFrame, sig:float,
         Matrix of p-values as floats (in [0, 1]).
     sig : `float`
         Significance cut-off expressed as a `-log10` threshold (a cell is
-        significant when `-log10(p) >= sig`).
+        significant when `-log10(p) >= sig`). Use `-inf` to disable the
+        significance filter (every non-missing cell is significant).
     ptrun : `float` or `int`, default 16
-        P-values smaller than `10^(-ptrun)` are truncated.
+        P-values smaller than `10^(-ptrun)` are truncated. Use `+inf` to
+        disable truncation (a p-value of exactly 0 maps to `+inf`).
     digits : `str`, default `3`
         Number of decimals the numeric tables and effect strings are rounded
         to (a single integer character).
@@ -659,13 +669,13 @@ def _format_matrices(effect:pd.DataFrame, pval:pd.DataFrame, sig:float,
 
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 def calc_matrices(data:pd.DataFrame,
-                  exposure_col:str,
-                  outcome_col:str,
+                  columns:str,
+                  rows:str,
                   point_col:str='point',
                   pvalue_col:str='pvalue',
-                  alpha:Real=0.05,
+                  alpha:Real | None =0.05,
                   sig_numbers:int=2,
-                  ptrun:Real=1e-16,
+                  ptrun:Real | None = None,
                   annotate:Literal['symbol',
                                    'star',
                                    'pvalues',
@@ -681,36 +691,43 @@ def calc_matrices(data:pd.DataFrame,
     """
     Generate value and annotation matrices for clustered heatmap visualisation.
     
-    This function transforms a long-format DataFrame into heatmap-ready matrices
-    based on statistical results. The output includes both numeric matrices
+    This function transforms a long-format DataFrame into heatmap-ready
+    matrices. The output includes both numeric matrices
     (e.g. signed -log10(p-values)) and string annotations (e.g. significance
     stars, p-values, or effect sizes).
     
     Arguments
     ---------
     data : `pd.DataFrame`
-        Long-format dataframe containing exposure, outcome, point estimate,
-        and p-value columns.
-    exposure_col : `str`
-        Column name indicating the exposure variable.
-    outcome_col : `str`
-        Column name indicating the outcome variable.
+        Long-format dataframe containing the column and row groups, as
+        well as point estimate and p-value columns (representing the matrix
+        values).
+    columns : `str`
+        Column name indicating the column labels.
+    rows : `str`
+        Column name indicating the row labels.
     point_col : `str`, default `point`
         Column name with point estimates.
     pvalue_col : `str`, default 'pvalue'
         Column name with p-values. Note p-values are expected to range between
         0 and 1.
-    alpha : `float`, default `0.05`
+    alpha : `float` or `None`, 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`.
+        (0, 1] raise `InputValidationError`. Set to `None` to disable the
+        significance filter: every non-missing cell is treated as significant
+        and annotated.
     sig_numbers : `int`, default 2
         The number of significant numbers the cell annotations should have.
-    ptrun : `float` or `int`, default 1e-16
+    ptrun : `float`, `int` or `None`, default `None`
         The truncation threshold as a raw p-value in (0, 1]: p-values smaller
-        than `ptrun` are floored to `ptrun` before the -log10 transform.
+        than `ptrun` are floored to `ptrun` before the -log10 transform. When
+        `None` (the default) no truncation is applied and a p-value of exactly
+        0 maps to `+inf` in the -log10 value tables, which can affect heatmap
+        colour scaling.
     annotate : `str`, default 'symbol'
         Annotation style to return. Options:
+        
         - 'symbol': significance markers using `symbol`.
         - 'star': **Deprecated** alias for 'symbol' — use 'symbol' instead.
         - 'pvalues': signed -log10(p-values). **Deprecated** — use
@@ -720,6 +737,7 @@ def calc_matrices(data:pd.DataFrame,
         - '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 `★`
@@ -744,27 +762,32 @@ def calc_matrices(data:pd.DataFrame,
         If `annotate` is not one of the supported values.
     InputValidationError
         If `alpha` is not a raw p-value in (0, 1].
+    
+    Notes
+    -----
+    The rows and columns of the returned matrices retain the order in which
+    they first appear in `data`. Pass ``sort=True`` to sort alphabetically.
     """
     #### check input
     is_type(data, pd.DataFrame)
-    is_type(exposure_col, str)
-    is_type(outcome_col, str)
+    is_type(columns, str)
+    is_type(rows, str)
     is_type(point_col, str)
     is_type(pvalue_col, str)
-    is_type(alpha, (int, float))
-    is_type(ptrun, (int, float))
+    is_type(alpha, (type(None), int, float))
+    is_type(ptrun, (type(None), 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):
+    if (alpha is not None) and 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):
+    if (ptrun is not None) and 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."
@@ -798,20 +821,26 @@ def calc_matrices(data:pd.DataFrame,
     else:
         pval_mode = 'signed_log'
     ### subsetting data
+    new_kwargs = _update_kwargs(update_dict=kwargs,
+                                sort=False,
+                                )
     point_mat, pvalue_mat = _extract(data,
-                                     exposure_col=exposure_col,
-                                     outcome_col=outcome_col,
+                                     columns=columns,
+                                     rows=rows,
                                      point_col=point_col,
                                      pvalue_col=pvalue_col,
-                                     **kwargs,
+                                     **new_kwargs,
                                      )
-    ### formatting data (convert the raw-p `alpha` to a -log10 threshold)
-    sig = -1 * np.log10(alpha)
+    ### formatting data (convert the raw-p `alpha` to a -log10 threshold;
+    ### `alpha=None` disables the significance filter entirely)
+    sig = -np.inf if alpha is None else -1 * np.log10(alpha)
+    ### `ptrun=None` disables truncation (p == 0 maps to +inf)
+    trun = np.inf if ptrun is None else -1 * np.log10(ptrun)
     (values, values_unsigned, values_raw, annot_effect, annot_star,
      annot_pval, values_point) =\
         _format_matrices(
             point_mat, pvalue_mat, sig=sig,
-            ptrun=-np.log10(ptrun), digits=str(sig_numbers),
+            ptrun=trun, digits=str(sig_numbers),
             symbol=symbol, pval_mode=pval_mode,
         )
     ### selecting the annotation to use

plot_misc/volcano.py

@@ -41,8 +41,10 @@ from typing import Any
 def plot_volcano(data:DataFrame, y_column:str, x_column:str,
                  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_sgnd: str | None = 'orangered',
+                 col_nsgnd: str | None = 'dimgrey',
                  col_vline: str = 'lightcoral',
+                 c_col: str | None = None,
                  xlab:str='Point estimate', ylab:str=r'$-log_{10}(pvalue)$',
                  ylim:tuple[float, float] | None = None, msize:Real=10,
                  lsize:Real=5, transparency_ns:Real=0.6,
@@ -79,12 +81,16 @@ def plot_volcano(data:DataFrame, y_column:str, x_column:str,
         The x-position of the vertical line
     alpha : `float`, default 1e-5
         P-value threshold for significance (used on –log10 scale).
-    col_sgnd : `str`, default `orangered`
+    col_sgnd : `str` or `None`, default `orangered`
         The colour for the dots above the significance threshold.
-    col_nsgnd : `str`, default `dimgrey`
+    col_nsgnd : `str` or `None`, default `dimgrey`
         The colour for the dots below the significance threshold.
     col_vline ; `str`, default `lightcoral`
         The colour of the vertical line.
+    c_col : `str` or `None`, default `None`
+        The column name of the colour indicator. Allows for per-point
+        colouring based on a data column. Will internally overrule
+        `col_sgnd` and `col_nsgnd`.
     xlab : `str`, default 'Point estimate'
         x-axis label.
     ylab : `str`, default '-log10(pvalue)'
@@ -131,7 +137,7 @@ def plot_volcano(data:DataFrame, y_column:str, x_column:str,
     points are labelled in a crowded region. Additional options can be passed
     to `adjustText` via `label_kwargs_dict`.
     
-    Please see the module documentation `here <https://pypi.org/project/adjustText/>`_.
+    Please see the `adjustText documentation <https://pypi.org/project/adjustText/>`_.
     """
     FT_FAM = 'font.family'
     # ###### Check input
@@ -140,9 +146,12 @@ def plot_volcano(data:DataFrame, y_column:str, x_column:str,
     is_type(x_column, str)
     is_type(point_label, (str, type(None)))
     is_type(font_label, (type(None), str))
-    is_type(col_sgnd, str)
-    is_type(col_nsgnd, str)
+    is_type(col_sgnd, (type(None), str))
+    is_type(col_nsgnd,(type(None), str))
+    is_type(c_col,(type(None), str))
     is_type(col_vline, str)
+    if c_col is not None and c_col not in data.columns:
+        raise IndexError('`c_col` is not present in data.columns.')
     # map None to dict
     label_kwargs_dict = label_kwargs_dict or {}
     scatter_sig_kwargs_dict = scatter_sig_kwargs_dict or {}
@@ -151,7 +160,11 @@ def plot_volcano(data:DataFrame, y_column:str, x_column:str,
     # raise warning
     if adjust and point_label is None:
         warnings.warn('`adjust` is ignored if `point_label` is None',
-                      SyntaxWarning)
+                      UserWarning, stacklevel=2,)
+    if (col_sgnd is not None or col_nsgnd is not None) and (c_col is not None):
+        warnings.warn('`c_col` overrules `col_sgnd` and `col_nsgnd`. Set these '
+                      'to None to silence this warning.',
+                      UserWarning, stacklevel=2,)
     ### getting figure
     # should we create a figure and axis
     if ax is None:
@@ -170,6 +183,9 @@ def plot_volcano(data:DataFrame, y_column:str, x_column:str,
     above = data[data[y_column] >= threshold]
     xs = above[x_column]
     ys = above[y_column]
+    # update col if needed
+    if c_col is not None:
+        col_sgnd = above[c_col]
     # kwargs
     new_sig_kwargs = _update_kwargs(
         update_dict=scatter_sig_kwargs_dict,
@@ -180,6 +196,9 @@ def plot_volcano(data:DataFrame, y_column:str, x_column:str,
     below = data[data[y_column] < threshold]
     xns = below[x_column]
     yns = below[y_column]
+    # update col if needed
+    if c_col is not None:
+        col_nsgnd = below[c_col]
     # kwargs
     new_nonsig_kwargs = _update_kwargs(
         update_dict=scatter_nonsig_kwargs_dict,

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: plot-misc
-Version: 2.2.2
-Summary: Various plotting templates built on top of matplotlib
+Version: 2.3.1
+Summary: Various plotting archetypes built on top of matplotlib
 Author-email: A Floriaan Schmidt <floriaanschmidt@gmail.com>
 License-Expression: GPL-3.0-or-later
 Project-URL: Homepage, https://gitlab.com/SchmidtAF/plot-misc
@@ -11,17 +11,19 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: Implementation :: PyPy
-Requires-Python: <3.13,>=3.10
+Requires-Python: <3.14,>=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pandas>=1.3
 Requires-Dist: numpy>=1.21
 Requires-Dist: matplotlib>=3.5
 Requires-Dist: scipy>=1.5
-Requires-Dist: statsmodels>=0.1
+Requires-Dist: statsmodels>=0.12
 Requires-Dist: scikit-learn>=1.4
 Requires-Dist: adjustText>=1.3
+Requires-Dist: typing_extensions>=4; python_version < "3.11"
 Provides-Extra: dev
 Requires-Dist: python-build; extra == "dev"
 Requires-Dist: twine; extra == "dev"
@@ -45,10 +47,10 @@ Requires-Dist: numpydoc; extra == "dev"
 Requires-Dist: docutils<0.21; extra == "dev"
 Dynamic: license-file
 
-<img src="https://schmidtaf.gitlab.io/plot-misc/_images/icon.png" alt="plot-misc icon" width="250"/>
+<img src="https://schmidtaf.gitlab.io/plot-misc/_images/fish.png" alt="plot-misc icon" width="250"/>
 
 # A collection of plotting functions
-__version__: `2.2.2`
+__version__: `2.3.1`
 
 This repository collects plotting modules written on top of `matplotlib`.
 The functions describe plotting archetypes intended to set up light-touch,
@@ -75,6 +77,25 @@ research:
 Please consult the **[documentation](https://SchmidtAF.gitlab.io/plot-misc/)** 
 for plot-misc.
 
+## Citation
+
+If you use this package in your research please cite the
+**[paper](https://academic.oup.com/bioinformaticsadvances/article/6/1/vbag184/8721292)**:
+
+```bibtex
+@article{Schmidt:2026,
+  author  = {Schmidt, Amand Floriaan and Hukerikar, Nikita and
+             Finan, Chris and van Vugt, Marion},
+  title   = {Effective visualization of biomedical data using plot-misc},
+  journal = {Bioinformatics Advances},
+  volume  = {6},
+  number  = {1},
+  pages   = {vbag184},
+  doi     = {10.1093/bioadv/vbag184},
+  year    = {2026}
+}
+```
+
 ## Installation 
 The package is available on PyPI, and conda, with the latest source code 
 available on gitlab. 
@@ -144,7 +165,7 @@ branches without reinstalling.
 Alternatively, you can install manually:
 ```bash
 python -m pip install -e .
-python .setup_git_hooks.py
+python .githooks/.setup_git_hooks.py
 ```
 
 #### Git Hooks Configuration
@@ -200,4 +221,8 @@ Please have a look at the examples in
 [resources](https://gitlab.com/SchmidtAF/plot-misc/-/tree/master/resources/examples)
 for some possible recipes. 
 
+## Icon
+
+The icon at the top of this README is a _mandarinfish_, widely regarded as one of
+the most colourful animals on the planet. 
 

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

@@ -1,17 +1,17 @@
-plot_misc/__init__.py,sha256=ZygAIkX6Nbjag1czWdQa-yP-GM1mBE_9ss21Xh__JFc,34
-plot_misc/_version.py,sha256=jsJ9CNIuUt8dDFB4i0PiBf07nzBU0RtG1CVRQ7TdoQ0,22
+plot_misc/__init__.py,sha256=9gmOKQn4BlRPhrNelBhlcHUeUg-RruLhHhO0UaUjRtA,807
+plot_misc/_version.py,sha256=0Ns5BhVD3XOEWhtSUJ76K319NapPiQfZKsWZRt-kZOk,22
 plot_misc/barchart.py,sha256=_4Fj8ypYi6Aehgv4b13Lh1zS1ee4z7OXrGo1P5QBshw,21925
 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=mON3VNdYZOKsUWARPapepcz3G8_6iCp9_9ZChx2Wcgc,19852
+plot_misc/forest.py,sha256=baQVlX4LLnb7AsNw_UPvOLt1eFqVKU0Ov_EM4vb2c9U,61988
+plot_misc/heatmap.py,sha256=EmsVXrDX80rI3IErqBFFYAIbSHnYAWCwtgmurkc8i7U,19855
 plot_misc/incidencematrix.py,sha256=BFDLQZT0nEhd8XzCtVVo7mR3s70DwzAMG4-ut7zLal8,18832
-plot_misc/machine_learning.py,sha256=R60w12PxLnEWQ9CNwgQKTF3S1K9JXkC68TgAzr-ib2s,48631
+plot_misc/machine_learning.py,sha256=8KgOKI1ukTEOgdIqEMpeIjR8IhQ3ubz-nbi6Uy7DJQ4,48679
 plot_misc/piechart.py,sha256=nKT9Xr-rP9t8hv6ITb_0594AlzgfnAEdqkyCslLriLc,8613
-plot_misc/survival.py,sha256=-C3s54qfxmIIaMp8ertaNjEiOMraoe0ZpP_5wYUqgKs,25405
-plot_misc/volcano.py,sha256=gEUOBYUqOE6fzjrS-2asgxi30EPv_Qjfk23lwCx2Cv4,9347
+plot_misc/survival.py,sha256=_fKxaHSLjLU1Pq9KsxVqby5kXhl6QIsTM4sqq3hv6ak,25410
+plot_misc/volcano.py,sha256=4zAC4GH-sC5jJyDeHOTq9-3N-UgSldMKgutFs35KE4g,10298
 plot_misc/example_data/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-plot_misc/example_data/examples.py,sha256=T9jBdtQEbZKEWVoT0SJt8sJ5fTSdXpTqfDA6Y898s0g,31498
+plot_misc/example_data/examples.py,sha256=9F7xuJQGBu0WweoG719NdHPaOJaj5Dd1TzrqJXVC040,31564
 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
@@ -23,13 +23,14 @@ plot_misc/example_data/example_datasets/incidence_matrix_data.tsv.gz,sha256=A5IQ
 plot_misc/example_data/example_datasets/lollipop_data.tsv.gz,sha256=2EivSWOoYOxLKjFHgB86k9ln9xm3elTHd3eUI2tEwpg,820
 plot_misc/example_data/example_datasets/mace_associations.tsv.gz,sha256=oTtSzrOUbOqXap-wmA5QhJxKgj4O5nbpZ964J7AXBcw,1732
 plot_misc/example_data/example_datasets/net_benefit.tsv.gz,sha256=eW9ltgCj0smsq1_rGFbI0bujw4GkECfP89jIMk461iM,1323
+plot_misc/example_data/example_datasets/string_data.txt,sha256=GttBz476DDdb9k0IvA_gJ6cg_vDXrAUUDCof4SABVaI,4
 plot_misc/example_data/example_datasets/volcano.tsv.gz,sha256=Cd0J-VeiVPruUqdbPoMOCqDpOKZthITfKEKybsZ0qU8,41139
 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=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,,
+plot_misc/utils/formatting.py,sha256=RRXCSlGBv5SkshfZPnURcYy_QV9Zyu_ApbMdWxWRkAE,14018
+plot_misc/utils/utils.py,sha256=Ydu3TVwz48K6FhqSjFg0CbagJp0WRQbTRVgn6BQetfA,52113
+plot_misc-2.3.1.dist-info/licenses/LICENSE,sha256=TAKLZop-WRQ03q1liEZVOMPZOrVwR2ndHSdxC7j1YeU,779
+plot_misc-2.3.1.dist-info/METADATA,sha256=ZAlUxBejWaIsGMzbQW5szU_pzuBSWWFZ32OQkzJ7WR8,6498
+plot_misc-2.3.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+plot_misc-2.3.1.dist-info/top_level.txt,sha256=WyOYx7sloAXvlDvWfFf57ZAf9PnKTWb0zqenkcZKkAE,10
+plot_misc-2.3.1.dist-info/RECORD,,

{plot_misc-2.2.2.dist-info → plot_misc-2.3.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (82.0.1)
+Generator: setuptools (84.0.0)
 Root-Is-Purelib: true
 Tag: py3-none-any