synaptrix 1.0.3

Library for live and offline denoising of multi-channel EEG data powered by auto-encoders, created by Synaptrix Labs Inc.

Synaptrix

A library for live and offline denoising of multi-channel EEG data powered by auto-encoders, created by Synaptrix Labs Inc. This README covers how to prepare LabStreamingLayer (LSL) for your platform, and how to install and initialize the SynaptrixClient.

Table of Contents

• Overview
• Prerequisites
  • Install LSL on macOS
  • Install LSL on Windows
  • Install LSL on Linux
• Installation
• Usage
  • Initialize SynaptrixClient
• License

Overview

Synaptrix provides a convenient Python API for EEG denoising using your own model or pre-trained models. It also integrates with LabStreamingLayer (LSL) for real-time data acquisition. To use LSL functionality, you must first install the native LSL libraries on your system (see Prerequisites).

Prerequisites

Install LSL on macOS

1. Ensure you have Homebrew installed.
2. Run:

   brew install labstreaminglayer/tap/lsl
   

This installs the native LSL libraries that pylsl depends on.

Install LSL on Windows

1. Visit the official LSL Windows Installation Docs
2. Download the appropriate installer/zip.
3. Follow instructions to install the .dlls so that pylsl can detect them.

Install LSL on Linux

1. Ubuntu/Debian (example):

   sudo apt-get update
   sudo apt-get install cmake build-essential
   git clone https://github.com/sccn/labstreaminglayer.git
   cd labstreaminglayer/LSL
   # Then follow build instructions from the official docs
   

Installation

After installing the native LSL libraries for your platform, you can install Synaptrix:

    pip install synaptrix

Usage

Initialize SynaptrixClient

    from synaptrix import SynaptrixClient
    import pandas as pd

    # Initialize the client
    client = SynaptrixClient(
        API_KEY="YourAPIKey"
    )

After initializing the client, you can then access all the functions of synaptrix.

Our model works best with normalized data. If your data is not normalized don't worry! The library will denoise your data by default.

Here is an example of how you can denoise a csv file called data.csv. Let's say the columns you want to denoise has indices [1,2,5,7], you want to skip the first 2 rows of data because they contain header data, the column with index 0 contains datetime data, and you want to output a df:

    data_in = pd.read_csv("data.csv")
    
    denoised = client.denoise_batch(
        data_in,
        data_columns=[1,2,5,7],
        skip_rows=2,
        datetime_column=0,
        output_format="df") 
    
    print("Denoised Data: ", denoised)

Now let's say you have a dataset that is already normalized. Set the normalize parameter to False first. Now let's say you want to denoise columns with indices [4,6,7], you want to skip no rows of data, the datetime column has index 3, and you want to output a csv called "denoised_data.csv":

    data_in = pd.read_csv("data.csv")
    
    client.denoise_batch(
        data_in,
        normalize=False,
        data_columns=[4,6,7],
        skip_rows=0,
        datetime_column=3,
        output_format="csv",
        file_name="denoised_data.csv") 

Here is an example of how you can generate a plot of the denoised data:

    data_in = pd.read_csv("data.csv)
    client.plot_denoised(data_in, num_channels=4, initial_window_sec=1)
    
    # initial_window_sec dictates how wide is the sliding viewing window

Here is an example of how to stream data through lsl into synaptrix and output denoised data:

    lsl_output = client.lsl_denoise(
        stream_duration = 10, # in seconds, change parameter to 0 for indefinite streaming
        num_channels = 4,
        sample_rate = 512, # adjust to match sampling rate of your device
        output_format = "csv",
        file_name = "lsl_test.csv" 
        
        # at the conclusion of the stream, all denoised data will be saved to this file
    )

---

License

This project is licensed under the Apache 2.0 license. See the LICENSE file for details.