Episode 2: Routing Signals

Discover how to manage signal flow within your pipelines. This episode covers combining, selecting, splitting, and mixing signals, which are the foundation for building complex, multi-stream processing setups.

Read

The Router node in g.Pype is a flexible tool for managing signal flow in your pipeline. With a single node, you can:

Combine signals from multiple input ports into one output port

Select specific channels from one input port to one output port

Split signals from one input port to multiple output ports

Mix signals from several input ports to several output ports

All these behaviors are controlled by the input_channels and output_channels parameters. Below, we will explore how to use the Router for each scenario.

Combine Signals

The Router node can be configured to combine signals from multiple input sources. To demonstrate this, create four sources source1 to source4 as shown in the code below. Each source generates a single-channel sinusoid with frequencies 2, 4, 6, and 8 Hz, respectively. Next, create a Router node named combiner with input_channels=[[0], [0], [0], [0]] to combine these four single-channel sources into one multi-channel signal:

import gpype as gp

if __name__ == "__main__":

    app = gp.MainApp()
    p = gp.Pipeline()

    source1, source2, source3, source4 = [
        gp.Generator(channel_count=1,
                     signal_frequency=f,
                     signal_amplitude=25) for f in (2, 4, 6, 8)
    ]

    combiner = gp.Router(input_channels=[[0], [0], [0], [0]])

    scope = gp.TimeSeriesScope()

Note – input_channels List Notation

The input_channels parameter can be a list of lists: each entry of the outer list corresponds to an input port, while each inner list specifies the channel indices to be taken from that port. We will explore an alternative dictionary-style notation below.

In this example, the combiner node configured with four input ports, each taking the first channel of its connected signal. To connect these input ports to the four sources created above, it is necessary to understand the port-naming convention in g.Pype nodes.

Note – Router Input Port Naming

The Router node automatically creates its input ports from the input_channels parameter. These ports are named implicitly as in1 through inN, where N is the number of input ports.

Note – Default Port Naming

By default, g.Pype nodes with a single input or output port assign the names in and out to these ports, unless specified otherwise.

Given this convention, the four input ports of the combiner node are named in1 through in4. Connect each of these ports to the corresponding source as shown below:

    scope = gp.TimeSeriesScope()

    p.connect(source1, combiner["in1"])
    p.connect(source2, combiner["in2"])
    p.connect(source3, combiner["in3"])
    p.connect(source4, combiner["in4"])
    p.connect(combiner, scope)

    app.add_widget(scope)

    p.start()
    app.run()  # blocking until window is closed
    p.stop()

Note – Port Addressing Scheme

In the connect() method of the Pipeline class, ports are addressed using dictionary-style notation. For example, p.connect(senderNode["out"], receiverNode["in"]) connects the output port out of senderNode to the input port in of receiverNode.

For nodes with only one input and/or one output port, this explicit addressing scheme is usually omitted. In such cases, the recommended shorthand is p.connect(senderNode, receiverNode), which connects the single output port of senderNode to the single input receiverNode.

Run the script and observe how the four individual sources are shown as one multi-channel signal in the scope.

S2E2 example screenshot — Figure 21: Four different sources combined into one signal.

Select Channels

The Router node can select individual channels from its input and route them to the output. To demonstrate this, let’s extract the first and last channel from the combined signal in the previous example. To do this, add a selector node with parameter output_channels=[[0, 3]]. This configuration routes the first and last channel of the input signal to the output port. Place the selector node between the combiner and the scope in the pipeline.

    combiner = gp.Router(input_channels=[[0], [0], [0], [0]])
    selector = gp.Router(output_channels=[[0, 3]])

    scope = gp.TimeSeriesScope()

    p.connect(source1, combiner["in1"])
    p.connect(source2, combiner["in2"])
    p.connect(source3, combiner["in3"])
    p.connect(source4, combiner["in4"])
    p.connect(combiner, selector)
    p.connect(selector, scope)

Note – Internal Routing Procedure

The Router node first combines the input channels (as defined by input_channels) into a single internal multi-channel signal. This signal is then routed to the output ports according to the output_channels parameter.

Note – output_channels List Notation

The output_channels parameter can be a list of lists: Each entry of the outer list defines one output port, while each inner list specifies the channel indices (from the internal multi-channel signal) to be routed to that port. We will explore an alternative dictionary-style notation below.

Run the script and observe that only the first and last channels are shown in the scope.

Split Signals

The Router node can split a signal by routing selected input channels to multiple output ports. To demonstrate this, modify the parameter in line 15 of the code above to output_channels=[[0, 3], [2, 1]] and, for clarity, rename the node to splitter. This configuration creates two output ports: out1 receives the first and last channel [0, 3] of the input signal, while out2 receives the third and second channel [2, 1]. To visualize the two data streams simulataneously, create two scopes scope1 and scope2, and connect them to the two output ports of the splitter node.

    combiner = gp.Router(input_channels=[[0], [0], [0], [0]])
    splitter = gp.Router(output_channels=[[0, 3], [1, 2]])

    scope1 = gp.TimeSeriesScope()
    scope2 = gp.TimeSeriesScope()

    p.connect(source1, combiner["in1"])
    p.connect(source2, combiner["in2"])
    p.connect(source3, combiner["in3"])
    p.connect(source4, combiner["in4"])
    p.connect(combiner, splitter)
    p.connect(splitter["out1"], scope1)
    p.connect(splitter["out2"], scope2)

Run the script and observe how the four-channel signal is split into two data streams, each shown in its own scope.

Mix Signals

The Router node can mix signals by routing channels from multiple input ports to multiple output ports. To illustrate this, let’s restore the original channel order from the previous example. In that example, the output channels were defined as output_channels=[[0, 3], [2, 1]]. Because the internal, combined signal is indexed sequentially, the original order is restored via the index sequence 0, 2, 3, 1. To achieve this, create a new Router node named mixer with parameters input_channels set to [gp.Router.ALL, gp.Router.ALL] and output_channels set to [[0, 2], [3, 1]]. Insert the mixer node between the splitter and the two scopes in the pipeline:

    combiner = gp.Router(input_channels=[[0], [0], [0], [0]])
    splitter = gp.Router(output_channels=[[0, 3], [1, 2]])
    mixer = gp.Router(input_channels=[gp.Router.ALL, gp.Router.ALL],
                      output_channels=[[0, 2], [3, 1]])

    scope1 = gp.TimeSeriesScope()
    scope2 = gp.TimeSeriesScope()
    p.connect(source1, combiner["in1"])
    p.connect(source2, combiner["in2"])
    p.connect(source3, combiner["in3"])
    p.connect(source4, combiner["in4"])
    p.connect(combiner, splitter)
    p.connect(splitter["out1"], mixer["in1"])
    p.connect(splitter["out2"], mixer["in2"])
    p.connect(mixer["out1"], scope1)
    p.connect(mixer["out2"], scope2)

Note – Router.ALL Selector

For convenience and readability, the gp.Router.ALL constant can be used to reference all available channels, either received from a given input port or routed to a given output port.

Run the script and observe how the original channel order is restored, showing the signals with increasing frequency in their respective scopes.

Great! You now know how to flexibly route signals within a g.Pype pipeline. Next, we’ll begin a project that extracts alpha power from EEG signals. This project will span several upcoming episodes, gradually expanding as new nodes are introduced. Be sure to follow along with the first step below!

Project: Alpha Power Extraction (Step 1)

In this training project, we will build a g.Pype application step by step to extract alpha-band power from EEG using standard library nodes. First, create three signal sources with the Generator to synthesize a realistic composite test signal:

an alpha source source_alpha producing a 10 Hz sinusoid,
a modulator source_mod producing a 0.2 Hz sinusoid that modulates the alpha amplitude,
a noise source source_noise to mimic background EEG.

To visualize these three sources (and the derived signals you will create next) in a single TimeSeriesScope, instantiate a Router (router) to combine them into one multi-channel stream.

import gpype as gp

if __name__ == "__main__":

    app = gp.MainApp()
    p = gp.Pipeline()

    source_alpha = gp.Generator(channel_count=1,
                                signal_frequency=10,
                                signal_amplitude=25)

    source_mod = gp.Generator(channel_count=1,
                              signal_frequency=0.2,
                              signal_amplitude=25)

    source_noise = gp.Generator(channel_count=1,
                                noise_amplitude=25)

    router = gp.Router(input_channels={"alpha": [0],
                                       "modulator": [0],
                                       "noise": [0]})

    scope = gp.TimeSeriesScope()

Note – input_channels / output_channels Dictionary Notation

Both the input_channels and output_channels can also be specified using a dictionary-style notation. In this form, each dictionary key corresponds to a port name, and the associated value is a list of channel indices to be taken from (for input ports) or routed to (for output ports).

Using the dictionary-style notation for the input_channels parameter, the router node is created with three input ports alpha, modulator, and noise. Connect the three sources to these ports.

    p.connect(source_alpha, router["alpha"])
    p.connect(source_mod, router["modulator"])
    p.connect(source_noise, router["noise"])
    p.connect(router, scope)

    app.add_widget(scope)

    p.start()
    app.run()  # blocking until window is closed
    p.stop()

Finished! Run the script to see the three sources in the scope.

With your understanding now extended through the alpha power example, we are ready to conclude this episode.

Summary

In this episode, you learned how to use the Router node to

combine signals from multiple input ports into one output port,
select specific channels from one input port to one output port,
split signals from one input port to multiple output ports, and
mix signals from several input ports to several output ports.

In addition, we took the first step in our alpha power extraction project, which we will continue to expand in the upcoming episodes.

Proceed to episode 3, where we will apply basic transforms to create a surrogate EEG signal with amplitude-modulated alpha activity.

Code

File s2e2_combiner.py – View file on GitHub

# --------------------------------------------------------------
# Example file s2e2_combiner.py
# For details and usage, see g.Pype Training Season 2, Episode 2
# --------------------------------------------------------------

import gpype as gp

if __name__ == "__main__":

    # Create main app and pipeline
    app = gp.MainApp()
    p = gp.Pipeline()

    # Create 4 sources with different frequencies
    source1, source2, source3, source4 = [
        gp.Generator(channel_count=1,
                     signal_frequency=f,
                     signal_amplitude=25) for f in (2, 4, 6, 8)
    ]

    # Create router to combine signals
    combiner = gp.Router(input_channels=[[0], [0], [0], [0]])

    # Create scope
    scope = gp.TimeSeriesScope()

    # Connect nodes
    p.connect(source1, combiner["in1"])
    p.connect(source2, combiner["in2"])
    p.connect(source3, combiner["in3"])
    p.connect(source4, combiner["in4"])
    p.connect(combiner, scope)

    # Add widget to main app
    app.add_widget(scope)

    # Start pipeline and run application
    p.start()
    app.run()  # blocking until window is closed
    p.stop()

File s2e2_selector.py – View file on GitHub

# --------------------------------------------------------------
# Example file s2e2_selector.py
# For details and usage, see g.Pype Training Season 2, Episode 2
# --------------------------------------------------------------

import gpype as gp

if __name__ == "__main__":

    # Create main app and pipeline
    app = gp.MainApp()
    p = gp.Pipeline()

    # Create 4 sources with different frequencies
    source1, source2, source3, source4 = [
        gp.Generator(channel_count=1,
                     signal_frequency=f,
                     signal_amplitude=25) for f in (2, 4, 6, 8)
    ]

    # Create router to combine signals
    combiner = gp.Router(input_channels=[[0], [0], [0], [0]])

    # Create router to select signals
    selector = gp.Router(output_channels=[[0, 3]])

    # Create scope
    scope = gp.TimeSeriesScope()

    # Connect nodes
    p.connect(source1, combiner["in1"])
    p.connect(source2, combiner["in2"])
    p.connect(source3, combiner["in3"])
    p.connect(source4, combiner["in4"])
    p.connect(combiner, selector)
    p.connect(selector, scope)

    # Add widget to main app
    app.add_widget(scope)

    # Start pipeline and run application
    p.start()
    app.run()  # blocking until window is closed
    p.stop()

File s2e2_splitter.py – View file on GitHub

# --------------------------------------------------------------
# Example file s2e2_splitter.py
# For details and usage, see g.Pype Training Season 2, Episode 2
# --------------------------------------------------------------

import gpype as gp

if __name__ == "__main__":

    # Create main app and pipeline
    app = gp.MainApp()
    p = gp.Pipeline()

    # Create 4 sources with different frequencies
    source1, source2, source3, source4 = [
        gp.Generator(channel_count=1,
                     signal_frequency=f,
                     signal_amplitude=25) for f in (2, 4, 6, 8)
    ]

    # Create router to combine signals
    combiner = gp.Router(input_channels=[[0], [0], [0], [0]])

    # Create router to split signals
    splitter = gp.Router(output_channels=[[0, 3], [1, 2]])

    # Create scopes
    scope1 = gp.TimeSeriesScope()
    scope2 = gp.TimeSeriesScope()

    # Connect nodes
    p.connect(source1, combiner["in1"])
    p.connect(source2, combiner["in2"])
    p.connect(source3, combiner["in3"])
    p.connect(source4, combiner["in4"])
    p.connect(combiner, splitter)
    p.connect(splitter["out1"], scope1)
    p.connect(splitter["out2"], scope2)

    # Add widget to main app
    app.add_widget(scope1)
    app.add_widget(scope2)

    # Start pipeline and run application
    p.start()
    app.run()  # blocking until window is closed
    p.stop()

File s2e2_mixer.py – View file on GitHub

# --------------------------------------------------------------
# Example file s2e2_mixer.py
# For details and usage, see g.Pype Training Season 2, Episode 2
# --------------------------------------------------------------

import gpype as gp

if __name__ == "__main__":

    # Create main app and pipeline
    app = gp.MainApp()
    p = gp.Pipeline()

    # Create 4 sources with different frequencies
    source1, source2, source3, source4 = [
        gp.Generator(channel_count=1,
                     signal_frequency=f,
                     signal_amplitude=25) for f in (2, 4, 6, 8)
    ]

    # Create router to combine signals
    combiner = gp.Router(input_channels=[[0], [0], [0], [0]])

    # Create router to split signals
    splitter = gp.Router(output_channels=[[0, 3], [1, 2]])

    # Create router to mix signals
    mixer = gp.Router(input_channels=[gp.Router.ALL, gp.Router.ALL],
                      output_channels=[[0, 2], [3, 1]])

    # Create scopes
    scope1 = gp.TimeSeriesScope()
    scope2 = gp.TimeSeriesScope()

    # Connect nodes
    p.connect(source1, combiner["in1"])
    p.connect(source2, combiner["in2"])
    p.connect(source3, combiner["in3"])
    p.connect(source4, combiner["in4"])
    p.connect(combiner, splitter)
    p.connect(splitter["out1"], mixer["in1"])
    p.connect(splitter["out2"], mixer["in2"])
    p.connect(mixer["out1"], scope1)
    p.connect(mixer["out2"], scope2)

    # Add widget to main app
    app.add_widget(scope1)
    app.add_widget(scope2)

    # Start pipeline and run application
    p.start()
    app.run()  # blocking until window is closed
    p.stop()

File s2e2_alpha1.py – View file on GitHub

# --------------------------------------------------------------
# Example file s2e2_alpha1.py
# For details and usage, see g.Pype Training Season 2, Episode 2
# --------------------------------------------------------------

import gpype as gp

if __name__ == "__main__":

    # Create main app and pipeline
    app = gp.MainApp()
    p = gp.Pipeline()

    # Create alpha source
    source_alpha = gp.Generator(channel_count=1,
                                signal_frequency=10,
                                signal_amplitude=25)

    source_mod = gp.Generator(channel_count=1,
                              signal_frequency=0.2,
                              signal_amplitude=25)

    source_noise = gp.Generator(channel_count=1,
                                noise_amplitude=25)

    # Create router to combine signals
    router = gp.Router(input_channels={"alpha": [0],
                                       "modulator": [0],
                                       "noise": [0]})

    # Create scope
    scope = gp.TimeSeriesScope()

    # Connect nodes
    p.connect(source_alpha, router["alpha"])
    p.connect(source_mod, router["modulator"])
    p.connect(source_noise, router["noise"])
    p.connect(router, scope)

    # Add widget to main app
    app.add_widget(scope)

    # Start pipeline and run application
    p.start()
    app.run()  # blocking until window is closed
    p.stop()