spacr.plot
==========

.. py:module:: spacr.plot






Module Contents
---------------

.. py:function:: plot_image_mask_overlay(file, channels, cell_channel, nucleus_channel, pathogen_channel, organelle_channel=None, figuresize=10, percentiles=(2, 98), thickness=3, save_pdf=True, mode='outlines', export_tiffs=False, all_on_all=False, all_outlines=False, filter_dict=None)

   Plot image and mask overlays.


.. py:function:: plot_image_mask_overlay_magenta_outlines(file, channels, cell_channel, nucleus_channel, pathogen_channel, figuresize=10, percentiles=(2, 98), thickness=3, save_pdf=True, mode='outlines', export_tiffs=False, all_on_all=False, all_outlines=False, filter_dict=None)

   Plot image and mask overlays.


.. py:function:: plot_cellpose4_output(batch, masks, flows, cmap='inferno', figuresize=10, nr=1, print_object_number=True)

   Display per-channel images, label mask and flow field for Cellpose v4 outputs.

   :param batch: Image batch of shape ``(N, H, W, C)``.
   :param masks: Label masks, one per image.
   :param flows: Flow arrays, one per image.
   :param cmap: Colormap for image channels. Default ``'inferno'``.
   :param figuresize: Base figure size. Default ``10``.
   :param nr: Maximum number of images to plot. Default ``1``.
   :param print_object_number: If True, annotate each object with its
       label ID. Default ``True``.
   :returns: None


.. py:function:: plot_organelle_output(img_batch, masks, settings, cmap='inferno', figuresize=10, nr=1, print_object_number=True)

   Plot organelle segmentation results: raw channel, label mask, morphology-specific diagnostic.

   :param img_batch: Single-channel image batch of shape ``(N, H, W)``.
   :param masks: Label masks, one per image.
   :param settings: Organelle settings dict; ``organelle_morphology``
       and ``organelle_method`` drive the diagnostic panel.
   :param cmap: Colormap for the raw channel. Default ``'inferno'``.
   :param figuresize: Base figure size. Default ``10``.
   :param nr: Maximum number of images to plot. Default ``1``.
   :param print_object_number: If True, annotate each object with its
       label ID. Default ``True``.
   :returns: None


.. py:function:: plot_masks(batch, masks, flows, cmap='inferno', figuresize=10, nr=1, file_type='.npz', print_object_number=True)

   Display per-channel images, label masks and flow fields for a batch.

   :param batch: Image batch — shape ``(N, H, W, C)`` or a single image
       of shape ``(H, W, C)``.
   :param masks: Label masks, one per image (list or ndarray).
   :param flows: Flow arrays, one per image.
   :param cmap: Colormap for image channels. Default ``'inferno'``.
   :param figuresize: Base figure size. Default ``10``.
   :param nr: Maximum number of images to plot. Default ``1``.
   :param file_type: Source file type of ``flows`` — ``'png'`` selects
       the first element of each flow entry. Default ``'.npz'``.
   :param print_object_number: If True, annotate each object with its
       label ID. Default ``True``.
   :returns: None


.. py:function:: generate_mask_random_cmap(mask)

   Return a random ``ListedColormap`` sized to the labels in ``mask``.

   :param mask: Label mask array (0 = background).
   :returns: Random colormap where index 0 is black and remaining
       entries are random opaque RGBA colours.


.. py:function:: random_cmap(num_objects=100)

   Return a random ``ListedColormap`` with ``num_objects + 1`` colours.

   :param num_objects: Number of foreground colours to generate.
       Default ``100``.
   :returns: Colormap with index 0 = black and remaining indices random
       opaque RGBA colours.


.. py:function:: plot_images_and_arrays(folders, lower_percentile=1, upper_percentile=99, threshold=1000, extensions=None, overlay=False, max_nr=None, randomize=True)

   Show side-by-side images and arrays found across multiple folders.

   Each image is either percentile-normalised (values below
   ``threshold``) or shown as a label mask. Optionally overlays object
   outlines from a matching mask file.

   :param folders: Folders to scan for image/array files.
   :param lower_percentile: Lower percentile clip. Default ``1``.
   :param upper_percentile: Upper percentile clip. Default ``99``.
   :param threshold: Values <= threshold are treated as label data
       instead of intensity. Default ``1000``.
   :param extensions: File extensions to include.
       Default ``['.npy', '.tif', '.tiff', '.png']``.
   :param overlay: If True, overlay object outlines. Default ``False``.
   :param max_nr: Maximum number of key groups to plot.
   :param randomize: If True, shuffle key order before plotting.
       Default ``True``.
   :returns: None


.. py:function:: plot_arrays(src, figuresize=10, cmap='inferno', nr=1, normalize=True, q1=1, q2=99)

   Plot random ``.npy`` / ``.npz`` arrays from ``src``, one channel per subplot.

   :param src: Directory or single ``.npy``/``.npz`` path.
   :param figuresize: Base figure size. Default ``10``.
   :param cmap: Matplotlib colormap. Default ``'inferno'``.
   :param nr: Maximum number of arrays to plot. Default ``1``.
   :param normalize: If True, percentile-normalise before display.
       Default ``True``.
   :param q1: Lower percentile for normalisation. Default ``1``.
   :param q2: Upper percentile for normalisation. Default ``99``.
   :returns: None


.. py:function:: plot_merged(src, settings)

   Show multi-channel image stacks with per-object outlines overlaid.

   :param src: Folder containing ``.npy`` merged stacks.
   :param settings: Plot settings dict — includes channel/mask dims,
       overlay colours, normalisation, filter and object-count keys.
   :returns: The last generated ``Figure`` when ``settings['nr']`` is
       exceeded; otherwise ``None``.


.. py:function:: generate_plate_heatmap(df, plate_number, variable, grouping, min_max, min_count)

   Aggregate a well-level DataFrame into a plate-shaped heatmap.

   :param df: Long-format DataFrame with a ``prc`` (plate_row_column)
       identifier and the requested ``variable`` column.
   :param plate_number: Plate ID selecting the subset to display.
   :param variable: Column to aggregate. Ignored when
       ``grouping='count'``.
   :param grouping: Aggregation — ``'count'``, ``'mean'`` or ``'sum'``.
   :param min_max: Colour scale spec — ``'all'``, ``'allq'``, or a
       two-element list ``[vmin, vmax]`` (floats treated as quantiles).
   :param min_count: Drop wells with fewer than this many rows.
   :returns: ``(plate_map, (vmin, vmax))`` — the pivoted matrix and
       the colour-limit tuple.
   :raises ValueError: if ``grouping`` is not one of the accepted values.
   :raises KeyError: if ``variable`` is missing and required.


.. py:function:: plot_plates(df, variable, grouping, min_max, cmap, min_count=0, verbose=True, dst=None)

   Grid every plate in ``df`` as its own heatmap panel.

   :param df: Long-format DataFrame with a ``prc`` identifier.
   :param variable: Column to aggregate (see :func:`generate_plate_heatmap`).
   :param grouping: Aggregation type — ``'count'``, ``'mean'``, ``'sum'``.
   :param min_max: Colour-scale spec passed through per plate.
   :param cmap: Matplotlib colormap name or object.
   :param min_count: Drop wells with fewer than this many rows.
   :param verbose: If True, call ``plt.show()``. Default ``True``.
   :param dst: If given, save the figure as ``plate_heatmap_<n>.pdf``
       under this folder.
   :returns: The generated ``Figure``.


.. py:function:: print_mask_and_flows(stack, mask, flows, overlay=True, max_size=1000, thickness=2)

   Show a single image, its label mask (optionally outlined) and flow image.

   :param stack: Original 2D image or ``(H, W, C)`` stack.
   :param mask: Label mask matching ``stack`` spatially.
   :param flows: Optional list of flow arrays; skipped when ``None``.
   :param overlay: If True, draw mask contours over the image instead
       of showing the mask alone. Default ``True``.
   :param max_size: Downsample any dimension exceeding this size.
       Default ``1000``.
   :param thickness: Contour line thickness in pixels. Default ``2``.
   :returns: None


.. py:function:: plot_resize(images, resized_images, labels, resized_labels)

   Show original vs. resized image/label pairs in a 2x2 grid.

   :param images: Sequence of original images (first element shown).
   :param resized_images: Sequence of resized images.
   :param labels: Sequence of original label arrays.
   :param resized_labels: Sequence of resized label arrays.
   :returns: None


.. py:function:: normalize_and_visualize(image, normalized_image, title='')

   Utility function for visualization


.. py:function:: visualize_masks(mask1, mask2, mask3, title='Masks Comparison')

   Show three masks side by side with random colormaps.

   :param mask1: First label mask.
   :param mask2: Second label mask.
   :param mask3: Third label mask.
   :param title: Figure suptitle. Default ``"Masks Comparison"``.
   :returns: None


.. py:function:: visualize_cellpose_masks(masks, titles=None, filename=None, save=False, src=None)

   Display an arbitrary set of Cellpose-style label masks side by side.

   :param masks: Sequence of label mask arrays.
   :param titles: Titles paired with ``masks``. Falls back to
       ``'Mask 1'``, ``'Mask 2'``, ...
   :param filename: Used in the figure suptitle and, if saving, as the
       PDF filename.
   :param save: If True, save under ``src/results/<filename>.pdf``.
       Default ``False``.
   :param src: Root folder for saving. Defaults to the current working
       directory.
   :returns: None
   :raises AssertionError: if ``titles`` and ``masks`` have different
       lengths.


.. py:function:: plot_comparison_results(comparison_results)

   Plot Jaccard, Dice, boundary-F1 and average-precision distributions per comparison.

   :param comparison_results: Iterable of dicts with per-file metrics
       (each key ending in ``jaccard``/``dice``/``boundary_f1``/
       ``average_precision``).
   :returns: The generated ``Figure``.


.. py:function:: plot_object_outlines(src, objects=None, channels=None, max_nr=10)

   Overlay mask outlines on the matching channel image for each object type.

   :param src: Experiment root; ``masks/<object>_mask_stack`` and
       channel folders live directly under it.
   :param objects: Object types to plot. Default
       ``['nucleus', 'cell', 'pathogen']``.
   :param channels: Channel indices paired with ``objects`` (channel
       folders are named ``<channel + 1>``). Default ``[0, 1, 2]``.
   :param max_nr: Maximum number of images to plot per object.
       Default ``10``.
   :returns: None


.. py:function:: plot_histogram(df, column, dst=None)

   Plot a histogram of ``df[column]`` and optionally save it as PDF.

   :param df: DataFrame containing ``column``.
   :param column: Column to plot.
   :param dst: If set, save under ``<dst>/<column>_histogram.pdf``.
   :returns: None


.. py:function:: plot_lorenz_curves(csv_files, name_column='grna_name', value_column='count', remove_keys=None, x_lim=None, y_lim=None, remove_outliers=False, save=True)

   Overlay Lorenz curves from multiple gRNA count CSVs with per-plate Gini coefficients.

   :param csv_files: Paths to per-plate CSVs, each with columns
       ``name_column`` and ``value_column``.
   :param name_column: Identifier column used for outlier filtering.
       Default ``'grna_name'``.
   :param value_column: Column whose distribution is analysed.
       Default ``'count'``.
   :param remove_keys: Names to exclude before analysis.
   :param x_lim: X-axis limits ``[lo, hi]``. Default ``[0.0, 1]``.
   :param y_lim: Y-axis limits ``[lo, hi]``. Default ``[0, 1]``.
   :param remove_outliers: If True, drop names whose per-well count
       falls outside a 1.5*IQR window. Default ``False``.
   :param save: If True, save the figure alongside the first CSV under
       ``results/lorenz_curve_with_gini.pdf``. Default ``True``.
   :returns: None


.. py:function:: plot_permutation(permutation_df)

   Plot a horizontal bar chart of permutation feature importances with error bars.

   :param permutation_df: DataFrame with columns ``feature``,
       ``importance_mean`` and ``importance_std``.
   :returns: The generated ``Figure``.


.. py:function:: plot_feature_importance(feature_importance_df)

   Plot a horizontal bar chart of raw feature importances.

   :param feature_importance_df: DataFrame with columns ``feature`` and
       ``importance``.
   :returns: The generated ``Figure``.


.. py:function:: read_and_plot__vision_results(base_dir, y_axis='accuracy', name_split='_time', y_lim=None)

   Aggregate vision-model test CSVs under ``base_dir`` and plot mean score per model.

   :param base_dir: Root directory containing ``*_test_result.csv``
       files nested per epoch.
   :param y_axis: Metric column to average. Default ``'accuracy'``.
   :param name_split: Substring that splits filename into model name
       and epoch info. Default ``'_time'``.
   :param y_lim: Y-axis limits ``[lo, hi]``. Default ``[0.8, 0.9]``.
   :returns: None


.. py:function:: jitterplot_by_annotation(src, x_column, y_column, plot_title='Jitter Plot', output_path=None, filter_column=None, filter_values=None)

   Read measurements + annotation from a spacr DB and plot a class-balanced jitter plot.

   :param src: Path to a spacr experiment directory containing
       ``measurements/measurements.db``.
   :param x_column: Column used as grouping variable (x-axis).
   :param y_column: Numeric column plotted on the y-axis.
   :param plot_title: Title for the plot. Default ``'Jitter Plot'``.
   :param output_path: If set, save the figure to this path; otherwise
       show it.
   :param filter_column: Optional column (or list of columns) to filter
       rows on before plotting.
   :param filter_values: Values (or list of value lists) accepted per
       ``filter_column``.
   :returns: Balanced ``DataFrame`` used for the plot.
   :raises KeyError: if required plate/row/col columns are missing.


.. py:function:: create_grouped_plot(df, grouping_column, data_column, graph_type='bar', summary_func='mean', order=None, colors=None, output_dir='./output', save=False, y_lim=None, error_bar_type='std')

   Plot grouped data with automatic normality-aware pairwise statistics.

   Runs D'Agostino normality per group, chooses the appropriate
   pairwise test (t-test / Mann-Whitney / ANOVA / Kruskal), adds Tukey
   HSD post-hoc when appropriate, renders the requested plot type and
   optionally persists both plot and stats to ``output_dir``.

   :param df: Source DataFrame.
   :param grouping_column: Categorical grouping variable.
   :param data_column: Numeric column to summarise.
   :param graph_type: One of ``'bar'``, ``'violin'``, ``'jitter'``,
       ``'box'``, ``'jitter_box'``. Default ``'bar'``.
   :param summary_func: Summary function for bar plots. Default
       ``'mean'``.
   :param order: Explicit group ordering. Default: alphabetical.
   :param colors: Colour palette; falls back to a HUSL palette.
   :param output_dir: Save location when ``save=True``.
   :param save: If True, save the plot and per-comparison stats CSV.
   :param y_lim: Two-element y-axis limits.
   :param error_bar_type: ``'std'`` or ``'sem'``. Default ``'std'``.
   :returns: None (side-effects: plot displayed, files written).
   :raises ValueError: if ``error_bar_type`` is not recognised.


.. py:class:: spacrGraph(df, grouping_column, data_column, graph_type='bar', summary_func='mean', order=None, colors=None, output_dir='./output', save=False, y_lim=None, log_y=False, log_x=False, error_bar_type='std', remove_outliers=False, theme='pastel', representation='object', paired=False, all_to_all=True, compare_group=None, graph_name=None)

   Grouped plot + statistical-test helper for spacr experiment DataFrames.

   Wraps preprocessing (aggregation by object / well / plate), normality
   and variance testing, group-wise pairwise stats, and plot rendering
   (bar / violin / jitter / box / jitter_box) in a single object whose
   output can optionally be persisted alongside a CSV of stats.

   :param df: Input DataFrame.
   :param grouping_column: Categorical grouping variable.
   :param data_column: Metric column (or list of columns) to summarise.
   :param graph_type: Plot type. Default ``'bar'``.
   :param summary_func: Aggregator for well/plate level. Default ``'mean'``.
   :param order: Explicit ordering of groups.
   :param colors: Optional colour palette.
   :param output_dir: Save location when ``save=True``.
   :param save: If True, persist plot and stats.
   :param y_lim: Two-element y-axis limits.
   :param log_y: Use log scale for y-axis.
   :param log_x: Use log scale for x-axis.
   :param error_bar_type: ``'std'`` or ``'sem'``. Default ``'std'``.
   :param remove_outliers: Drop 1.5*IQR outliers per group before plotting.
   :param theme: Seaborn palette name. Default ``'pastel'``.
   :param representation: Aggregation level — ``'object'``, ``'well'``
       or ``'plate'``. Default ``'object'``.
   :param paired: Treat groups as paired samples where applicable.
   :param all_to_all: Run every pairwise comparison; ``False`` compares
       each group to ``compare_group``.
   :param compare_group: Reference group when ``all_to_all=False``.
   :param graph_name: Prefix for saved file names.


   .. py:attribute:: df


   .. py:attribute:: grouping_column


   .. py:attribute:: order


   .. py:attribute:: data_column


   .. py:attribute:: graph_type
      :value: 'bar'



   .. py:attribute:: summary_func
      :value: 'mean'



   .. py:attribute:: colors
      :value: None



   .. py:attribute:: output_dir
      :value: './output'



   .. py:attribute:: save
      :value: False



   .. py:attribute:: error_bar_type
      :value: 'std'



   .. py:attribute:: remove_outliers
      :value: False



   .. py:attribute:: theme
      :value: 'pastel'



   .. py:attribute:: representation
      :value: 'object'



   .. py:attribute:: paired
      :value: False



   .. py:attribute:: all_to_all
      :value: True



   .. py:attribute:: compare_group
      :value: None



   .. py:attribute:: y_lim
      :value: None



   .. py:attribute:: graph_name
      :value: None



   .. py:attribute:: log_x
      :value: False



   .. py:attribute:: log_y
      :value: False



   .. py:attribute:: results_df


   .. py:attribute:: sns_palette
      :value: None



   .. py:attribute:: fig
      :value: None



   .. py:attribute:: results_name
      :value: '___'



   .. py:attribute:: raw_df


   .. py:method:: preprocess_data()

      Preprocess the data: remove NaNs, optionally ensure 'plateID' column is created,
      then group by either 'prc', 'plateID', or do no grouping at all if representation == 'object'.



   .. py:method:: remove_outliers_from_plot()

      Remove outliers from the plot but keep them in the data.



   .. py:method:: perform_normality_tests()

      Perform normality tests for each group and data column.



   .. py:method:: perform_levene_test(unique_groups)

      Return Levene's test statistic and p-value for the current data column across groups.

      :param unique_groups: Groups to compare.
      :returns: ``(statistic, p_value)`` tuple.



   .. py:method:: perform_statistical_tests(unique_groups, is_normal)

      Perform statistical tests separately for each data column.



   .. py:method:: perform_posthoc_tests(is_normal, unique_groups)

      Perform post-hoc tests for multiple groups based on all_to_all flag.



   .. py:method:: create_plot(ax=None)

      Create and display the plot based on the chosen graph type.



   .. py:method:: get_results()

      Return the results dataframe.



   .. py:method:: get_figure()

      Return the generated figure.



.. py:function:: plot_data_from_db(settings)

   Read one or more measurement DBs, annotate conditions and render a ``spacrGraph`` plot.

   Concatenates results across source directories, derives the
   ``recruitment`` column if requested, drops missing rows, then hands
   the data to :class:`spacrGraph` for statistics + plotting.

   :param settings: Settings dict. See
       ``settings.set_default_plot_data_from_db`` for accepted keys
       (notably ``src``, ``database``, ``table_names``, ``data_column``,
       ``grouping_column``, ``graph_type``, ``graph_name``).
   :returns: The plotted DataFrame, or ``None`` when the requested data
       or grouping column is missing.
   :raises ValueError: if ``src`` is neither a string nor a list.


.. py:function:: plot_data_from_csv(settings)

   Load per-plate CSVs, filter/outlier-clean and render a ``spacrGraph`` plot.

   :param settings: Settings dict — see
       ``settings.get_plot_data_from_csv_default_settings`` for keys
       (``src``, ``data_column``, ``grouping_column``, ``keep_groups``,
       ``remove_outliers``, ``graph_type``, ``graph_name``, ...).
   :returns: ``(fig, results_df, df)`` — the figure, stats DataFrame
       and plotted DataFrame.
   :raises ValueError: if ``src`` is not a string or list.


.. py:function:: plot_region(settings)

   Render mask overlay, cropped PNG grid and activation-map grid for one FOV.

   Reads the FOV's merged NPY, resolves its PNG crops and activation
   maps from the measurements and activation DBs, and writes three PDFs
   under ``<src>/results/<name>/`` when possible.

   :param settings: Settings dict with ``src``, ``name``, ``channels``,
       ``cell_channel``, ``nucleus_channel``, ``pathogen_channel``,
       ``percentiles``, ``activation_mode``, ``activation_db``,
       ``mode``, ``export_tiffs``.
   :returns: Tuple ``(fig_mask_overlay, fig_png_grid,
       fig_activation_grid)`` — any element may be ``None`` when the
       corresponding assets were not found.


.. py:function:: plot_image_grid(image_paths, percentiles)

   Render a square grid of percentile-normalised images with a black background.

   :param image_paths: Image files to display; extra tiles are filled
       black.
   :param percentiles: Two-element percentile pair used to normalise
       each channel.
   :returns: The generated ``Figure``.


.. py:function:: overlay_masks_on_images(img_folder, normalize=True, resize=True, save=False, plot=False, thickness=2)

   Overlay ``masks/*`` outlines onto matching images from ``img_folder``.

   :param img_folder: Folder containing images; masks live in
       ``img_folder/masks`` with matching filenames.
   :param normalize: If True, percentile-normalise images before
       blending. Default ``True``.
   :param resize: If True, resize the blended overlay to 1000x1000.
       Default ``True``.
   :param save: If True, write PNGs to ``img_folder/overlay/``.
       Default ``False``.
   :param plot: If True, show each overlay via matplotlib.
       Default ``False``.
   :param thickness: Contour line thickness in pixels. Default ``2``.
   :returns: None


.. py:function:: graph_importance(settings)

   Concatenate feature-importance CSVs and hand off to :class:`spacrGraph` for plotting.

   :param settings: Settings dict with ``csvs`` (single path or list),
       ``grouping_column``, ``data_column``, ``graph_type``, ``save``.
   :returns: None (side-effects: plot shown, artefacts saved).


.. py:function:: plot_proportion_stacked_bars(settings, df, group_column, bin_column, prc_column='prc', level='object', cmap='viridis')

   Plot stacked proportion bars per group with chi-squared and pairwise stats.

   :param settings: Settings dict — ``verbose`` toggles pairwise
       chi-squared verbosity.
   :param df: Long-format DataFrame with categorical ``group_column``
       and ``bin_column``.
   :param group_column: Group axis of the stacked bars.
   :param bin_column: Categorical column stacked within each bar.
   :param prc_column: Per-well identifier used when aggregating at the
       well or plate level. Default ``'prc'``.
   :param level: Aggregation level — ``'object'`` for direct counts, or
       ``'well'`` / ``'plateID'`` for per-well means with SD bars.
   :param cmap: Matplotlib colormap. Default ``'viridis'``.
   :returns: ``(results_df, pairwise_results, fig)`` — chi-squared
       summary, pairwise comparison table and the plot figure.


.. py:function:: create_venn_diagram(file1, file2, gene_column='gene', filter_coeff=0.1, save=True, save_path=None)

   Compute a two-set gene overlap from CSVs and draw its Venn diagram.

   :param file1: First CSV file.
   :param file2: Second CSV file.
   :param gene_column: Column identifying genes. Default ``'gene'``.
   :param filter_coeff: Threshold on the ``coefficient`` column —
       positive filters ``> threshold``, negative filters ``< threshold``.
   :param save: If True, save as PDF; requires ``save_path``.
   :param save_path: Output PDF path when ``save`` is True.
   :returns: ``{'overlap', 'unique_to_file1', 'unique_to_file2'}`` lists.
   :raises ValueError: if ``save`` is True but ``save_path`` is missing.


.. py:function:: volcano_plot(data: Union[str, pandas.DataFrame], *, fold_change_col: str, p_value_col: str, name_col: Optional[str] = None, x_transform: str = 'none', y_transform: str = '-log10', fold_change_threshold: Optional[float] = None, p_value_threshold: Optional[float] = None, annotate: bool = True, annotate_max: Optional[int] = None, point_size: float = 20.0, alpha: float = 0.7, figsize: Tuple[float, float] = (8.0, 6.0), title: Optional[str] = None, xlim: Optional[Tuple[float, float]] = None, ylim: Optional[Tuple[float, float]] = None, threshold_line_kwargs: Optional[dict] = None, scatter_kwargs: Optional[dict] = None, text_kwargs: Optional[dict] = None, save_path: Optional[str] = None, show: bool = True, ax: Optional[matplotlib.pyplot.Axes] = None, sheet_name: Union[int, str] = 0) -> Tuple[matplotlib.pyplot.Figure, matplotlib.pyplot.Axes, list]

   Read a table (CSV/TSV/XLS/XLSX or a DataFrame) and render a volcano plot.

   Auto-detects file type from extension (.csv, .tsv/.tab, .xls/.xlsx)
   and applies the requested x/y transforms before drawing.

   :param data: Path to table file or a pandas ``DataFrame``.
   :param fold_change_col: Column of raw fold change (or logFC when
       ``x_transform='none'``).
   :param p_value_col: Column of p-values.
   :param name_col: Optional column supplying point labels.
   :param x_transform: One of ``'none'``, ``'log2'``, ``'log10'``,
       ``'ln'``. Use ``'none'`` when the column already stores logFC
       (may be negative).
   :param y_transform: One of ``'none'``, ``'-log10'``, ``'-ln'``,
       ``'log10'``, ``'ln'``. Default ``'-log10'``.
   :param fold_change_threshold: Threshold on x — in plotted units when
       ``x_transform='none'``, otherwise in raw FC units.
   :param p_value_threshold: Threshold on raw p; drawn as a dashed
       horizontal line in plotted units.
   :param annotate: Annotate significant points when a name column is
       supplied.
   :param annotate_max: Cap on the number of annotated points (highest
       y first).
   :param point_size: Scatter marker size.
   :param alpha: Scatter marker alpha.
   :param figsize: Figure size in inches.
   :param title: Optional figure title.
   :param xlim: Optional x-axis limits.
   :param ylim: Optional y-axis limits.
   :param threshold_line_kwargs: Extra kwargs for threshold lines.
   :param scatter_kwargs: Extra kwargs for the scatter call.
   :param text_kwargs: Extra kwargs for label texts.
   :param save_path: If given, save the figure to this path.
   :param show: Call ``plt.show()`` at the end. Default ``True``.
   :param ax: Existing axes to draw on; a new figure is created if None.
   :param sheet_name: Excel sheet index/name for .xls/.xlsx inputs.
   :returns: ``(fig, ax, hits)`` where ``hits`` are the labels drawn.
   :raises ValueError: on unknown transforms, or numeric columns that
       cannot be coerced.


