Skip to content

R package setup and tutorial#

Deprecated integration

This integration is not actively maintained and does not work on Windows.

Unless there's a clear signal from the user community, we do not plan on updating it.

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

Installing the Neptune client package#

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

The following one-time setup is needed. If you already have a Python environment that you want to use, skip to Using an existing virtual environment.

Creating a new virtual Python environment#

The following installs miniconda (a minimalistic Python environment) and sets it up for you:

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

install_miniconda()

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

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

library(neptune)
neptune_install()

Using an existing virtual environment#

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

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

install.packages("neptune")
library(neptune)
neptune_install(
    method = "virtualenv",
    envname = "/absolute/path/to/your/venv/directory"
)

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

install.packages("neptune")
library(neptune)
neptune_install(
    method = "conda",
    envname = "/absolute/path/to/your/venv/directory"
)

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

install.packages("neptune")
library(neptune)
neptune_install(
    method = "conda",
    envname = "/absolute/path/to/your/venv/directory"
)

For details on creating virtual environments, see the Python documentation .

Creating a run#

The code below creates a run in the specified project. You log metadata by assigning it to the run variable in your 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. Open the settings menu ( ) and select Details & privacy.
  3. Copy the name.

Finding project details

To find and copy your API token:

  1. In the Neptune app, in the bottom-left corner, expand your user menu.
  2. Select Get your API token.
  3. Copy the token.
Haven't registered?

If you haven't registered and want to start a run anonymously in a public project, you can initialize Neptune in the following way:

run <- neptune_init_run(
    api_token = ANONYMOUS_API_TOKEN,
    project = "common-r/quickstarts"
)

Saving your credentials as environment variables#

As a best practice in your workflow, set your Neptune API token and full project name to the NEPTUNE_API_TOKEN and NEPTUNE_PROJECT environment variables, respectively.

You can then leave the credentials out of your neptune_init_run() command.

export NEPTUNE_API_TOKEN="h0dHBzOi8aHR0cHM4kl0jvYh3Kb8...6Lc"

export NEPTUNE_PROJECT="ml-team/classification"

setx NEPTUNE_API_TOKEN "h0dHBzOi8aHR0cHM4kl0jvYh3Kb8...6Lc"

setx NEPTUNE_PROJECT "ml-team/classification"

You can also set the API token for the current session with the following R command:

neptune_set_api_token(token = "h0dHBzOi8aHR0cHM4kl0jvYh3Kb8...6Lc")

Tracking metadata#

Log hyperparamaters#

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

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

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#

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

Each neptune_append() adds a new value at the end of the series:

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

You can also use reticulate-based syntax:

run["train/epoch/loss"]$append(loss)

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.

A ggplot object will be 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.

neptune_upload(run["model"], "model.Rdata")

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

neptune_upload_files(run["model"], "models")
Reticulate-based syntax
run["model"]$upload("model.Rdata")
run["model"]$upload_files("models")

Track artifacts#

The neptune_track_files() function logs artifact metadata: version (hash), location (path), size, folder structure, and contents. It works for files, folders, and S3-compatible storage.

It's a handy alternative when you want to track an artifact without uploading it in full.

neptune_track_files(run["artifacts/images"], "datasets/train/images")
Reticulate-based syntax
run["artifacts/images"]$track_files("datasets/train/images")

Tag the run#

You can add tags to the run with the neptune_add() function:

neptune_add(run["sys/tags"], ["lgbm", "testing"])
Reticulate-based syntax
run["sys/tags"]$add(["lgbm", "testing"])

Stopping the run#

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

neptune_stop(run)
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 experiments table, click on a run to display the logged metadata.
  • To compare metadata between runs, toggle the eye icons ( ).

Related

Querying metadata#

To resume a run in order to fetch metadata from it:

resumed_run <- neptune_init_run(
    api_token = ANONYMOUS_API_TOKEN,
    project = "common-r/quickstarts",
    run = "HEL-3",
    mode = "read-only" # (1)!
)
  1. You can always initialize Neptune objects in read-only mode if you're only fetching data from them and not adding to or modifying the data.

Single values#

Use neptune_fetch() for single values:

params <- neptune_fetch(resumed_run["model/paramaters"])

Last value from series#

last_auc_value <- neptune_fetch_last(run["metrics/auc"])

Downloading files#

Anything uploaded, you can download.

neptune_download(run["train/images"], destination = "datasets/train/images")

If you have logged your images as a series, you can use neptune_download_last() to access only the last file:

df <- neptune_download_last(run["train/predictions"])

Fetching all runs as table#

To fetch the metadata of all your runs as a table:

df <- neptune_fetch_runs_table(project = "ml-team/classification")

Related