Classes
FoldChangePlot
Horizontal bar chart of fold changes with significance colouring.
For each numeric feature the class computes a log2 fold change (group_b / group_a) and a Welch's t-test p-value. Multiple-testing correction is applied optionally. Features are then coloured as Up (blue), Down (red), or Not-Significant (grey).
Parameters:
dfTidy DataFrame containing group labels and numeric feature columns.group_colColumn name containing group labels. Must have at least twounique values. When more than two unique values are present, ``group_a`` and ``group_b`` must be specified explicitly.
group_aReference group label (denominator of the fold change).If ``None`` the first unique value (sorted) is used.
group_bComparison group label (numerator). If ``None`` the secondunique value (sorted) is used.
value_colsSubset of numeric columns to analyse. If ``None`` allnumeric columns except ``group_col`` are used.
log2If ``True`` (default) the fold change is expressed in log2scale. If ``False`` the raw ratio is returned instead, and ``fc_threshold`` is interpreted as a raw ratio.
p_value_thresholdSignificance threshold applied to (optionallycorrected) p-values. Default ``0.05``.
fc_thresholdFold-change magnitude threshold for colouring. When``log2=True`` this is an absolute log2FC threshold (default ``1.0``). When ``log2=False`` it is an absolute raw-ratio threshold.
correct_pMultiple-testing correction method forwarded to``statsmodels.stats.multitest.multipletests``. Pass ``None`` to skip correction. Default ``"fdr_bh"``.
Examples: >>> import pandas as pd >>> import numpy as np >>> from metbit.viz.profiling import FoldChangePlot >>> X = pd.DataFrame(np.random.rand(40, 10), columns=[f"f{i}" for i in range(10)]) >>> X["group"] = ["A"]*20 + ["B"]*20 >>> fc = FoldChangePlot(X, group_col="group") >>> fig = fc.plot() >>> tbl = fc.get_table() >>> assert "log2FC" in tbl.columns
Methods
__init__(self, df: pd.DataFrame, group_col: str, group_a: Optional[str]=None, group_b: Optional[str]=None, value_cols: Optional[List[str]]=None, log2: bool=True, p_value_threshold: float=0.05, fc_threshold: float=1.0, correct_p: Optional[str]='fdr_bh')
get_table(self)
Return the per-feature statistics table.
Returns: DataFrame with columns ``feature``, ``log2FC``, ``p_value``, ``p_adj``, and ``label``.
Examples: >>> import pandas as pd, numpy as np >>> from metbit.viz.profiling import FoldChangePlot >>> X = pd.DataFrame(np.random.rand(20, 5), columns=list("ABCDE")) >>> X["g"] = ["X"]*10 + ["Y"]*10 >>> tbl = FoldChangePlot(X, "g").get_table() >>> list(tbl.columns) ['feature', 'log2FC', 'p_value', 'p_adj', 'label']
plot(self, top_n: int=30, sort_by: str='fc', fig_height: int=700, fig_width: int=900, font_size: int=13, title: Optional[str]=None)
Render a horizontal bar chart of fold changes.
Bars are colour-coded: Up (blue), Down (red), NS (grey). Vertical dashed lines mark ±fc_threshold.
Parameters:
top_nMaximum number of features to display (by absolute FC).Default ``30``.
sort_bySorting criterion. One of:``"fc"`` - sort by absolute log2FC (descending), ``"p_value"`` - sort by adjusted p-value (ascending), ``"feature"`` - sort alphabetically. Default ``"fc"``.
fig_heightFigure height in pixels. Default ``700``.fig_widthFigure width in pixels. Default ``900``.font_sizeGlobal font size. Default ``13``.titlePlot title. If ``None`` a default title is generated.Returns: Plotly ``go.Figure`` object.
Examples: >>> import pandas as pd, numpy as np >>> from metbit.viz.profiling import FoldChangePlot >>> X = pd.DataFrame(np.random.rand(40, 6), columns=list("ABCDEF")) >>> X["g"] = ["P"]*20 + ["Q"]*20 >>> fig = FoldChangePlot(X, "g").plot(top_n=6) >>> assert fig is not None
GroupComparison
Side-by-side box/violin plots for a set of selected features.
Renders a subplot grid where each panel shows the distribution of one feature across all groups using a box plot or violin plot. Groups are coloured consistently across all panels.
Parameters:
dfTidy DataFrame containing group labels and numeric feature columns.group_colColumn name containing group labels.feature_colsNumeric columns to visualise. If ``None`` all numericcolumns (excluding ``group_col``) are used.
group_orderExplicit ordering of groups on the x-axis. If ``None``groups are sorted alphabetically.
color_dictMapping of group label to hex/named colour. If ``None``Plotly's default qualitative palette is used.
Examples: >>> import pandas as pd, numpy as np >>> from metbit.viz.profiling import GroupComparison >>> X = pd.DataFrame(np.random.rand(30, 4), columns=list("ABCD")) >>> X["group"] = ["X"]*10 + ["Y"]*10 + ["Z"]*10 >>> gc = GroupComparison(X, group_col="group") >>> fig = gc.plot(features=["A", "B"], n_cols=2) >>> assert fig is not None
Methods
__init__(self, df: pd.DataFrame, group_col: str, feature_cols: Optional[List[str]]=None, group_order: Optional[List[str]]=None, color_dict: Optional[Dict[str, str]]=None)
plot(self, features: Optional[List[str]]=None, n_cols: int=4, plot_type: str='box', show_points: bool=True, fig_height: int=300, fig_width: int=300, font_size: int=12, title: Optional[str]=None)
Create a subplot grid with one box/violin per feature.
Parameters:
featuresFeatures to plot. If ``None`` ``self.feature_cols``(up to 20) are used.
n_colsNumber of subplot columns. Default ``4``.plot_type``"box"`` or ``"violin"``. Default ``"box"``.show_pointsOverlay individual data points. Default ``True``.fig_heightHeight of each individual subplot panel in pixels.Default ``300``.
fig_widthWidth of each individual subplot panel in pixels.Default ``300``.
font_sizeGlobal font size. Default ``12``.titleOverall figure title. If ``None`` no title is set.Returns: Plotly ``go.Figure`` object.
Examples: >>> import pandas as pd, numpy as np >>> from metbit.viz.profiling import GroupComparison >>> X = pd.DataFrame(np.random.rand(20, 3), columns=list("ABC")) >>> X["g"] = ["M"]*10 + ["N"]*10 >>> fig = GroupComparison(X, "g").plot(features=["A", "B"], n_cols=2) >>> assert fig is not None
MetaboliteDashboard
Interactive Dash dashboard combining a volcano plot and group comparison.
The left panel shows an interactive volcano plot powered by :class:`metbit.stats.multitest.VolcanoPlot`. Clicking a point selects that feature and updates the right panel, which shows a box plot for the selected feature across all groups. Dropdowns allow live adjustment of the FC threshold, p-value threshold, and multiple-testing correction method.
Parameters:
dfTidy DataFrame containing group labels and numeric feature columns.group_colColumn name containing group labels.value_colsNumeric columns to analyse. If ``None`` all numeric columns(excluding ``group_col``) are used.
group_orderExplicit ordering of groups. If ``None`` groups are sortedalphabetically.
color_dictMapping of group label to colour. If ``None`` Plotly'sdefault qualitative palette is used.
p_value_thresholdInitial p-value significance threshold. Default``0.05``.
fc_thresholdInitial log2FC threshold. Default ``1.0``.Examples: >>> import pandas as pd, numpy as np >>> from metbit.viz.profiling import MetaboliteDashboard >>> X = pd.DataFrame(np.random.rand(40, 8), columns=[f"m{i}" for i in range(8)]) >>> X["group"] = ["A"]*20 + ["B"]*20 >>> dashboard = MetaboliteDashboard(X, group_col="group") >>> app = dashboard.run_ui() >>> app # doctest: +ELLIPSIS <...Dash...>
Methods
__init__(self, df: pd.DataFrame, group_col: str, value_cols: Optional[List[str]]=None, group_order: Optional[List[str]]=None, color_dict: Optional[Dict[str, str]]=None, p_value_threshold: float=0.05, fc_threshold: float=1.0)
run_ui(self)
Return the configured Dash app object without starting the server.
Returns: Configured ``dash.Dash`` instance.
Examples: >>> import pandas as pd, numpy as np >>> from metbit.viz.profiling import MetaboliteDashboard >>> X = pd.DataFrame(np.random.rand(20, 4), columns=list("ABCD")) >>> X["g"] = ["X"]*10 + ["Y"]*10 >>> app = MetaboliteDashboard(X, group_col="g").run_ui()
run(self, debug: bool=True, port: int=8052)
Launch the Dash server.
Parameters:
debugEnable Dash debug mode. Default ``True``.portTCP port the server listens on. Default ``8052``.Examples: >>> import pandas as pd, numpy as np >>> from metbit.viz.profiling import MetaboliteDashboard >>> X = pd.DataFrame(np.random.rand(20, 4), columns=list("ABCD")) >>> X["g"] = ["X"]*10 + ["Y"]*10 >>> dashboard = MetaboliteDashboard(X, group_col="g") >>> dashboard.run(debug=False, port=8052) # doctest: +SKIP