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 : 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
print(get_report_data())
print(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": [
[
"pageId",
"study.DATA_ANALYSIS"
],
[
"reportType",
"ReportService.ipynbReport"
],
[
"redirectUrl",
"/labkey/my%20studies/demo/project-begin.view?pageId=study.DATA_ANALYSIS"
],
[
"reportId",
"DB:155"
]
],
"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