Skip to content

style: apply /style-guide pass to models/track #2728

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.

Sign up for GitHub

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

Open
johndmulhausen wants to merge 3 commits into
base: main
Choose a base branch
from
Open

style: apply /style-guide pass to models/track #2728

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4f19936
style: apply /style-guide pass to models/track
johndmulhausen Jun 4, 2026
2a44a77
style: apply review feedback to models/track
johndmulhausen Jun 5, 2026
b1e6a42
fix: address Copilot review comments on models/track
johndmulhausen Jun 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 29 additions & 29 deletions models/track/config.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,37 +1,37 @@
---
description: Use a dictionary-like object to save your experiment configuration
title: Configure experiments
keywords: ["wandb.config", "argparse", "absl.FLAGS", "config-defaults.yaml", "hyperparameters"]
---
import { ColabLink } from '/snippets/_includes/colab-link.mdx';

<ColabLink url="https://colab.research.google.com/github/wandb/examples/blob/master/colabs/wandb-log/Configs_in_W%26B.ipynb" />

Use the `config` property of a run to save your training configuration:
- hyperparameter
- input settings such as the dataset name or model type
- any other independent variables for your experiments.
This page shows you how to save the configuration of a W&B run so that you can analyze, compare, and reproduce your experiments later. Use the `config` property of a run to save your training configuration:

The `wandb.Run.config` property makes it easy to analyze your experiments and reproduce your work in the future. You can group by configuration values in the W&B App, compare the configurations of different W&B runs, and evaluate how each training configuration affects the output. The `config` property is a dictionary-like object that can be composed from multiple dictionary-like objects.
- Hyperparameters.
- Input settings such as the dataset name or model type.
- Any other independent variables for your experiments.

The `wandb.Run.config` property helps you analyze your experiments and reproduce your work. You can group by configuration values in the W&B App, compare the configurations of different W&B runs, and evaluate how each training configuration affects the output. The `config` property is a dictionary-like object that you can compose from multiple dictionary-like objects.

<Note>
To save output metrics or dependent variables like loss and accuracy, use `wandb.Run.log()` instead of `wandb.Run.config`.
</Note>



## Set up an experiment configuration
Configurations are typically defined in the beginning of a training script. Machine learning workflows may vary, however, so you are not required to define a configuration at the beginning of your training script.
You typically define configurations at the beginning of a training script. Machine learning workflows vary, so you don't have to.

Use dashes (`-`) or underscores (`_`) instead of periods (`.`) in your config variable names.

Use the dictionary access syntax `["key"]["value"]` instead of the attribute access syntax `config.key.value` if your script accesses `wandb.Run.config` keys below the root.
You must use dashes (`-`) or underscores (`_`) instead of periods (`.`) in your config variable names.

The following sections outline different common scenarios of how to define your experiments configuration.
If your script accesses `wandb.Run.config` keys below the root, you must use the dictionary access syntax `["key"]["value"]` instead of the attribute access syntax `config.key.value`.

The following sections outline common scenarios for how to define your experiment's configuration.

### Set the configuration at initialization
Pass a dictionary at the beginning of your script when you call the `wandb.init()` API to generate a background process to sync and log data as a W&B Run.
Pass a dictionary at the beginning of your script when you call the `wandb.init()` API to start a background process that syncs and logs your data as a run.

The following code snippet demonstrates how to define a Python dictionary with configuration values and how to pass that dictionary as an argument when you initialize a W&B Run.
The following code snippet demonstrates how to define a Python dictionary with configuration values and how to pass that dictionary as an argument when you initialize a run.

```python
import wandb
Expand Down Expand Up @@ -68,15 +68,15 @@ activation = run.config.get("activation")
```

<Note>
Throughout the Developer Guide and examples we copy the configuration values into separate variables. This step is optional. It is done for readability.
Throughout the Developer Guide and examples, we copy the configuration values into separate variables. This step is optional and improves readability.
</Note>

### Set the configuration with argparse
You can set your configuration with an argparse object. [argparse](https://docs.python.org/3/library/argparse.html), short for argument parser, is a standard library module in Python 3.2 and above that makes it easy to write scripts that take advantage of all the flexibility and power of command line arguments.
You can set your configuration with an argparse object. [argparse](https://docs.python.org/3/library/argparse.html) is a standard library module in Python 3.2 and above. Use it to write scripts that take advantage of command-line arguments.

This is useful for tracking results from scripts that are launched from the command line.
This approach is useful for tracking results from scripts that you launch from the command line.

The following Python script demonstrates how to define a parser object to define and set your experiment config. The functions `train_one_epoch` and `evaluate_one_epoch` are provided to simulate a training loop for the purpose of this demonstration:
The following Python script demonstrates how to define a parser object to define and set your experiment config. The functions `train_one_epoch` and `evaluate_one_epoch` simulate a training loop for this demonstration:

```python
# config_experiment.py
Expand Down Expand Up @@ -141,6 +141,7 @@ if __name__ == "__main__":
args = parser.parse_args()
main(args)
```

### Set the configuration throughout your script
You can add more parameters to your config object throughout your script. The following code snippet demonstrates how to add new key-value pairs to your config object:

Expand Down Expand Up @@ -171,10 +172,10 @@ You can update multiple values at a time:
run.config.update({"lr": 0.1, "channels": 16})
```

### Set the configuration after your Run has finished
Use the [W&B Public API](/models/ref/python/public-api/) to update a completed run's config.
### Set the configuration after your run has finished
If a run has already completed and you need to add or correct config values, use the [W&B Public API](/models/ref/python/public-api/) to update the stored configuration.

You must provide the API with your entity, project name and the run's ID. You can find these details in the Run object or in the [W&B App](/models/track/workspaces/):
You must provide the API with your entity, project name, and the run's ID. You can find these details in the run object or in the [W&B App](/models/track/workspaces/):

```python
with wandb.init() as run:
Expand All @@ -195,7 +196,7 @@ api_run.update()

## Highlight config values

Pin config keys to the **References** section at the top of a run's overview page.
Pin important config keys to the **References** section at the top of a run's overview page so that you can find them quickly when reviewing the run.

Use [`wandb.Run.pin_config_keys`](/models/ref/python/experiments/run#method-run-pin_config_keys) to pin one or more config keys with the Python SDK.

Expand All @@ -217,19 +218,18 @@ with wandb.init(config=config) as run:
run.pin_config_keys(["grafana_url"])
```

## Use absl flags

## `absl.FLAGS`

You can also pass in [`absl` flags](https://abseil.io/docs/python/guides/flags).
If your training script uses [`absl` flags](https://abseil.io/docs/python/guides/flags) for configuration, you can pass them directly into your run's config.

```python
flags.DEFINE_string("model", None, "model to run") # name, default, help

run.config.update(flags.FLAGS) # adds absl flags to config
```

## File-Based Configs
If you place a file named `config-defaults.yaml` in the same directory as your run script, the run automatically picks up the key-value pairs defined in the file and passes them to `wandb.Run.config`.
## File-based configs
If you prefer to keep configuration outside your Python code, you can load it from a YAML file. If you place a file named `config-defaults.yaml` in the same directory as your run script, the run automatically picks up the key-value pairs defined in the file and passes them to `wandb.Run.config`.

The following code snippet shows a sample `config-defaults.yaml` YAML file:

Expand All @@ -249,7 +249,7 @@ with wandb.init(config={"epochs": 200, "batch_size": 64}) as run:
...
```

To load a configuration file other than `config-defaults.yaml`, use the `--configs command-line` argument and specify the path to the file:
To load a configuration file other than `config-defaults.yaml`, use the `--configs` command-line argument and specify the path to the file:

```bash
python train.py --configs other-config.yaml
Expand All @@ -276,7 +276,7 @@ with wandb.init(config=config_dictionary) as run:

## TensorFlow v1 flags

You can pass TensorFlow flags into the `wandb.Run.config` object directly.
If you use TensorFlow v1, you can pass TensorFlow flags into the `wandb.Run.config` object directly.

```python
with wandb.init() as run:
Expand Down
69 changes: 40 additions & 29 deletions models/track/create-an-experiment.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,29 @@
---
description: "Create a W&B Experiment using the Python SDK to track run initialization, hyperparameters, and metric logging."
title: Create an experiment
keywords: ["wandb.init", "run.log", "log_artifact", "hyperparameters", "training loop"]
---

Use the W&B Python SDK to track machine learning experiments. You can then review the results in an interactive dashboard or export your data to Python for programmatic access with the [W&B Public API](/models/ref/python/public-api/).

This guide describes how to use W&B building blocks to create a W&B Experiment.
This guide describes how to use W&B building blocks to create a W&B Experiment so you can capture hyperparameters, log metrics, and save model artifacts for later analysis and comparison. This page is for you if you train machine learning models in Python and want to track your work with W&B.

## How to create a W&B Experiment
## Create a W&B Experiment

Create a W&B Experiment in four steps:

1. [Initialize a W&B Run](#initialize-a-wb-run)
2. [Capture a dictionary of hyperparameters](#capture-a-dictionary-of-hyperparameters)
3. [Log metrics inside your training loop](#log-metrics-inside-your-training-loop)
4. [Log an artifact to W&B](#log-an-artifact-to-wb)
1. [Initialize a W&B Run](#initialize-a-wb-run).
2. [Capture a dictionary of hyperparameters](#capture-a-dictionary-of-hyperparameters).
3. [Log metrics inside your training loop](#log-metrics-inside-your-training-loop).
4. [Log an artifact to W&B](#log-an-artifact-to-wb).

The following sections describe each step in detail.

### Initialize a W&B run
Use [`wandb.init()`](/models/ref/python/functions/init) to create a W&B Run.

The following snippet creates a run in a W&B project named `“cat-classification”` with the description `“My first experiment”` to help identify this run. Tags `“baseline”` and `“paper1”` are included to remind us that this run is a baseline experiment intended for a future paper publication.
A run is the basic unit of computation tracked by W&B, and every experiment begins by creating one. Use [`wandb.init()`](/models/ref/python/functions/init) to create a W&B Run.

The following snippet creates a run in a W&B project named `"cat-classification"` with the description `"My first experiment"` to help identify this run. The tags `"baseline"` and `"paper1"` indicate that this run is a baseline experiment intended for a future paper publication.

```python
import wandb
Expand All @@ -35,10 +39,11 @@ with wandb.init(
`wandb.init()` returns a [Run](/models/ref/python/experiments/run) object.

<Note>
Note: Runs are added to pre-existing projects if that project already exists when you call `wandb.init()`. For example, if you already have a project called `“cat-classification”`, that project will continue to exist and not be deleted. Instead, a new run is added to that project.
W&B adds runs to pre-existing projects if that project already exists when you call `wandb.init()`. For example, if you already have a project called `"cat-classification"`, that project continues to exist and isn't deleted. Instead, W&B adds a new run to that project.
</Note>

### Capture a dictionary of hyperparameters

Save a dictionary of hyperparameters such as learning rate or model type. The model settings you capture in config are useful later to organize and query your results.

```python
Expand All @@ -49,10 +54,11 @@ with wandb.init(
...
```

For more information on how to configure an experiment, see [Configure Experiments](./config).
For more information about how to configure an experiment, see [Configure Experiments](./config).

### Log metrics inside your training loop
Call [`run.log()`](/models/ref/python/experiments/run/#method-runlog) to log metrics about each training step such as accuracy and loss.

Log metrics during training to monitor progress and compare runs in the W&B dashboard. Call [`run.log()`](/models/ref/python/experiments/run/#method-runlog) to log metrics about each training step such as accuracy and loss.

```python
model, dataloader = get_model(), get_data()
Expand All @@ -63,21 +69,25 @@ for epoch in range(run.config.epochs):
run.log({"accuracy": accuracy, "loss": loss})
```

For more information on different data types you can log with W&B, see [Log Data During Experiments](/models/track/log/).
For more information about different data types you can log with W&B, see [Log Data During Experiments](/models/track/log/).

### Log an artifact to W&B

Optionally log a W&B Artifact. Artifacts let you version datasets and models.

### Log an artifact to W&B
Optionally log a W&B Artifact. Artifacts make it easy to version datasets and models.
```python
# You can save any file or even a directory. In this example, we pretend
# You can save any file or even a directory. This example assumes
# the model has a save() method that outputs an ONNX file.
model.save("path_to_model.onnx")
run.log_artifact("path_to_model.onnx", name="trained-model", type="model")
```

Learn more about [Artifacts](/models/artifacts/) or about versioning models in [Registry](/models/registry/).

### Complete example

The following script combines the previous code snippets into a complete experiment that initializes a run, captures configuration, logs metrics, and saves a model artifact:

### Putting it all together
The full script with the preceding code snippets is found below:
```python
import wandb

Expand All @@ -102,21 +112,22 @@ with wandb.init(
run.log_artifact("path_to_model.onnx", name="trained-model", type="model")
```

## Next steps: Visualize your experiment
Use the W&B Dashboard as a central place to organize and visualize results from your machine learning models. With just a few clicks, construct rich, interactive charts like [parallel coordinates plots](/models/app/features/panels/parallel-coordinates/), [parameter importance analyses](/models/app/features/panels/parameter-importance/), and [additional chart types](/models/app/features/panels/).
## Next steps: visualize your experiment

After your run completes, the metrics, configuration, and artifacts you logged are available in the W&B App. Use the W&B Dashboard as a central place to organize and visualize results from your machine learning models. With a few clicks, construct interactive charts such as [parallel coordinates plots](/models/app/features/panels/parallel-coordinates/), [parameter importance analyses](/models/app/features/panels/parameter-importance/), and [additional chart types](/models/app/features/panels/).

<Frame>
<img src="/images/sweeps/quickstart_dashboard_example.png" alt="Quickstart Sweeps Dashboard example" />
</Frame>

For more information on how to view experiments and specific runs, see [Visualize results from experiments](/models/track/workspaces/).

For more information about how to view experiments and specific runs, see [Visualize results from experiments](/models/track/workspaces/).

## Best practices

The following are some suggested guidelines to consider when you create experiments:

1. **Finish your runs**: Use `wandb.init()` in a `with` statement to automatically mark the run as finished when the code completes or raises an exception.
* In Jupyter notebooks, it may be more convenient to manage the Run object yourself. In this case, you can explicitly call `finish()` on the Run object to mark it complete:
- **Finish your runs**: Use `wandb.init()` in a `with` statement to automatically mark the run as finished when the code completes or raises an exception.
* In Jupyter notebooks, it might be more convenient to manage the Run object yourself. In this case, you can explicitly call `finish()` on the Run object to mark it complete:

```python
# In a notebook cell:
Expand All @@ -125,13 +136,13 @@ The following are some suggested guidelines to consider when you create experime
# In a different cell:
run.finish()
```
2. **Config**: Track hyperparameters, architecture, dataset, and anything else you'd like to use to reproduce your model. These will show up in columns— use config columns to group, sort, and filter runs dynamically in the app.
3. **Project**: A project is a set of experiments you can compare together. Each project gets a dedicated dashboard page, and you can easily turn on and off different groups of runs to compare different model versions.
4. **Notes**: Set a quick commit message directly from your script. Edit and access notes in the Overview section of a run in the W&B App.
5. **Tags**: Identify baseline runs and favorite runs. You can filter runs using tags. You can edit tags at a later time on the Overview section of your project's dashboard on the W&B App.
6. **Create multiple run sets to compare experiments**: When comparing experiments, create multiple run sets to make metrics easy to compare. You can toggle run sets on or off on the same chart or group of charts.
- **Config**: Track hyperparameters, architecture, dataset, and anything else you'd like to use to reproduce your model. These show up in columns. Use config columns to group, sort, and filter runs dynamically in the app.
- **Project**: A project is a set of experiments you can compare together. Each project gets a dedicated dashboard page, and you can turn on and off different groups of runs to compare different model versions.
- **Notes**: Set a quick commit message directly from your script. Edit and access notes in the Overview section of a run in the W&B App.
- **Tags**: Identify baseline runs and favorite runs. You can filter runs using tags. You can edit tags later on the Overview section of your project's dashboard on the W&B App.
- **Create multiple run sets to compare experiments**: When you compare experiments, create multiple run sets to make metrics easy to compare. You can toggle run sets on or off on the same chart or group of charts.

The following code snippet demonstrates how to define a W&B Experiment using the best practices listed above:
The following code snippet demonstrates how to define a W&B Experiment using the previous best practices:

```python
import wandb
Expand Down
Loading
Loading