plot

All interactive Altair-based visualizations for multidms.

Every public function accepts DataFrames and returns alt.Chart objects, making them independently testable and usable with any data source.

Public functions

multidms.plot.color_gradient_hex(start, end, n)

Get a list of colors linearly spanning a range.

Parameters:

  • start (str) – Starting color.

  • end (str) – Ending color.

  • n (int) – Number of colors in list.

Returns:

List of hex codes for colors spanning start to end.

Return type:

list

Example

>>> import multidms.plot as mplt
>>> mplt.color_gradient_hex('white', 'red', n=5)
['#ffffff', '#ffbfbf', '#ff8080', '#ff4040', '#ff0000']
multidms.plot.lineplot_and_heatmap(*, data_df, stat_col, category_col, alphabet=None, sites=None, addtl_tooltip_stats=None, addtl_slider_stats=None, init_floor_at_zero=True, init_site_statistic='sum', cell_size=11, lineplot_width=690, lineplot_height=100, site_zoom_bar_width=500, site_zoom_bar_color_col=None, plot_title=None, show_single_category_label=True, category_colors=None, heatmap_negative_color=None, heatmap_color_scheme=None, heatmap_color_scheme_mid_0=True, heatmap_max_at_least=None, heatmap_min_at_least=None, site_zoom_bar_color_scheme='set3', slider_binding_range_kwargs=None, category_prefix_as_replicate=False, categorical_wildtype=False)

Lineplots and heatmaps of per-site and per-mutation values.

Note

This code is _mostly_ from polyclonal, but modified for use with multidms

Parameters:

  • data_df (pandas.DataFrame) – Data to plot. Must have columns “site”, “wildtype”, “mutant”, stat_col, and category_col. The wildtype values (wildtype = mutant) should be included, but are not used for the slider filtering or included in site summary lineplot.

  • stat_col (str) – Column in data_df with statistic to plot.

  • category_col (str) – Column in data_df with category to facet plots over. You can just create a dummy column with some dummy value if you only have one category.

  • alphabet (array-like or None) – Alphabet letters in order. If None, use natsorted “mutant” col of data_df.

  • sites (array-like or None) – Sites in order. If None, use natsorted “site” col of data_df.

  • addtl_tooltip_stats (None or array-like) – Additional mutation-level stats to show in the heatmap tooltips. Values in addtl_slider_stats automatically included.

  • addtl_slider_stats (None or dict) – Additional stats for which to have a slider, value is initial setting. Ignores wildtype and drops it when all mutants have been dropped at site. Null values are not filtered.

  • init_floor_at_zero (bool) – Initial value for option to put floor of zero on value is stat_col.

  • init_site_statistic ({'sum', 'mean', 'max', 'min'}) – Initial value for site statistic in lineplot, calculated from stat_col.

  • cell_size (float) – Size of cells in heatmap

  • lineplot_width (float or None) – Overall width of lineplot.

  • lineplot_height (float) – Height of line plot.

  • site_zoom_bar_width (float) – Width of site zoom bar.

  • site_zoom_bar_color_col (float) – Column in data_df with which to color zoom bar. Must be the same for all entries for a site.

  • plot_title (str or None) – Overall plot title.

  • show_single_category_label (bool) – Show the category label if just one category.

  • category_colors (None or dict) – Map each category to its color, or None to use default. These are the colors for positive values of stat_col.

  • heatmap_negative_color (None or str) – Color used for negative values in heatmaps, or None to use default.

  • heatmap_color_scheme (None or str) – Heatmap uses this Vega scheme rather than category_colors and heatmap_negative_color.

  • heatmap_color_scheme_mid_0 (bool) – Set the heatmap color scheme so the domain mid is zero.

  • heatmap_max_at_least (None or float) – Make heatmap color max at least this large.

  • heatmap_min_at_least (None or float) – Make heatmap color min at least this small, but still set to 0 if floor of zero selected.

  • site_zoom_bar_color_scheme (str) – If using site_zoom_bar_color_col, the Vega color scheme to use.

  • slider_binding_range_kwargs (dict) – Keyed by keys in addtl_slider_stats, with values being dicts giving keyword arguments passed to altair.binding_range (eg, ‘min’, ‘max’, ‘step’, etc.

  • category_prefix_as_replicate (bool) – The first part of the category will be treated as a key on which to merge conditions as if they were replicates. Any number of replicates can be matched with any given category. The replicates will be combined using an inner merge, and tooltips will be added to each point showing the average value of all replicates.

  • categorical_wildtype (bool) – if true, then the columns that are prefixed with ‘wildtype’ and follow with a suffix matching a specific condition, will be labeled with points at all non identical sites when compared with the ‘wildtype’ column (which will be used to mark ‘x’ on each category heatmap).

multidms.plot.convergence_trajectory(df, *, x='iteration', id_cols=None, tooltip_cols=None, trajectory_groups=None, init_group='loss', log_y=True, skip_first=True, width=700, height=250, title='Convergence Diagnostics')

Interactive convergence trajectory plot.

Creates an Altair chart with a dropdown to switch between groups of convergence diagnostics (overall loss, block errors, block stepsizes, block iterations, per-condition parameters). Within each group, individual metrics can be toggled via legend clicks.

Parameters:

  • df (pandas.DataFrame) – Convergence trajectory data, typically from ModelCollection.convergence_trajectory_df() or Model.convergence_trajectory_df. Must contain an iteration column and one or more trajectory value columns.

  • x (str) – Column for the x-axis. Default 'iteration'.

  • id_cols (list of str or None) – Columns that identify distinct model runs (e.g. ['dataset_name', 'fusionreg']). Each unique combination gets a distinct line style. If None, no model identity distinction is made.

  • tooltip_cols (list of str or None) – Extra columns to carry into the hover tooltip (e.g. ['dataset_name', 'fusionreg']). Any name present in df and not already in id_cols is preserved through the melt and shown on hover. These do NOT contribute to line identity (model_id); grouping is determined by id_cols alone.

  • trajectory_groups (dict or None) – Mapping from group name to list of column names. If None, auto-detected from the DataFrame using canonical groupings plus any per-condition columns.

  • init_group (str) – Which group to display initially. Default 'overall'.

  • log_y (bool) – Whether to use log scale on the y-axis. Default True.

  • skip_first (bool) – If True, filter out iteration == 0. Default True.

  • width (int) – Chart width in pixels. Default 700.

  • height (int) – Chart height in pixels. Default 250.

  • title (str or None) – Chart title. Default 'Convergence Diagnostics'.

Returns:

Interactive Altair chart with group dropdown and legend toggle.

Return type:

alt.Chart

multidms.plot.mut_param_heatmap(muts_df_tall, *, mut_param='shift', **kwargs)

Interactive heatmap of mutation parameters across conditions.

Thin wrapper around lineplot_and_heatmap() with mutation-specific defaults.

Parameters:

  • muts_df_tall (pandas.DataFrame) – Long-form DataFrame with columns site, wildtype, mutant, condition, and mut_param.

  • mut_param (str) – Name of the statistic column in muts_df_tall.

  • **kwargs – Passed to lineplot_and_heatmap().

Return type:

alt.Chart

multidms.plot.mut_param_traceplot(muts_df_tall, *, x='fusionreg', mut_param='shift', width_scalar=100, height_scalar=100)

Trace mutation parameter values across regularization weights.

Parameters:

  • muts_df_tall (pandas.DataFrame) – Long-form DataFrame with columns dataset_name, x, mut_type, mutation, condition, and mut_param.

  • x (str) – Column for the x-axis. Default 'fusionreg'.

  • mut_param (str) – Column with mutation parameter values. Default 'shift'.

  • width_scalar (int) – Width multiplier per facet column.

  • height_scalar (int) – Height multiplier per facet row.

Return type:

alt.FacetChart

multidms.plot.shift_sparsity(sparsity_df, *, x='fusionreg', width_scalar=100, height_scalar=100)

Visualize shift parameter sparsity across regularization weights.

Parameters:

  • sparsity_df (pandas.DataFrame) – DataFrame with columns dataset_name, x, mut_type, mut_param, and sparsity.

  • x (str) – Column for the x-axis. Default 'fusionreg'.

  • width_scalar (int) – Width multiplier per facet column.

  • height_scalar (int) – Height multiplier per facet row.

Return type:

alt.FacetChart

multidms.plot.mut_param_dataset_correlation(replicate_df, *, x='fusionreg', r=1, width_scalar=400, height=400)

Visualize mutation parameter correlation between replicate datasets.

Parameters:

  • replicate_df (pandas.DataFrame) – DataFrame with columns datasets, mut_param, correlation, and x.

  • x (str) – Column for the x-axis. Default 'fusionreg'.

  • r (int) – Exponent used (1 for pearson, 2 for R^2). Only affects title.

  • width_scalar (int) – Width multiplier per facet column.

  • height (int) – Chart height.

Return type:

alt.FacetChart

multidms.plot.replicate_param_scatter(muts_df_pair, *, x_col, y_col, x_label=None, y_label=None, color_by=None, point_size=30, point_opacity=0.5, width=500, height=500)

Scatter plot comparing mutation parameters between two replicates.

Parameters:

  • muts_df_pair (pandas.DataFrame) – One row per mutation with columns x_col, y_col. The mutation column (or index) contains mutation strings like “A5G”. Optional columns for tooltips: site, wildtype, mutant (derived by parsing mutation strings via split_sub).

  • x_col (str) – Column names for the two datasets’ parameter values.

  • y_col (str) – Column names for the two datasets’ parameter values.

  • x_label (str or None) – Axis labels (default to column names).

  • y_label (str or None) – Axis labels (default to column names).

  • color_by (str or None) – Column to color points by.

  • point_size (float) – Point styling.

  • point_opacity (float) – Point styling.

  • width (int) – Chart dimensions.

  • height (int) – Chart dimensions.

Returns:

Scatter + diagonal identity line + Pearson r annotation.

Return type:

alt.LayerChart

multidms.plot.times_seen_hist(mutations_df, *, conditions=None, width=400, height=300)

Interactive histogram of mutation occurrence counts.

Parameters:

  • mutations_df (pandas.DataFrame) – Mutations DataFrame with times_seen_{condition} columns.

  • conditions (list of str or None) – Condition names. If None, auto-detected from column names matching times_seen_*.

  • width (int) – Chart width in pixels.

  • height (int) – Chart height in pixels.

Return type:

alt.Chart

multidms.plot.func_score_boxplot(variants_df, *, width=400, height=300)

Interactive boxplot of functional scores by condition.

Parameters:

  • variants_df (pandas.DataFrame) – Variants DataFrame with condition and func_score columns.

  • width (int) – Chart width in pixels.

  • height (int) – Chart height in pixels.

Return type:

alt.Chart

multidms.plot.ge_landscape(variants_df, ge_curve_df, fitness_col=None, color_by='condition', point_size=5, point_opacity=0.3, curve_color='grey', curve_width=3, width=500, height=400, space='fitness', params_df=None, annotate_params=True)

Plot the global epistasis landscape.

Overlays per-variant fitness scores on the global epistasis curve g(φ), showing how the nonlinear transformation maps latent phenotype to observed fitness. Wildtype latent phenotypes for each condition are shown as dashed vertical reference lines.

Parameters:

  • variants_df (pandas.DataFrame) – Variant-level data with columns predicted_latent, condition, wildtype_latent, and fitness_col. Typically from Model.get_ge_landscape_df().

  • ge_curve_df (pandas.DataFrame) – Curve DataFrame. For space="fitness" it has columns predicted_latent and ge_curve_value; for space="func_score" it is long-form with condition, predicted_latent and func_score_curve_value. Typically from Model.get_ge_landscape_df().

  • fitness_col (str, optional) – Which variant column to scatter on the y-axis. When None (the default), resolves to the measured observation for each space: 'measured_fitness' for space="fitness" and 'func_score' for space="func_score". The model’s prediction is the curve itself (predicted_func_score equals the per-condition curve evaluated at each variant’s latent), so the scatter shows measured data and the curve shows the fit; the vertical gap is the residual. Pass 'predicted_func_score' explicitly to overlay predictions.

  • color_by (str) – Column to color scatter points by. Default is 'condition'.

  • point_size (float) – Size of scatter points. Default is 5.

  • point_opacity (float) – Opacity of scatter points. Default is 0.3.

  • curve_color (str) – Color of the g(φ) curve. Default is 'grey'.

  • curve_width (float) – Stroke width of the g(φ) curve. Default is 3.

  • width (int) – Chart width in pixels. Default is 500.

  • height (int) – Chart height in pixels. Default is 400.

  • space (str) – "fitness" (default) draws the single shared g(φ) curve on ge_curve_value. "func_score" draws one condition-colored curve per condition on func_score_curve_value and labels the y-axis “Functional score”.

  • params_df (pandas.DataFrame, optional) – Per-condition placement parameters from Model.get_ge_params_df(), used to annotate the chart with α, β0 and the bundle sum. When None (the default) no annotation is drawn, so direct callers of this function are unaffected. Model.plot_ge_landscape() supplies it automatically.

  • annotate_params (bool) – Master switch for the annotation. The annotation renders only when annotate_params is True and params_df is not None.

Returns:

Altair layered chart with scatter, curve, and wildtype reference lines, plus two text layers when annotating.

Return type:

alt.LayerChart