How to use Neptune with Leaflet maps#

When using the Folium library to create and manipulate Leaflet maps in Python, you can use Neptune to log maps saved as HTML.

Leaflet map

See in Neptune Example script

Quickstart#

The below example creates a map and logs it under a File field named leaflet_map.

import folium
import neptune

m = folium.Map()
m.save("map.html")

run = neptune.init_run()
run["leaflet_map"].upload("map.html")

To display it in Neptune, select the run where the map was logged and navigate to All metadata, or create a custom dashboard with a File preview widget.

Walkthrough#

Below is a more detailed example that you can follow along.

Before you start#

Sign up at neptune.ai/register.
Create a project for storing your metadata.

Have Folium and Neptune installed:

pipconda

pip install -U folium neptune

conda install -c conda-forge folium neptune

Tip

To follow the guide without any setup, run the example notebook in Colab

Logging Leaflet maps with Neptune#

Import Neptune and start a run:
```
import neptune

run = neptune.init_run() # (1)!
```
1. If you haven't set up your credentials, you can log anonymously:
```
neptune.init_run(
    api_token=neptune.ANONYMOUS_API_TOKEN,
    project="common/quickstarts",
)
```
If Neptune can't find your project name or API token

As a best practice, you should save your Neptune API token and project name as environment variables:
```
export NEPTUNE_API_TOKEN="h0dHBzOi8aHR0cHM6Lkc78ghs74kl0jv...Yh3Kb8"
```
```
export NEPTUNE_PROJECT="ml-team/classification"
```
Alternatively, you can pass the information when using a function that takes api_token and project as arguments:
```
run = neptune.init_run( # (1)!
    api_token="h0dHBzOi8aHR0cHM6Lkc78ghs74kl0jv...Yh3Kb8",  # your token here
    project="ml-team/classification",  # your full project name here
)
```
1. Also works for init_model(), init_model_version(), init_project(), and integrations that create Neptune runs underneath the hood, such as NeptuneLogger or NeptuneCallback.
2. API token: In the bottom-left corner, expand the user menu and select Get my API token.
3. Project name: You can copy the path from the project details ( → Edit project details).
If you haven't registered, you can log anonymously to a public project:
```
api_token=neptune.ANONYMOUS_API_TOKEN
project="common/quickstarts"
```
Make sure not to publish sensitive data through your code!

Create a map:

import folium

# Define coordinates for the map center
Reykjavik = [64.146667, -21.94]

# Create the map
my_map = folium.Map(location=Reykjavik, zoom_start=11)

Save the map as HTML:
```
my_map.save("my_map.html")
```
Use the upload() method to log the HTML map to the Neptune run:
```
run["leaflet_map"].upload("my_map.html")
```
To stop the connection to Neptune and sync all data, call the stop() method:
```
run.stop()
```

To open the run, click the Neptune link that appears in the console output.

[neptune] [info ] Neptune initialized. Open in the app: https://app.neptune.ai/workspace/project/e/RUN-1

Result

You can view the map in the All metadata section.

Displaying a map in the Neptune web app#

Apart from viewing the map in the All metadata section, you can create a custom dashboard and add the map as a widget.

In the top tabs, navigate to Run details.
Create a custom dashboard if you don't have one already.
Select Add widget.
In the top input box, start typing the name of the field where the map was logged (leaflet_map, in the example above) or choose the File preview widget and then find your map field.
To finish, click Add widget.

To download the logged map via the Neptune API, you need to connect to the run in your code and then access the field where the map was logged.

Assuming that a run with the ID GEO-7 exists:

import neptune

run = neptune.init_run(with_id="GEO-7")
run["leaflet_map"].download()

For more download options, see the File.download() reference.