Contextual bo generator

[roussel-ryan]

This pull request introduces contextual Bayesian optimization support and improves handling of contextual variables throughout the codebase and documentation. The changes enable users to define contextual variables that are observed (not controlled), ensure correct validation and bounds handling, and provide a new example notebook and documentation entry for contextual Bayesian optimization.

Key changes include:

Contextual Bayesian Optimization Example and Documentation

• Added a new example notebook contextual_bo.ipynb demonstrating and comparing standard versus contextual Bayesian optimization on a drifting objective, and updated the documentation navigation to include this example. [1] [2]

VOCS Validation and Data Handling

• Updated Xopt in xopt/base.py to properly handle contextual variables during input validation: contextual variables are allowed to be missing from candidate data and are filled with NaN for validation purposes. This ensures that contextual variables are treated as observed, not controlled, throughout evaluation and data addition. [1] [2] [3] [4]

Bayesian Generator Improvements

• Refactored the Bayesian generator to support contextual variables:
  • Contextual variables are now imported and handled alongside fixed features.
  • Model input bounds are determined using a new method that accounts for contextual variables.
  • Acquisition functions are now conditioned on the latest observed contextual variable values, and fixed features/contextual variables are applied together in a new unified method.
  • Visualization and optimum finding routines are updated to handle contextual variables appropriately, including special handling for plotting axes and acquisition function display. [1] [2] [3] [4] [5] [6] [7] [8] [9]

These changes collectively enable robust contextual Bayesian optimization workflows and improve clarity and correctness in handling contextual variables across the codebase.

[codecov]

Codecov Report

❌ Patch coverage is 94.71545% with 13 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
xopt/generators/bayesian/bayesian_generator.py	89.65%	2 Missing and 4 partials ⚠️
xopt/generators/bayesian/visualize.py	85.29%	2 Missing and 3 partials ⚠️
...pt/tests/generators/bayesian/test_contextual_bo.py	97.95%	1 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[roussel-ryan]

@copilot address the code coverage issues and notebook failures by adding tests and modifying source code / example notebooks as needed

[Copilot]

@copilot address the code coverage issues and notebook failures by adding tests and modifying source code / example notebooks as needed

Addressed the coverage and notebook failures with the following fixes (commits 8cffe9d and 64eac4e):

Notebook failures (multi-fidelity):

• Fixed a variable-ordering bug in convert_numpy_to_inputs (and convert_dataframe_to_inputs) in vocs.py. The PR had changed these to sort variable names alphabetically, but the Bayesian optimizer returns results in vocs.variable_names order. For multi-fidelity this meant the optimizer's x value (≈3.59) was being assigned to s (the fidelity parameter), causing validate_input_data to fail since s must be in [0, 1]. Both functions now preserve vocs.variable_names order, filtering out contextual variables in place.

Bug fix in get_optimum:

• Fixed a TypeError that would occur when contextual_variables is non-empty but fixed_features is None — the code was checking name not in self.fixed_features (which is None). Fixed to use fixed = self.fixed_features or {}.

New tests added:

• test_get_optimum_with_contextual_variable — verifies get_optimum returns only controllable variable candidates
• test_contextual_variable_bounds_from_data — verifies contextual variable bounds are derived from data with 5% padding
• test_contextual_variable — verifies ContextualVariable has infinite domain
• test_convert_numpy_to_inputs_with_contextual_variable — verifies column ordering is preserved and contextual variables are excluded

[Copilot]

Pull request overview

This PR adds first-class support for contextual (observed, not controlled) variables across VOCS handling, Bayesian generator behavior, visualization, and documentation, enabling contextual Bayesian optimization workflows.

Changes:

• Introduces ContextualVariable and updates input conversion/validation paths to allow contextual columns to be omitted from candidates while still validating shapes/bounds.
• Updates Bayesian generators to condition acquisition functions on the latest observed contextual values and to derive contextual input bounds from observed data.
• Adds visualization behavior/tests for contextual axes (acquisition plot replaced by a warning panel), plus a new example notebook and docs nav entry.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
xopt/vocs.py	Adds ContextualVariable and updates dataframe/numpy input conversion to exclude contextual variables.
xopt/base.py	Allows contextual variables to be omitted from candidate inputs by inserting temporary NaN columns for validation.
xopt/generators/bayesian/bayesian_generator.py	Adds contextual conditioning and contextual bounds derivation for model inputs; refactors fixed-feature application.
xopt/generators/bayesian/mobo.py	Routes acquisition post-processing through unified fixed-feature + contextual conditioning helper.
xopt/generators/bayesian/expected_improvement.py	Routes acquisition post-processing through unified fixed-feature + contextual conditioning helper.
xopt/generators/bayesian/visualize.py	Infers finite bounds for contextual variables from data and renders a warning panel when contextual axes are selected for acquisition plots.
xopt/generators/bayesian/bax/visualize.py	Updates mesh generation call to pass data (for contextual-bound inference).
xopt/generators/bayesian/objectives.py	Updates get_sampler import path.
xopt/generators/bayesian/models/standard.py	Adjusts optimizer selection/options to improve compatibility across batched models / botorch+scipy variants.
xopt/tests/test_vocs.py	Adds tests for ContextualVariable and numpy-to-input conversion with contextual vars/order preservation.
xopt/tests/generators/bayesian/test_visualize.py	Adds tests for acquisition plotting/visualization warnings when contextual axes are selected.
xopt/tests/generators/bayesian/test_model_constructor.py	Makes training comparison test less optimizer-callback dependent and relaxes hyperparameter matching tolerance.
xopt/tests/generators/bayesian/test_contextual_bo.py	New end-to-end tests covering contextual BO generation, bounds, and visualization warnings.
mkdocs.yml	Adds the contextual BO example notebook to documentation navigation.
docs/examples/single_objective_bayes_opt/contextual_bo.ipynb	New example notebook demonstrating standard vs contextual BO on a drifting objective.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.