comet.multiverse

class comet.multiverse.Multiverse(name='multiverse', path=None)

Bases: object

Multiverse class for creating, running, and visualizing a multiverse analysis.

Parameters:

• name (str) – Name of the multiverse analysis. Default is “multiverse”.

• path (str) – Path to a multiverse directory (only used by the GUI).

create(analysis_template, forking_paths, config={})

Create the individual universe scripts

Parameters:

• analysis_template (function) – Function containing the analysis template

• forking_paths (dict) – Dictionary containing the forking paths

• config (dict) – Configuration dictionary with optional combination rules - order : list of lists specifying the order of decisions - exclude : list of list[dict or str] (set listed keys to NaN if conditions match) - remove : list of list[dict or str] (drop universes if conditions match) - deduplicate : bool (collapse duplicates after exclude/remove; default True)

get_results(universe=None, as_df=False, expand_dec=False)

Get the results of the multiverse (or a specific universe).

Parameters:

• universe (int | None) – If given, return results for that specific universe.

• as_df (bool) – False returns the raw dict (default). True returns a pandas DataFrame (only valid when universe is None).

integrate(measure=None, method='uniform', type='mean')

Integrate the multiverse results.

Parameters:

• measure (string) – Name of the measure to integrate.

• method (string) –

  Method to use for integration. Options are:

  ”uniform” (default): Simple mean/median across all universes “bma”: Bayesian model averaging (requires BIC values in the results)

• type (string) – Type of (weighted) integration. Options are “mean” (default) or “median”.

multiverse_plot(measure: str, n_bins: int = 20, sig_col: str | None = None, sig_threshold: float = 0.05, baseline: float | None = None, name_map: dict | None = None, figsize: tuple = (7, 9), ftype: str = 'pdf', dpi: int = 300)

Multiverse plot as introduced by Krähmer & Young (2026).

This plot visualises the distribution of multiverse outcomes together with heatmap strips showing how different analytic choices relate to the outcome. For each decision level, the average change in the outcome relative to the reference level is shown on the right.

The figure is saved to the results directory as “multiverse_plot.{ftype}”.

References

Krähmer, D., & Young, C. (2026). Visualizing vastness: Graphical methods for multiverse analysis. PLOS One, 21(2). https://doi.org/10.1371/journal.pone.0339452

Parameters:

• measure (str) – Name of the outcome/measure column in the multiverse results. Entries may be scalars or lists/arrays (in which case the mean is used).

• n_bins (int, optional) – Number of bins used to discretise the outcome axis for the heatmap strips.

• sig_col (str | None, optional) – Column indicating statistical significance. If provided: - boolean values are interpreted directly (True = significant), - numeric values are compared against sig_threshold. If None, no significance overlay is drawn.

• sig_threshold (float, optional) – Threshold used when sig_col is numeric (default is 0.05).

• baseline (float | None, optional) – Optional baseline value for the outcome. If provided, a vertical dashed reference line is drawn at this value in the density plot.

• name_map (dict | None, optional) – Optional mapping for display names. Keys may include the measure name and decision names. Values are the desired display labels.

• figsize (tuple, optional) – Figure size passed to Matplotlib (width, height) in inches.

• ftype (str, optional) – File type used when saving the figure (e.g., "pdf", "png").

• dpi (int, optional) – Resolution (dots per inch) used when saving the figure.

Returns:

The figure if in a .py script. None if in a .ipynb notebook (the figure is saved and displayed inline)

Return type:

Any

run(universe=None, parallel=1, combine_results=True)

Run either an individual universe or the entire multiverse

Parameters:

• universe (None, int, list, range) – Number of the universe to run. Default is None, which runs all universes

• parallel (int) – Number of universes to run in parallel

specification_curve(measure: str, baseline: float | None = None, p_value: float | str | bool | None = None, ci: int | str | bool | None = None, smooth_ci: bool = True, title: str | None = None, name_map: dict | None = None, cmap: str = 'Set3', linewidth: float = 2, figsize: tuple | None = None, height_ratio: tuple = (2, 1), fontsize: int = 10, dotsize: int = 50, line_pad: float = 0.3, ftype: str = 'pdf', dpi: int = 300, p_threshold: float = 0.05, ci_level_default: int = 95)

Create a specification curve plot from multiverse results.

The figure is saved to the results directory as “specification curve.{ftype}”.

Notes

• If p_value is float or True, measure must contain list/array samples per universe.

• If ci is int or True, measure must contain list/array samples per universe.

• If p_value is a string, it is interpreted as a p-value column (numeric) or a significance flag (bool).

• If ci is a string, it must contain per-universe (lower, upper) bounds.

Returns:

The figure if in a .py script. None if in a .ipynb notebook (the figure is saved and displayed inline)

Return type:

Any

summary(universe=None, print_df=True, return_df=False)

Print the multiverse summary to the terminal/notebook

Parameters:

universe (int, range, or None) – The universe number(s) to display. Default is None (prints the head)

visualize(universe=None, figsize=(8, 5), node_size=1500, text_size=12, max_label_len=15, label_offset=0.04, cmap='Set2', exclude_single=False)

Visualize the multiverse as a network.

Parameters:

• universe (int or None) – The universe to highlight in the network. If None or if the provided universe number is higher than available universes, the entire multiverse is shown without highlighting. Default is None.

• figsize (tuple) – Size of the figure. Default is (8,5).

• node_size (int) – Size of the nodes. Default is 1500.

• text_size (int) – Size of the text labels. Default is 12.

• max_label_len (int) – Maximum length of decision labels before wrapping.

• label_offset (float) – Offset multiplier for decision labels.

• cmap (str) – Colormap to use for the nodes. Default is “Set2”.

• exclude_single (bool) – Whether to exclude parameters with only one unique option.

comet.multiverse.load_multiverse(path=None)

Load a previously created multiverse from disk.

Parameters:

path (str) – A full/relative path to an existing multiverse folder