API Reference

This section documents the public API of bioviz-kit.

Configuration Classes

All configuration classes are Pydantic models that validate inputs and provide sensible defaults for publication-ready output. Individual config classes are documented below; the package-level module re-exports are intentionally omitted to avoid duplicated entries in the API reference.

KMPlotConfig

class bioviz.configs.KMPlotConfig(**data)[source]

Bases: BaseModel

Configuration for Kaplan-Meier plot generation.

Notes

Field names match the KM plotting kwargs where possible.
time_col, event_col, and group_col describe data schema; they are required.
color_dict maps group labels to colors; optional.
You can override xticks directly or provide xtick_interval_months to auto-build ticks.
Font sizes default to None to inherit from rcParams (set via RVMDStyle.apply_theme()).

Parameters:

time_col (Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Column containing times (e.g., months)')])
event_col (Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Column containing event indicator (1/0 or True/False)')])
group_col (Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Column for grouping/stratification')])
title (Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Plot title')])
xlim (Annotated[tuple[float | None, float | None] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='X-axis limits (min, max)')])
ylim (Annotated[tuple[float, float], FieldInfo(annotation=NoneType, required=False, default=(0.0, 1.05), description='Y-axis limits (min, max)')])
xlabel (Annotated[str, FieldInfo(annotation=NoneType, required=False, default='Time (Months)', description='X-axis label (preferred)')])
ylabel (Annotated[str, FieldInfo(annotation=NoneType, required=False, default='Survival Probability', description='Y-axis label (preferred)')])
xlab (Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Alias for xlabel (for tm-modeling compatibility)')])
ylab (Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Alias for ylabel (for tm-modeling compatibility)')])
figsize (Annotated[tuple[float, float] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Figure size as (width, height) tuple. Takes precedence over fig_width/fig_height.')])
fig_width (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=10.0, description='Figure width in inches (used if figsize is None)', metadata=[Ge(ge=1.0)])])
fig_height (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=6.0, description='Figure height in inches for KM panel (used if figsize is None)', metadata=[Ge(ge=1.0)])])
legend_loc (Annotated[Literal['bottom', 'right', 'inside'], FieldInfo(annotation=NoneType, required=False, default='bottom', description="Legend location: 'bottom', 'right', or 'inside'")])
legend_title (Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Legend title')])
legend_title_fontweight (Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default='bold', description='Legend title font weight')])
legend_fontsize (Annotated[int | None, FieldInfo(annotation=NoneType, required=False, default=None, description="Legend font size. None uses rcParams['legend.fontsize'].", metadata=[Ge(ge=1)])])
legend_frameon (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=False, description='Whether to draw a frame around the legend')])
legend_markerscale (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=1.0, description='Scale factor for legend marker sizes', metadata=[Gt(gt=0.0)])])
legend_linewidth_scale (Annotated[float | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Multiply legend line widths by this factor')])
legend_show_n (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=False, description='Whether to show (n=...) in legend labels')])
legend_label_wrap_chars (Annotated[int | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Wrap legend labels at this many characters')])
legend_label_max_lines (Annotated[int, FieldInfo(annotation=NoneType, required=False, default=2, description='Maximum lines for wrapped legend labels', metadata=[Ge(ge=1)])])
legend_label_overrides (Annotated[dict[Any, str] | None, FieldInfo(annotation=NoneType, required=False, default=None, description="Override labels: {group_value: 'Display Label'}")])
auto_expand_for_legend (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=False, description='Auto-expand figure to fit legend')])
show_pvalue (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True, description='Whether to show p-value annotation')])
pval_loc (Annotated[Literal['top_left', 'top_right', 'bottom_left', 'bottom_right', 'center_right'], FieldInfo(annotation=NoneType, required=False, default='top_right', description='P-value annotation location')])
pvalue_fontsize (Annotated[int | None, FieldInfo(annotation=NoneType, required=False, default=None, description="P-value font size. None uses rcParams['font.size'].", metadata=[Ge(ge=1)])])
pvalue_box (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=False, description='Whether to draw a box around p-value')])
show_ci (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True, description='Whether to show confidence intervals')])
ci_style (Annotated[Literal['fill', 'lines'], FieldInfo(annotation=NoneType, required=False, default='fill', description="CI style: 'fill' or 'lines'")])
ci_alpha (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.25, description='CI fill transparency', metadata=[Ge(ge=0.0), Le(le=1.0)])])
linewidth (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=3.0, description='Survival curve line width', metadata=[Ge(ge=0.0)])])
linestyle (Annotated[str, FieldInfo(annotation=NoneType, required=False, default='-', description='Survival curve line style')])
conf_type (Annotated[Literal['log_log', 'linear'], FieldInfo(annotation=NoneType, required=False, default='log_log', description="Confidence interval type: 'log_log' or 'linear'")])
censor_marker (Annotated[str, FieldInfo(annotation=NoneType, required=False, default='+', description='Marker style for censored points')])
censor_markersize (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=12.0, description='Size of censor markers', metadata=[Ge(ge=0.0)])])
censor_markeredgewidth (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=2.5, description='Edge width of censor markers', metadata=[Ge(ge=0.0)])])
force_show_censors (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True, description='Force show censors even if none detected')])
per_patient_censor_markers (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True, description='Show individual censor markers per patient')])
show_risktable (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True, description='Whether to show risk table below plot')])
risktable_fontsize (Annotated[int | None, FieldInfo(annotation=NoneType, required=False, default=None, description="Risk table font size. None uses rcParams['font.size'].", metadata=[Ge(ge=1)])])
risktable_title_fontsize (Annotated[int | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Risk table title font size. None uses risktable_fontsize + 2.')])
risktable_row_spacing (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=1.8, description='Vertical spacing multiplier between risk table rows', metadata=[Ge(ge=0.5)])])
risktable_title_gap_factor (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.6, description='Extra top padding between title and first row', metadata=[Ge(ge=0.0)])])
risktable_hspace (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.5, description='Space between KM plot and risk table', metadata=[Ge(ge=0.0)])])
risktable_min_rows (Annotated[int, FieldInfo(annotation=NoneType, required=False, default=4, description='Minimum risk table rows to reserve for layout', metadata=[Ge(ge=1)])])
color_risktable_counts (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=False, description='Whether to color risk table counts by group')])
risktable_label_wrap_chars (Annotated[int | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Wrap risk table labels at this many characters')])
risktable_label_max_lines (Annotated[int, FieldInfo(annotation=NoneType, required=False, default=2, description='Maximum lines for wrapped risk table labels', metadata=[Ge(ge=1)])])
risktable_label_overrides (Annotated[dict[Any, str] | None, FieldInfo(annotation=NoneType, required=False, default=None, description="Override risk table labels: {group_value: 'Label'}")])
xticks (Annotated[list[float] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Explicit x-tick positions')])
timeline (Annotated[Iterable[float] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Timeline values for risk table')])
xtick_interval_months (Annotated[float | None, FieldInfo(annotation=NoneType, required=False, default=3.0, description='Interval for auto-generated x-ticks', metadata=[Gt(gt=0)])])
group_order (Annotated[list[Any] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Explicit order of groups for plotting and legend. If None, uses pd.Categorical order if set, else data order.')])
color_dict (Annotated[dict[Any, str] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Mapping of group values to colors')])
label_fontsize (Annotated[int | None, FieldInfo(annotation=NoneType, required=False, default=None, description="Axis label font size. None uses rcParams['axes.labelsize'].", metadata=[Ge(ge=1)])])
title_fontsize (Annotated[int | None, FieldInfo(annotation=NoneType, required=False, default=None, description="Title font size. None uses rcParams['axes.titlesize'].", metadata=[Ge(ge=1)])])
title_fontweight (Annotated[str, FieldInfo(annotation=NoneType, required=False, default='bold', description="Font weight for title ('normal', 'bold', 'light', etc.).")])
save_bbox_inches (Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default='tight', description='bbox_inches argument for savefig')])

auto_expand_for_legend: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=False, description='Auto-expand figure to fit legend')]

censor_marker: Annotated[str, FieldInfo(annotation=NoneType, required=False, default='+', description='Marker style for censored points')]

censor_markeredgewidth: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=2.5, description='Edge width of censor markers', metadata=[Ge(ge=0.0)])]

censor_markersize: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=12.0, description='Size of censor markers', metadata=[Ge(ge=0.0)])]

ci_alpha: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.25, description='CI fill transparency', metadata=[Ge(ge=0.0), Le(le=1.0)])]

ci_style: Annotated[Literal['fill', 'lines'], FieldInfo(annotation=NoneType, required=False, default='fill', description="CI style: 'fill' or 'lines'")]

color_dict: Annotated[dict[Any, str] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Mapping of group values to colors')]

color_risktable_counts: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=False, description='Whether to color risk table counts by group')]

conf_type: Annotated[Literal['log_log', 'linear'], FieldInfo(annotation=NoneType, required=False, default='log_log', description="Confidence interval type: 'log_log' or 'linear'")]

event_col: Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Column containing event indicator (1/0 or True/False)')]

fig_height: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=6.0, description='Figure height in inches for KM panel (used if figsize is None)', metadata=[Ge(ge=1.0)])]

fig_width: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=10.0, description='Figure width in inches (used if figsize is None)', metadata=[Ge(ge=1.0)])]

figsize: Annotated[tuple[float, float] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Figure size as (width, height) tuple. Takes precedence over fig_width/fig_height.')]

force_show_censors: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True, description='Force show censors even if none detected')]

get_figsize()[source]

Return effective figsize, preferring figsize over fig_width/fig_height.

Return type:: tuple[float, float]

get_xlabel()[source]

Return effective xlabel, preferring xlab alias if set.

Return type:: str

get_ylabel()[source]

Return effective ylabel, preferring ylab alias if set.

Return type:: str

group_col: Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Column for grouping/stratification')]

group_order: Annotated[list[Any] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Explicit order of groups for plotting and legend. If None, uses pd.Categorical order if set, else data order.')]

label_fontsize: Annotated[int | None, FieldInfo(annotation=NoneType, required=False, default=None, description="Axis label font size. None uses rcParams['axes.labelsize'].", metadata=[Ge(ge=1)])]

legend_fontsize: Annotated[int | None, FieldInfo(annotation=NoneType, required=False, default=None, description="Legend font size. None uses rcParams['legend.fontsize'].", metadata=[Ge(ge=1)])]

legend_frameon: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=False, description='Whether to draw a frame around the legend')]

legend_label_max_lines: Annotated[int, FieldInfo(annotation=NoneType, required=False, default=2, description='Maximum lines for wrapped legend labels', metadata=[Ge(ge=1)])]

legend_label_overrides: Annotated[dict[Any, str] | None, FieldInfo(annotation=NoneType, required=False, default=None, description="Override labels: {group_value: 'Display Label'}")]

legend_label_wrap_chars: Annotated[int | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Wrap legend labels at this many characters')]

legend_linewidth_scale: Annotated[float | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Multiply legend line widths by this factor')]

legend_loc: Annotated[Literal['bottom', 'right', 'inside'], FieldInfo(annotation=NoneType, required=False, default='bottom', description="Legend location: 'bottom', 'right', or 'inside'")]

legend_markerscale: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=1.0, description='Scale factor for legend marker sizes', metadata=[Gt(gt=0.0)])]

legend_show_n: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=False, description='Whether to show (n=...) in legend labels')]

legend_title: Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Legend title')]

legend_title_fontweight: Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default='bold', description='Legend title font weight')]

linestyle: Annotated[str, FieldInfo(annotation=NoneType, required=False, default='-', description='Survival curve line style')]

linewidth: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=3.0, description='Survival curve line width', metadata=[Ge(ge=0.0)])]

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

per_patient_censor_markers: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True, description='Show individual censor markers per patient')]

pval_loc: Annotated[Literal['top_left', 'top_right', 'bottom_left', 'bottom_right', 'center_right'], FieldInfo(annotation=NoneType, required=False, default='top_right', description='P-value annotation location')]

pvalue_box: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=False, description='Whether to draw a box around p-value')]

pvalue_fontsize: Annotated[int | None, FieldInfo(annotation=NoneType, required=False, default=None, description="P-value font size. None uses rcParams['font.size'].", metadata=[Ge(ge=1)])]

risktable_fontsize: Annotated[int | None, FieldInfo(annotation=NoneType, required=False, default=None, description="Risk table font size. None uses rcParams['font.size'].", metadata=[Ge(ge=1)])]

risktable_hspace: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.5, description='Space between KM plot and risk table', metadata=[Ge(ge=0.0)])]

risktable_label_max_lines: Annotated[int, FieldInfo(annotation=NoneType, required=False, default=2, description='Maximum lines for wrapped risk table labels', metadata=[Ge(ge=1)])]

risktable_label_overrides: Annotated[dict[Any, str] | None, FieldInfo(annotation=NoneType, required=False, default=None, description="Override risk table labels: {group_value: 'Label'}")]

risktable_label_wrap_chars: Annotated[int | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Wrap risk table labels at this many characters')]

risktable_min_rows: Annotated[int, FieldInfo(annotation=NoneType, required=False, default=4, description='Minimum risk table rows to reserve for layout', metadata=[Ge(ge=1)])]

risktable_row_spacing: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=1.8, description='Vertical spacing multiplier between risk table rows', metadata=[Ge(ge=0.5)])]

risktable_title_fontsize: Annotated[int | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Risk table title font size. None uses risktable_fontsize + 2.')]

risktable_title_gap_factor: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.6, description='Extra top padding between title and first row', metadata=[Ge(ge=0.0)])]

save_bbox_inches: Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default='tight', description='bbox_inches argument for savefig')]

show_ci: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True, description='Whether to show confidence intervals')]

show_pvalue: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True, description='Whether to show p-value annotation')]

show_risktable: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True, description='Whether to show risk table below plot')]

time_col: Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Column containing times (e.g., months)')]

timeline: Annotated[Iterable[float] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Timeline values for risk table')]

title: Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Plot title')]

title_fontsize: Annotated[int | None, FieldInfo(annotation=NoneType, required=False, default=None, description="Title font size. None uses rcParams['axes.titlesize'].", metadata=[Ge(ge=1)])]

title_fontweight: Annotated[str, FieldInfo(annotation=NoneType, required=False, default='bold', description="Font weight for title ('normal', 'bold', 'light', etc.).")]

xlab: Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Alias for xlabel (for tm-modeling compatibility)')]

xlabel: Annotated[str, FieldInfo(annotation=NoneType, required=False, default='Time (Months)', description='X-axis label (preferred)')]

xlim: Annotated[tuple[float | None, float | None] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='X-axis limits (min, max)')]

xtick_interval_months: Annotated[float | None, FieldInfo(annotation=NoneType, required=False, default=3.0, description='Interval for auto-generated x-ticks', metadata=[Gt(gt=0)])]

xticks: Annotated[list[float] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Explicit x-tick positions')]

ylab: Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Alias for ylabel (for tm-modeling compatibility)')]

ylabel: Annotated[str, FieldInfo(annotation=NoneType, required=False, default='Survival Probability', description='Y-axis label (preferred)')]

ylim: Annotated[tuple[float, float], FieldInfo(annotation=NoneType, required=False, default=0.0, 1.05, description='Y-axis limits (min, max)')]

VolcanoConfig

class bioviz.configs.VolcanoConfig(**data)[source]

Bases: BaseModel

Parameters:

x_col (str)
y_col (str)
label_col (str | None)
values_to_label (list[str] | None)
additional_values_to_label (list[str] | None)
label_mode (Literal['auto', 'sig', 'sig_and_thresh', 'thresh', 'sig_or_thresh', 'all'])
y_col_thresh (float)
abs_x_thresh (float)
y_thresh (float | None)
x_thresh (Iterable[float] | None)
thresh_line_color (str)
thresh_line_style (str)
thresh_line_width (float)
x_thresh_line_color (str | None)
x_thresh_line_style (str | None)
x_thresh_line_width (float | None)
y_thresh_line_color (str | None)
y_thresh_line_style (str | None)
y_thresh_line_width (float | None)
direction_col (str | None)
direction_colors (dict[str, str] | None)
palette (dict[str, str])
color_mode (Literal['sig', 'thresh', 'sig_and_thresh', 'sig_or_thresh', 'all'])
label_offset_mode (str)
label_offset (float)
force_label_side_by_point_sign (bool)
force_labels_adjustable (bool)
annotation_fontweight_sig (str)
annotation_fontweight_nonsig (str)
annotation_sig_color (str | None)
annotation_nonsig_color (str)
annotation_sig_up_color (str | None)
annotation_sig_down_color (str | None)
horiz_offset_range (tuple[float, float])
vert_jitter_range (tuple[float, float])
use_adjust_text (bool)
adjust (bool)
log_transform_ycol (bool)
nudge_padding_pixels (float)
x_label (str | None)
y_label (str | None)
xlim (tuple[float, float] | None)
ylim (tuple[float, float] | None)
xticks (Iterable[float] | None)
yticks (Iterable[float] | None)
xtick_step (int | None)
fontsize_sig (int)
fontsize_nonsig (int)
tick_label_fontsize (int)
axis_label_fontsize (int)
title (str | None)
title_fontsize (int)
title_fontweight (str)
figsize (tuple[int, int])
group_label_top (tuple[str, str] | None)
group_label_kwargs (dict | None)
marker_size (float)
attach_to_marker_edge (bool)
pad_by_marker (bool)
connector_color (str)
connector_width (float)
connector_color_sig (str | None)
connector_color_nonsig (str | None)
connector_color_left (str | None)
connector_color_right (str | None)
connector_color_sig_left (str | None)
connector_color_sig_right (str | None)
connector_color_nonsig_left (str | None)
connector_color_nonsig_right (str | None)
connector_color_use_point_color (bool)
ax (Axes | None)
explicit_label_positions (Any | None)
explicit_label_replace (bool)
explicit_label_adjustable (bool)

abs_x_thresh: float

additional_values_to_label: list[str] | None

adjust: bool

annotation_fontweight_nonsig: str

annotation_fontweight_sig: str

annotation_nonsig_color: str

annotation_sig_color: str | None

annotation_sig_down_color: str | None

annotation_sig_up_color: str | None

attach_to_marker_edge: bool

ax: Axes | None

axis_label_fontsize: int

color_mode: Literal['sig', 'thresh', 'sig_and_thresh', 'sig_or_thresh', 'all']

connector_color: str

connector_color_left: str | None

connector_color_nonsig: str | None

connector_color_nonsig_left: str | None

connector_color_nonsig_right: str | None

connector_color_right: str | None

connector_color_sig: str | None

connector_color_sig_left: str | None

connector_color_sig_right: str | None

connector_color_use_point_color: bool

connector_width: float

direction_col: str | None

direction_colors: dict[str, str] | None

explicit_label_adjustable: bool

explicit_label_positions: Any | None

explicit_label_replace: bool

figsize: tuple[int, int]

fontsize_nonsig: int

fontsize_sig: int

force_label_side_by_point_sign: bool

force_labels_adjustable: bool

group_label_kwargs: dict | None

group_label_top: tuple[str, str] | None

horiz_offset_range: tuple[float, float]

label_col: str | None

label_mode: Literal['auto', 'sig', 'sig_and_thresh', 'thresh', 'sig_or_thresh', 'all']

label_offset: float

label_offset_mode: str

log_transform_ycol: bool

marker_size: float

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

nudge_padding_pixels: float

pad_by_marker: bool

palette: dict[str, str]

thresh_line_color: str

thresh_line_style: str

thresh_line_width: float

tick_label_fontsize: int

title: str | None

title_fontsize: int

title_fontweight: str

use_adjust_text: bool

values_to_label: list[str] | None

vert_jitter_range: tuple[float, float]

x_col: str

x_label: str | None

x_thresh: Iterable[float] | None

x_thresh_line_color: str | None

x_thresh_line_style: str | None

x_thresh_line_width: float | None

xlim: tuple[float, float] | None

xtick_step: int | None

xticks: Iterable[float] | None

y_col: str

y_col_thresh: float

y_label: str | None

y_thresh: float | None

y_thresh_line_color: str | None

y_thresh_line_style: str | None

y_thresh_line_width: float | None

ylim: tuple[float, float] | None

yticks: Iterable[float] | None

OncoplotConfig

class bioviz.configs.OncoplotConfig(**data)[source]

Bases: BaseModel

Config for oncoplot rendering.

The plotter treats x_col, y_col, value_col, and row_group_col as required logical columns even though defaults exist. Callers should set these explicitly to match their DataFrame so patient IDs, feature rows, pathway/group labels, and heatmap values are drawn correctly.

Parameters:

fig_title (Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None)])
fig_title_fontsize (Annotated[float | int, FieldInfo(annotation=NoneType, required=False, default=22)])
fig_top_margin (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.9)])
fig_bottom_margin (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.18)])
col_split_by (Annotated[list[str], FieldInfo(annotation=NoneType, required=False, default_factory=list)])
col_split_order (Annotated[dict[str, list[str]], FieldInfo(annotation=NoneType, required=False, default_factory=dict)])
col_sort_by (Annotated[list[str], FieldInfo(annotation=NoneType, required=False, default_factory=list)])
figsize (Annotated[tuple[float, float], FieldInfo(annotation=NoneType, required=False, default=(12, 8))])
bar_width (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.1)])
bar_width_points (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=5.0)])
bar_width_use_points (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True)])
apply_post_row_group_shift (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True)])
row_group_post_bar_shift (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=-5.5)])
row_group_post_label_shift (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=-5.0)])
row_group_post_bar_shift_points (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=-240.0)])
row_group_post_label_shift_points (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=-220.0)])
row_group_post_shift_use_points (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True)])
row_group_label_fontsize (Annotated[float | int, FieldInfo(annotation=NoneType, required=False, default=16)])
row_label_fontsize (Annotated[float | int, FieldInfo(annotation=NoneType, required=False, default=16)])
column_label_fontsize (Annotated[float | int, FieldInfo(annotation=NoneType, required=False, default=16)])
yticklabel_xoffset (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=-0.05)])
rowlabel_use_points (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True)])
legend_fontsize (Annotated[float | int, FieldInfo(annotation=NoneType, required=False, default=16)])
legend_title_fontsize (Annotated[float | int, FieldInfo(annotation=NoneType, required=False, default=16)])
rotate_left_annotation_label (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=False)])
x_col (Annotated[str, FieldInfo(annotation=NoneType, required=False, default_factory=str)])
y_col (Annotated[str, FieldInfo(annotation=NoneType, required=False, default_factory=str)])
row_group_col (Annotated[str, FieldInfo(annotation=NoneType, required=False, default_factory=str)])
row_group_order (Annotated[list[str] | None, FieldInfo(annotation=NoneType, required=False, default=None)])
heatmap_annotation (Annotated[HeatmapAnnotationConfig | None, FieldInfo(annotation=NoneType, required=False, default=None)])
value_col (Annotated[str, FieldInfo(annotation=NoneType, required=False, default_factory=str)])
top_annotation_order (Annotated[list[str] | None, FieldInfo(annotation=NoneType, required=False, default=None)])
cell_aspect (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=1.0)])
target_cell_width (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.55)])
target_cell_height (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.55)])
auto_adjust_cell_size (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True)])
top_annotations (Annotated[dict[str, Any] | None, FieldInfo(annotation=NoneType, required=False, default_factory=dict)])
top_annotation_inter_spacer (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=1.3)])
top_annotation_intra_spacer (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.17)])
top_annotation_label_offset (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.3)])
top_annotation_label_offset_points (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=12.0)])
top_annotation_label_use_points (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True)])
col_split_gap (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.25)])
row_split_gap (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.25)])
bar_offset (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=2.5)])
bar_buffer (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0)])
bar_offset_use_points (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True)])
row_group_label_gap_use_points (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True)])
legend_category_order (Annotated[list[str] | None, FieldInfo(annotation=NoneType, required=False, default=None)])
xticklabel_xoffset (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.0)])
xticklabel_yoffset (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.0)])
legend_bbox_to_anchor (Annotated[tuple[float, float] | None, FieldInfo(annotation=NoneType, required=False, default=None)])
legend_offset (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.1)])
legend_offset_points (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=24.0)])
legend_offset_use_points (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True)])
fig_y_margin (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.02)])
aspect (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=1.0)])
spacing_aspect_scale (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.0)])
xtick_aspect_scale (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.0)])
xticklabel_use_points (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True)])
row_group_label_gap (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=30.0)])
value_legend_title (Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None)])
remove_unused_keys_in_legend (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True)])
figure_facecolor (Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None)])
figure_transparent (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=False)])
row_values_color_dict (Annotated[dict[str, str] | None, FieldInfo(annotation=NoneType, required=False, default=None)])
heatmap_bottom_left_triangle_values (Annotated[list[str], FieldInfo(annotation=NoneType, required=False, default_factory=list)])
heatmap_upper_right_triangle_values (Annotated[list[str], FieldInfo(annotation=NoneType, required=False, default_factory=list)])

apply_post_row_group_shift: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True)]

aspect: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=1.0)]

auto_adjust_cell_size: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True)]

bar_buffer: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0)]

bar_offset: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=2.5)]

bar_offset_use_points: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True)]

bar_width: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.1)]

bar_width_points: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=5.0)]

bar_width_use_points: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True)]

cell_aspect: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=1.0)]

col_sort_by: Annotated[list[str], FieldInfo(annotation=NoneType, required=False, default_factory=list)]

col_split_by: Annotated[list[str], FieldInfo(annotation=NoneType, required=False, default_factory=list)]

col_split_gap: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.25)]

col_split_order: Annotated[dict[str, list[str]], FieldInfo(annotation=NoneType, required=False, default_factory=dict)]

column_label_fontsize: Annotated[float | int, FieldInfo(annotation=NoneType, required=False, default=16)]

fig_bottom_margin: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.18)]

fig_title: Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None)]

fig_title_fontsize: Annotated[float | int, FieldInfo(annotation=NoneType, required=False, default=22)]

fig_top_margin: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.9)]

fig_y_margin: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.02)]

figsize: Annotated[tuple[float, float], FieldInfo(annotation=NoneType, required=False, default=12, 8)]

figure_facecolor: Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None)]

figure_transparent: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=False)]

heatmap_annotation: Annotated[HeatmapAnnotationConfig | None, FieldInfo(annotation=NoneType, required=False, default=None)]

heatmap_bottom_left_triangle_values: Annotated[list[str], FieldInfo(annotation=NoneType, required=False, default_factory=list)]

heatmap_upper_right_triangle_values: Annotated[list[str], FieldInfo(annotation=NoneType, required=False, default_factory=list)]

legend_bbox_to_anchor: Annotated[tuple[float, float] | None, FieldInfo(annotation=NoneType, required=False, default=None)]

legend_category_order: Annotated[list[str] | None, FieldInfo(annotation=NoneType, required=False, default=None)]

legend_fontsize: Annotated[float | int, FieldInfo(annotation=NoneType, required=False, default=16)]

legend_offset: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.1)]

legend_offset_points: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=24.0)]

legend_offset_use_points: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True)]

legend_title_fontsize: Annotated[float | int, FieldInfo(annotation=NoneType, required=False, default=16)]

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(_OncoplotConfig__context=None)[source]

Infer value_col from heatmap_annotation if not set.

Return type:: None
Parameters:: _OncoplotConfig__context (dict | None)

remove_unused_keys_in_legend: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True)]

rotate_left_annotation_label: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=False)]

row_group_col: Annotated[str, FieldInfo(annotation=NoneType, required=False, default_factory=str)]

row_group_label_fontsize: Annotated[float | int, FieldInfo(annotation=NoneType, required=False, default=16)]

row_group_label_gap: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=30.0)]

row_group_label_gap_use_points: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True)]

row_group_order: Annotated[list[str] | None, FieldInfo(annotation=NoneType, required=False, default=None)]

row_group_post_bar_shift: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=-5.5)]

row_group_post_bar_shift_points: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=-240.0)]

row_group_post_label_shift: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=-5.0)]

row_group_post_label_shift_points: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=-220.0)]

row_group_post_shift_use_points: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True)]

row_label_fontsize: Annotated[float | int, FieldInfo(annotation=NoneType, required=False, default=16)]

row_split_gap: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.25)]

row_values_color_dict: Annotated[dict[str, str] | None, FieldInfo(annotation=NoneType, required=False, default=None)]

rowlabel_use_points: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True)]

spacing_aspect_scale: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.0)]

target_cell_height: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.55)]

target_cell_width: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.55)]

top_annotation_inter_spacer: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=1.3)]

top_annotation_intra_spacer: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.17)]

top_annotation_label_offset: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.3)]

top_annotation_label_offset_points: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=12.0)]

top_annotation_label_use_points: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True)]

top_annotation_order: Annotated[list[str] | None, FieldInfo(annotation=NoneType, required=False, default=None)]

top_annotations: Annotated[dict[str, Any] | None, FieldInfo(annotation=NoneType, required=False, default_factory=dict)]

value_col: Annotated[str, FieldInfo(annotation=NoneType, required=False, default_factory=str)]

value_legend_title: Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None)]

x_col: Annotated[str, FieldInfo(annotation=NoneType, required=False, default_factory=str)]

xtick_aspect_scale: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.0)]

xticklabel_use_points: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True)]

xticklabel_xoffset: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.0)]

xticklabel_yoffset: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.0)]

y_col: Annotated[str, FieldInfo(annotation=NoneType, required=False, default_factory=str)]

yticklabel_xoffset: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=-0.05)]

ForestPlotConfig

class bioviz.configs.ForestPlotConfig(**data)[source]

Bases: BaseModel

Configuration for forest plot generation.

Notes

Column names (hr_col, ci_lower_col, etc.) describe your data schema.
Font sizes default to None to inherit from rcParams (e.g., RVMDStyle.apply_theme()).
Use log_scale=True for standard HR visualization (centered around 1.0).

Parameters:

hr_col (Annotated[str, FieldInfo(annotation=NoneType, required=False, default='hr', description='Column name for hazard ratio values')])
ci_lower_col (Annotated[str, FieldInfo(annotation=NoneType, required=False, default='ci_lower', description='Column name for lower CI bound')])
ci_upper_col (Annotated[str, FieldInfo(annotation=NoneType, required=False, default='ci_upper', description='Column name for upper CI bound')])
label_col (Annotated[str, FieldInfo(annotation=NoneType, required=False, default='comparator', description='Column name for row labels')])
pvalue_col (Annotated[str, FieldInfo(annotation=NoneType, required=False, default='p_value', description='Column name for p-values')])
reference_col (Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default='reference', description='Column name for reference group')])
variable_col (Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default='variable', description='Column for variable grouping (multi-section plots)')])
figsize (Annotated[tuple[float, float], FieldInfo(annotation=NoneType, required=False, default=(10.0, 8.0), description='Figure size (width, height) in inches')])
title (Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Plot title')])
xlabel (Annotated[str, FieldInfo(annotation=NoneType, required=False, default='Hazard Ratio (95% CI)', description='X-axis label')])
show_reference_line (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True, description='Show vertical line at HR=1')])
reference_line_color (Annotated[str, FieldInfo(annotation=NoneType, required=False, default='#D32F2F', description='Reference line color')])
reference_line_style (Annotated[str, FieldInfo(annotation=NoneType, required=False, default='--', description='Reference line style')])
reference_line_width (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=1.5, description='Reference line width', metadata=[Ge(ge=0.0)])])
show_stats_table (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True, description='Show HR/CI/p-value table on right side')])
stats_table_x_position (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=1.05, description='X-position for stats table (>1.0 = right of plot)')])
stats_table_col_spacing (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.15, description='Spacing between stats table columns')])
stats_fontsize (Annotated[int | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Stats table font size. None uses rcParams.', metadata=[Ge(ge=1)])])
log_scale (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=False, description='Use log scale for x-axis')])
xlim (Annotated[tuple[float, float] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='X-axis limits (min, max)')])
xticks (Annotated[list[float] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Custom x-tick positions')])
center_around_null (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=False, description='Center x-axis symmetrically around HR=1')])
color_significant (Annotated[str, FieldInfo(annotation=NoneType, required=False, default='#2E7D32', description='Color for significant results (p < alpha)')])
color_nonsignificant (Annotated[str, FieldInfo(annotation=NoneType, required=False, default='#757575', description='Color for non-significant results')])
marker_color_significant (Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Marker color for significant. None uses color_significant.')])
marker_color_nonsignificant (Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Marker color for non-significant. None uses color_nonsignificant.')])
alpha_threshold (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.05, description='Significance threshold', metadata=[Ge(ge=0.0), Le(le=1.0)])])
marker_size (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=8.0, description='Size of point markers', metadata=[Ge(ge=0.0)])])
marker_style (Annotated[Literal['s', 'o', 'D', '^', 'v', '<', '>', 'p', '*', 'h'], FieldInfo(annotation=NoneType, required=False, default='s', description='Marker style (s=square, o=circle, D=diamond, etc.)')])
linewidth (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=2.0, description='Error bar line width', metadata=[Ge(ge=0.0)])])
show_caps (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=False, description='Show caps on error bars')])
capsize (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=2.0, description='Size of error bar caps', metadata=[Ge(ge=0.0)])])
section_labels (Annotated[dict[str, str] | None, FieldInfo(annotation=NoneType, required=False, default=None, description="Custom section labels: {variable: 'Display Name'}")])
show_section_separators (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True, description='Show separator lines between sections')])
section_separator_color (Annotated[str, FieldInfo(annotation=NoneType, required=False, default='blue', description='Color of section separator lines')])
section_separator_alpha (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.25, description='Transparency of separator lines', metadata=[Ge(ge=0.0), Le(le=1.0)])])
section_gap (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.0, description='Extra vertical spacing between sections')])
section_label_x_position (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=-0.35, description='X-position for section labels (negative = left)')])
show_grid (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=False, description='Show vertical grid lines')])
show_y_spine (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=False, description='Show left y-axis spine')])
show_yticks (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=False, description='Show y-axis tick marks')])
y_margin (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.5, description='Padding above/below plot in row units', metadata=[Ge(ge=0.0)])])
ytick_fontsize (Annotated[int | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Y-axis label font size. None uses rcParams.', metadata=[Ge(ge=1)])])
xtick_fontsize (Annotated[int | None, FieldInfo(annotation=NoneType, required=False, default=None, description='X-tick label font size. None uses rcParams.', metadata=[Ge(ge=1)])])
xlabel_fontsize (Annotated[int | None, FieldInfo(annotation=NoneType, required=False, default=None, description='X-axis label font size. None uses rcParams.', metadata=[Ge(ge=1)])])
title_fontsize (Annotated[int | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Title font size. None uses rcParams.', metadata=[Ge(ge=1)])])
category_order (Annotated[dict[str, list[Any]] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Custom ordering for variable sections and categories. Dict maps variable names to lists of comparator values in display order.')])

alpha_threshold: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.05, description='Significance threshold', metadata=[Ge(ge=0.0), Le(le=1.0)])]

capsize: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=2.0, description='Size of error bar caps', metadata=[Ge(ge=0.0)])]

category_order: Annotated[dict[str, list[Any]] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Custom ordering for variable sections and categories. Dict maps variable names to lists of comparator values in display order.')]

center_around_null: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=False, description='Center x-axis symmetrically around HR=1')]

ci_lower_col: Annotated[str, FieldInfo(annotation=NoneType, required=False, default='ci_lower', description='Column name for lower CI bound')]

ci_upper_col: Annotated[str, FieldInfo(annotation=NoneType, required=False, default='ci_upper', description='Column name for upper CI bound')]

color_nonsignificant: Annotated[str, FieldInfo(annotation=NoneType, required=False, default='#757575', description='Color for non-significant results')]

color_significant: Annotated[str, FieldInfo(annotation=NoneType, required=False, default='#2E7D32', description='Color for significant results (p < alpha)')]

figsize: Annotated[tuple[float, float], FieldInfo(annotation=NoneType, required=False, default=10.0, 8.0, description='Figure size (width, height) in inches')]

hr_col: Annotated[str, FieldInfo(annotation=NoneType, required=False, default='hr', description='Column name for hazard ratio values')]

label_col: Annotated[str, FieldInfo(annotation=NoneType, required=False, default='comparator', description='Column name for row labels')]

linewidth: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=2.0, description='Error bar line width', metadata=[Ge(ge=0.0)])]

log_scale: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=False, description='Use log scale for x-axis')]

marker_color_nonsignificant: Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Marker color for non-significant. None uses color_nonsignificant.')]

marker_color_significant: Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Marker color for significant. None uses color_significant.')]

marker_size: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=8.0, description='Size of point markers', metadata=[Ge(ge=0.0)])]

marker_style: Annotated[Literal['s', 'o', 'D', '^', 'v', '<', '>', 'p', '*', 'h'], FieldInfo(annotation=NoneType, required=False, default='s', description='Marker style (s=square, o=circle, D=diamond, etc.)')]

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pvalue_col: Annotated[str, FieldInfo(annotation=NoneType, required=False, default='p_value', description='Column name for p-values')]

reference_col: Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default='reference', description='Column name for reference group')]

reference_line_color: Annotated[str, FieldInfo(annotation=NoneType, required=False, default='#D32F2F', description='Reference line color')]

reference_line_style: Annotated[str, FieldInfo(annotation=NoneType, required=False, default='--', description='Reference line style')]

reference_line_width: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=1.5, description='Reference line width', metadata=[Ge(ge=0.0)])]

section_gap: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.0, description='Extra vertical spacing between sections')]

section_label_x_position: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=-0.35, description='X-position for section labels (negative = left)')]

section_labels: Annotated[dict[str, str] | None, FieldInfo(annotation=NoneType, required=False, default=None, description="Custom section labels: {variable: 'Display Name'}")]

section_separator_alpha: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.25, description='Transparency of separator lines', metadata=[Ge(ge=0.0), Le(le=1.0)])]

section_separator_color: Annotated[str, FieldInfo(annotation=NoneType, required=False, default='blue', description='Color of section separator lines')]

show_caps: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=False, description='Show caps on error bars')]

show_grid: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=False, description='Show vertical grid lines')]

show_reference_line: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True, description='Show vertical line at HR=1')]

show_section_separators: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True, description='Show separator lines between sections')]

show_stats_table: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True, description='Show HR/CI/p-value table on right side')]

show_y_spine: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=False, description='Show left y-axis spine')]

show_yticks: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=False, description='Show y-axis tick marks')]

stats_fontsize: Annotated[int | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Stats table font size. None uses rcParams.', metadata=[Ge(ge=1)])]

stats_table_col_spacing: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.15, description='Spacing between stats table columns')]

stats_table_x_position: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=1.05, description='X-position for stats table (>1.0 = right of plot)')]

title: Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Plot title')]

title_fontsize: Annotated[int | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Title font size. None uses rcParams.', metadata=[Ge(ge=1)])]

variable_col: Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default='variable', description='Column for variable grouping (multi-section plots)')]

xlabel: Annotated[str, FieldInfo(annotation=NoneType, required=False, default='Hazard Ratio (95% CI)', description='X-axis label')]

xlabel_fontsize: Annotated[int | None, FieldInfo(annotation=NoneType, required=False, default=None, description='X-axis label font size. None uses rcParams.', metadata=[Ge(ge=1)])]

xlim: Annotated[tuple[float, float] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='X-axis limits (min, max)')]

xtick_fontsize: Annotated[int | None, FieldInfo(annotation=NoneType, required=False, default=None, description='X-tick label font size. None uses rcParams.', metadata=[Ge(ge=1)])]

xticks: Annotated[list[float] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Custom x-tick positions')]

y_margin: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.5, description='Padding above/below plot in row units', metadata=[Ge(ge=0.0)])]

ytick_fontsize: Annotated[int | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Y-axis label font size. None uses rcParams.', metadata=[Ge(ge=1)])]

GroupedBarConfig

class bioviz.configs.GroupedBarConfig(**data)[source]

Bases: BaseModel

Configuration for bar plots with optional grouping and confidence intervals.

Supports: - Grouped bar plots (multiple bars per category) or simple bar plots - Horizontal or vertical orientation - Optional confidence intervals (Clopper-Pearson, bootstrap, or pre-computed) - Flexible styling and annotations

Common use cases: - Gene prevalence comparisons across cohorts - Response rates by treatment arm - Mutation frequency at baseline vs progression - Any categorical comparison with or without error bars

Parameters:

category_col (Annotated[str, FieldInfo(annotation=NoneType, required=False, default='Category', description='Column for categories (e.g., Gene, Pathway, Treatment).')])
group_col (Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default='Group', description='Column for grouping within categories. None for ungrouped bars.')])
value_col (Annotated[str, FieldInfo(annotation=NoneType, required=False, default='value', description='Column for bar values (heights/lengths).')])
orientation (Annotated[Literal['horizontal', 'vertical'], FieldInfo(annotation=NoneType, required=False, default='horizontal', description="Bar orientation: 'horizontal' (barh) or 'vertical' (bar).")])
ci_low_col (Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Column for lower CI bound. None to skip error bars.')])
ci_high_col (Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Column for upper CI bound. None to skip error bars.')])
k_col (Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Column for count (numerator) to compute proportion CI.')])
n_col (Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Column for total (denominator) to compute proportion CI.')])
ci_method (Annotated[Literal['clopper-pearson', 'bootstrap', 'none'], FieldInfo(annotation=NoneType, required=False, default='none', description="CI method: 'clopper-pearson', 'bootstrap', or 'none'.")])
alpha (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.05, description='Significance level for CI (0.05 = 95% CI).')])
n_boot (Annotated[int, FieldInfo(annotation=NoneType, required=False, default=10000, description="Number of bootstrap samples (if method='bootstrap').")])
random_state (Annotated[int | None, FieldInfo(annotation=NoneType, required=False, default=12345, description='Random seed for bootstrap reproducibility.')])
group_order (Annotated[list[str] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Order of groups within each category.')])
group_colors (Annotated[dict[str, str] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Mapping of group name to color.')])
group_labels (Annotated[dict[str, str] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Mapping of group name to display label (e.g., with n=X).')])
figsize (Annotated[tuple[float, float] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Figure size (width, height). Auto-computed if None.')])
bar_width (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.28, description='Width/height of each bar.')])
group_spacing (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=1.5, description='Spacing between category groups.')])
title (Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Plot title.')])
title_fontweight (Annotated[str, FieldInfo(annotation=NoneType, required=False, default='normal', description="Font weight for title ('normal', 'bold', 'light', etc.).")])
xlabel (Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None, description='X-axis label.')])
ylabel (Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Y-axis label.')])
title_fontsize (Annotated[float | None, FieldInfo(annotation=NoneType, required=False, default=None, description="Font size for title. None uses rcParams['axes.titlesize'].")])
xlabel_fontsize (Annotated[float | None, FieldInfo(annotation=NoneType, required=False, default=None, description="Font size for x-axis label. None uses rcParams['axes.labelsize'].")])
ylabel_fontsize (Annotated[float | None, FieldInfo(annotation=NoneType, required=False, default=None, description="Font size for y-axis label. None uses rcParams['axes.labelsize'].")])
tick_fontsize (Annotated[float | None, FieldInfo(annotation=NoneType, required=False, default=None, description="Font size for tick labels. None uses rcParams['xtick.labelsize'].")])
show_annotations (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True, description='Whether to show value annotations on bars.')])
annot_fontsize (Annotated[float | None, FieldInfo(annotation=NoneType, required=False, default=None, description="Font size for value annotations. None uses rcParams['font.size'] * 0.9.")])
annot_format (Annotated[str, FieldInfo(annotation=NoneType, required=False, default='{:.1f}%', description='Format string for annotations.')])
annot_offset (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.8, description='Offset for annotations from bar end (data units).')])
annot_padding (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=5.0, description='Extra padding (data units) added to axis limit to ensure annotations fit.')])
show_legend (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True, description='Whether to show legend.')])
legend_loc (Annotated[str, FieldInfo(annotation=NoneType, required=False, default='upper left', description='Legend location.')])
legend_bbox_to_anchor (Annotated[tuple[float, float] | None, FieldInfo(annotation=NoneType, required=False, default=(1.02, 1), description='Legend bbox_to_anchor. None for auto.')])
legend_fontsize (Annotated[float | None, FieldInfo(annotation=NoneType, required=False, default=None, description="Font size for legend. None uses rcParams['legend.fontsize'].")])
legend_title (Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Legend title.')])
default_color (Annotated[str, FieldInfo(annotation=NoneType, required=False, default='#1f77b4', description='Default bar color when no group_colors specified.')])
bar_edgecolor (Annotated[str, FieldInfo(annotation=NoneType, required=False, default='white', description='Edge color for bars.')])
bar_linewidth (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.9, description='Line width for bar edges.')])
capsize (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=4, description='Size of error bar caps.')])
error_color (Annotated[str, FieldInfo(annotation=NoneType, required=False, default='black', description='Color for error bars.')])
value_min (Annotated[float | None, FieldInfo(annotation=NoneType, required=False, default=0, description='Minimum value axis limit. None for auto.')])
value_max (Annotated[float | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Maximum value axis limit. None for auto.')])
value_padding_pct (Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.15, description='Padding as fraction of max value for auto limit.')])
xlim (Annotated[tuple[float, float] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Explicit (min, max) for x-axis. Overrides value_min/max for horizontal.')])
ylim (Annotated[tuple[float, float] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Explicit (min, max) for y-axis. Overrides value_min/max for vertical.')])
xticks (Annotated[list[float] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Custom x-tick positions. None uses auto ticks.')])
yticks (Annotated[list[float] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Custom y-tick positions. None uses auto ticks.')])
xtick_labels (Annotated[list[str] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Custom x-tick labels. Must match xticks length.')])
ytick_labels (Annotated[list[str] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Custom y-tick labels. Must match yticks length.')])
invert_categories (Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True, description='Invert category axis (first category at top for horizontal).')])

category_col: Column name for categories (x-axis for vertical, y-axis for horizontal).

group_col: Column for grouping within categories. None for simple (ungrouped) bars.

value_col: Column name for bar values.

orientation: ‘horizontal’ (barh) or ‘vertical’ (bar).

ci_low_col: Column for lower CI bound. None to skip error bars.

ci_high_col: Column for upper CI bound. None to skip error bars.

k_col: Column for count (numerator) to compute CI from proportions.

n_col: Column for total (denominator) to compute CI from proportions.

ci_method: Method for CI computation: ‘clopper’, ‘bootstrap’, or ‘none’.

alpha: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.05, description='Significance level for CI (0.05 = 95% CI).')]

annot_fontsize: Annotated[float | None, FieldInfo(annotation=NoneType, required=False, default=None, description="Font size for value annotations. None uses rcParams['font.size'] * 0.9.")]

annot_format: Annotated[str, FieldInfo(annotation=NoneType, required=False, default='{:.1f}%', description='Format string for annotations.')]

annot_offset: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.8, description='Offset for annotations from bar end (data units).')]

annot_padding: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=5.0, description='Extra padding (data units) added to axis limit to ensure annotations fit.')]

bar_edgecolor: Annotated[str, FieldInfo(annotation=NoneType, required=False, default='white', description='Edge color for bars.')]

bar_linewidth: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.9, description='Line width for bar edges.')]

bar_width: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.28, description='Width/height of each bar.')]

capsize: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=4, description='Size of error bar caps.')]

category_col: Annotated[str, FieldInfo(annotation=NoneType, required=False, default='Category', description='Column for categories (e.g., Gene, Pathway, Treatment).')]

ci_high_col: Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Column for upper CI bound. None to skip error bars.')]

ci_low_col: Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Column for lower CI bound. None to skip error bars.')]

ci_method: Annotated[Literal['clopper-pearson', 'bootstrap', 'none'], FieldInfo(annotation=NoneType, required=False, default='none', description="CI method: 'clopper-pearson', 'bootstrap', or 'none'.")]

default_color: Annotated[str, FieldInfo(annotation=NoneType, required=False, default='#1f77b4', description='Default bar color when no group_colors specified.')]

error_color: Annotated[str, FieldInfo(annotation=NoneType, required=False, default='black', description='Color for error bars.')]

figsize: Annotated[tuple[float, float] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Figure size (width, height). Auto-computed if None.')]

group_col: Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default='Group', description='Column for grouping within categories. None for ungrouped bars.')]

group_colors: Annotated[dict[str, str] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Mapping of group name to color.')]

group_labels: Annotated[dict[str, str] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Mapping of group name to display label (e.g., with n=X).')]

group_order: Annotated[list[str] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Order of groups within each category.')]

group_spacing: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=1.5, description='Spacing between category groups.')]

invert_categories: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True, description='Invert category axis (first category at top for horizontal).')]

k_col: Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Column for count (numerator) to compute proportion CI.')]

legend_bbox_to_anchor: Annotated[tuple[float, float] | None, FieldInfo(annotation=NoneType, required=False, default=1.02, 1, description='Legend bbox_to_anchor. None for auto.')]

legend_fontsize: Annotated[float | None, FieldInfo(annotation=NoneType, required=False, default=None, description="Font size for legend. None uses rcParams['legend.fontsize'].")]

legend_loc: Annotated[str, FieldInfo(annotation=NoneType, required=False, default='upper left', description='Legend location.')]

legend_title: Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Legend title.')]

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

n_boot: Annotated[int, FieldInfo(annotation=NoneType, required=False, default=10000, description="Number of bootstrap samples (if method='bootstrap').")]

n_col: Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Column for total (denominator) to compute proportion CI.')]

orientation: Annotated[Literal['horizontal', 'vertical'], FieldInfo(annotation=NoneType, required=False, default='horizontal', description="Bar orientation: 'horizontal' (barh) or 'vertical' (bar).")]

random_state: Annotated[int | None, FieldInfo(annotation=NoneType, required=False, default=12345, description='Random seed for bootstrap reproducibility.')]

show_annotations: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True, description='Whether to show value annotations on bars.')]

show_legend: Annotated[bool, FieldInfo(annotation=NoneType, required=False, default=True, description='Whether to show legend.')]

tick_fontsize: Annotated[float | None, FieldInfo(annotation=NoneType, required=False, default=None, description="Font size for tick labels. None uses rcParams['xtick.labelsize'].")]

title: Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Plot title.')]

title_fontsize: Annotated[float | None, FieldInfo(annotation=NoneType, required=False, default=None, description="Font size for title. None uses rcParams['axes.titlesize'].")]

title_fontweight: Annotated[str, FieldInfo(annotation=NoneType, required=False, default='normal', description="Font weight for title ('normal', 'bold', 'light', etc.).")]

value_col: Annotated[str, FieldInfo(annotation=NoneType, required=False, default='value', description='Column for bar values (heights/lengths).')]

value_max: Annotated[float | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Maximum value axis limit. None for auto.')]

value_min: Annotated[float | None, FieldInfo(annotation=NoneType, required=False, default=0, description='Minimum value axis limit. None for auto.')]

value_padding_pct: Annotated[float, FieldInfo(annotation=NoneType, required=False, default=0.15, description='Padding as fraction of max value for auto limit.')]

xlabel: Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None, description='X-axis label.')]

xlabel_fontsize: Annotated[float | None, FieldInfo(annotation=NoneType, required=False, default=None, description="Font size for x-axis label. None uses rcParams['axes.labelsize'].")]

xlim: Annotated[tuple[float, float] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Explicit (min, max) for x-axis. Overrides value_min/max for horizontal.')]

xtick_labels: Annotated[list[str] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Custom x-tick labels. Must match xticks length.')]

xticks: Annotated[list[float] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Custom x-tick positions. None uses auto ticks.')]

ylabel: Annotated[str | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Y-axis label.')]

ylabel_fontsize: Annotated[float | None, FieldInfo(annotation=NoneType, required=False, default=None, description="Font size for y-axis label. None uses rcParams['axes.labelsize'].")]

ylim: Annotated[tuple[float, float] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Explicit (min, max) for y-axis. Overrides value_min/max for vertical.')]

ytick_labels: Annotated[list[str] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Custom y-tick labels. Must match yticks length.')]

yticks: Annotated[list[float] | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Custom y-tick positions. None uses auto ticks.')]

Plotter Classes

Plotters take a DataFrame and a configuration object, then produce matplotlib figures.

KMPlotter

class bioviz.plots.KMPlotter(data, config)[source]

Bases: object

Generate Kaplan-Meier survival plots with optional risk tables.

Parameters:

data (pd.DataFrame) – Survival data with time, event, and group columns.
config (KMPlotConfig) – Configuration object specifying plot options.

data

Type:: pd.DataFrame

config

Type:: KMPlotConfig

plot(ax=None, fig=None, output_path=None)[source]

Generate the Kaplan-Meier plot.

Parameters:

ax (Axes, optional) – Existing axes; if None, a new figure/axes is created.
fig (Figure, optional) – Existing figure.
output_path (str, optional) – Path to save the figure.

Return type:

tuple[Any, Any, float | None]

Returns:

fig (Figure)
ax (Axes)
p_value (float or None) – Log-rank p-value if computed.

VolcanoPlotter

class bioviz.plots.VolcanoPlotter(df, config)[source]

Bases: object

Stateful, interactive wrapper around the functional API.

Mirrors the interaction pattern of OncoPlotter: the instance exposes .df and .config attributes, and the constructor accepts either (df, config) or (config, df) for backwards compatibility. Rendering delegates to plot_volcano so the pure function remains the canonical implementation.

Parameters:

df (pd.DataFrame)
config (VolcanoConfig | dict)

annotate(explicit_positions, replace=True)[source]

Add explicit label placements and re-render.

explicit_positions should be a mapping label -> (x, y). If replace is True the explicit placements replace auto labels (cfg.explicit_label_replace=True). The placements are recorded in annotation_history so callers can inspect what was added.

Return type:

VolcanoPlotter

Parameters:

explicit_positions (Mapping[str, tuple[float, float]])
replace (bool)

close()[source]

Return type:: None

classmethod from_dict(data)[source]

Return type:: VolcanoPlotter
Parameters:: data (Mapping)

label_more(n=10)[source]

Convenience to expand cfg.values_to_label using the internal resolver – useful for interactive ‘label more’ flows.

Return type:: VolcanoPlotter
Parameters:: n (int)

plot(df=None)[source]

Render the volcano. If df is provided, set it as the current data.

Returns the (fig, ax) produced by plot_volcano and stores them on the instance.

Return type:: tuple[Figure, Axes]
Parameters:: df (DataFrame | None)

resolve_labels()[source]

Return type:: list[str]

save(path, **save_kwargs)[source]

Return type:: None
Parameters:: path (str)

set_data(df)[source]

Return type:: VolcanoPlotter
Parameters:: df (DataFrame)

to_dict()[source]

Return type:: dict

update_config(**kwargs)[source]

Update configuration in-place and return self for chaining.

Return type:: VolcanoPlotter

OncoPlotter

class bioviz.plots.OncoPlotter(df, config, row_groups=None, row_groups_color_dict=None, style=None)[source]

Bases: object

High-level oncoplot drawing helper.

Construct with mutation/event df and an OncoplotConfig. The plot() method renders a full oncoprint including heatmap cell fills, top annotations, legends, and optional row-group bars. Instances keep temporary references to created patches/texts to allow post-render adjustments (e.g., shifting labels).

Parameters:

df (DataFrame)
config (OncoplotConfig)
row_groups (DataFrame | None)
row_groups_color_dict (dict | None)
style (StyleBase | None)

get_dynamic_bar_x(bar_offset, cell_aspect)[source]

Compute a dynamic X coordinate for row-group bars based on existing left-side text extents.

Parameters:

ax – Matplotlib Axes to inspect for left-aligned text items.
bar_offset – Base offset to apply from the leftmost text position.
cell_aspect – Cell width multiplier affecting scaled offset.

Return type:

Any

Returns:

Computed X coordinate where a row-group bar should be placed.

move_row_group_labels(ax, new_bar_x, bar_width=None)[source]

Move row-group bar patches and associated labels to a new X coordinate.

Parameters:

ax – Matplotlib Axes containing the bar patches and labels.
new_bar_x – New X coordinate to place row-group bars.
bar_width – Optional new width to set on bar patches.

Return type:

None

plot()[source]

Render the oncoplot and return the produced matplotlib Figure.

This method computes layout (column positions, row ordering, cell sizing), draws background cells, heatmap/triangle fills, top annotations, mutation glyphs, legends, and optional row-group bars/labels according to the provided OncoplotConfig and supporting config objects.

Return type:: Figure
Returns:: A matplotlib Figure instance containing the completed oncoplot.

static redraw_row_group_labels(ax, row_groups, row_groups_color_dict, gene_to_idx, row_group_col, row_group_label_fontsize, rotate_left_annotation_label, bar_x, bar_width)[source]

Return type:: None

shift_row_group_bars_and_labels(ax, row_groups, bar_shift=-6, label_shift=-5.5, bar_shift_points=-240.0, label_shift_points=-220.0, use_points=True, bar_width=None, bar_width_points=None)[source]

Shift row-group bar patches and their labels horizontally to avoid overlaps.

This adjusts previously-stored _row_group_bar_patches and _row_group_label_texts positions, or finds matching patches/texts in the axes when not tracked. Coordinates can be supplied in data units or physical points; when use_points is True the provided point offsets are converted to data units for consistent visual spacing across figure sizes.

Parameters:

ax – Matplotlib Axes containing the row-group bars/labels.
row_groups – DataFrame mapping genes/features to group/pathway names.
bar_shift – Data-unit fallback horizontal shift for bars.
label_shift – Data-unit fallback horizontal shift for labels.
bar_shift_points – Horizontal shift for bars expressed in points (preferred).
label_shift_points – Horizontal shift for labels expressed in points.
use_points – If True convert the _points offsets to data units.
bar_width (float | None)
bar_width_points (float | None)

Return type:

None

ForestPlotter

class bioviz.plots.ForestPlotter(data, config)[source]

Bases: object

Generate forest plots for hazard ratio visualization.

Parameters:

data (pd.DataFrame) – DataFrame containing HR data with columns for HR, CI bounds, labels, p-values.
config (ForestPlotConfig) – Configuration object specifying plot options.

data

Type:: pd.DataFrame

config

Type:: ForestPlotConfig

compute_y_positions(df)[source]

Compute y-positions with optional section gaps.

Parameters:: df (pd.DataFrame) – Prepared dataframe from prepare_data().
Returns:: Array of y-coordinates for each row.
Return type:: np.ndarray

plot(ax=None, fig=None, output_path=None)[source]

Generate the forest plot.

Parameters:

ax (Axes, optional) – Existing axes; if None, a new figure/axes is created.
fig (Figure, optional) – Existing figure.
output_path (str or Path, optional) – Path to save the figure.

Return type:

tuple[Any, Any]

Returns:

fig (Figure)
ax (Axes)

prepare_data()[source]

Prepare and order data for plotting.

Returns:: Cleaned and ordered dataframe ready for plotting.
Return type:: pd.DataFrame

GroupedBarPlotter

class bioviz.plots.GroupedBarPlotter(data, config=None)[source]

Bases: object

Class-based interface for grouped bar plots.

Supports: - Direct plotting from pre-computed DataFrames - Computation + plotting from raw group configurations (for proportion CIs) - Both grouped and simple (ungrouped) bar plots - Horizontal and vertical orientations

Examples

>>> # Simple bar plot (no grouping)
>>> config = GroupedBarConfig(
...     group_col=None,
...     orientation="vertical",
... )
>>> plotter = GroupedBarPlotter(df, config)
>>> fig, ax = plotter.plot()

>>> # Grouped horizontal bars with CI
>>> config = GroupedBarConfig(
...     ci_low_col="ci_low",
...     ci_high_col="ci_high",
...     orientation="horizontal",
... )
>>> plotter = GroupedBarPlotter(df, config)
>>> fig, ax = plotter.plot()

>>> # From raw counts (computes Clopper-Pearson CI)
>>> plotter = GroupedBarPlotter.from_proportions(
...     category_list=["TP53", "KRAS", "CDKN2A"],
...     group_configs=[
...         {"name": "Treatment", "k": gene_counts_trt, "n": n_treatment},
...         {"name": "Control", "k": gene_counts_ctrl, "n": n_control},
...     ],
...     config=GroupedBarConfig(ci_method="clopper"),
... )
>>> fig, ax = plotter.plot()

Parameters:

data (DataFrame)
config (GroupedBarConfig | None)

classmethod from_proportions(category_list, group_configs, config=None, value_scale=100.0)[source]

Create plotter by computing proportion summary from group configurations.

Parameters:

category_list (list[str]) – List of categories to analyze.
group_configs (list[dict]) –
Each dict should contain:
- ’name’: str, group name
- ’k’: dict or Series, category -> count mapping
- ’n’: int, total group size
config (GroupedBarConfig, optional) – Configuration for CI method and visual settings.
value_scale (float) – Scale factor (100.0 for percentages).

Returns:

Instance with computed summary data.

Return type:

GroupedBarPlotter

plot(ax=None)[source]

Generate the bar plot.

Parameters:: ax (plt.Axes, optional) – Axes to draw into. Creates new figure if None.
Returns:: The figure and axes objects.
Return type:: tuple[plt.Figure, plt.Axes]

TablePlotter

class bioviz.plots.TablePlotter(df, config)[source]

Bases: object

Stateful wrapper for styled tables.

Construct with (df, config) where config is StyledTableConfig or a dict acceptable to it. Delegates rendering to generate_styled_table.

Parameters:

df (DataFrame)
config (StyledTableConfig | dict)

close()[source]

Return type:: None

plot(ax=None)[source]

Render the styled table and store fig, ax on the instance.

Return type:: tuple[Figure | None, Axes | None]
Parameters:: ax (Axes | None)

save(path, **save_kwargs)[source]

Return type:: None
Parameters:: path (str)

set_data(df)[source]

Return type:: TablePlotter
Parameters:: df (DataFrame)

update_config(**kwargs)[source]

Return type:: TablePlotter

Utility Functions

Kaplan-Meier survival plotter for bioviz-kit.

Provides a high-level interface for generating KM survival curves with optional risk tables using lifelines. Font sizes default to None to inherit from rcParams.

Example

>>> from bioviz.configs import KMPlotConfig
>>> from bioviz.plots import KMPlotter
>>> cfg = KMPlotConfig(time_col="PFS_M", event_col="EVENT", group_col="ARM")
>>> plotter = KMPlotter(df, cfg)
>>> fig, ax, pvalue = plotter.plot()

bioviz.plots.km.add_pvalue_annotation(ax, p_value, loc='bottom_right', box=True, fontsize=12, alpha=0.8, format_p=True)[source]

Add p-value annotation to an axes.

Parameters:

ax (Axes) – The axes to annotate.
p_value (float) – The p-value to display.
loc (str) – Location: ‘top_left’, ‘top_right’, ‘bottom_left’, ‘bottom_right’, ‘center_right’.
box (bool) – Whether to draw a box around the annotation.
fontsize (int | float) – Font size for annotation.
alpha (float) – Background transparency.
format_p (bool) – Whether to format using format_pvalue().

Return type:

Text or None

bioviz.plots.km.format_pvalue(p_value, significance_cutoffs=None)[source]

Format p-value with appropriate precision and notation.

Parameters:

p_value (float) – The p-value to format.
significance_cutoffs (dict, optional) – Mapping of cutoffs to format strings.

Returns:

Formatted p-value string.

Return type:

str