2021-03-31: NeuroPype Custom Node Tutorial

If you have not already heard of it, NeuroPype is a great tool for developing pipelines to perform sensor data acquisition, processing, analysis, and/or display.  Its Pipeline Designer, based on the Orange application, has a well-developed drag-and-drop interface that makes it easy for anyone from students to experienced clinicians to perform biosignal data analysis.  The NeuroPype - Academic Edition is also freely available to university researchers, faculty and students for non-commercial research.

Although the current NeuroPype release comes with hundreds of nodes readily available for use, they may not always provide the functionality that you desire.  Luckily, NeuroPype makes it fairly easy for developers to write and deploy their own Python-based nodes to support their biosignal processing requirements.  In this tutorial, I will take you step-by-step in creating your first NeuroPype custom node. 

Getting Started

You must first create an account using your school email address and download NeuroPype - Academic Edition to your computer.  I am using version 2020.0.4 for this tutorial.  Next, double click the executable to begin the installation.  During the installation, you may chose to install NeuroPype outside of the default C:\Program Files folder.  This will allow you to work within its nodes folder without the need for administrator privileges.  You may choose default setting for everything else to complete the installation.  If you have never downloaded NeuroPype before, you will be prompted to activate your license.  For more information regarding the installation of NeuroPype, refer to their Getting Started page. 

Once NeuroPype is installed, go to your desktop, right-click the NeuroPype (Academic) desktop icon and select properties from the pop-up menu.  Add " /console" following the path in the Target textfield then click the OK button.  This will allow you to run NeuroPype in console mode and view error messages in a terminal window.  You will find this to be helpful when deploying and debugging your custom nodes.

You should decide whether you want to place your node in one of the built in packages or create your own package.  If you want to use one of the built in packages, simply place the Python file for your node in the corresponding folder.  However, if your node is not a good fit for one of the existing packages or you would like to create your own working folder, go to Windows Explorer and create a new folder under the nodes directory of your NeuroPype installation.  I have created a new folder called nirdslab as shown in the figure below. 

Since this is a new folder, I also had to create the __init__.py file as required to make Python treat the directory containing the file as a package.  The contents of a basic __init__.py file are shown as follows.

Creating Your First Node

You can create your node in any Integrated Development Environment (IDE) that supports Python or use a text editor.  However, an IDE will better support debugging.  Nevertheless, I will use Notepad++ for the purposes of this tutorial.  In Notepad++, create a new file and save it as HelloWorldNode.py.  Within this file, we will first import the neuropype.engine package.  This package can be found under your NeuroPype installation within the NeuroPype\neuropype\engine folder.  Any other packages required for your particular implementation should also be imported.  Next, we will declare the name of the class, which should be the same as the file name, which in this case is HelloWorldNode.

As usual, you will add the __init__  reserved method to your Python class.  To learn more about the __init__ method, other reserved methods or for more on Python classes, refer to the Python documentation. 

DataPorts

You can expect to add one or more DataPorts to your node to control the flow of data between it and other nodes.  It is common to have just one DataPort that handles both inputs and outputs as follows:

data = DataPort(Packet, "Data to process")

This technique will be used for our first node.  Therefore, you should add this line of code within your class.  However, you should note that it is possible to have multiple input and/or output DataPorts in your node.  NeuroPype's developer reference provides can provide additional information on DataPorts should you need to utilize multiple in the future.

Node Properties

Users can change input values for your node through property ports.  These property can be input values, output values, or both and each have a type associated with them such as int, float, string, bool, enum, or list.  For the purpose of this tutorial, we will declare three input property ports (ListPort, IntPort, and BoolPort), which you will be able to view and modify in NeuroPype's Pipeline Designer once your node is deployed.  Each port accepts a default value, value type, help text, and data flow direction (in, out, or in/out) as parameters.

            list_property = ListPort([A,B,C], str, """Example list""") 

      int_property = IntPort(3, None, """Example integer""")

      bool_property = BoolPort(True, """Example boolean""")

Your code should now look similar to the following:

Data Setter 

The data() setter function is where the main logic of your node lives.  This usually involves iterating over the non-empty stream chucks found within the Packet v, which is passed into the method as one of its parameters.  After processing, the results of v should be written to the node's data property.

Other functions

You will want to add description() method that is typically used in Python to convert an object to its string representation.  While your node will now compile and deploy as is, you may want to considering override and/or add other node methods depending on your implementation.  Nodes that maintain internal state would be expected to override the on_signal_changed() method.  If you need to customize how your node determines it is finished processing, you will want to override the is_finished() method.  Overriding get_model() and set_model() methods may be necessary for those nodes performing machine learning or signal processing.

Deploying Your Node

If you did not save your node in the appropriate place already, drag and drop your Python file into the appropriate folder under the nodes directory as previously mentioned.  Double click the NeuroPype (Academic) desktop icon to start NeuroPype then start Pipeline Designer.  If there are any errors on startup, you should see them scroll by in the console window that opened with NeuroPype. 

Your node should be found under category with the same name as the folder that you placed your Python file in.  You can now drag your node into the , double click it to view Node properties.  You can now connect your custom node to other nodes in your own pipeline implementation. 

While this is a very basic node that is only intended to get you started, also refer to the sample node on the NeuroPype website.  Hopefully, you find this tutorial helpful but there is also a lot of documentation and a discussion board found on the NeuroPype website.

--Bathsheba Farrow (@sheisheba)