Session and Experiment

‘Session’ and ‘Experiment’ are two core concepts in Neptune. This tutorial guides you through them and explains how to work with them.


In the first tutorial, as you remember, we initialized Neptune using neptune.init:

import neptune


However, the full definition of the neptune.init is as follows:

  • project_qualified_name - this is USERNAME/PROJECT_NAME, where first the component is the workspace name and the second is the project name (as you created in the Neptune web application).

  • api_token - User can explicitly paste NEPTUNE_API_TOKEN here, however, it is not recommended. This method first looks for an environment variable, then a value is passed in here. Note that this value overwrites the environment variable.


If you have your API token stored in the NEPTUNE_API_TOKEN environment variable you can leave the api_token argument empty.

That is not the only way of doing things but it does make things simpler. If you want to have more control, you can explicitly start a Neptune session:

from neptune.sessions import Session

session = Session(api_token='YOUR_LONG_API_TOKEN')

The session object contains all of the projects that you have access too. You can fetch the project on which you want to work on by running:

project = session.get_project(project_qualified_name='USERNAME/PROJECT_NAME')

And create a new experiment in that project.

experiment = project.create_experiment()

Returned experiment lets you invoke all methods that you know from the previous tutorial, for example:

experiment = project.create_experiment()

experiment.log_metric('iteration', i)
experiment.log_metric('loss', 1/i**0.5)
experiment.set_property('n_iterations', 117)


Let’s dive into the create_experiment method and what you can track with it. As you remember in the minimal example, we started an experiment, logged something to it, and stopped it:

neptune.log_metric('auc', 0.93)

You can make it cleaner and create your experiments in with statement blocks:

with neptune.create_experiment() as exp:
    exp.log_metric('auc', 0.93)

By doing so, you will never forget to stop your experiments. We recommend you use this option. Also, if you are creating more than one experiment, this approach keeps things organized.

Ok, now that we know how to start and stop experiments let’s see what happens in the app when you actually run it.

create experiment

With every create_experiment, a new record is added to Neptune with a state running. When you run stop in your experiment, either explicitly or implicitly, the state is changed to succeeded.