wandb.Run

Search…
wandb.Run
​​
View source on GitHub​
A unit of computation logged by wandb. Typically this is an ML experiment.
1
Run(
2
    settings: Settings,
3
    config: Optional[Dict[str, Any]] = None,
4
    sweep_config: Optional[Dict[str, Any]] = None
5
) -> None
Copied!
Create a run with wandb.init():
1
import wandb
2
​
3
run = wandb.init()
Copied!
There is only ever at most one active wandb.Run in any process, and it is accessible as wandb.run:
1
import wandb
2
​
3
assert wandb.run is None
4
​
5
wandb.init()
6
​
7
assert wandb.run is not None
Copied!
anything you log with wandb.log will be sent to that run.
If you want to start more runs in the same script or notebook, you'll need to finish the run that is in-flight. Runs can be finished with wandb.finish or by using them in a with block:
1
import wandb
2
​
3
wandb.init()
4
wandb.finish()
5
​
6
assert wandb.run is None
7
​
8
with wandb.init() as run:
9
    pass  # log data here
10
​
11
assert wandb.run is None
Copied!
See the documentation for wandb.init for more on creating runs, or check out our guide to wandb.init.
In distributed training, you can either create a single run in the rank 0 process and then log information only from that process or you can create a run in each process, logging from each separately, and group the results together with the group argument to wandb.init. For more details on distributed training with W&B, check out our guide.
Currently there is a parallel Run object in the wandb.Api. Eventually these two objects will be merged.
Attributes
Text
history
(History) Time series values, created with wandb.log(). History can contain scalar values, rich media, or even custom plots across multiple steps.
summary
(Summary) Single values set for each wandb.log() key. By default, summary is set to the last value logged. You can manually set summary to the best value, like max accuracy, instead of the final value.
config
Returns the config object associated with this run.
dir
Returns the directory where files associated with the run are saved.
entity
Returns the name of the W&B entity associated with the run. Entity can be a user name or the name of a team or organization.
group
Returns the name of the group associated with the run. Setting a group helps the W&B UI organize runs in a sensible way. If you are doing a distributed training you should give all of the runs in the training the same group. If you are doing crossvalidation you should give all the crossvalidation folds the same group.
id
Returns the identifier for this run.
mode
For compatibility with 0.9.x and earlier, deprecate eventually.
name
Returns the display name of the run. Display names are not guaranteed to be unique and may be descriptive. By default, they are randomly generated.
notes
Returns the notes associated with the run, if there are any. Notes can be a multiline string and can also use markdown and latex equations inside $, like $x + 3$.
path
Returns the path to the run. Run paths include entity, project, and run ID, in the format entity/project/run_id.
project
Returns the name of the W&B project associated with the run.
resumed
Returns True if the run was resumed, False otherwise.
settings
Returns a frozen copy of run's Settings object.
start_time
Returns the unix time stamp, in seconds, when the run started.
starting_step
Returns the first step of the run.
step
Returns the current value of the step. This counter is incremented by wandb.log.
sweep_id
Returns the ID of the sweep associated with the run, if there is one.
tags
Returns the tags associated with the run, if there are any.
url
Returns the W&B url associated with the run.
Methods
alert
​View source​
1
alert(
2
    title: str,
3
    text: str,
4
    level: Union[str, 'AlertLevel'] = None,
5
    wait_duration: Union[int, float, timedelta, None] = None
6
) -> None
Copied!
Launch an alert with the given title and text.
Arguments
Text
title
(str) The title of the alert, must be less than 64 characters long.
text
(str) The text body of the alert.
level
(str or wandb.AlertLevel, optional) The alert level to use, either: INFO, WARN, or ERROR.
wait_duration
(int, float, or timedelta, optional) The time to wait (in seconds) before sending another alert with this title.
define_metric
​View source​
1
define_metric(
2
    name: str,
3
    step_metric: Union[str, wandb_metric.Metric, None] = None,
4
    step_sync: bool = None,
5
    hidden: bool = None,
6
    summary: str = None,
7
    goal: str = None,
8
    overwrite: bool = None,
9
    **kwargs
10
) -> wandb_metric.Metric
Copied!
Define metric properties which will later be logged with wandb.log().
Arguments
Text
name
Name of the metric.
step_metric
Independent variable associated with the metric.
step_sync
Automatically add step_metric to history if needed. Defaults to True if step_metric is specified.
hidden
Hide this metric from automatic plots.
summary
Specify aggregate metrics added to summary. Supported aggregations: "min,max,mean,best,last,none" Default aggregation is copy Aggregation best defaults to goal==minimize
goal
Specify direction for optimizing the metric. Supported direections: "minimize,maximize"
Returns
Text
A metric object is returned that can be further specified.
​
display
​View source​
1
display(
2
    height: int = 420,
3
    hidden: bool = (False)
4
) -> bool
Copied!
Displays this run in jupyter.
finish
​View source​
1
finish(
2
    exit_code: int = None,
3
    quiet: Optional[bool] = None
4
) -> None
Copied!
Marks a run as finished, and finishes uploading all data.
This is used when creating multiple runs in the same process. We automatically call this method when your script exits or if you use the run context manager.
Arguments
Text
exit_code
Set to something other than 0 to mark a run as failed
quiet
Set to true to minimize log output
finish_artifact
​View source​
1
finish_artifact(
2
    artifact_or_path: Union[wandb_artifacts.Artifact, str],
3
    name: Optional[str] = None,
4
    type: Optional[str] = None,
5
    aliases: Optional[List[str]] = None,
6
    distributed_id: Optional[str] = None
7
) -> wandb_artifacts.Artifact
Copied!
Finishes a non-finalized artifact as output of a run.
Subsequent "upserts" with the same distributed ID will result in a new version.
Arguments
Text
artifact_or_path
(str or Artifact) A path to the contents of this artifact, can be in the following forms: - /local/directory - /local/directory/file.txt - s3://bucket/path You can also pass an Artifact object created by calling wandb.Artifact.
name
(str, optional) An artifact name. May be prefixed with entity/project. Valid names can be in the following forms: - name:version - name:alias - digest This will default to the basename of the path prepended with the current run id if not specified.
type
(str) The type of artifact to log, examples include dataset, model
aliases
(list, optional) Aliases to apply to this artifact, defaults to ["latest"]
distributed_id
(string, optional) Unique string that all distributed jobs share. If None, defaults to the run's group name.
Returns
Text
An Artifact object.
​
get_project_url
​View source​
1
get_project_url() -> Optional[str]
Copied!
Returns the url for the W&B project associated with the run, if there is one.
Offline runs will not have a project url.
get_sweep_url
​View source​
1
get_sweep_url() -> Optional[str]
Copied!
Returns the url for the sweep associated with the run, if there is one.
get_url
​View source​
1
get_url() -> Optional[str]
Copied!
Returns the url for the W&B run, if there is one.
Offline runs will not have a url.
join
​View source​
1
join(
2
    exit_code: int = None
3
) -> None
Copied!
Deprecated alias for finish() - please use finish.
log
​View source​
1
log(
2
    data: Dict[str, Any],
3
    step: int = None,
4
    commit: bool = None,
5
    sync: bool = None
6
) -> None
Copied!
Logs a dictonary of data to the current run's history.
Use wandb.log to log data from runs, such as scalars, images, video, histograms, plots, and tables.
See our guides to logging for live examples, code snippets, best practices, and more.
The most basic usage is wandb.log({"train-loss": 0.5, "accuracy": 0.9}). This will save the loss and accuracy to the run's history and update the summary values for these metrics.
Visualize logged data in the workspace at wandb.ai, or locally on a self-hosted instance of the W&B app, or export data to visualize and explore locally, e.g. in Jupyter notebooks, with our API.
In the UI, summary values show up in the run table to compare single values across runs. Summary values can also be set directly with wandb.run.summary["key"] = value.
Logged values don't have to be scalars. Logging any wandb object is supported. For example wandb.log({"example": wandb.Image("myimage.jpg")}) will log an example image which will be displayed nicely in the W&B UI. See the reference documentation for all of the different supported types or check out our guides to logging for examples, from 3D molecular structures and segmentation masks to PR curves and histograms. wandb.Tables can be used to logged structured data. See our guide to logging tables for details.
Logging nested metrics is encouraged and is supported in the W&B UI. If you log with a nested dictionary like wandb.log({"train": {"acc": 0.9}, "val": {"acc": 0.8}}), the metrics will be organized into train and val sections in the W&B UI.
wandb keeps track of a global step, which by default increments with each call to wandb.log, so logging related metrics together is encouraged. If it's inconvenient to log related metrics together calling wandb.log({"train-loss": 0.5, commit=False}) and then wandb.log({"accuracy": 0.9}) is equivalent to calling wandb.log({"train-loss": 0.5, "accuracy": 0.9}).
wandb.log is not intended to be called more than a few times per second. If you want to log more frequently than that it's better to aggregate the data on the client side or you may get degraded performance.
Arguments
Text
row
(dict, optional) A dict of serializable python objects i.e str, ints, floats, Tensors, dicts, or any of the wandb.data_types.
commit
(boolean, optional) Save the metrics dict to the wandb server and increment the step. If false wandb.log just updates the current metrics dict with the row argument and metrics won't be saved until wandb.log is called with commit=True.
step
(integer, optional) The global step in processing. This persists any non-committed earlier steps but defaults to not committing the specified step.
sync
(boolean, True) This argument is deprecated and currently doesn't change the behaviour of wandb.log.
Examples:
For more and more detailed examples, see our guides to logging.
Basic usage
1
import wandb
2
wandb.init()
3
wandb.log({'accuracy': 0.9, 'epoch': 5})
Copied!
Incremental logging
1
import wandb
2
wandb.init()
3
wandb.log({'loss': 0.2}, commit=False)
4
# Somewhere else when I'm ready to report this step:
5
wandb.log({'accuracy': 0.8})
Copied!
Histogram
1
import numpy as np
2
import wandb
3
​
4
# sample gradients at random from normal distribution
5
gradients = np.random.randn(100, 100)
6
wandb.init()
7
wandb.log({"gradients": wandb.Histogram(gradients)})
Copied!
Image from numpy
1
import numpy as np
2
import wandb
3
​
4
wandb.init()
5
examples = []
6
for i in range(3):
7
    pixels = np.random.randint(low=0, high=256, size=(100, 100, 3))
8
    image = wandb.Image(pixels, caption=f"random field {i}")
9
    examples.append(image)
10
wandb.log({"examples": examples})
Copied!
Image from PIL
1
import numpy as np
2
from PIL import Image as PILImage
3
import wandb
4
​
5
wandb.init()
6
examples = []
7
for i in range(3):
8
    pixels = np.random.randint(low=0, high=256, size=(100, 100, 3), dtype=np.uint8)
9
    pil_image = PILImage.fromarray(pixels, mode="RGB")
10
    image = wandb.Image(pil_image, caption=f"random field {i}")
11
    examples.append(image)
12
wandb.log({"examples": examples})
Copied!
Video from numpy
1
import numpy as np
2
import wandb
3
​
4
wandb.init()
5
# axes are (time, channel, height, width)
6
frames = np.random.randint(low=0, high=256, size=(10, 3, 100, 100), dtype=np.uint8)
7
wandb.log({"video": wandb.Video(frames, fps=4)})
Copied!
Matplotlib Plot
1
from matplotlib import pyplot as plt
2
import numpy as np
3
import wandb
4
​
5
wandb.init()
6
fig, ax = plt.subplots()
7
x = np.linspace(0, 10)
8
y = x * x
9
ax.plot(x, y)  # plot y = x^2
10
wandb.log({"chart": fig})
Copied!
PR Curve
1
wandb.log({'pr': wandb.plots.precision_recall(y_test, y_probas, labels)})
Copied!
3D Object
1
wandb.log({"generated_samples":
2
[wandb.Object3D(open("sample.obj")),
3
    wandb.Object3D(open("sample.gltf")),
4
    wandb.Object3D(open("sample.glb"))]})
Copied!
Raises
Text
wandb.Error
if called before wandb.init
ValueError
if invalid data is passed
log_artifact
​View source​
1
log_artifact(
2
    artifact_or_path: Union[wandb_artifacts.Artifact, str],
3
    name: Optional[str] = None,
4
    type: Optional[str] = None,
5
    aliases: Optional[List[str]] = None
6
) -> wandb_artifacts.Artifact
Copied!
Declare an artifact as an output of a run.
Arguments
Text
artifact_or_path
(str or Artifact) A path to the contents of this artifact, can be in the following forms: - /local/directory - /local/directory/file.txt - s3://bucket/path You can also pass an Artifact object created by calling wandb.Artifact.
name
(str, optional) An artifact name. May be prefixed with entity/project. Valid names can be in the following forms: - name:version - name:alias - digest This will default to the basename of the path prepended with the current run id if not specified.
type
(str) The type of artifact to log, examples include dataset, model
aliases
(list, optional) Aliases to apply to this artifact, defaults to ["latest"]
Returns
Text
An Artifact object.
​
log_code
​View source​
1
log_code(
2
    root: str = ".",
3
    name: str = None,
4
    include_fn: Callable[[str], bool] = (lambda path: path.endswith(".py")),
5
    exclude_fn: Callable[[str], bool] = filenames.exclude_wandb_fn
6
) -> Optional[Artifact]
Copied!
Saves the current state of your code to a W&B Artifact.
By default it walks the current directory and logs all files that end with .py.
Arguments
Text
root
The relative (to os.getcwd()) or absolute path to recursively find code from.
name
(str, optional) The name of our code artifact. By default we'll name the artifact source-$RUN_ID. There may be scenarios where you want many runs to share the same artifact. Specifying name allows you to achieve that.
include_fn
A callable that accepts a file path and returns True when it should be included and False otherwise. This defaults to: lambda path: path.endswith(".py")
exclude_fn
A callable that accepts a file path and returns True when it should be excluded and False otherwise. Thisdefaults to: lambda path: False
Examples:
Basic usage
1
run.log_code()
Copied!
Advanced usage
1
run.log_code("../", include_fn=lambda path: path.endswith(".py") or path.endswith(".ipynb"))
Copied!
Returns
Text
An Artifact object if code was logged
​
mark_preempting
​View source​
1
mark_preempting() -> None
Copied!
Marks this run as preempting.
Also tells the internal process to immediately report this to server.
plot_table
​View source​
1
plot_table(
2
    vega_spec_name, data_table, fields, string_fields=None
3
)
Copied!
Creates a custom plot on a table.
Arguments
Text
vega_spec_name
the name of the spec for the plot
table_key
the key used to log the data table
data_table
a wandb.Table object containing the data to be used on the visualization
fields
a dict mapping from table keys to fields that the custom visualization needs
string_fields
a dict that provides values for any string constants the custom visualization needs
project_name
​View source​
1
project_name() -> str
Copied!
restore
​View source​
1
restore(
2
    name: str,
3
    run_path: Optional[str] = None,
4
    replace: bool = (False),
5
    root: Optional[str] = None
6
) -> Union[None, TextIO]
Copied!
Downloads the specified file from cloud storage.
File is placed into the current directory or run directory. By default will only download the file if it doesn't already exist.
Arguments
Text
name
the name of the file
run_path
optional path to a run to pull files from, i.e. username/project_name/run_id if wandb.init has not been called, this is required.
replace
whether to download the file even if it already exists locally
root
the directory to download the file to. Defaults to the current directory or the run directory if wandb.init was called.
Returns
Text
None if it can't find the file, otherwise a file object open for reading
​
Raises
Text
wandb.CommError
if we can't connect to the wandb backend
ValueError
if the file is not found or can't find run_path
save
​View source​
1
save(
2
    glob_str: Optional[str] = None,
3
    base_path: Optional[str] = None,
4
    policy: str = "live"
5
) -> Union[bool, List[str]]
Copied!
Ensure all files matching glob_str are synced to wandb with the policy specified.
Arguments
Text
glob_str
(string) a relative or absolute path to a unix glob or regular path. If this isn't specified the method is a noop.
base_path
(string) the base path to run the glob relative to
policy
(string) on of live, now, or end - live: upload the file as it changes, overwriting the previous version - now: upload the file once now - end: only upload file when the run ends
to_html
​View source​
1
to_html(
2
    height: int = 420,
3
    hidden: bool = (False)
4
) -> str
Copied!
Generates HTML containing an iframe displaying the current run.
unwatch
​View source​
1
unwatch(
2
    models=None
3
) -> None
Copied!
upsert_artifact
​View source​
1
upsert_artifact(
2
    artifact_or_path: Union[wandb_artifacts.Artifact, str],
3
    name: Optional[str] = None,
4
    type: Optional[str] = None,
5
    aliases: Optional[List[str]] = None,
6
    distributed_id: Optional[str] = None
7
) -> wandb_artifacts.Artifact
Copied!
Declare (or append to) a non-finalized artifact as output of a run.
Note that you must call run.finish_artifact() to finalize the artifact. This is useful when distributed jobs need to all contribute to the same artifact.
Arguments
Text
artifact_or_path
(str or Artifact) A path to the contents of this artifact, can be in the following forms: - /local/directory - /local/directory/file.txt - s3://bucket/path You can also pass an Artifact object created by calling wandb.Artifact.
name
(str, optional) An artifact name. May be prefixed with entity/project. Valid names can be in the following forms: - name:version - name:alias - digest This will default to the basename of the path prepended with the current run id if not specified.
type
(str) The type of artifact to log, examples include dataset, model
aliases
(list, optional) Aliases to apply to this artifact, defaults to ["latest"]
distributed_id
(string, optional) Unique string that all distributed jobs share. If None, defaults to the run's group name.
Returns
Text
An Artifact object.
​
use_artifact
​View source​
1
use_artifact(
2
    artifact_or_name, type=None, aliases=None, use_as=None
3
)
Copied!
Declare an artifact as an input to a run.
Call download or file on the returned object to get the contents locally.
Arguments
Text
artifact_or_name
(str or Artifact) An artifact name. May be prefixed with entity/project/. Valid names can be in the following forms: - name:version - name:alias - digest You can also pass an Artifact object created by calling wandb.Artifact
type
(str, optional) The type of artifact to use.
aliases
(list, optional) Aliases to apply to this artifact
use_as
(string, optional) Optional string indicating what purpose the artifact was used with. Will be shown in UI.
Returns
Text
An Artifact object.
​
watch
​View source​
1
watch(
2
    models, criterion=None, log="gradients", log_freq=100, idx=None,
3
    log_graph=(False)
4
) -> None
Copied!
__enter__
​View source​
1
__enter__() -> "Run"
Copied!
__exit__
​View source​
1
__exit__(
2
    exc_type: Type[BaseException],
3
    exc_val: BaseException,
4
    exc_tb: TracebackType
5
) -> bool
Copied!
wandb.Artifact
wandb.agent
Last modified 1mo ago
Methods

`alert`

`define_metric`

`display`

`finish`

`finish_artifact`

`get_project_url`

`get_sweep_url`

`get_url`

`join`

`log`

Examples:

Basic usage

Incremental logging

Histogram

Image from numpy

Image from PIL

Video from numpy

Matplotlib Plot

PR Curve

3D Object

`log_artifact`

`log_code`

Examples:

`mark_preempting`

`plot_table`

`project_name`

`restore`

`save`

`to_html`

`unwatch`

`upsert_artifact`

`use_artifact`

`watch`

`enter`

`exit`
