Experiment

class neptune.experiments.Experiment(client, project, _id, internal_id)[source]

Bases: object

A class for managing Neptune experiment.

Each time User creates new experiment instance of this class is created. It lets you manage experiment, log_metric(), log_text(), log_image(), set_property(), and much more.

Parameters
  • client (neptune.Client) – API Client object

  • project (neptune.Project) – Project instance

  • _id (str) – Experiment short id

  • internal_id (str) – internal UUID

Example

Assuming that project is an instance of Project.

experiment = project.create_experiment()

Warning

User should never create instances of this class manually. Always use: create_experiment().

append_tag(tag, *tags)[source]

Append tag(s) to the current experiment.

Alias: append_tags(). Only [a-zA-Z0-9] and - (dash) characters are allowed in tags.

Parameters

tag (single str or multiple str or list of str) –

Tag(s) to add to the current experiment.

  • If str is passed, singe tag is added.

  • If multiple - comma separated - str are passed, all of them are added as tags.

  • If list of str is passed, all elements of the list are added as tags.

Examples

neptune.append_tag('new-tag')  # single tag
neptune.append_tag('first-tag', 'second-tag', 'third-tag')  # few str
neptune.append_tag(['first-tag', 'second-tag', 'third-tag'])  # list of str
append_tags(tag, *tags)[source]

Append tag(s) to the current experiment.

Alias for: append_tag()

download_artifact(filename, destination_dir)[source]

Download an artifact (file) from the experiment storage.

Download filename from the experiment storage and save it in destination_dir.

Parameters
  • filename (str) – Name of the file to be downloaded.

  • destination_dir (str) – The directory where the file will be downloaded.

Raises

NotADirectory – When destination_dir is not a directory.

Examples

Assuming that experiment is an instance of Experiment.

experiment.download_artifact('forest_results.pkl', '/home/user/files/')
get_channels()[source]

Alias for get_logs()

get_hardware_utilization()[source]

Retrieve GPU, CPU and memory utilization data.

Get hardware utilization metrics for entire experiment as a single pandas.DataFrame object. Returned DataFrame has following columns (assuming single GPU with 0 index):

  • x_ram - time (in milliseconds) from the experiment start,

  • y_ram - memory usage in GB,

  • x_cpu - time (in milliseconds) from the experiment start,

  • y_cpu - CPU utilization percentage (0-100),

  • x_gpu_util_0 - time (in milliseconds) from the experiment start,

  • y_gpu_util_0 - GPU utilization percentage (0-100),

  • x_gpu_mem_0 - time (in milliseconds) from the experiment start,

  • y_gpu_mem_0 - GPU memory usage in GB.

If more GPUs are available they have their separate columns with appropriate indices (0, 1, 2, …), for example: x_gpu_util_1, y_gpu_util_1.
The returned DataFrame may contain NaN s if one of the metrics has more values than others.
Returns

pandas.DataFrame - DataFrame containing the hardware utilization metrics.

Examples

The following values denote that after 3 seconds, the experiment used 16.7 GB of RAM

  • x_ram = 3000

  • y_ram = 16.7

Assuming that experiment is an instance of Experiment:

hardware_df = experiment.get_hardware_utilization()
get_logs()[source]

Retrieve all log names along with their last values for this experiment.

Returns

dict - A dictionary mapping a log names to the log’s last value.

Example

Assuming that experiment is an instance of Experiment.

exp_logs = experiment.get_logs()
get_numeric_channels_values(*channel_names)[source]

Retrieve values of specified metrics (numeric logs).

The returned pandas.DataFrame contains 1 additional column x along with the requested metrics.

Parameters

*channel_names (one or more str) – comma-separated metric names.

Returns

pandas.DataFrame - DataFrame containing values for the requested metrics.

The returned DataFrame may contain NaN s if one of the metrics has more values than others.

Example

Invoking get_numeric_channels_values('loss', 'auc') returns DataFrame with columns x, loss, auc.

Assuming that experiment is an instance of Experiment:

batch_channels = experiment.get_numeric_channels_values('batch-1-loss', 'batch-2-metric')
epoch_channels = experiment.get_numeric_channels_values('epoch-1-loss', 'epoch-2-metric')

Note

It’s good idea to get metrics with common temporal pattern (like iteration or batch/epoch number). Thanks to this each row of returned DataFrame has metrics from the same moment in experiment. For example, combine epoch metrics to one DataFrame and batch metrics to the other.

get_parameters()[source]

Retrieve parameters for this experiment.

Returns

dict - dictionary mapping a parameter name to value.

Examples

Assuming that experiment is an instance of Experiment.

exp_params = experiment.get_parameters()
get_properties()[source]

Retrieve User-defined properties for this experiment.

Returns

dict - dictionary mapping a property key to value.

Examples

Assuming that experiment is an instance of Experiment.

exp_properties = experiment.get_properties()
get_system_properties()[source]

Retrieve experiment properties.

Experiment properties are for example: owner, time of creation, time of completion, hostname.
List of experiment properties may change over time.
Returns

dict - dictionary mapping a property name to value.

Examples

Assuming that experiment is an instance of Experiment.

sys_properties = experiment.get_system_properties
get_tags()[source]

Get tags associated with experiment.

Returns

list of str with all tags for this experiment.

Example

Assuming that experiment is an instance of Experiment.

experiment.get_tags()
id

Experiment short id

Combination of project key and unique experiment number.
Format is <project_key>-<experiment_number>, for example: MPI-142.
Returns

str - experiment short id

Examples

Assuming that experiment is an instance of Experiment.

exp_id = experiment.id
log_artifact(artifact, destination=None)[source]

Save an artifact (file) in experiment storage.

Parameters
  • artifact (str) – A path to the file in local filesystem.

  • destination (str, optional, default is None) – A destination path. If None is passed, an artifact file name will be used.

Raises
  • FileNotFound – When artifact file was not found.

  • StorageLimitReached – When storage limit in the project has been reached.

Example

Assuming that experiment is an instance of Experiment:

# simple use
experiment.log_artifact('images/wrong_prediction_1.png')
log_graph(graph_id, value)[source]

Upload a TensorFlow graph for this experiment.

Parameters
  • graph_id (str) – A string UUID identifying the graph

  • value (str) – A string representation of TensorFlow graph

Example

Assuming that:
1. experiment is an instance of Experiment,
2. uuid is string representation of uuid.uuid4(),
3. value is string representation of tf.GraphDef instance.
experiment.log_graph(uuid, value)
log_image(log_name, x, y=None, image_name=None, description=None, timestamp=None)[source]

Log image data in Neptune

If a log with provided log_name does not exist, it is created automatically.
If log exists (determined by log_name), then new value is appended to it.
See Limits for information about API and storage usage upper bounds.
Parameters
  • log_name (str) – The name of log, i.e. mse, loss, accuracy.

  • x (double or PIL image) –

    Depending, whether y parameter is passed:

    • y not passed: The value of the log (data-point). Must be PIL image.

    • y passed: Index of log entry being appended. Must be strictly increasing.

  • y (PIL image, optional, default is None) – The value of the log (data-point).

  • image_name (str, optional, default is None) – Image name

  • description (str, optional, default is None) – Image description

  • timestamp (time, optional, default is None) – Timestamp to be associated with log entry. Must be Unix time. If None is passed, time.time() (Python 3.6 example) is invoked to obtain timestamp.

Example

Assuming that experiment is an instance of Experiment:

# simple use
experiment.log_image('bbox_images', PIL_object_1)
experiment.log_image('bbox_images', PIL_object_2)
experiment.log_image('bbox_images', PIL_object_3, image_name='difficult_case')

Note

For efficiency, logs are uploaded in batches via a queue. Hence, if you log a lot of data, you may experience slight delays in Neptune web application.

log_metric(log_name, x, y=None, timestamp=None)[source]

Log metrics (numeric values) in Neptune

If a log with provided log_name does not exist, it is created automatically.
If log exists (determined by log_name), then new value is appended to it.
See Limits for information about API and storage usage upper bounds.
Parameters
  • log_name (str) – The name of log, i.e. mse, loss, accuracy.

  • x (double) –

    Depending, whether y parameter is passed:

    • y not passed: The value of the log (data-point).

    • y passed: Index of log entry being appended. Must be strictly increasing.

  • y (double, optional, default is None) – The value of the log (data-point).

  • timestamp (time, optional, default is None) –

    Timestamp to be associated with log entry. Must be Unix time. If None is passed, time.time() (Python 3.6 example) is invoked to obtain timestamp.

Example

Assuming that experiment is an instance of Experiment and ‘accuracy’ log does not exists:

# Both calls below have the same effect

# Common invocation, providing log name and value
experiment.log_metric('accuracy', 0.5)
experiment.log_metric('accuracy', 0.65)
experiment.log_metric('accuracy', 0.8)

# Providing both x and y params
experiment.log_metric('accuracy', 0, 0.5)
experiment.log_metric('accuracy', 1, 0.65)
experiment.log_metric('accuracy', 2, 0.8)

Note

For efficiency, logs are uploaded in batches via a queue. Hence, if you log a lot of data, you may experience slight delays in Neptune web application.

log_text(log_name, x, y=None, timestamp=None)[source]

Log text data in Neptune

If a log with provided log_name does not exist, it is created automatically.
If log exists (determined by log_name), then new value is appended to it.
See Limits for information about API and storage usage upper bounds.
Parameters
  • log_name (str) – The name of log, i.e. mse, my_text_data, timing_info.

  • x (double or str) –

    Depending, whether y parameter is passed:

    • y not passed: The value of the log (data-point). Must be str.

    • y passed: Index of log entry being appended. Must be strictly increasing.

  • y (str, optional, default is None) – The value of the log (data-point).

  • timestamp (time, optional, default is None) –

    Timestamp to be associated with log entry. Must be Unix time. If None is passed, time.time() (Python 3.6 example) is invoked to obtain timestamp.

Example

Assuming that experiment is an instance of Experiment:

# common case, where log name and data are passed
neptune.log_text('my_text_data', str(data_item))

# log_name, x and timestamp are passed
neptune.log_text(log_name='logging_losses_as_text',
                 x=str(val_loss),
                 timestamp=1560430912)

Note

For efficiency, logs are uploaded in batches via a queue. Hence, if you log a lot of data, you may experience slight delays in Neptune web application.

name

Experiment name

Returns

str experiment name

Examples

Assuming that project is an instance of Project.

experiment = project.create_experiment('exp_name')
exp_name = experiment.name
remove_property(key)[source]

Removes a property with given key.

Parameters

key (single str) – Key of property to remove.

Examples

Assuming that experiment is an instance of Experiment:

experiment.remove_property('host')
remove_tag(tag)[source]

Removes single tag from the experiment.

Parameters

tag (str) – Tag to be removed

Example

Assuming that experiment is an instance of Experiment.

# assuming experiment has tags: `['tag-1', 'tag-2']`.
experiment.remove_tag('tag-1')

Note

Removing a tag that is not assigned to this experiment is silently ignored.

reset_log(log_name)[source]

Resets the log.

Removes all data from the log and enables it to be reused from scratch.

Parameters

log_name (str) – The name of log to reset.

Raises

ChannelDoesNotExist – When the log with name log_name does not exist on the server.

Example

Assuming that experiment is an instance of Experiment.

experiment.reset_log('my_metric')

Note

Check Neptune web application to see that reset charts have no data.

send_artifact(artifact, destination=None)[source]

Save an artifact (file) in experiment storage.

Alias for log_artifact()

send_graph(graph_id, value)[source]

Alias for log_graph()

send_image(channel_name, x, y=None, name=None, description=None, timestamp=None)[source]

Log image data in Neptune.

Alias for log_image()

send_metric(channel_name, x, y=None, timestamp=None)[source]

Log metrics (numeric values) in Neptune.

Alias for log_metric()

send_text(channel_name, x, y=None, timestamp=None)[source]

Log text data in Neptune.

Alias for log_text()

set_property(key, value)[source]

Set key-value pair as an experiment property.

If property with given key does not exist, it adds a new one.

Parameters
  • key (str) – Property key.

  • value (obj) – New value of a property.

Examples

Assuming that experiment is an instance of Experiment:

experiment.set_property('model', 'LightGBM')
experiment.set_property('magic-number', 7)
state

Current experiment state

Possible values: ‘running’, ‘succeeded’, ‘failed’, ‘aborted’.

Returns

str - current experiment state

Examples

Assuming that experiment is an instance of Experiment.

state_str = experiment.state
stop(exc_tb=None)[source]

Marks experiment as finished (succeeded or failed).

Parameters

exc_tb (str, optional, default is None) – Additional traceback information to be stored in experiment details in case of failure (stacktrace, etc). If this argument is None the experiment will be marked as succeeded. Otherwise, experiment will be marked as failed.

Examples

Assuming that experiment is an instance of Experiment:

# Marks experiment as succeeded
experiment.stop()

# Assuming 'ex' is some exception,
# it marks experiment as failed with exception info in experiment details.
experiment.stop(str(ex))