Percept Decoder Documentation

Overview

The Percept Decoder is a collection of python functions that extract and process Medtronic Percept Neurostimulator’s exported JSON File Format.

Methods

decoder.Percept.decodeJSON(inputFilename)

Parse Medtronic JSON File into JSON object.

Parameters

inputFilename – Path to utf-8 encoded JSON text file.

Returns

The raw exported Percept JSON object.

decoder.Percept.decodeEncryptedJSON(inputFilename, key)

Parse Encrypted Medtronic JSON File into JSON object.

Parameters

  • inputFilename – Path to Fernet encrypted JSON text file.

  • key – Fernet Encoder Passkey

Returns

The raw exported Percept JSON object.

decoder.Percept.estimateSessionDateTime(JSON)

Find all common occurance of Session DateTime String

Percept JSON often display wrong DateTime for “SessionDate” field due to unknown errors. There are a few most likely accurate locations that we can cross-reference for accuracy.

  1. SessionEndDate Field

  2. FirstPacketDateTime for BrainSense Data or BrainSense Surveys.

  3. SessionEndDate of EventSummary.

Parameters

JSON – The raw exported Percept JSON object.

Returns

The estimated unix timestamp (in seconds) of the session JSON file.

decoder.Percept.reformatStimulationChannel(channel)

Reformat Stimulation electrode definitions to common expressions.

Parameters

channel – Medtronic Channel Definition object.

Returns

Single text string of electrode contacts (i.e. -E02+CAN).

decoder.Percept.reformatElectrodeDef(electrodeDef)

Reformat electrode definitions to common expressions.

Parameters

electrodeDef – Medtronic Channel Definition string.

Returns

Returns a tuple (ChannelName, ChannelID) where ChannelName is a single text string of electrode contacts (i.e. E02), and ChannelID is numeric index of that channel.

Raises

ValueError – electrodeDef is of new electrode type. Script update is required.

decoder.Percept.reformatChannelName(string)

Reformat Recording electrode definitions to common expressions.

Parameters

string – Medtronic Sensing-Channel Definition string.

Returns

Returns a tuple (ChannelID, Hemisphere) where ChannelID is a decimal number indicating channel ID, and Hemisphere is brain hemisphere of the electrode.

decoder.Percept.getTimestamp(DateTimeString)

Convert Medtronic ISOFormat DateTime String to Unix Time.

Parameters

DateTimeString – Medtronic ISOFormat DateTime string.

Returns

Unix Timestamp (in seconds)

decoder.Percept.checkMissingPackage(Data)

Process and Correct Recordings with Missing Packages.

Percept BrainSense Streaming has possbility for missing data due to communication issue. This code will attempt to correct for the missing data by filling in 0s where there are no data to keep sampling rate consistent.

The correction occur in place of the data structure, so input/output is the identical structure. The correction will be applied to Indefinite Streaming and BrainSense Streaming.

TimeDomain Streaming Implementation:

  1. Calculate time (millisecond) difference between each packet using “Ticks” field in JSON object.

  2. Calculate the median time elapsed, and any packets above the median time is considered as skipped packets.

  3. Calculate average packet size (data come in packet of 62 or 63, 4 packets per second).

  4. Calculate number of missing packets (total skip time / median packet time)

  5. Calculate insertion index based on cumulative sum packet length

  6. Insert 0s to Time-Domain data, Label [“Missing”] field to 1s.

  7. Repeat above until all missing packets are accounted for.

Power Band Streaming Implementation:

  1. Calculate time (millisecond) difference between each packet using “Ticks” field in JSON object.

  2. Calculate the median time elapsed, and any packets above the median time is considered as skipped packets.

  3. If missing packets exist, create a template power band timestamp array using numpy.arange.

  4. Take in existing power band timestamp and power values and perform linear interpolation.

  5. Repeat the same for Stimulation Amplitude because power band comes in the same packet as Stimulation.

Timeshift between TimeDomain and Power Band packets:

Time shift may exist, and it can be calculated using the difference of the first tick values in milliseconds for TimeDomain and Power band packets. If the shift is within 1000ms, it will be a easy subtraction. However, if the value is uncommonly large, it is identified that an overflow has occured. Such diffence should be compensated with 2^15 (maximum absolute value of signed 16-bit variable).

Parameters

Data – Processed Percept Data Format.

Returns

Processed Percept Data Format.

decoder.Percept.processBreakingTimeDomain(Data)

Process and Correct Recordings with break in between.

Percept BrainSense Streaming has possbility for splitting one recording into 2 structures due to communication issue. This code will attempt to correct for the splitted data by merging multiple recordings into one.

The correction occur in place of the data structure, so input/output is the identical structure. Check source code for detail implementation of the algorithm. The correction will be applied to BrainSense Streaming.

Parameters

Data – Processed Percept Data Format.

Returns

Processed Percept Data Format.

decoder.Percept.extractPerceptJSON(JSON)

Primary Percept Data extraction code.

This code is a general wrapper to extract the following data structure from Percept JSON file and keep them in a standardized format.

The following function will be executed:

  1. extractPatientInformation

  2. extractTherapySettings

  3. extractStreamingData,

  4. extractIndefiniteStreaming,

  5. extractBrainSenseSurvey

  6. extractSignalCalibration,

  7. extractChronicLFP

Then data will be going through missing package handler (checkMissingPackage) and merging handler (processBreakingTimeDomain) for final output.

Parameters

JSON – The raw exported Percept JSON object.

Returns

Processed Percept Data Format.

decoder.Percept.extractPatientInformation(JSON, sourceData={})

Extract Patient Information.

Patient Information are mostly text indicator of the PHI or Device Information. Lead configuration and battery information will be copied and saved.

If session file contain impedance measurement, that will be extract as well.

Parameters

  • JSON – The raw exported Percept JSON object.

  • sourceData – Processed Percept Data Format (up to current step).

Returns

Processed Percept Data Format.

decoder.Percept.extractTherapySettings(JSON, sourceData={})

Extract Therapy Settings.

Medtronic uses various structure format for different type of stimulation settings, often result in different field pointer for the same type of data. The therapy settings will be extracted and organized in the same format regardless of stimulation type for final database table.

Four main fields are processed here:

  1. Previous Therapy Configuration at the beginning of Session (“Groups”-“Initial”)

  2. Final Therapy Configuration at the beginning of Session (“Groups”-“Final”)

  3. Therapy Configuration History up to 6 sessions before this (“GroupHistory”)

  4. Therapy Change Logs (“DiagnosticData”-“EventLogs”)

Parameters

  • JSON – The raw exported Percept JSON object.

  • sourceData – Processed Percept Data Format (up to current step).

Returns

Processed Percept Data Format.

decoder.Percept.extractTimeDomainStreamingData(JSON, sourceData={})

Extract BrainSense Streaming Time-Domain Data

This is a modified function that handles TimeDomain Data alone without information from PowerDomain Data.

Parameters

  • JSON – The raw exported Percept JSON object.

  • sourceData – Processed Percept Data Format (up to current step).

Returns

Processed Percept Data Format.

decoder.Percept.extractPowerDomainStreamingData(JSON, sourceData={})

Extract BrainSense Streaming Power-Domain Data

This is a modified function that handles Power and Stimulation Data alone without information from TimeDomain Data.

Parameters

  • JSON – The raw exported Percept JSON object.

  • sourceData – Processed Percept Data Format (up to current step).

Returns

Processed Percept Data Format.

decoder.Percept.extractStreamingData(JSON, sourceData={})

Extract BrainSense Streaming during Stimulation.

BrainSense Streaming is data collected during Stimulation Group configuration where you can stream powerband while varying stimulation amplitude. Data collected during this time is split into BrainSenseTimeDomain (250Hz TimeDomain recording) and BrainSenseLfp (Bilateral 5Hz PowerBand streaming).

Although minimum modification will be made during this step, we will still attempt to align bilateral recordings for BrainSenseTimeDomain and BrainSenseLfp for future processing. IMPORTANT: Check source code for a special condition that was seen once in the past where BrainSenseTimeDomain got divided but not BrainSenseLfp.

Parameters

  • JSON – The raw exported Percept JSON object.

  • sourceData – Processed Percept Data Format (up to current step).

Returns

Processed Percept Data Format.

decoder.Percept.extractIndefiniteStreaming(JSON, sourceData={})

Extract Indefinite Streaming during BrainSense Survey.

Indefinite Streaming is data collected during BrainSense Survey where user can stream all 6-channels (Bilateral 0-2, 1-3, 0-3) TimeDomain data nonstop.

Minimum modification will be made during extraction. Missing packages will be handled during “checkMissingPackage()”.

Parameters

  • JSON – The raw exported Percept JSON object.

  • sourceData – Processed Percept Data Format (up to current step).

Returns

Processed Percept Data Format.

decoder.Percept.extractBrainSenseSurvey(JSON, sourceData={})

Extract BrainSense Survey.

BrainSense Survey are short 20-30 seconds recording of all 6 channels (Unilateral 0-1, 0-2, 1-2, 1-3, 2-3, 0-3) TimeDomain data. Segmented recording is also part of BrainSense Survey.

Minimum modification will be made during extraction. Missing packages will NOT be handled as of now.

Parameters

  • JSON – The raw exported Percept JSON object.

  • sourceData – Processed Percept Data Format (up to current step).

Returns

Processed Percept Data Format.

decoder.Percept.extractSignalCalibration(JSON, sourceData={})

Extract BrainSense Calibration.

Calibration data is similar to BrainSense Survey but limited to 3 channels (Unilateral 0-2, 1-3, 0-3). Stimulation will also be turned on (with unknown parameters) to allow computation of Transfer Function for stimulation.

Minimum modification will be made during extraction. Missing packages will NOT be handled as of now.

Parameters

  • JSON – The raw exported Percept JSON object.

  • sourceData – Processed Percept Data Format (up to current step).

Returns

Processed Percept Data Format.

decoder.Percept.extractChronicLFP(JSON, sourceData={})

Extract Chronic BrainSense Power.

Chronic BrainSense Power are collected every 10 minutes if device is setup with BrainSense enabled group. Power values are collected alongside with stimulation amplitude.

Patient Events are processed alongside BrainSense Power because both are stored in DiagnosticData field.

Minimum modification will be made during extraction.

Parameters

  • JSON – The raw exported Percept JSON object.

  • sourceData – Processed Percept Data Format (up to current step).

Returns

Processed Percept Data Format.