extendedmosaicperm.experiments.plotting module

compute_power_table(df_flat, alpha=0.05)

Aggregate empirical power across methods and configurations.

Parameters:

• df_flat (DataFrame) – Long-form DataFrame from BaseExperiment.flatten().

• alpha (float) – Significance level used to compute power (default 0.05).

Returns:

DataFrame with columns:

• "gen",

• "size",

• "sym",

• "method",

• "violation_strength",

• "power".

Return type:

pandas.DataFrame

enrich_flatten(df_flat)

Add parsed label components as columns to a flattened DataFrame.

Parameters:

df_flat (DataFrame) – Long-form DataFrame from BaseExperiment.flatten(), containing at least a "label" column.

Returns:

Copy of df_flat with extra columns added:

• "gen",

• "size",

• "sym",

• "method".

Return type:

pandas.DataFrame

parse_label(label)

Parse an experiment label into components.

Parameters:

label (str) – Label string of the form "<generator>_<size>_<sym|asym>_<method>".

Returns:

Parsed components with keys:

• "gen",

• "size",

• "sym",

• "method".

Return type:

Dict[str, str]

plot_figure3_panels(L_time, simulate_fn, *, test_stat=<function mean_maxcorr_stat>, n_rep_a=100, n_rep_b=100, b_boot=300, n_runs_c=100, n_perm_c=300, bins_a=25, bins_b=25, bins_c=25, seed=42, colors=None, outdir=None, save_basename='figure3_panels', title_fontsize=14, label_fontsize=12, tick_fontsize=11, legend_fontsize=11)

Reproduce a three-panel comparison: naive permutation, bootstrap, and Mosaic test.

Panel (a) compares the naive permutation distribution of the maximum off-diagonal correlation with the observed OLS-based statistic. Panel (b) compares bootstrap Z-statistics with a standard normal. Panel (c) compares Mosaic test statistics with their permutation null.

Parameters:

• L_time (ndarray) – Time-varying exposures of shape (T, p, k).

• simulate_fn (Callable[[Generator], ndarray]) – Callable that takes a NumPy Generator and returns a simulated outcome matrix Y of shape (T, p).

• test_stat (Callable) – Test statistic to be used by the Mosaic test.

• n_rep_a (int) – Number of datasets for panel (a).

• n_rep_b (int) – Number of datasets for panel (b).

• b_boot (int) – Number of bootstrap draws per dataset in panel (b).

• n_runs_c (int) – Number of datasets for panel (c).

• n_perm_c (int) – Number of permutations per dataset in panel (c).

• bins_a (int) – Number of bins for the histogram in panel (a).

• bins_b (int) – Number of bins for the histogram in panel (b).

• bins_c (int) – Number of bins for the histogram in panel (c).

• seed (int) – Seed used to initialize the random generator.

• colors (Optional[Dict[str, str]]) – Optional mapping for color names {"null": ..., "alt": ..., "boot": ...}.

• outdir (Optional[str]) – Optional output directory to save the figure as PNG.

• save_basename (str) – Base file name for saving (without extension).

• title_fontsize (int) – Font size for panel titles.

• label_fontsize (int) – Font size for axis labels.

• tick_fontsize (int) – Font size for tick labels.

• legend_fontsize (int) – Font size for legend entries.

Returns:

The figure and a dictionary with the simulated statistics.

Return type:

tuple[matplotlib.figure.Figure, Dict[str, np.ndarray]]

plot_qq_grid_all_sizes(df_flat, generators=None, sizes=None, v=0.0, symmetry_options=('sym', 'asym'), method_linestyles=None, figscale=(12, 16), output_path=None, title_fontsize=17, label_fontsize=16, tick_fontsize=15, legend_fontsize=14, legend_ncol=None, legend_offset=-0.012, tight_rect=(0.02, 0.05, 0.98, 0.96))

Create a QQ-grid by generator (rows) and symmetry (columns).

Each panel shows QQ-plots of p-values at a fixed violation level v, colored by size and styled by method.

Parameters:

• df_flat (DataFrame) – Long-form DataFrame from BaseExperiment.flatten().

• generators (Optional[Iterable[str]]) – Generators to display. If None, all available generators are used.

• sizes (Optional[Iterable[str]]) – Size categories to display. If None, all available sizes are used.

• v (float) – Violation strength to slice on.

• symmetry_options (Iterable[str]) – Iterable of symmetry flags (e.g. ("sym", "asym")).

• method_linestyles (Optional[Dict[str, str]]) – Mapping from method to line style, e.g. {"perm": "-", "sign": "--"}. If None, a default mapping is used.

• figscale (Tuple[int, int]) – Figure size as (width, height) in inches.

• output_path (Optional[str]) – Optional path to save the figure as an image.

• title_fontsize (int) – Font size for panel titles.

• label_fontsize (int) – Font size for axis labels.

• tick_fontsize (int) – Font size for tick labels.

• legend_fontsize (int) – Font size for legend labels.

• legend_ncol (Optional[int]) – Number of columns in the combined legend. If None, a heuristic is used.

• legend_offset (float) – Vertical offset for the combined legend in figure coordinates.

• tight_rect (Tuple[float, float, float, float]) – Bounding rectangle for matplotlib.pyplot.tight_layout().

Returns:

The created figure.

Return type:

matplotlib.figure.Figure

Raises:

ValueError – If the required label structure or requested generators / sizes are not present in the data.

plot_qq_grid_generators_by_alpha(df_flat, generators, alphas, sizes=None, symmetry='asym', method_linestyles=None, figscale_base=(5.8, 4.8), output_path=None, title_fontsize=17, label_fontsize=16, tick_fontsize=15, legend_fontsize=14, legend_ncol=3, legend_offset=-0.012, tight_rect=(0.02, 0.05, 0.98, 0.94))

Create a QQ-grid with rows = generators and columns = violation strengths.

Parameters:

• df_flat (DataFrame) – Long-form DataFrame from BaseExperiment.flatten().

• generators (Iterable[str]) – Generators to include as rows.

• alphas (Iterable[float]) – Violation strength values (x-axis conditions) to include as columns.

• sizes (Optional[Iterable[str]]) – Size categories to display. If None, all available sizes are used.

• symmetry (str) – Symmetry flag to filter on (e.g. "asym").

• method_linestyles (Optional[Dict[str, str]]) – Mapping from method to line style. If None, a default mapping is used.

• figscale_base (Tuple[float, float]) – Base figure size for a single panel. Total figure size scales with the grid dimensions.

• output_path (Optional[str]) – Optional path to save the figure as an image.

• title_fontsize (int) – Font size for panel titles.

• label_fontsize (int) – Font size for axis labels.

• tick_fontsize (int) – Font size for tick labels.

• legend_fontsize (int) – Font size for legend labels.

• legend_ncol (int) – Number of columns in the combined legend.

• legend_offset (float) – Vertical offset for the combined legend.

• tight_rect (Tuple[float, float, float, float]) – Bounding rectangle for matplotlib.pyplot.tight_layout().

Returns:

The created figure.

Return type:

matplotlib.figure.Figure

Raises:

ValueError – If there is no data after filtering or requested sizes are not present.