AdvExpDesigner

class obsidian.experiment.advanced_design.AdvExpDesigner(continuous_params: dict | None = None, conditional_subparameters: dict | None = None, subparam_mapping: dict | None = None, design_df: DataFrame | None = None, X_space=None, seed: int | None = None, n_category_trials: int = 100, corr_threshold: float = 0.01)

Bases: ExpDesigner

An advanced experimental designer that extends ExpDesigner with support for biased/constrained sampling, categorical subparameters, and design quality metrics.

Extends ExpDesigner so it can be passed directly to Campaign as the designer argument. When X_space is provided, campaign.initialize() will call generate_design() and honor all biases and constraints defined in continuous_params and conditional_subparameters.

__init__(continuous_params: dict | None = None, conditional_subparameters: dict | None = None, subparam_mapping: dict | None = None, design_df: DataFrame | None = None, X_space=None, seed: int | None = None, n_category_trials: int = 100, corr_threshold: float = 0.01)

Initializes the AdvExpDesigner with experimental parameters and optional subparameter mappings.

Parameters:

• continuous_params –

  A dictionary containing the continuous parameters for the design. Each parameter can be specified as:

  • (low, high, step): Linear spacing with a fixed step size.

  • (low, high, "geometric"): Geometric spacing (doubling).

  • (low, high, "logarithmic"): Logarithmic spacing (powers of 10).

  • [value1, value2, ...]: Custom list of specific levels to sample from.

  • {'levels': [...], 'biases': [...]}: Custom levels with optional bias weights for non-uniform sampling. Biases are normalized to sum to 1.0 if they do not already.

• conditional_subparameters – A dictionary containing the conditional subparameters for the design.

• subparam_mapping – A dictionary for mapping; inferred automatically if not provided.

• design_df – A pandas DataFrame of an existing experimental design. Defaults to None.

• X_space – obsidian ParamSpace for Campaign integration. When provided, the designer can be passed as designer= to a Campaign and campaign.initialize() will use the biased/constrained sampling defined here. The keys in continuous_params must match the parameter names in X_space.

• seed – Random seed for reproducibility (used by initialize()).

• n_category_trials – Number of random category assignments evaluated when optimize_categories=True. Higher values reduce inter-category correlation at the cost of runtime. Defaults to 100.

• corr_threshold – Early-exit correlation threshold for category optimization. When the best assignment reaches a max correlation below this value the search terminates early. Defaults to 0.01.

Methods

__init__([continuous_params, ...])	Initializes the AdvExpDesigner with experimental parameters and optional subparameter mappings.
compare_frequencies(design[, verbose])	Compares the empirical frequencies of categorical variables in the design with the expected frequencies defined in conditional_subparameters.
evaluate_design(design[, metrics_to_optimize])	Evaluates the quality of the given design based on specified metrics.
extend_design(existing_design, n[, seed, ...])	Extends an existing design by appending the best-scoring set of new samples chosen from multiple candidates.
generate_design(seed, n_samples[, ...])	Generates a design by sampling from the given parameter space.
initialize([m_initial, method, ...])	Generates an initial experimental design honoring all biases and constraints defined in continuous_params and conditional_subparameters.
load_state(obj_dict[, X_space, seed])	Reconstruct an AdvExpDesigner from a saved state dictionary.
optimize_design(n_trials, n_samples[, ...])	Optimizes the design by generating multiple candidates and selecting the best according to a composite score over the specified metrics.
plot_correlation(design)	Plots a mixed correlation matrix heatmap for the design's parameters.
plot_histograms(design)	Plots histograms (continuous) and bar charts (categorical) for each parameter in the design.
plot_mds(design[, hue])	Performs Multidimensional Scaling (MDS) on the continuous parameters and plots the two-dimensional embedding.
plot_pca(design[, hue])	Performs PCA on the continuous parameters and plots the first two components.
plot_quality_evolution(metrics_df)	Plots per-metric bar charts over trial seeds to visualize design quality evolution.
plot_umap(design[, hue, verbose])	Performs UMAP dimensionality reduction on the continuous parameters and plots the two-dimensional embedding.
save_state()	Save the designer state to a JSON-serializable dictionary.

compare_frequencies(design, verbose=True)

Compares the empirical frequencies of categorical variables in the design with the expected frequencies defined in conditional_subparameters.

Parameters:

• design – The design DataFrame to analyze.

• verbose – If True, print the frequency table to stdout. Defaults to True.

Returns:

A DataFrame with columns

['categorical_var', 'level', 'expected', 'empirical'] containing one row per level of each categorical variable.

Return type:

pd.DataFrame

evaluate_design(design, metrics_to_optimize=None)

Evaluates the quality of the given design based on specified metrics.

Parameters:

• design – The design DataFrame to evaluate.

• metrics_to_optimize – List of metric names to evaluate. Defaults to all metrics in DEFAULT_METRICS.

Returns:

Computed metric values keyed by metric name.

Return type:

dict

extend_design(existing_design, n, seed=None, n_trials=10, metrics_to_optimize=None, maximize_metrics=None, max_workers=None)

Extends an existing design by appending the best-scoring set of new samples chosen from multiple candidates.

Parameters:

• existing_design – The existing design DataFrame to extend.

• n – Number of new samples to add.

• seed – Optional random seed for reproducibility.

• n_trials – Number of candidate extensions to evaluate. Defaults to 10.

• metrics_to_optimize – List of metric names to include in scoring. Defaults to all seven standard metrics.

• maximize_metrics – List of booleans indicating whether to maximize each metric. Defaults to [True, False, False, ...].

• max_workers – Number of parallel worker processes.

Returns:

(extended_design, metrics_summary) where extended_design

contains all original rows plus the best new rows, and metrics_summary is a pd.DataFrame of candidate scores.

Return type:

tuple

generate_design(seed, n_samples, optimize_categories=True)

Generates a design by sampling from the given parameter space.

Parameters:

• seed – Random seed for reproducibility.

• n_samples – Number of samples to generate.

• optimize_categories – Whether to optimize categorical assignments to reduce inter-category correlation. Defaults to True.

Returns:

The generated sample design.

Return type:

pd.DataFrame

Note

When optimize_categories=True, only the first subparam-mapped category (as determined by subparam_mapping) is optimized. Additional categorical variables are assigned with a single random draw.

initialize(m_initial=None, method='LHS', sample_custom=None, optimize_categories=False)

Generates an initial experimental design honoring all biases and constraints defined in continuous_params and conditional_subparameters.

Overrides ExpDesigner.initialize() so that a Campaign whose designer is an AdvExpDesigner will automatically use biased/constrained sampling.

Parameters:

• m_initial – Number of initial experiments. Defaults to 2 * n_dim when X_space is provided, or raises if neither is available.

• method –

  Sampling strategy.

  • 'LHS' (default): calls generate_design() with LHS + biases.

  • 'Optimized': calls optimize_design() to maximize D-optimality across multiple trials (slower but higher-quality).

• sample_custom – Ignored; retained for API compatibility with ExpDesigner.

• optimize_categories – Whether to optimize categorical assignments to minimize correlation (passed to generate_design()). Defaults to False.

Returns:

The generated design.

Return type:

pd.DataFrame

Raises:

ValueError – If m_initial cannot be inferred (no X_space and no m_initial given).

classmethod load_state(obj_dict: dict, X_space=None, seed: int | None = None) → AdvExpDesigner

Reconstruct an AdvExpDesigner from a saved state dictionary.

Parameters:

• obj_dict (dict) – Output of save_state().

• X_space – Override for the parameter space. When provided (typically by Campaign.load_state()), the X_space payload in obj_dict is ignored. Defaults to None.

• seed (int | None, optional) – Override for the seed. When provided, obj_dict['seed'] is ignored. Defaults to None.

Returns:

A new designer instance equivalent to the saved one.

Return type:

AdvExpDesigner

optimize_design(n_trials, n_samples, metrics_to_optimize=None, maximize_metrics=None, seed_start=0, max_workers=None)

Optimizes the design by generating multiple candidates and selecting the best according to a composite score over the specified metrics.

Parameters:

• n_trials – Number of candidate designs to generate and evaluate.

• n_samples – Number of experiments in each candidate design.

• metrics_to_optimize – List of metric names to include in the composite score. Defaults to all seven standard metrics.

• maximize_metrics – List of booleans, one per metric, indicating whether each metric should be maximized (True) or minimized (False). Defaults to [True, False, False, ...] — maximize D-optimality only.

• seed_start – Starting random seed for candidate generation. Defaults to 0.

• max_workers – Maximum number of parallel worker processes. Defaults to None (uses all available CPUs).

Returns:

(best_design, metrics_df) where best_design is the

highest-scoring pd.DataFrame and metrics_df is a pd.DataFrame summarizing all candidates.

Return type:

tuple

plot_correlation(design)

Plots a mixed correlation matrix heatmap for the design’s parameters.

Parameters:

design – The design DataFrame to visualize.

plot_histograms(design)

Plots histograms (continuous) and bar charts (categorical) for each parameter in the design.

Parameters:

design – The design DataFrame to visualize.

plot_mds(design, hue=None)

Performs Multidimensional Scaling (MDS) on the continuous parameters and plots the two-dimensional embedding.

Parameters:

• design – The design DataFrame to analyze.

• hue – Name of a categorical column to use for color-coding points.

plot_pca(design, hue=None)

Performs PCA on the continuous parameters and plots the first two components.

Parameters:

• design – The design DataFrame to analyze.

• hue – Name of a categorical column to use for color-coding points.

plot_quality_evolution(metrics_df)

Plots per-metric bar charts over trial seeds to visualize design quality evolution.

Parameters:

metrics_df – DataFrame containing trial metrics (must include a ‘seed’ column).

plot_umap(design, hue=None, verbose=False)

Performs UMAP dimensionality reduction on the continuous parameters and plots the two-dimensional embedding.

Parameters:

• design – The design DataFrame to analyze.

• hue – Name of a categorical column to use for color-coding points.

• verbose – Whether to show UMAP’s internal progress log. Defaults to False.

save_state() → dict

Save the designer state to a JSON-serializable dictionary.

Returns:

JSON-safe payload containing every constructor argument plus

the class name for polymorphic dispatch.

Return type:

dict