How to add Neptune to your code

Adding Neptune to your code is a really simple and quick process. You don't need to modify your existing code almost at all, simply add few lines to track metadata relevant to you. We’ll go through this process step by step.

This how-to guide covers the most important Neptune functionalities, but you can log many different types of metadata - audio, video, interactive charts, dataset info and many others. To learn more read What can you log and display?

How to add Neptune to your code - step by step

Before you start

Make sure you meet the following prerequisites before starting:

Step 1: Import Neptune and create a Run

import neptune.new as neptune
from neptune.new.types import File
run = neptune.init(
api_token='<your_api_token>',
project='<your_project_name>',
)

This code imports Neptune client library and creates a Run in the project of your choice. This will be your gateway to log relevant to you metadata to Neptune.

Step 2: Log hyperparameters

parameters = {
'dense_units': 128,
'activation': 'relu',
'dropout': 0.23,
'learning_rate': 0.15,
'batch_size': 64,
'n_epochs': 30,
}
run['model/parameters'] = parameters

If you have parameters in form of a dictionary you can log them to Neptune in batch. It will create a field with the appropriate type for each dictionary entry.

You can update the hyperparameters or add new ones later in the code:

# Add additional parameters
run['model/parameters/seed'] = RANDOM_SEED
# Update parameters e.g. after triggering an early stopping
run['model/parameters/n_epochs'] = epoch

Step 3: Log training metrics

Any framework
TF/Keras
XGBoost
LightGBM
scikit-learn
Any framework
for epoch in range(parameters['n_epochs']):
[...] # My training loop
run['train/epoch/loss'].log(loss)
run['train/epoch/accuracy'].log(acc)
TF/Keras
from neptune.new.integrations.tensorflow_keras import NeptuneCallback
model.fit(
x_train,
y_train,
callbacks=[NeptuneCallback(run=run)],
)
XGBoost
from neptune.new.integrations.xgboost import NeptuneCallback
xgb.train(
params=parameters,
dtrain=dtrain,
callbacks=[NeptuneCallback(run=run)],
)
LightGBM
from neptune.new.integrations.lightgbm import NeptuneCallback
gbm = lgb.train(
parameters,
lgb_train,
callbacks=[NeptuneCallback(run=run)],
)
scikit-learn
import neptune.new.integrations.sklearn as npt_utils
run['cls_summary'] = npt_utils.create_classifier_summary(gbc, X_train, X_test, y_train, y_test)
run['rfr_summary'] = npt_utils.create_regressor_summary(rfr, X_train, X_test, y_train, y_test)
run['kmeans_summary'] = npt_utils.create_kmeans_summary(km, X, n_clusters=17)

You can log training metrics to Neptune using series fields. Each .log() will add a new value at the end of the series. You can use Neptune with any machine learning framework, but if you are using a framework that supports logging (most of them do!) you don't need to write yourself the logging code at all. Just add the Neptune integration and it will track all the training metrics.

Neptune integrates with 25+ tools and frameworks. Check out the full list of integrations.

Step 4: Log evaluation results

Evaluation metrics

run['evaluation/accuracy'] = eval_acc
run['evaluation/loss'] = eval_loss

To log evaluation metrics simply assign them to a field of your choice. Using the snippet above, both evaluation metrics will be stored in the same evaluation namespace.

Evaluation charts

Matplotlib
From disc
Matplotlib
import matplotlib.pyplot as plt
from scikitplot.metrics import plot_roc, plot_precision_recall
fig, ax = plt.subplots()
plot_roc(y_test, y_pred_proba, ax=ax)
run['evaluation/ROC'].upload(fig)
fig, ax = plt.subplots()
plot_precision_recall(y_test, y_pred_proba, ax=ax)
run['evaluation/precision-recall'].upload(fig)
From disc
run['evaluation/ROC'].upload('roc.png')
run['evaluation/precision-recall'].upload('prec-recall.jpg')

You can log plots and charts easily using the .upload() function. In case of a plot object it gets converted to an image file and uploaded, but you can also upload images from the local disc.

Sample predictions

Images
Tabular data
Images
for image, predicted_label, probabilites in sambple_predictions:
description = '\n'.join(['class {}: {}'.format(label, prob) for label, prob in probabilites])
run['evaluation/predictions'].log(
image,
name=predicted_label,
description=description
)
Tabular data
import pandas as pd
df = pd.DataFrame(
data={
'y_test': y_test,
'y_pred': y_pred,
'y_pred_probability': y_pred_proba.max(axis=1),
}
)
run['evaluation/predictions'].upload(File.as_html(df))

The snippet above logs sample predictions by using FileSeries to log a series of labeled images. If you are working with tabular data you can upload Pandas DataFrame and inspect it as a neat table from the UI.

Step 5: Upload model file

From disk
As a pickle
From disk
torch.save(net.state_dict(), 'model.pt')
run['model/saved_model').upload('model.pt')
As a pickle
run['model/pickled_model').upload(File.as_pickle(model_object))

You can upload any binary file (e.g. model file) from disk using the .upload() method. If your model is saved as multiple files you can upload a whole folder as a FileSet using .upload_files().

Step 6: Run your script and explore your metadata in Neptune

That's all! By adding just those few lines you are tracking your hyperparameters, training metrics, trained model and evaluation results. Now it's time to run your script and explore your metadata in Neptune.

What's next?

This how-to guide covered the most imporant Neptune functionalities, but you can log many different types of metadata - audio, video, interactive charts, dataset info and many others. To learn more read What can you log and display?