> For the complete documentation index, see [llms.txt](https://rocket-9.gitbook.io/rocket-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rocket-9.gitbook.io/rocket-docs/track-refinement-with-weights-and-biases.md).

# Track Refinement with Weights & Biases

ROCKET can stream `rk.refine` metrics to Weights & Biases (W\&B) while a run is active.

Use this when you want live curves, run comparison, and shared experiment history.

{% hint style="info" %}
This works for both cryo-EM and X-ray refinement. You only need to update the YAML you pass to `rk.refine`.
{% endhint %}

### 1. Install W\&B

Install `wandb` in the same environment where you run ROCKET:

```bash
pip install wandb
```

### 2. Choose a logging mode

{% tabs %}
{% tab title="Cloud logging" %}
Use this when you want a hosted dashboard and easy sharing.

1. Create an account at [wandb.ai](https://wandb.ai/signup).
2. Login from the same shell where you run ROCKET:

```bash
wandb login
```

Paste the API key from [wandb.ai/authorize](https://wandb.ai/authorize).
{% endtab %}

{% tab title="Offline logging" %}
Use this when your compute node has no internet access, or when you want to sync later.

Set offline mode before launching refinement:

```bash
export WANDB_MODE=offline
```

ROCKET will write W\&B files locally under `./wandb/`.
{% endtab %}

{% tab title="Disable W\&B" %}
W\&B is off by default.

If you keep `use_wandb: false` in your config, ROCKET still writes its normal local outputs.

That includes metrics in the output directory and any saved trajectory files you enable.
{% endtab %}
{% endtabs %}

### 3. Update your refinement config

Open the same YAML file you pass to [rk.refine](/rocket-docs/api/rk.refine.md).

Add the W\&B fields you want to use:

```yaml
use_wandb: true
wandb_entity: my-lab
wandb_project: rocket-refinement
wandb_name: 8p4pH-phase1
wandb_tags:
  - cryo-em
  - phase1
wandb_notes: First ROCKET run with live tracking
```

`wandb_entity` sets the username or team workspace that owns the run. `wandb_project` groups related runs. `wandb_name` sets the run label. `wandb_tags` and `wandb_notes` are optional.

If you leave `wandb_entity` unset, W\&B uses your default logged-in account.

{% hint style="warning" %}
Use the field names exactly as shown. Keep them in the same YAML you pass to `rk.refine`.
{% endhint %}

### 4. Run refinement as usual

Launch refinement with your updated config:

```bash
rk.refine 8p4pH_processed/ROCKET_config_phase1.yaml
```

You can use the same setup for either [Launch with Your Own Cryo-EM Data](/rocket-docs/launch-with-your-own-cryo-em-data.md) or [Launch with Your Own X-ray Data](/rocket-docs/launch-with-your-own-x-ray-data.md).

If you run phase 2, keep the same W\&B fields in the phase 2 config.

### 5. View results

{% tabs %}
{% tab title="Cloud" %}
Open your project in the browser:

```
https://wandb.ai/<your-entity>/<your-project>
```

Use it to compare runs, inspect metrics, and share results.
{% endtab %}

{% tab title="Offline" %}
You have a few ways to work with offline runs.

Start a local dashboard:

```bash
pip install wandb[local]
wandb local
```

Or sync a saved run later:

```bash
wandb sync ./wandb/offline-run-*/
```

Offline run files are stored under `./wandb/`.
{% endtab %}
{% endtabs %}

### What ROCKET logs to W\&B

When `use_wandb: true`, ROCKET can log:

* Refinement settings from your YAML
* Per-iteration metrics such as loss and confidence
* Run metadata such as names, tags, and notes
* Saved models and trajectory artifacts when enabled

Exactly which metrics appear depends on your ROCKET version and enabled outputs.

{% hint style="success" %}
W\&B does not replace ROCKET outputs. Your normal local files still remain in the working directory.
{% endhint %}

### A practical pattern

A simple naming scheme makes comparison much easier:

```yaml
wandb_entity: my-lab
wandb_project: groel-tests
wandb_name: 8p4pH-phase1-lr1e-4
wandb_tags:
  - cryo-em
  - groel
  - phase1
```

Keep one project per dataset family, then use names and tags for phase, target, and hyperparameters.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://rocket-9.gitbook.io/rocket-docs/track-refinement-with-weights-and-biases.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.