How to Create Custom Jupyter Notebook Reports

BMON has a top-level Menu Item titled “Energy Reports” (a BMON version of March 24, 2020 or later must be present, and the Energy Reports feature must be configured in the BMON Settings file). A number of special reports that analyze the energy use of individual Buildings and analyze the energy use of Organziations are available to show on this BMON page. These reports satsify many analysis needs, but you also have the ability to create your own custom report developed in a Jupyter Notebook using the Python Programming Language. Note that these reports fall under the “Energy Reports” menu item, your custom reports do not have to be related to energy use; they can use any sensor data available in BMON and perform any form of data analysis.

A Jupyter Notebook is a document that contains live programming code, equations, visualizations, and formatted text. Through use of the Python Programming language within the Notebook, data from BMON can be acquired, analyzed, visualized and reported on. The BMON Jupyter Notebook reporting is structured to run these reports nightly and convert the output from the report into an HTML document that is viewable through the “Energy Reports” menu item in BMON.

The purpose of this How-To Guide is to show you how to create your own custom Jupyter Notebook report that is automatically run nightly and viewable through BMON. Your report can use BMON data and data from anywhere on the Internet. The Notebook has the full power of the Python programming language available to it, so the range of available processing and data analysis tools is very large.

To successfully create a custom report, you will need to have some basic level of skill with the following tools and services:

  • The Python programming language.

  • Jupyter Notebooks

  • GitHub, a file sharing and version control system, which is used BMON to store the Jupyter Notebooks used for the creation of Energy Reports.

Note that BMON for a number of years has had a “Custom Reports” feature that allows you to combine a number of BMON Graphs onto one page, and have that page accessible as a Report. This feature is described here: Custom Reports. This feature is simpler to use than the Custom Jupyter Report feature, but it lacks the power and flexibility offered by Jupyter Notebooks and the Python programming language.

This guide provides some introductory text, but the bulk of the guide is in the form of videos that walks through creation of a simple custom report. These videos are available in the last section of this page.

Prerequisites

This Guide assumes that your BMON system is already configured to run Energy Reports. There are a number of steps required to reach that point. This Guide is not meant to provide detail on those steps, but they are briefly listed here:

  • Create a GitHub repository to hold the all of the Jupyter Notebooks that are used to create the Energy Reports, including your custom report. Here is a Sample GitHub Repository.

    • That repository must include a config.yaml configuration file in the root directory. This file indicates which BMON Servers the reports will run against, and it also specifies the formatting theme used for the Jupyter Notebooks.

  • Ensure that the bmonreporter software is setup to run nightly and that the configuration file for that software lists the above GitHub repository. That software stores the created HTML reports in an Amazon AWS S3 bucket configured as a static website. This website is accessed by BMON to display the created the reports.

  • The ENERGY_REPORTS_URL setting in the settings.py file for your BMON server must have the URL of the AWS S3 static website. Further, that settings file must have an Energy Reports item in the BMSAPP_NAV_LINKS setting.

Again, if your BMON install is already set up to run Energy Reports, none of the above needs to be performed prior to creating a Custom Jupyter Notebook Report.

Creating the Custom Jupyter Notebook Report

This section contains two videos to explain how the Custom Jupyter Report is created. In this first video, the difference between Building reports and Organization reports is explained. Also, the video explains where to store your Custom Juptyer Notebook file in the GitHub repository. (Hint: In the YouTube Settings menu–cog symbol on the lower right–you can increase Playback speed to 1.25x, which may improve your listening experience!)

This next video walks through creation of an actual Jupyter Notebook report. Please not some of the reference links below the video for important resources.

As indicated in the video, creation of Custom Jupyter Notebook reports requires installation of a couple of special Python packages:

  • bmondata allows access to data (e.g. sensor readings, building characteristics) on BMON servers.

  • scrapbook is a special library for attaching arbitrary information to Jupyter notebooks. This is used to assign title and report order information to the notebook, which is then used by the report creation script.

To install these packages, execute the following commands:

pip install bmondata
pip install nteract-scrapbook

Here is some documentation for the bmondata Python package, which allows for easy access to BMON data from within your Jupyter Notebook (or any Python script for that matter). Example usage of the library is shown here.

The Jupyter Notebook report that was created in the video above is available here.

The Jupyter Notebook Reports that were used to create the primary Energy Reports for BMON are available in this repository. Find the reports in the templates directory.