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.
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 "http://service-prefix-jupyter.srvc.int.jupyter:3031"
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
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
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 : 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