Introduction

The information that follows may be used to query a Ponemah 6.xx Experiment database and to retrieve data from Ponemah 6.xx Waveform files.

A Ponemah 6.xx Experiment consists of a sub-directory that contains a single Experiment database (.PnmExp) and one or more Waveform file (.PnmWav) that are associated with the current Experiment.  The assumption is that we are dealing with a valid Experiment, there is no error checking for an invalid Experiment structure in this example. 

The Matlab .m files are provided as samples for users to incorporate into their solutions as needed.  This solution is being provided outside DSI’s standard Development and Test process.  Please see the Testing section for details about what tests have been executed.

Quick Start

• Follow Installation instructions
• Call GetExperimentInfo(<Experiment Folder>, 1)
  • g. GetExperimentInfo(‘C:\Ponemah_Data\Exp_xxxx’, 1);
  • g. GetExperimentInfo('.\TestData\Exp_1Subj_ECG_BP_Scheduled', 1);
• Identify the Channel Ids of interest in the output generated
• In GetAllData.m modify szExpPath and channelId
• Add signal processing in while loop

Installation

Download the zip file from https://datasci.box.com/s/i0zo9pqn28jre91xtu0uk1vm0kj8h4ji and copy its contents into your Matlab folder. 

32 bit Matlab

Copy the contents of the x32 subdirectory into its parent directory

64 bit Matlab

Copy the contents of the x64 subdirectory into its parent directory

Compatibility

• m requires R2014b or greater: uses datetime which was introduced in R2014b
• R2009a or greater is needed for .NET support

File Descriptions

The following files are available in the folder:

• Binary/Config files

• Matlab Sample files
  Update the “%% User Inputs” section as needed

• Matlab Functions

• Test files

Retrieving data

Identify Channel Ids

• Each channel in an Experiment has a unique Channel Id. The data associated with a channel is retrieved by using this Channel Id
• The Channel Ids associated with a subject can be determined by using GetExperimentInfo()
• GetExperimentInfo(szExpPath, fileId)
  • szExpPath                   Experiment Folder
    fileId                           return from fopen() or 1 for output to the screen
    E.g. GetExperimentInfo('C:\Ponemah_Data\Exp_1Subj_ECG_BP_Scheduled', 1)
  • For each Subject in the Experiment, the following information is displayed:
    • Start Time: Local time of the first sample in the first channel
    • End Time: Local time of the last sample in the first channel
    • Num Segments: Number of contiguous sets of data in the Subject’s first channel
    • Channel Id and Channel Label for each channel in the Subject
  • Record the Channel Id of interest

Determine Sample Times

• Times stored in the waveform file are in UTC.
• The timezone in which the acquisition occurred is saved in the Experiment database.
• When accessing a user defined range of samples, GetTimeSegmentsLocal() may be used to retrieve the available time ranges for a channel. See a usage example in PrintAllTimeSegments.m
• Typically all channels in the subject share the same time ranges, this may not be the case if a channel was deleted or added between acquisitions
• Often all subjects will share the same time ranges as well, this may not be the case if a subject was added or deleted.

Requesting Samples

Samples are retrieved by calling GetPnmWaveformData_Setup() followed by one or more calls to GetPnmWaveformDataUtc().  The calls have been split up for speed, permitting setup information to be retrieved once and faster processing when calling GetPnmWaveformDataUtc()

Request All Samples

• See GetAllData.m
• Adjust numSamplesRequested based on memory availability

Request Specific Samples

• Determine the Local start time and the number of samples you wish to retrieve
• See Display1000Samples.m for an example

Functions

GetExperimentInfo()

Retrieves information about the Experiment from the Experiment database.

Inputs

• szExpPath                      Experiment folder
• fileId                              value from fopen() to write output to file
                                        use 1 to display output on the screen

GetPnmWaveformData_Setup()

First of a pair of functions used to retrieve data, this is followed by one or more calls to GetPnmWaveformDataUtc()

Inputs

• szExpPath Experiment folder
• channelId Channel Id from which samples are being requested. 
• numSamplesRequested Number of samples requested

Outputs

• reader                   WaveformDatasetReader object
• timezone                Experiment timezone
• segStartTimesUtc         Channel segment start times in UTC
• segEndTimesUtc         Channel segment end times in UTC
• sampleRate              Channel samples rate
• sampleBuffer             Buffer allocated to retrieve samples

GetPnmWaveformDataUtc()

Retrieves sample data from an Experiment waveform file.  This is the second of a pair of functions used to retrieve data, one or more of these calls is preceded by a call to GetPnmWaveformData_Setup()

Inputs

• reader                   WaveformDatasetReader object
• channelId              Channel Id from which samples are being requested. 
• startTimeUtc             UTC time of first requested sample
• numSamplesRequested Number of samples requested
• sampleBuffer             Buffer in which samples are stored
• sampleRate                         Channel sample rate
• segStartTimesUtc         Channel UTC segment start times
• segEndTimesUtc         Channel UTC segment end times

Outputs

• actualStartTimeUtc        UTC time of the first sample returned in sampleBuffer
• samplesReturned        Number of samples returned in sampleBuffer

GetTimeSegmentsLocal()

Retrieves all segment times in Local (Experiment) time

Inputs

• szExpPath                Experiment folder
• channelId                Channel Id from which samples are being requested

 Outputs

• segStartTimesLocal         Local segment start times (acq timezone)
• segEndTimesLocal         Local segment end times (acq timezone)

GetTimeSegmentsUtc()

Retrieves all segment times in UTC time

Inputs

• szExpPath                Experiment folder
• channelId                Channel Id from which samples are being requested

 Outputs

• segStartTimesUtc            UTC segment start times
• segEndTimesUtc            UTC segment end times

Testing

• Tested with R2015b
• The sample code has been tested with the 3 Experiments that are included in the TestData folder
• The expected results used in TestExperimentInfo.m were verified by viewing the Experiments in Ponemah 6.1.

The expected results used in TestSamples.m were generated by using an ASCII output feature in Ponemah 6.1 (BP channels) or from Dataquest ART (ECG, EMG, EEG channels) Ponemah 6.1 was not used for these channels due to a limitation in the ASCII output fo