Reports for JupyterLab

Requirements

JupyterLab v3.x.x.; note that version 4.0.0 or newer have not been tested and are not officially supported. For information on how to install and configure JupyterLab of an appropriate version locally, refer to Jupyter documentation. For Jupyter versions, see Jupyter changelog.

Python v3.6 or newer. Python distributions can be downloaded from this page.

Installation and configuration

Instructions below do not cover the general usage of JupyterLab; refer to Jupyter User Guide

Jupyter Reports is hosted as a PyPi package and can be installed directly in JupyterLab or via the user’s system terminal using the pip command:

pip install energy_machines_jupyter_reports

When running from the system terminal, do not forget to either start Python console or prefix the command above with the PATH variable for the appropriate Python interpreter.

Once installed, Jupyter Reports becomes visible in JupyterLab’s Extension Manager (you might need to refresh the list of extensions or restart the kernel):

The next step is to configure the extension. Go to Settings » Advanced Settings Editor » Energy Machines jupyterlab extension. Like most of JupyterLab’s settings, the extension is configured by entering the parameters in a JSON-formatted text file. A default configuration with no parameter values is provided for convenience and can be copied and pasted to preserve JSON formatting:

{
    // Energy Machines jupyterlab extension settings
    // energy_machines_jupyter_reports:settings
    // Energy Machines jupyterlab extension settings
    //
*********************************************

    // Access token
    // Energy Machines public API access token, provided by your administrator.
    "accessToken": "$YOUR_PROVIDED_ACCESS_TOKEN",

    // Domain
    // Domain for public API.
    "domain": "https://energymachines.cloud"
}

For accessToken, use API access token received from EM Cloud administration/support (the token in the example above is a dummy). For domain, use https://energymachines.cloud. Save the settings and proceed to use the extension in a notebook.

Usage

The extension adds three buttons to the toolbar atop the notebook editor:

Edit or set period

Opens a date picker. Select an arbitrary range of dates and click Ok to generate and run a code block to set the date range:

time_from = 1698793200000 # 2023-11-01 00:00:00
time_to = 1699225199999 # 2023-11-05 23:59:59

Alternatively, click Close or anywhere outside the date picker to close it without generating any code.

Since the interface only allows to select dates, the code it runs will always set the time to 00:00:00 for the starting point and 23:59:59 for the end point. It is, however, possible to set different times by declaring the variables time_from and time_to manually. In that case, each must be an integer expressing the corresponding time as a Unix epoch timestamp in milliseconds.

Select tags from list

Opens the list of projects accessible with the configured API access token. Select the project(s) to retrieve tags from and click Next to retrieve the complete list of available tags as arranged under Tags. Select tags to retrieve the history of. Note that a filter field is available for convenience at both steps.

Select tags from page

Opens the list of projects accessible with the configured API access token. Select the project to retrieve tags from and click Next to retrieve the complete list of available pages as arranged under Pages. Select a page and click Next to open it; alternatively, click Select project to go back to the list of projects.

Opening a page iframes the page viewer where a tag or multiple tags can be selected in the left pane or picked from the page view, if added there in the page editor as appropriate tag objects. Note that the checkboxes in both parts of the interface are synced. Select the tags to retrieve the history of; alternatively, click Prev to go back to the list of pages.

Once the necessary tags have been selected, click Finish to generate and run a code block that will authenticate the script with the provided API token and create a dictionary with tag history values:

import requests

headers = {'Content-Type': 'application/json','Authorization': 'Bearer $YOUR_PROVIDED_ACCESS_TOKEN' }
Project_X_tags_history = requests.post('https://energymachines.cloud/api/v1/$YOUR_PROVIDED_ACCESS_TOKEN/history/aggregate/by-path/json', headers=headers, json = {
        "groupingType": "MINUTES",
        "tagList": ['test_folder/Temp_delta','Counter1'],
        "timeFrom": time_from,
        "timeTo": time_to
      }).json()

# Project X tags history variables
Project_X_test_folder_Temp_delta_history = Project_X_tags_history[0]
Project_X_Counter1_history = Project_X_tags_history[1]

Alternatively, click Cancel or anywhere outside the tag selector to close it without generating any code.

Note that both time_from and time_to need to be defined beforehand for this tool to work. The returned dictionary consists of entries structured as follows:

• tagID
  Tag ID as used in the Cloud. Can be used in other API calls that require it
• name
  Tag name expressed as full path
• unit
  Unit configured for the tag, see Tag Editor
• points
  A subdictionary that enumerates changes in the tag’s value throughout the selected timespan:
  • time
    Unix epoch timestamp in seconds
  • value
    Value assumed by the tag at the specified timepoint

If there have not been any changes during the selected timespan, there will be no points.

Note that Jupyter Reports will also create a variable for each dictionary entry; variables are declared as project_name_tag_name_history. Thus, in the example above, Project_X_test_folder_Temp_delta_history stands for tag Temp delta found in the test_folder directory under Project X. Variable names preserve case but replace spaces and slashes with underscores.

Selecting new tags with either tool will re-run the tag selection code block and every subsequent code cell, erasing earlier retrieved data. Use caution

Troubleshooting and deinstallation

Since the extension only attempts to authenticate when selecting a tag, most errors related to API access will not pop up until either  Select tags from list or  Select tags from page is used. Note as well as this section does not cover errors related to Python syntax.

Error messages

SyntaxError: Unexpected token '<', "

This error has two possible causes (note that the error message text might be misleading):

• JSON configuration file is incorrectly formatted. Refer to Installation and configuration for configuration guidelines.
• URL has an incorrect scheme or no scheme at all. URL (the domain parameter) must begin with the correct scheme, which is https://.

TypeError: Failed to fetch

This error occurs when the supplied URL is incorrect. Make sure that the URL in the configuration file is https:\\energymachines.cloud.

No projects found

This error occurs when the supplied API access token is incorrect or when the token does not provide access to any projects.

Deinstallation

To uninstall the extension, run the pip command below in the system terminal (use Python console or an appropriate interpreter prefix, see Installation and configuration above):

pip uninstall energy_machines_jupyter_reports

After the script has listed files to be deleted, press Y to proceed.

Alternatively, the extension can be uninstalled directly from JupyterLab by running the same command in a notebook cell. However, since Jupyter does not support keystroke interactions with the runtime, the confirmation needs to be suffixed to the command preemptively:

pip uninstall energy_machines_jupyter_reports --yes