Pass Inputs Into a SystemLink Jupyter Notebook

This article demonstrates how to pass input parameters into a SystemLink Jupyter Notebook. This approach can be useful if it is necessary to reactively change the Jupyter Notebook output data based on an input parameter.
 

Prerequisites

• The SystemLink Server PC must have the NI SystemLink Server - JupyterHub Module installed.
• [OPTIONAL] If passing the Jupyter Notebook inputs from a Grafana dashboard, Grafana must be installed on the SystemLink Server PC. Refer to [External] GitHub: NI Grafana Plugins for instructions.

To pass an input parameter into a Jupyter Notebook, the notebook must have properly defined parameters within the Cell Metadata block of the Property Inspector.

Within the notebook, a Code Cell must define a variable(s) to be used as the input parameter(s). Below is an example of a Code Cell that defines a single variable called num_elements with a value of 50:



To configure the variable as an input parameter, the Cell Metadata on the Code Cell must be modified.
Each input parameter must be defined within the "papermill" : {"parameters" : {}} and parameters[] sections of the Cell Metadata. Below is an example where one input parameter is defined based on the num_elements variable above:




For a step-by-step tutorial on configuring an input parameter and modifying the notebook's output data respectively, refer to the section below.

Example: Pass an Input to a Jupyter Notebook and Modify the Output Data Respectively

1. Open the SystemLink Server web interface.
2. From the navigation menu, select Utilities >> Jupyter to access the JupyterHub.
3. Create a new Jupyter Notebook.

• From the Launcher window, select Python 3 under the Notebook section.
• If the Launcher window is not visible, click the blue New Launcher button from the File Browser.

4. Create a Code Cell that imports any required Python modules.

• At minimum, the pandas and scrapbook modules must be imported to handle the output data.
• For this example, the random and datetime modules are used to generate a table of random numbers over time.

import pandas as pd
import scrapbook as sb
import random
import datetime

5. In another Code Cell, define the variable(s) that will be used as the input parameter(s).

• For this example, a variable called num_elements is assigned a value of 50. Later, this variable will be used to determine how many random data points are outputted by the notebook.

num_elements = 50

6. In a new Code Cell, generate the data that should be outputted by the notebook. Format the data as a [External] Dictionary, and then convert it to a [External] DataFrame.

• The example code below creates a Dictionary to store timestamps and random numbers. A [External] For Loop is used to populate the Dictionary with num_elements number of points.
• The Dictionary is converted into a DataFrame using pd.DataFrame.from_dict(<dictionary name>).

# Create a dictionary that will store the output data
data_dictionary = {
	"timestamps" : [],
	"values" : []
}

# In a For Loop, populate the "values" array with random data and "timestamp" array with corresponding timestamps.
current_time = datetime.datetime.now()

for i in range(num_elements):
	data_dictionary["timestamps"].append(current_time - (i*datetime.timedelta(seconds = 30)))
	data_dictionary["values"].append(random.randint(0,100))

# Convert the dictionary into a DataFrame
df_data_dictionary = pd.DataFrame.from_dict(data_dictionary)

7. Convert the DataFrame into a structure that is required by SystemLink.

• Below, the DataFrame is converted back into a Dictionary, and then included in a new DataFrame that includes some additional keys such as type and id.

# Convert the DataFrame back into a Dictionary
df_dict = {
	"columns" : pd.io.json.build_table_schema(df_data_dictionary, index = False)['fields'],
	"values" : df_data_dictionary.values.tolist()
}

# Include the above in a new Dictionary that will be outputted by the notebook
result = {
	"type" : "data_frame",
	"id" : "randomdata",
	"data" : df_dict
}

8. Record the output data with the [External] Scrapbook Glue API.

sb.glue("result", [result])

9. Configure the input and output parameters of the notebook using the Property Inspector.

1. Scroll back to the top of the notebook where your input parameter was defined (Code Cell containing num_elements = 50) and select the cell.
2. Click on the cog icon in the right-hand corner to open the Property Inspector.
3. Expand the Advanced Tools section.
4. Within the Cell Metadata block, ensure that:
   • The input parameter display_name, id and type is defined under the parameters[] section.
     • The id must match the name of your variable, and type must match the data type of the variable.
   • The default value for num_elements variable is defined under the parameters section.
     • If you require a notebook to ingest multiple inputs, each must be defined under the parameters section.
   • The data with ID randomdata (created in step 7) is referenced under the outputs[] section.
     • The output parameter display_name defines the name that will appear in Grafana/SystemLink, the id must match the id defined in step 7, and the type must be scalar or data_frame.
     • If you require a notebook to output multiple DataFrames, refer to Configure Multiple Outputs in SystemLink Jupyter Notebook.

{
    "papermill": {
        "parameters": {
            "num_elements": 50
        }
    },
    "systemlink": {
        "namespaces": [
            "ni-testmanagement"
        ],
        "outputs": [
            {
                "display_name": "Random Data",
                "id": "randomdata",
                "type": "data_frame"
            }
        ],
        "parameters": [
            {
                "display_name": "# of elements",
                "id": "num_elements",
                "type": "number"
            }
        ],
        "version": 2
    },
    "tags": [
        "parameters"
    ]
}

Download the attached notebook to test this example in full.
 

Next Steps

If using a Grafana dashboard, the input parameter will appear similar to below when you select the Jupyter Notebook as a Data Source. Updating the value of # of elements will cause the example Jupyter Notebook to update the amount of random data points generated.



Refer to Using SystemLink Server Jupyter Notebooks as a Data Source in Grafana for more details.