Skip to content

R package setup and tutorial#

This tutorial walks you through setting up and using the Neptune R client package.

Related

Installing the Neptune client package#

Underneath the hood, the Neptune package uses Python through the reticulate package.

The following one-time setup is needed:

install.packages("reticulate")
library(reticulate)
install_miniconda()

install.packages("neptune")
library(neptune)
neptune_install()

The above installs miniconda (a minimalistic Python environment) and sets it up for you.

To work with Neptune after this initial setup, you only need to run the last two lines:

library(neptune)
neptune_install()

Using an existing Python virtual environment#

If you have a Python virtual environment (conda, miniconda, or virtualenv) already set up, you can use it instead of creating a new one. All the needed Python libraries will be installed there.

install.packages("neptune")
library(neptune)
neptune_install(
    method = "virtualenv",
    envname = "PATH/TO/YOUR/VIRTUALENV"
)
install.packages("neptune")
library(neptune)
neptune_install(
    method = "conda",
    envname = "PATH/TO/YOUR/CONDA/ENVIRONMENT"
)
install.packages("neptune")
library(neptune)
neptune_install(
    method = "conda",
    envname = "PATH/TO/YOUR/MINICONDA/ENVIRONMENT"
)

Creating a run#

The code below creates a run in the project of your choice. You track metadata by assigning it to the run in the code.

run <- neptune.init_run(
    project = "workspace-name/project-name",
    api_token = "Your Neptune API token",
)

Replace the project and api_token arguments with your own information.

To find and copy your project name:

  1. In the Neptune app, navigate to your project.
  2. Select SettingsProperties.
  3. Copy the name.

Copying the project name

To find and copy your API token:

  1. In the Neptune app, in the top-right corner, click your avatar top open the menu.
  2. Select Get your API token.
  3. Copy the token.

You can also set the API token globally:

neptune_set_api_token(token = "Your Neptune API token")

Tracking metadata#

Log hyperparamaters#

params <- list(
  "dense_units" = 128,
  "activation" = "relu",
  "dropout" = 0.23,
  "learning_rate" = 0.15,
  "batch_size" = 64,
  "n_epochs" = 30
)
run["parameters"] <- params

If you have parameters in the form of a dictionary, you can log them to Neptune in batch.

It will create a field with an appropriate type for each dictionary entry. You can update the parameters or add new ones later in the code:

# Add additional parameters 
run["model/parameters/seed"] <- RANDOM_SEED

# Update parameters, for example, after triggering an early stopping
run["model/parameters/n_epochs"] <- epoch

Log training metrics#

for (i in 1:epochs) {
  [...] # My training loop
  neptune_log(run["train/epoch/loss"], loss)
  neptune_log(run["train/epoch/accuracy"], acc)
}

# You can also use reticulate-based syntax:
run["train/epoch/loss"]$log(loss)

You can log training metrics to Neptune using series fields. In Neptune there are three types of series: FloatSeries, StringSeries, and FileSeries.

Each neptune_log() adds a new value at the end of the series.

Related

To learn more about field types, see the Field types reference.

Log evaluation results#

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

run["evaluation/accuracy"] <- eval_acc
run["evaluation/loss"] <- eval_loss

You can log plots and charts using the neptune_upload() function.

In the case of a ggplot object, it gets converted to an image file, but you can also upload images from the local disk.

neptune_upload(run["evaluation/ROC"], "roc.png")

# You can upload ggplot plots directly without saving them to a file
neptune_upload(run["evaluation/ROC"], ggplot_roc)

# If you want to control additional parameters, like the size of the plot,
# you can pass the same arguments as to ggsave
neptune_upload(
    run["evaluation/ROC"],
    ggplot_roc,
    width=20,
    height=20,
    units="cm"
)

# You can also use reticulate-based syntax:
run["evaluation/ROC"]$upload("roc.png")
run["evaluation/ROC"]$upload(ggplot_roc)

Upload model file#

You can upload any binary file from disk using the neptune_upload() method.

If your content consists of multiple files, you can upload a whole folder as a FileSet with neptune_upload_files().

# Upload a single file
neptune_upload(run["model"], "model.Rdata")

# If you don't need access to the separate files,
# you can also upload folders in batch
neptune_upload_files(run["model"], "models")

# Note that you can also use reticulate based syntax:
run["model"]$upload("model.Rdata")
run["model"]$upload_files("models")

Stopping the run#

Once you are finished with tracking metadata, stop the connection for that particular run:

neptune_stop(run)

# You can also use reticulate-based syntax:
run$stop()

Note

If you're executing a script, tracking stops automatically at the end.

In interactive environments such as RStudio, however, you need to stop runs explicitly with neptune_stop().

Exploring the results#

Head to the app to explore your tracked runs.

  • In the runs table, click on a run to display the logged metadata.
  • Select multiple runs and click Compare runs in the far-left nav to compare metadata between runs.