Universal methods and parameters#

This reference lists methods and parameters that are common to all Neptune objects (or classes): You can use them whether you're working with runs, models, or project metadata.

Note: Most metadata logging methods apply to fields within the object rather than the object as a whole. For the full reference and methods, see:

Field types

Methods#

Field lookup: `[]`#

You can access the field of an object through a dict-like field lookup: neptune_object[field_path].

This way, you can:

Track metadata:

run["params/max_epochs"] = 20
for epoch in range(20):
    run["epoch/acc"].append(epoch_accuracy)

Fetch already tracked metadata, such as retrieving parameters when resuming a run or downloading metadata for a custom analysis:
```
learning_rate = run["params/max_epochs"].fetch()
acc_df = run["epoch/acc"].fetch_values()
```

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: "train"

Field "train/acc" exists

Namespace handler object

Examples

import neptune
run = neptune.init_run()

# Create new Float field
run["parameters/momentum"] = 0.9

# Create new FloatSeries field
run["train/acc"].append(0.01)

# Continue logging to existing Series field
run["train/acc"].append(0.02)

# If you access a namespace handler, you can interact with it as with the run object
params_ns = run["parameters"]
params_ns["learning_rate"] = 0.3  # Stores 0.3 under path "parameters/learning_rate"

Assignment: `=`#

Convenience alias for assign().

`assign()`#

When called on object (such as Run): Assigns values to multiple fields from a dictionary.
When called on namespace handler (such as Run["parameters"]): Assigns individual value or a dictionary of values.

Parameters

Name Type Default Description

value

Object-level: dict

Namespace-level: Int, Float, Boolean, String

None

Object-level: A dictionary with values to assign, where keys (str) become the paths of the fields.

Namespace-level: Value or dictionary of values.

Dictionaries 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.

Example

import neptune

run = neptune.init_run()

You can use either the = operator or the assign() method when assigning values to a path inside the run.

Assign single value to field

run["parameters/lr"] = 0.8
# or equivalently
run["parameters/lr"].assign(0.8)

Assign dictionary of values to namespace

run["parameters"] = {"max_epochs": 10, "optimizer": "Adam", "lr": 0.8}
# or equivalently
run["parameters"].assign({"max_epochs": 10, "optimizer": "Adam", "lr": 0.8})

If you assign values directly to the run object, use the assign() method.

run.assign(
    {"parameters": {"max_epochs": 10, "optimizer": "Adam", "lr": 0.8}}
)

Doesn't work

run = {"lr": 0.8}

run = 0.8

The above will change the run variable reference instead of logging metadata to the run.

In all of the above examples, the resulting metadata structure is:

run (object)
|-- parameters (namespace)
    |-- max_epochs (Int field)
        |-- 10
    |-- optimizer (String field)
        |-- "Adam"
    |-- lr (Float field)
        |-- 0.8

`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.

`exists()`#

Checks if there is a field or namespace under the specified path.

Info

This method checks the local representation of the object. 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 object to synchronize the local representation with the server.
Call wait() on the object 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"]

Using wait() to ensure that previous tracking calls reach the server:

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.

Returns

dict containing the values of all non-File single-value fields.

Example

import neptune

# Resume version 12 of model CLS-FOREST
model_version = neptune.init_model_version(
    model="CLS-FOREST-12",
)

# Fetch the model parameters
params = model_version["params"].fetch()

`get_structure()`#

Returns the metadata structure of an object in the form of a dictionary.

This method can be used to traverse the metadata structure programmatically when using Neptune in automated workflows.

`get_url()`#

Returns a direct link to the object.

The same link is printed in the console once the object has been initialized.

Returns

str with the URL of the object in Neptune.

Example

>>> import neptune
>>> # Initialize existing model with ID "CLS-TREE"
>>> model = neptune.init_model(with_id="CLS-TREE")
>>> model.get_url()
https://app.neptune.ai/ml-team/classification/m/CLS-TREE

`pop()`#

Completely removes the field or namespace and all associated metadata stored under the path.

`print_structure()`#

Pretty-prints the structure of the object metadata.

Paths are ordered lexicographically and the structure is colored.

`stop()`#

Stops the connection to Neptune and synchronizes all data.

Info

Every active object keeps a connection open with Neptune. If you're performing multiple training jobs from one script, one after the other, stop each object once tracking is no longer needed.

Neptune calls stop() automatically in the following scenarios:

If you're running a script, the connection stops when the script finishes executing.
When using context managers, the connection stops when exiting the object context.

However, it's a best practice to explicitly call stop() when the connection is no longer needed.

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.

Parameters

Name	Type	Default	Description
`seconds`	`int` or `float`, optional	`None`	Wait for the specified time for all metadata tracking calls to finish before stopping the connection. If `None`, wait for all tracking calls to finish.

Examples

import neptune

run = neptune.init_run()
model = neptune.init_model(key="FOREST")

[...]  # Your training or monitoring code

# stop() is automatically called at the end for every Neptune object

Stopping multiple objects manually at the end of a training job:

for config in configs:
    run = neptune.init_run()
    model = neptune.init_model(key="FOREST")
    [...]  # Your training or monitoring code
    run.stop()
    model.stop()

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 object with the representation on the 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 queued data before executing the call.

Info

some_neptune_object.sync(wait=True) is equivalent to:

some_neptune_object.wait()
some_neptune_object.sync()

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 (queued operations) to reach the Neptune servers.

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.

Initialization functions#

To work with any Neptune object in your code, you initialize it with its respective init function.

Object type (class)	Function	ID format	Example
`Run`	`init_run()`	`PROJKEY-#`	New run: `run = neptune.init_run()` Existing run: `run = neptune.init_run(with_id="CLS-7")`
`Model`	`init_model()`	`PROJKEY-MODKEY`	New model: `model = neptune.init_model(key="FOREST")` Existing model: `model = neptune.init_model(with_id="CLS-FOREST")`
`ModelVersion`	`init_model_version()`	`PROJKEY-MODKEY-#`	New model version: `model_version = neptune.init_model_version(model="CLS-FOREST")` Existing model version: `model_version = neptune.init_model_version(with_id="CLS-FOREST-11")`
`Project`	`init_project()`	`workspace-name/project-name`	`project = neptune.init_project(project="ml-team/classification")`

The general rule is:

If you supply the ID of an existing object through the with_id parameter, that object is resumed and you can continue logging to it. You can add, change, or delete fields as you normally would.
If you don't supply an ID of an existing object, a new object is created.

For detailed usage, see API reference ≫ neptune

Initialization parameters#

The table below lists parameters which are common to all Neptune init functions.

For object-specific initialization functions and examples, see neptune.

Parameters

Name	Type	Default	Description
`api_token`	`str`, optional	`None`	User's API token. If `None`, the value of the `NEPTUNE_API_TOKEN` environment variable is used.
`flush_period`	`float`, optional	`5`	In asynchronous mode, how often Neptune should trigger disk flushing (in seconds).
`mode`	`str`, optional	`async`	Connection mode in which the tracking will work.
`name`*	`str`, optional	`Untitled`	Custom name for the object.
`project`*	`str`, optional	`None`	Name of a project in the form `workspace-name/project-name`.*
`proxies`	`dict`, optional	`None`	Argument passed to HTTP calls made via the Requests library.
`with_id`*	`str`, optional	`None`	The Neptune identifier of an existing object to resume, such as "CLS-11". The identifier is stored in the object's "sys/id" field. If omitted or `None` is passed, a new object is created.

* Does not apply to init_project(). See the parameter-specific sections for details.

`api_token`#

Name	Type	Default
`api_token`	`str`, optional	`None`

User's API token. If None, the value of the NEPTUNE_API_TOKEN environment variable is used.

Warning

To keep your token secure, avoid placing it in source code. Instead, save it as an environment variable.

Set to neptune.ANONYMOUS_API_TOKEN to log metadata anonymously.

`flush_period`#

Name	Type	Default
`flush_period`	`float`, optional	`5` (seconds)

In asynchronous (default) connection mode, how often Neptune should trigger disk flushing.

`mode`#

Name	Type	Default
`mode`	`str`, optional	`async`

Connection mode in which the tracking will work. Possible values are async, sync, offline, read-only, and debug.

`name`#

Name	Type	Default
`name`	`str`, optional	`Untitled`

A custom name for the run, model, or model version.

Neptune stores the name in the sys/name field.

Example

# Create a new version of model "CLS-FOREST"
model_version = neptune.init_model_version(
    model="CLS-FOREST",
    name="New forest-based classification model for emotion detection",
)

`project`#

Name	Type	Default
`project`	`str`, optional	`None`

Name of a project in the form workspace-name/project-name. If None, the value of the NEPTUNE_PROJECT environment variable is used.

Example

# Create a new run in the project "classification" in the workspace "ml-team"
run = neptune.init_run(project="ml-team/classification")

`proxies`#

Name	Type	Default
`proxies`	`dict`, optional	`None`

Argument passed to HTTP calls made via the Requests library. For details on proxies, see the Requests documentation.

`with_id`#

Name	Type	Default
`with_id`	`str`, optional	`None`

The Neptune identifier of an existing object to resume, such as "CLS-11" in the case of a run.

If omitted, a new object is created.

The identifier is stored in the object's sys/id field and displayed in the leftmost column of any table view.

Example

# Resume logging to an existing run
run = neptune.init_run(with_id="CLS-11")
run["namespace/field"] = "new metadata"
...

# Resume a model in order to fetch metadata
model = neptune.init_model(with_id="CLS-TREE", mode="read_only")
model_sig = model["signature"].download()
...

How do I find the ID?

The Neptune ID is a unique identifier for the object. In the table view, it's displayed in the leftmost column.

The ID is stored in the system namespace. If the object is active, you can obtain its ID with neptune_object["sys/id"].fetch(). For example:

>>> run = neptune.init_run(project="ml-team/classification")
>>> run["sys/id"].fetch()
'CLS-26'

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.

Universal methods and parameters#

Methods#

Field lookup: []#

Assignment: =#

assign()#

del#

exists()#

fetch()#

get_structure()#

get_url()#

pop()#

print_structure()#

stop()#

sync()#

wait()#

Initialization functions#

Initialization parameters#

api_token#

flush_period#

mode#

name#

project#

proxies#

with_id#

Field lookup: `[]`#

Assignment: `=`#

`assign()`#

`del`#

`exists()`#

`fetch()`#

`get_structure()`#

`get_url()`#

`pop()`#

`print_structure()`#

`stop()`#

`sync()`#

`wait()`#

`api_token`#

`flush_period`#

`mode`#

`name`#

`project`#

`proxies`#

`with_id`#