Premium Feature — Available in the Professional and Enterprise Editions of LabKey Server. Learn more or contact LabKey.

This topic describes how to import reports from Jupyter Notebooks and use them with live data in LabKey Server. By configuring a Jupyter scripting engine, you can add a Jupyter Reports option on the menu of data grids.

In previous versions, this feature was enabled by configuring a docker image and a "Docker Report Engine". You can still use the same docker image configuration and use the resulting "localhost" URL for the "Jupyter Report Engine".

Once integrated, users can access the Jupyter report builder to import .ipynb files exported from Jupyter Notebooks. These reports can then be displayed and shared in LabKey.

Jupyter Notebooks URL

The Jupyter scripting configuration requires the URL of the service endpoint. Depending on where your Jupyter service is running, it could be something like "http://localhost:3031/" or ""

If you are connecting to a docker image, find the Remote URL by going to the Settings tab of the Admin Console. Under Premium Features, click Docker Host Settings. The "Docker Host" line shows your Remote URL.

The URL "http://noop.test:3031" can be used to configure a fake 'do nothing' service. This is only useful for testing.

Add Jupyter Report Engine on LabKey Server

  • Select (Admin) > Site > Admin Console.
  • Under Configuration, click Views and Scripting.
  • Select Add > New Jupyter Report Engine. In the popup, you'll see the default options and can adjust them if needed.
  • Language: Python
  • Language Version: optional
  • File extension: ipynb (don't include the . before the extension)
  • Remote URL: enter it here
  • Enabled: checked
Click Submit to save.

You can now see the Jupyter Reports menu option in the Data Views web part and on the grid menu where you created it.

Obtain Report .ipynb from Jupyter Notebooks

Within Jupyter Notebooks, you can now open and author your report. You can use the LabKey Python API to access data and craft the report you want. One way to get started is to export the desired data in a python script form that you can use to obtain that data via API.

Use this script as the basis for your Jupyter Notebook report.

When ready, you'll "export" the report by simply saving it as an .ipynb file. To save to a location where you can easily find it for importing to LabKey, choose 'Save As' and specify the desired location.

Create Jupyter Report on LabKey Server

From any data grid, or from the Data Views web part, you can add a new Jupyter Report. You'll see a popup asking if you want to:

Import From File

Click Import From File in the popup and browse to select the .ipynb file to open. You'll see your report text on the Source tab of the Jupyter Report Builder.

Click Save to save this report on LabKey. Enter a report name and click OK. Now your report will be accessible from the menu.

Start with Blank Report

The blank report option offers a basic wrapper for building your report.

Jupyter Report Builder

The Report Builder offers tabs for:

  • Report: See the report.
  • Data: View the data on which the report is based.
  • Source: Script source, including Save and Cancel for the report. Options are also available here:
    • Make this report available to all users
    • Show source tab to all users
    • Make this report available in child folders
  • Help: Details about the report configuration options available.

Help Tab - Report Config Properties

When a Jupyter Report is executed, a config file is generated and populated with properties that may be useful to report authors in their script code. The file is written in JSON to : report_config.json. A helper utility : is included in the nbconfig image. The class contains functions that will parse the generated file and return configured properties to your script. An example of the code you could use in your script:

from ReportConfig import get_report_api_wrapper, get_report_data, get_report_parameters

This is an example of a configuration file and the properties that are included.

"baseUrl": "http://localhost:8080",
"contextPath": "/labkey",
"scriptName": "myReport.ipynb",
"containerPath": "/my studies/demo",
"parameters": [
"version": 1

Export Jupyter Report from LabKey Server

The Jupyter report in LabKey can also be exported as an .ipynb file for use elsewhere. Open the report, choose the Source tab, and under Jupyter Report Options, click Export.

Related Topics

Was this content helpful?

Log in or register an account to provide feedback

expand allcollapse all