advanced_design#

Functions

`assign_conditional_subparameter`(cat_samples, ...)	Sample subparameter values conditioned on the parent category assignment.
`calculate_a_optimality`(design, ...)	Calculate A-optimality (trace of the inverse information matrix) for the continuous and subparameter columns.
`calculate_condition_number`(design, ...)	Calculate the condition number of the information matrix for the continuous and subparameter columns.
`calculate_d_optimality`(design, ...)	Calculate D-optimality (determinant of the information matrix) for the continuous and subparameter columns.
`calculate_max_categorical_correlation`(...)	Calculate the maximum Cramér's V association among all pairs of categorical columns.
`calculate_max_continuous_correlation`(design, ...)	Calculate the maximum absolute Pearson correlation among all pairs of continuous and subparameter columns.
`calculate_max_mixed_correlation`(design, ...)	Calculate the maximum association between categorical and continuous/subparameter columns using eta-squared (sqrt).
`calculate_mixed_correlation_matrix`(df[, ...])	Compute a pairwise correlation matrix that handles mixed variable types:
`calculate_pairwise_distance_uniformity`(...)	Calculate the coefficient of variation (CV) of pairwise Euclidean distances between design points in the continuous/subparameter space.
`cramers_v_np`(contingency)	Compute Cramér's V association statistic for a contingency table.
`eta_squared_np`(cat_codes, num_values)	Compute the eta-squared effect size between a categorical and a numeric variable.
`evaluate_candidate`(i, seed_start, n, ...[, ...])	Generate `n` new samples, append them to `existing_design`, and compute quality metrics for the combined design.
`evaluate_design`(design, continuous_keys, ...)	Evaluate a design using the specified quality metrics.
`extend_design`(existing_design, n, ...[, ...])	Extend an existing design by finding the best set of `n` new samples from among multiple candidates evaluated in parallel.
`find_best_design_parallel`(n, n_samples, ...)	Generate `n` candidate designs in parallel and return the one with the highest composite score.
`generate_and_evaluate`(seed, n_samples, ...)	Generate a single candidate design and compute its quality metrics.
`infer_column_types`(df)	Canonical column-type rule: object/category dtype -> categorical, else numerical.
`infer_subparam_mapping`(conditional_subparameters)	Infer the subparameter mapping from `conditional_subparameters` by finding categorical variables that have exactly one subparameter across all their levels.
`non_uniform_lhs_categorical`(level_dict, ...)	Draw LHS-stratified categorical samples using inverse-transform sampling with per-level frequency weights.
`optimize_category_assignment_parallel`(...[, ...])	Search for the category assignment (for the variable that has a subparam mapping) that minimizes the maximum inter-category correlation.
`plot_correlation_matrix`(design, categorical_vars)	Plot a heatmap of the mixed correlation matrix.
`plot_design_histograms`(design, ...[, ...])	Plot histograms for continuous parameters and bar charts for categorical variables, with stacked histograms for subparameters colored by parent category.
`plot_design_quality_evolution`(metrics_df)	Plot per-metric bar charts over trial seeds to visualize design quality evolution.
`plot_mds`(design, continuous_params_keys, ...)	Plot an MDS projection of the continuous and subparameter columns.
`plot_pca`(design, continuous_params_keys, ...)	Plot a PCA projection of the continuous and subparameter columns.
`plot_umap`(design, continuous_params_keys, ...)	Plot a UMAP projection of the continuous and subparameter columns.
`sample_continuous_lhs`(continuous_params, ...)	Draw LHS samples for all continuous parameters, mapping [0, 1) uniform samples to the discrete level sets defined in `continuous_params`.
`sample_design`(seed, n_samples, ...[, ...])	Generate a complete experimental design by LHS-sampling all continuous and categorical parameters.

Classes

AdvExpDesigner([continuous_params, ...])

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

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)[source]#

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.

compare_frequencies(design, verbose=True)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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[source]#

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)[source]#

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)[source]#

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

Parameters:: design – The design DataFrame to visualize.

plot_histograms(design)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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[source]#

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