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. A docker image is configured that will essentially apply the command 'jupyter nbconvert' to allow generating output files from a Jupyter notebook file. When configured correctly, a Jupyter Report scripting engine can be added and authorized users will see a Jupyter Reports option on the menu of data grids.

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.

Set Up Docker Image

Install Docker Desktop for your operating system. For a development system you can choose "Expose Docker Daemon on on tcp://localhost:2375 without TLS". Learn about installing docker in the first sections of this topic:

Next, you'll clone the docker-rstudio project and build the python/nbconvert image. Note that this is not a module and should not be cloned into your LabKey enlistment. In Docker Desktop, confirm that you can see labkey/nbconvert in the list of available Images.

Configure Docker Host on LabKey Server

First, confirm that your LabKey Server includes the docker module. Select (Admin) > Site > Admin Console and check the Module Information tab. Contact your Account Manager if you don't see Docker on the list.

Next, switch to the Settings tab of the Admin Console. Under Premium Features, click Docker Host Settings. Enable the Docker Host and provide the port and other settings as described in this topic:

Click Test Saved Host to confirm the configuration.

Add Docker Report Engine

Still within the Admin Console, under Configuration, click Views and Scripting. Select Add > Docker Report Engine. In the popup, you'll see the default options and can adjust them if needed.

  • Language: Python
  • File extension: ipynb (don't include the . before the extension)
  • Docker Image Name: labkey/nbconvert
  • 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

Boilerplate image/contents

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 all collapse all