Plotting

BasePlotter

BasePlotter(dpi=150, prefix='')

plot

plot(*args, **kwargs)

Wrapper that handles styling, delegates to :meth:plot_func, and saves/shows the figure.

All keyword arguments not consumed by plot_func are forwarded. Extra keys recognised here:

• file_name — destination path; if None the figure is shown interactively.
• prefix — prepended to file_name (default from self.prefix).
• dpi — resolution (default from self.dpi).

Returns:

Type	Description
dict or None	The info dict returned by plot_func.

handle_colors

handle_colors(
    palette: str = "deep",
    alt_palette: str = "Spectral",
    n_colors_used: int = 10,
    warn_when_switch=True,
)

Return a list of colours from palette, switching to alt_palette if needed.

Parameters:

Name	Type	Description	Default
palette	str	Seaborn palette name, by default "deep".	'deep'
alt_palette	str	Fallback palette when palette has too few colours, by default "Spectral".	'Spectral'
n_colors_used	int	Minimum number of distinct colours required, by default 10.	10
warn_when_switch	bool	Emit a warning when the palette is switched, by default True.	True

Returns:

Type	Description
list	A list of RGB tuples.

plot_clustermap

plot_clustermap(
    data: DataFrame,
    model_groups: Optional[Dict[str, str]] = None,
    group_list: Optional[List[str]] = None,
    row_category: Optional[str] = None,
    cbar_label: Optional[str] = None,
    top_ele_ratio: float = 0.1,
    row_cluster: bool = False,
    row_dendrogram: bool = True,
    palette: str = "muted",
    c_palette: str = "Spectral",
    fig_title: Optional[str] = None,
    fig_size: Tuple[float, float] = (10, 40),
    **kwargs
) -> Dict[str, plt.Figure]

Plot a clustered heatmap of the input data and (optional) save it.

Parameters:

Name	Type	Description	Default
data	DataFrame or ndarray	Rectangular dataset to plot.	required
model_groups	dict or None	Dictionary mapping sample ids to group labels used to color the columns.	None
group_list	list or None	List of group labels used to color the columns. If None, use all unique values of model_groups.	None
row_category	Series or None	Pandas series that contains a categorical variable used to color the rows.	None
cbar_label	str or None	Colorbar label. If None, no colorbar label is shown.	None
top_ele_ratio	float	Ratio of the top elements to the heatmap, given as a float in [0, 1].	0.1
row_cluster	bool	Whether to cluster the rows. Default is False.	False
row_dendrogram	bool	Whether to show the dendrogram of the rows. Default is True.	True
palette	str or list - like	Palette name (as a string) or list of colors to use for the model groups. Default is "muted".	'muted'
c_palette	str	Color palette name (as a string) used to color the rows based on row_category. Default is "Spectral".	'Spectral'
fig_title	str or None	Figure title. If None, no title is shown.	None
fig_size	tuple	Figure size in inches, as a tuple of width and height. Default is (10, 40).	(10, 40)
**kwargs		Additional keyword arguments passed to sns.clustermap.	{}

Returns:

Name	Type	Description
plotting_kws	dict	A dictionary containing the resulting matplotlib figure as a value under the key "g".

save_fig

save_fig(
    func=None,
    *,
    prefix="",
    dpi=150,
    name_format="{file_name}"
)

Decorator that wraps a plotting function with automatic file saving.

The decorated function should return a dict containing at least a "g" key with the figure object, and optionally "name_format" for customised file naming.

Parameters:

Name	Type	Description	Default
func	callable	The plotting function to wrap.	None
prefix	str	Default filename prefix, by default "".	''
dpi	int	Default resolution, by default 150.	150
name_format	str	Default format template for the filename, by default "{file_name}".	'{file_name}'

get_logger

get_logger(name: str) -> logging.Logger

Get a logger within the pipeGEM namespace.

Parameters:

Name	Type	Description	Default
name	str	The name of the logger, typically __name__ of the calling module.	required

Returns:

Type	Description
Logger

plot_data_cat

plot_data_cat(
    long_data: DataFrame,
    id_col,
    val_col,
    ids,
    group_col=None,
    vertical=True,
    kind: str = "bar",
    palette: Union[str] = "deep",
    log_scale=False,
)

Plot categorical data using seaborn catplot.

Parameters:

Name	Type	Description	Default
long_data	DataFrame	Long-form DataFrame.	required
id_col	str	Column identifying categories (e.g., reaction IDs).	required
val_col	str	Column with numeric values to plot.	required
ids	list of str	Subset of id_col values to include.	required
group_col	str	Column for hue grouping.	None
vertical	bool	If True, categories on x-axis and values on y-axis.	True
kind	str	Seaborn catplot kind, by default "bar".	'bar'
palette	str	Seaborn palette name.	'deep'
log_scale	bool	Apply log scale to the value axis.	False

Returns:

Type	Description
dict	{"g": FacetGrid}

plot_model_components

plot_model_components(
    comp_df: DataFrame,
    order: List[str],
    group: str = "group",
    **kwargs
)

Plots boxplots of model components for different groups.

Parameters:

Name	Type	Description	Default
comp_df	DataFrame	A pandas DataFrame containing information about the model components.	required
order	list	A list containing the order in which the groups should be plotted.	required
group	str	The column name of the grouping variable in the DataFrame, by default "group".	'group'
**kwargs		Additional keyword arguments to pass to the seaborn boxplot function.	{}

Returns:

Type	Description
dict	A dictionary containing the plot figure.

plot_local_threshold_boxplot

plot_local_threshold_boxplot(
    data,
    genes,
    groups,
    group_dic,
    local_th,
    global_on_th,
    global_off_th,
    width=0.8,
    figsize: Tuple[float, float] = (8, 6),
    **kwargs
)

Plot expression boxplots overlaid with local and global thresholds.

Parameters:

Name	Type	Description	Default
data	DataFrame	Expression matrix (genes × samples).	required
genes	list of str	Gene IDs to include.	required
groups	list of str or ``"all"``	Group names to include (or "all" for all groups).	required
group_dic	dict	{group_name: [sample_names]}.	required
local_th	DataFrame	Local thresholds (genes × groups).	required
global_on_th	Series	Global "on" threshold per group.	required
global_off_th	Series	Global "off" threshold per group.	required
width	float	Box width, by default 0.8.	0.8
figsize	tuple	Figure size, by default (8, 6).	(8, 6)

Returns:

Type	Description
dict	{"g": Figure}

plot_heatmap

plot_heatmap(
    data: Union[DataFrame, ndarray],
    scale: int = 1,
    cbar_label: str = "",
    cbar_kw: Dict[str, Any] = None,
    fig_title: Optional[str] = None,
    row_groups: DataFrame = None,
    row_color_palette: Union[
        List[str], str, Dict[str, str]
    ] = "deep",
    row_color_order: Optional[Dict[str, List[str]]] = None,
    col_groups: DataFrame = None,
    col_color_palette: Union[
        List[str], str, Dict[str, str]
    ] = "deep",
    col_color_order: Optional[Dict[str, List[str]]] = None,
    palette_replacement="Spectral",
    figsize=(10, 10),
    **kwargs
) -> Dict[str, plt.Figure]

Plot a heatmap of the input data and (optional) save it.

Parameters:

Name	Type	Description	Default
data	DataFrame or ndarray	The rectangular dataset to plot.	required
scale	int	An integer representing the scaling factor for the heatmap, by default 1.	1
cbar_label	str	A string representing the label for the colorbar, by default ''.	''
cbar_kw	dict	A dictionary containing additional keyword arguments to be passed to the colorbar, by default None.	None
fig_title	str	A string representing the title of the figure, by default None.	None
**kwargs	optional	Additional keyword arguments to be passed to seaborn.clustermap().	{}

Returns:

Type	Description
dict	A dictionary containing the plot figure.

plot_fba

plot_fba(
    flux_df: DataFrame,
    rxn_ids: Union[List[str], Dict[str, str]],
    group_by=None,
    kind: str = "bar",
    palette: Union[str] = "deep",
    filter_all_zeros: bool = True,
    fig_title: str = None,
    threshold: float = 1e-06,
    vertical: bool = True,
    height: int = 6,
    aspect: int = 2,
    name_format: str = "{method}_result.png",
    flux_unit: str = "($m$mol/hr/gDW)",
    verbosity: int = 0,
    **kwargs
)

Plot FBA flux results as a categorical plot.

Parameters:

Name	Type	Description	Default
flux_df	DataFrame	DataFrame with a "Reaction" column and "fluxes" column (plus optional categorical columns like "model").	required
rxn_ids	list of str or dict	Reaction IDs to plot. If a dict, keys are original IDs and values are display names.	required
group_by	str	Column name used to colour/group the bars (e.g., "model").	None
kind	str	Seaborn catplot kind — "bar", "box", "violin", etc.	'bar'
palette	str	Seaborn palette name.	'deep'
filter_all_zeros	bool	Remove reactions whose absolute flux is below threshold.	True
fig_title	str	Figure title.	None
threshold	float	Minimum absolute flux for a reaction to be plotted.	1e-06
vertical	bool	If True, reactions on x-axis, fluxes on y-axis.	True
height	int	Seaborn FacetGrid sizing parameters.	6
aspect	int	Seaborn FacetGrid sizing parameters.	6
name_format	str	Template for auto-generated file names.	'{method}_result.png'
flux_unit	str	Unit label appended to the flux axis.	'($m$mol/hr/gDW)'

Returns:

Type	Description
dict	{"g": FacetGrid, "name_format": str, ...}

plot_fva

plot_fva(
    fva_df: DataFrame,
    rxn_ids: Union[List[str], Dict[str, str]],
    fig_title: str = None,
    filter_all_zeros: bool = True,
    color_by: bool = "model",
    threshold: float = 1e-06,
    vertical: bool = True,
    name_format: str = "{method}_result.png",
    verbosity: int = 0,
    **kwargs
)

Plot FVA flux ranges as a boxplot.

Parameters:

Name	Type	Description	Default
fva_df	DataFrame	DataFrame with "Reaction", "minimum" and "maximum" columns.	required
rxn_ids	list of str or dict	Reactions to include.	required
fig_title	str	Figure title.	None
filter_all_zeros	bool	Remove reactions with |max − min| < threshold.	True
color_by	str	Column used for hue grouping, by default "model".	'model'
threshold	float	Minimum range for a reaction to be plotted.	1e-06
vertical	bool	If True, reactions on x-axis.	True
name_format	str	File-name template.	'{method}_result.png'

Returns:

Type	Description
dict	{"g": Figure, "name_format": str, ...}

plot_sampling_df

plot_sampling_df(
    flux_df,
    rxn_id,
    kind,
    group_by,
    group_order=None,
    vertical=True,
    plotting_type="displot",
    stat_analysis=None,
    y_lim=None,
    x_lim=None,
    **kwargs
)

Plot flux sampling results as a distribution or categorical plot.

Parameters:

Name	Type	Description	Default
flux_df	DataFrame	Sampling flux DataFrame.	required
rxn_id	str	Reaction column to plot.	required
kind	str	Seaborn plot kind ("kde", "hist", "box", "violin", …).	required
group_by	str	Column used for grouping / hue.	required
group_order	list of str	Order of groups on the categorical axis.	None
vertical	bool	Orientation.	True
plotting_type	``"displot"``, ``"catplot"``	Which seaborn high-level function to use.	``"displot"``
stat_analysis	object	A pairwise test result used to draw significance stars (catplot only).	None
y_lim	tuple	Axis limits.	None
x_lim	tuple	Axis limits.	None

Returns:

Type	Description
dict	{"g": Figure}

plot_rFastCormic_thresholds

plot_rFastCormic_thresholds(
    x: ndarray,
    y: ndarray,
    exp_th: float,
    nonexp_th: float,
    right_c: Optional[ndarray] = None,
    left_c: Optional[ndarray] = None,
) -> dict

Plots a gene expression distribution along with fitted expressed and non-expressed distributions, and gene expression thresholds.

Parameters:

Name	Type	Description	Default
x	ndarray	A numpy array containing the values of the x-axis.	required
y	ndarray	A numpy array containing the values of the y-axis.	required
exp_th	float	The threshold for expressed genes.	required
nonexp_th	float	The threshold for non-expressed genes.	required
right_c	Optional[ndarray]	A numpy array containing the values of the fitted expressed distribution, by default None.	None
left_c	Optional[ndarray]	A numpy array containing the values of the fitted non-expressed distribution, by default None.	None

Returns:

Type	Description
dict	A dictionary containing the plot figure.

plot_percentile_thresholds

plot_percentile_thresholds(
    data: Union[DataFrame, Series],
    exp_th: Union[float, Series],
    figsize: Tuple[float, float] = (8, 6),
    palette: str = "deep",
    palatte: str = None,
    **kwargs
) -> dict

Plot a histogram of expression data with threshold lines.

Parameters:

Name	Type	Description	Default
data	DataFrame or Series	Expression data to plot.	required
exp_th	float or Series	Expression threshold(s). A single float draws one line; a Series draws one per entry.	required
figsize	tuple	Figure size (width, height) in inches, by default (8, 6).	(8, 6)
palette	str	Seaborn palette name, by default "deep".	'deep'
palatte	str	Deprecated spelling kept for backward compatibility. Use palette.	None

Returns:

Type	Description
dict	{"g": fig} — the matplotlib Figure.

plot_PCA

plot_PCA(
    data: Dict[str, DataFrame],
    groups: Optional[
        Dict[str, Union[str, List[str]]]
    ] = None,
    title: Optional[str] = None,
    plot_2D: bool = True,
    plot_score: bool = True,
    plot_scree: bool = True,
    plot_loading: bool = False,
    sheet_file_name: Optional[str] = None,
    score_prefix: str = "PC_",
    scree_prefix: str = "scree_",
    loading_prefix: str = "loading_",
    **kwargs
)

Generate various plots for a principal component analysis (PCA) of the given data.

Parameters:

data: dict A dictionary containing the following keys: - 'PC': pandas DataFrame with the principal components as columns - 'exp_var': pandas DataFrame with the explained variance of each principal component - 'components': pandas DataFrame with the loadings of each principal component groups: dict, optional A dictionary mapping group names to lists of column names to group together in the plots. By default, each column is assigned to its own group. title: str, optional A title to add to the plots. If not provided, a default title is used. plot_2D: bool, optional If True, generate a 2D plot of the principal component scores. Defaults to True. plot_score: bool, optional If True, generate a plot of the principal component scores. Defaults to True. plot_scree: bool, optional If True, generate a plot of the explained variance for each principal component. Defaults to True. plot_loading: bool, optional If True, generate a plot of the component loadings for each principal component. Defaults to False. sheet_file_name: str, optional If provided, the generated plots are saved as CSV files with the same name as this string, but with "PCA", "_EXP_VAR", or "_COMP" appended to the filename for the PCA, explained variance, and components DataFrames, respectively. score_prefix: str, optional If provided, a prefix to add to the filename of the score plot when saving to disk. Defaults to "PC". scree_prefix: str, optional If provided, a prefix to add to the filename of the scree plot when saving to disk. Defaults to "scree_". loading_prefix: str, optional If provided, a prefix to add to the filename of the loading plot when saving to disk. Defaults to "loading_". **kwargs: additional keyword arguments Additional keyword arguments to pass to the individual plotting functions.

Returns:

A dictionary with no keys or values, used solely as a placeholder to indicate that the function has completed.

plot_embedding

plot_embedding(
    embedding_df: DataFrame,
    groups: dict = None,
    title: str = None,
    palette: str = "deep",
    plot_2D: bool = True,
    reducer: str = "UMAP",
    figsize: tuple = (7, 7),
    sheet_file_name: str = None,
    **kwargs: dict
) -> dict

Plot embeddings in 2D or 3D.

Parameters:

Name	Type	Description	Default
embedding_df	DataFrame	DataFrame with embeddings. Columns should include "embedding 1", "embedding 2" (and "embedding 3" for 3-D). Index holds sample names.	required
groups	dict	Mapping of group names to lists of sample names. If None, each sample is its own group.	None
title	str	Figure title.	None
palette	str	Seaborn colour palette name.	'deep'
plot_2D	bool	If True, plot in 2-D; otherwise 3-D.	True
reducer	str	Dimensionality-reduction method name (used for axis labels).	'UMAP'
figsize	tuple	Figure size (width, height) in inches.	(7, 7)
sheet_file_name	str	If provided, save the embedding DataFrame as CSV.	None

Returns:

Type	Description
dict	Dictionary with "g" key holding the matplotlib Figure.