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
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
to save this report on LabKey. Enter a report name and click OK
. Now your report will be accessible from the
Start with Blank 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 : ReportConfig.py 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.
"containerPath": "/my studies/demo",
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