Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation, especially on the botorch.org landing page, should reflect current best practices #2421

Closed
esantorella opened this issue Jul 10, 2024 · 0 comments
Labels

Comments

@esantorella
Copy link
Member

This is the current "Get Started" example on botorch.org:

# Fit a model
import torch
from botorch.models import SingleTaskGP
from botorch.fit import fit_gpytorch_mll
from botorch.utils import standardize
from gpytorch.mlls import ExactMarginalLogLikelihood

train_X = torch.rand(10, 2)
Y = 1 - torch.linalg.norm(train_X - 0.5, dim=-1, keepdim=True)
Y = Y + 0.1 * torch.randn_like(Y)  # add some noise
train_Y = standardize(Y)

gp = SingleTaskGP(train_X, train_Y)
mll = ExactMarginalLogLikelihood(gp.likelihood, gp)
fit_gpytorch_mll(mll)

# Construct an acquisition function
from botorch.acquisition import UpperConfidenceBound

UCB = UpperConfidenceBound(gp, beta=0.1)

# Optimize the acquisition function
bounds = torch.stack([torch.zeros(2), torch.ones(2)])
candidate, acq_value = optimize_acqf(
    UCB, bounds=bounds, q=1, num_restarts=5, raw_samples=20,
)
candidate  # tensor([0.4887, 0.5063])

This code doesn't follow best practices in a few ways:

  • It uses standardize rather than a transform, so predictions will be in the transformed space, which can be hard to interpret. The Standardize outcome transform would be better.
  • It doesn't illustrate use of the Normalize input transform. I appreciate the concision of this example, but I think it's oversimplified; a user who runs this code on different data will get a warning telling them to normalize and not know how to do it.
  • The data and bounds are in single precision, which will also generate a warning.
  • We're more likely to recommend an acquisition function in the LogEI family than UCB.

Ideally, all references to standardize would be removed and there would be an audit of tutorials and other documentation for adherence to current best practices, but fixing the landing page would be a great improvement.

facebook-github-bot pushed a commit that referenced this issue Jul 11, 2024
Summary:
## Motivation

Getting-started documentation should be as simple as possible but no simpler. See #2421 for context.

### Have you read the [Contributing Guidelines on pull requests](https://github.com/pytorch/botorch/blob/main/CONTRIBUTING.md#pull-requests)?

Yes

Pull Request resolved: #2425

Test Plan:
- ran the example code to ensure it works
- built and ran the website locally and checked it looked okay
- previewed Markdown in Markdown viewer

Reviewed By: Balandat

Differential Revision: D59606022

Pulled By: esantorella

fbshipit-source-id: 201361879feb26cce309e3c49e8c7a497fabce5e
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

1 participant