Run
#
Representation of all metadata of a tracked experiment.
Initialize with the init_run()
function:
import neptune
# Create new run
run = neptune.init_run()
# Initialize existing run with ID "CLS-16", to resume logging
run = neptune.init_run(with_id="CLS-16")
With the run
object, you can:
- Log metadata in a structure of your choosing.
- Download run metadata to your local machine.
- Delete metadata from the run.
Field lookup: []
#
You can access the field of a run through a dict-like field lookup: run[field_path]
.
This way, you can
-
track metadata:
-
fetch already tracked metadata, such as retrieving parameters when resuming a run or downloading metadata for a custom analysis:
Returns
The returned type depends on the field type and whether a field is stored under the given path.
Path | Example | Returns |
---|---|---|
Field exists | - | The returned type matches the type of the field |
Field does not exist | - | Handler object |
Path is namespace and has field | Path: Field |
Namespace handler object |
Examples
When you assign some metadata to a new path in the Neptune object, it creates a field of a certain type.
The above example creates a Float
field with the value 0.9
.
If you reassign a value of the same type, it'll override the previous value stored in the field.
# Update the value of the field
run["parameters/momentum"] = 0.8
# It's no longer possible to store a File under a Float field
run["parameters/momentum"].upload("sampl.csv") # Error
Creating a series field:
# Create new Series field
run["train/logs"].append("Experimenting Day 1:")
run["train/acc"].append(0.01)
# Continue logging to existing Series field
run["train/logs"].append("I embark on a journey")
run["train/acc"].append(0.02)
If you access a namespace handler, you can interact with it similarly to the run object.
Assignment: =
#
Convenience alias for assign()
.
assign()
#
Assign values to multiple fields from a dictionary. For example, you can use this method to quickly log all the parameters of a run.
Parameters
Name | Type | Default | Description |
---|---|---|---|
value |
dict |
None |
A dictionary with values to assign, where keys (str ) become the paths of the fields. The dictionary can be nested, in which case the path will be a combination of all keys. |
wait |
Boolean , optional |
False |
By default, tracked metadata is sent to the server in the background. With this option set to True , Neptune first sends all data before executing the call. See Connection modes. |
Example
import neptune
run = neptune.init_run()
# Assign multiple fields from a dictionary
params = {"max_epochs": 10, "optimizer": "Adam"}
run["parameters"] = params
# The above is equivalent to
run.assign({"parameters": {"max_epochs": 10, "optimizer": "Adam"}})
# You can also assign parameters one by one
run["parameters/max_epochs"] = 10
run["parameters/optimizer"] = "Adam"
# The above is equivalent to
run["parameters/max_epochs"].assign(10)
run["parameters/optimizer"].assign("Adam")
# Dictionaries can be nested
params = {"train": {"max_epochs": 10}}
run["parameters"] = params
# This logs the value 10 under the path "parameters/train/max_epochs"
del
#
Completely removes the field or namespace and all associated metadata stored under the path.
If you need to free up storage or reduce the number of fields, use del
to remove unneeded metadata that takes up space, such as notebook training checkpoints.
See also: pop()
.
Examples
import neptune
run = neptune.init_run()
params = {"max_epochs": 10, "optimizer": "Adam"}
run["model/parameters"] = params
# Delete field with path "model/parameters/optimizer"
del run["model/parameters/optimizer"]
# You can also delete the whole namespace
del run["model/parameters"]
Freeing up space by deleting checkpoints:
# Resume an existing run
run = neptune.init_run(with_id="CLS-47")
# Delete the namespace "training/checkpoints" with the training checkpoint
del run["training/checkpoints"]
exists()
#
Checks if there is a field or namespace under the specified path.
Info
This method checks the local representation of the run. If the field was created by another process or the metadata has not reached the Neptune servers, it may not be possible to fetch. In this case you can:
- Call
sync()
on the run to synchronize the local representation with the server. - Call
wait()
on the run to wait for all tracking calls to finish.
Parameters
Name | Type | Default | Description |
---|---|---|---|
path |
str |
- | Path to check for the existence of a field or namespace |
Examples
import neptune
# Resume run with identifier CLS-34
run = neptune.init_run(with_id="CLS-34")
# If the training is complete remove training checkpoints if they are there
if run.exists("model/checkpoints") and run["train/finished"].fetch() == True:
del run["model/checkpoints"]
Info
When working in asynchronous (default) mode, the metadata you track may not be immediately available to fetch from the server, even if it appears in the local representation.
To work around this, you can call wait()
on the run.
import neptune
run = neptune.init_run()
run["learning_rate"] = 0.1
# The path exists in the local representation
if run.exists("learning_rate"):
# However, the tracking call may have not reached Neptune servers yet
run["learning_rate"].fetch() # Error: the field does not exist
run.wait()
fetch()
#
Fetches the values of all single-value fields (that are not of type File
) as a dictionary.
The result preserves the hierarchical structure of the model metadata. You can use this method, for example, to quickly retrieve run parameters.
Returns
dict
containing the values of all non-File
single-value fields.
Example
import neptune
# Resume run with identifier CLS-123
run = neptune.init_run(project="ml-team/classification", with_id="CLS-123")
# Fetch the run parameters
params = run["model/params"].fetch()
get_structure()
#
Returns the metadata structure of a run in the form of a dictionary.
This method can be used to traverse the metadata structure programmatically when using Neptune in automated workflows.
See also: print_structure()
.
Warning
The returned object is a shallow copy of the run's internal structure. Any modifications to it may result in tracking malfunction.
Returns
dict
with the run metadata structure.
Example
>>> run.get_structure()
{'data': {'val': <neptune.attributes.atoms.artifact.Artifact object at 0x0000020374B822C0>}, 'f1_score': <neptune.attributes.atoms.float.Float object at 0x0000020374B81A50>, 'monitoring': {'cpu': <neptune.attributes.series.float_series.FloatSeries object at 0x0000020374B81A80>, ... }}
get_url()
#
Returns a direct link to the run in Neptune. The same link is printed in the console once the run has been initialized.
Returns
str
with the URL of the run in Neptune.
Example
>>> import neptune
>>> run = neptune.init_run(with_id="NER-35")
>>> run.get_url()
https://app.neptune.ai/jackie/named-entity-recognition/e/NER-35
pop()
#
Completely removes the field or namespace and all associated metadata stored under the path.
See also del
.
Parameters
Name | Type | Default | Description |
---|---|---|---|
path |
str |
- | Path of the field or namespace to be removed. |
wait |
Boolean , optional |
False |
By default, tracked metadata is sent to the server in the background. With this option set to True , Neptune first sends all data before executing the call. See Connection modes. |
Examples
import neptune
run = neptune.init_run()
run["parameters/learninggg_rata"] = 0.3
# Let's correct the misspelled field
# Delete the field along with its data
run.pop("parameters/learninggg_rata")
# Reassign to correct field
run["parameters/learning_rate"] = 0.3
# Training finished
run["trained_model"].upload("model.pt")
# "model_checkpoint" is a File field
run.pop("model_checkpoint")
You can invoke pop() directly on fields and namespaces:
# The following line
run.pop("parameters/learninggg_rata")
# is equiavlent to this line
run["parameters/learninggg_rata"].pop()
# and this line
run["parameters"].pop("learninggg_rata")
# You can also batch-delete the whole namespace
run["parameters"].pop()
print_structure()
#
Pretty-prints the structure of the run metadata. Paths are ordered lexicographically and the structure is colored.
See also: get_structure()
Example
>>> import neptune
>>> run = neptune.init_run(with_id="NER-35")
>>> run.print_structure()
'data':
'val': Artifact
'f1_score': Float
'monitoring':
'cpu': FloatSeries
'gpu': FloatSeries
'gpu_memory': FloatSeries
'memory': FloatSeries
'stderr': StringSeries
'stdout': StringSeries
'parameters':
'learning_rate': Float
'optimizer': String
...
stop()
#
Stops the connection to Neptune and synchronizes all data.
Info
Every active run keeps a connection open with Neptune, monitors hardware usage, etc. If you are performing multiple training jobs from one script, one after the other, stop each run once tracking is no longer needed.
You can also use context managers. Neptune will automatically call stop()
when exiting the run context.
Warning
Always call stop()
in interactive environments, such as a Python interpreter or Jupyter notebook. The connection to Neptune is not stopped when the cell has finished executing, but rather when the entire notebook stops.
If you're running a script, the connection is stopped automatically when the script finishes executing. However, it's a best practice to call stop()
when the connection is no longer needed.
Parameters
Name | Type | Default | Description |
---|---|---|---|
seconds |
int or float , optional |
None |
Wait for the specified time for all tracking calls to finish before stopping the connection. If None , wait for all tracking calls to finish. |
Examples
If you are creating tracked runs from a Python script, Neptune stops the run automatically when the script finishes executing.
import neptune
run = neptune.init_run()
[...] # Your training or monitoring code
# stop() is automatically called at the end for every Neptune object
Stopping multiple tracked runs manually at the end of a training job:
Using with
statement and context manager:
for config in configs:
with neptune.init_run() as run:
[...] # Your training or monitoring code
# stop() is automatically called
# when code execution exits the with statement
sync()
#
Synchronizes the local representation of the run with Neptune servers.
Parameters
Name | Type | Default | Description |
---|---|---|---|
wait |
Boolean , optional |
False |
By default, tracked metadata is sent to the server in the background. With this option set to True , Neptune first sends all data before executing the call. See Connection modes. |
Example
import neptune
# Connect to a run from Worker #3
worker_id = 3
run = neptune.init_run(
with_id="DIST-43",
monitoring_namespace=f"monitoring/{worker_id}",
)
# Try to access logs that were created in the meantime by Worker #2
worker_2_status = run["status/2"].fetch()
# Error if this field was created after this script starts
run.sync() # Synchronize local representation with Neptune servers
worker_2_status = run["status/2"].fetch() # No error
wait()
#
Wait for all the tracking calls to finish.
Parameters
Name | Type | Default | Description |
---|---|---|---|
disk_only |
Boolean , optional |
False |
If True , the process will wait only for the data to be saved locally from memory, but will not wait for it to reach Neptune servers. |
Deprecated#
get_run_url()
#
Deprecated
This method is deprecated. As of neptune 1.0
it's no longer supported.
Use get_url()
instead.