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.
SessionEndDate Field
FirstPacketDateTime for BrainSense Data or BrainSense Surveys.
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:
Calculate time (millisecond) difference between each packet using “Ticks” field in JSON object.
Calculate the median time elapsed, and any packets above the median time is considered as skipped packets.
Calculate average packet size (data come in packet of 62 or 63, 4 packets per second).
Calculate number of missing packets (total skip time / median packet time)
Calculate insertion index based on cumulative sum packet length
Insert 0s to Time-Domain data, Label [“Missing”] field to 1s.
Repeat above until all missing packets are accounted for.
Power Band Streaming Implementation:
Calculate time (millisecond) difference between each packet using “Ticks” field in JSON object.
Calculate the median time elapsed, and any packets above the median time is considered as skipped packets.
If missing packets exist, create a template power band timestamp array using
numpy.arange
.Take in existing power band timestamp and power values and perform linear interpolation.
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:
extractPatientInformation
extractTherapySettings
extractStreamingData,
extractIndefiniteStreaming,
extractBrainSenseSurvey
extractSignalCalibration,
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:
Previous Therapy Configuration at the beginning of Session (“Groups”-“Initial”)
Final Therapy Configuration at the beginning of Session (“Groups”-“Final”)
Therapy Configuration History up to 6 sessions before this (“GroupHistory”)
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.