Building the Pipeline¶

This tutorial explains how to set up and run a preprocessing pipeline for biosignal data. It guides you through loading data, configuring modules, and executing a complete pipeline. For details on configuration files, see the configuration tutorial.

Overview¶

A BioPAP pipeline typically follows these steps:

1. Load your data
2. Inspect the data and module outputs individually
3. Configure modules with appropriate parameters
4. Create a pipeline and add processing steps
5. Run the pipeline and access results
6. Save the processed results

Load the Data¶

The first step is to load your biosignal data into memory. Use the LoadData() module, which currently supports BDF (BioSemi Data Format) files.

# Read the data file and load it into memory
load = LoadData(file_path=data_file)

Once loaded, inspect the data properties to understand what you're working with:

# Display basic information about the recording
load.raw.info

# Show detailed channel information
load.raw.describe()

For a visual inspection of the data, use the Plot() module. This opens an interactive window where you can navigate through the recording:

# Visualize the raw data in an interactive plot
plt = Plot(raw=load.raw, title="Raw Data Inspection")

Test and Configure Modules¶

Before adding modules to your pipeline, you can test them individually to ensure the configuration is correct. This allows you to inspect intermediate outputs and verify that each processing step works as expected.

Running Modules Independently¶

When running modules individually, always specify the input data using the raw parameter:

# Run the Anonymize module and inspect the output
ano = Anonymize(
    raw=load.raw,
    daysback=100,
    experimenter='J. Jansen',
    participant_id='AB00123'
)

# Check the output
ano.processed.info

The output of one module can be chained as input to another:

# Run the Rereference module on the output of the Anonymize module
ref = Rereference(raw=ano.processed, ref_channels=['EXG1', 'EXG2'])

# Verify the result
ref.processed.info

Overriding Configuration Parameters¶

When running modules individually, you can override the default configuration parameters. Any arguments passed to the module will override values from the configuration file:

# Override configuration: custom downsampling rate
ds = Downsample(raw=ref.processed, sfreq=100)

For details on which arguments are required or optional for each module, see the API documentation.

Create the Pipeline¶

Once you've tested your modules and finalized your configurations, create a pipeline by instantiating the Pipeline class with your data and configuration file:

# Create a new pipeline
pipe = Pipeline(data=load.raw, config_file=config_file)

View the pipeline's configuration settings:

# Print all configuration parameters
from pprint import pprint
pprint(pipe.config)

Refer to the configuration tutorial for details on modifying these settings.

Add Processing Steps¶

Add processing modules to the pipeline in the order you want them to execute. Important: Do not specify input data when adding steps to a pipeline—each step automatically receives the output of the previous step.

# Add processing steps in the desired order
pipe.add_step(Anonymize)
pipe.add_step(Downsample)
pipe.add_step(IIRFilter)
pipe.add_step(Rereference)
pipe.add_step(SaveOutput)

View all steps and their configurations:

# Display an overview of all pipeline steps with their settings
print(*pipe.steps, sep='\n')

Run the Pipeline¶

Execute the pipeline using the run() method:

# Run the pipeline
pipe.run()

The pipeline processes the data sequentially through each step. After execution, access the final processed data via:

# Access the processed output
processed_data = pipe.raw

To inspect and visualize the results:

# Check the processed data info
pipe.raw.info

# Visualize the processed data
plot_result = Plot(raw=pipe.raw, title="Processed Data")

Save Pipeline configuration¶

To save the current configuration of a pipeline, you can call the to_config method:

# Save complete Pipeline configuration to 'config.yaml'
pipe.to_config('./config.yaml')

This configuration file can be used to automatically recreate and run your pipeline. See Batch processing for more information.

Reset the Pipeline¶

To clear the pipeline and start over (useful for testing different configurations), use the reset() method:

# Clear the pipeline
pipe.reset()

No arguments are required. This resets all processing steps while keeping the pipeline structure intact.