nsMCDLibrary
Neuroshare Implementation for MC_Rack Data
Information in this document is subject to change without notice.
No part of this document may be reproduced or transmitted without the express written permission of Multi Channel Systems MCS GmbH.
While every precaution has been taken in the preparation of this document, the publisher and the author assume no responsibility for errors or omissions, or for damages resulting from the use of information contained in this document or from the use of programs and source code that may accompany it. In no event shall the publisher and the author be liable for any loss of profit or any other commercial damage caused or alleged to have been caused directly or indirectly by this document.
© 2013 Multi Channel Systems MCS GmbH. All rights reserved.
Printed: 18. 09. 2013
Multi Channel Systems
MCS GmbH
Aspenhaustraße 21
72770 Reutlingen
Germany
Fon +49-71 21-90 92 5 - 0
Fax +49-71 21-90 92 5 -11 [email protected] www.multichannelsystems.com
Microsoft and Windows are registered trademarks of Microsoft Corporation. Products that are referred to in this document may be either trademarks and/or registered trademarks of their respective holders and should be noted as such. The publisher and the author make no claim to these trademark.
Table of Contents
1 Introduction 7
1.1
About Matlab and Neuroshare
1.2
Installation of Neuroshare Library
7
8
2 Implementation Details 11
2.1
Mapping of Continuous Data
2.2
Mapping of Triggered Data
11
12
2.3
Entities 13
2.3.1
Event Entities 13
2.3.2
Analog Entities
2.3.3
Segment Entities
2.3.4
Neural Event Entities
13
14
14
2.4
Nomenclature for Entities
2.5
Configure Behavior
14
15
2.6
Missing 15
3 MCS Specific Matlab Functions
3.1
mcs_SetLibrary.m: Summary of Functionality
3.2
mcs_Info.m: Summary of Functionality
3.3
mcs_GetEntities.m: Summary of Functionality:
3.4
mcs_Graphic.m: Summary of Functionality
4 Toolboxes that use Neuroshare
16
18
19
20
21
22 v
1 Introduction
1.1 About Matlab and Neuroshare
Matlab is a software package for numerical calculations and for the visualisation of data in the technical and scientific sector. Using Matlab for the analysis of company specific data files, an interface is needed. The Neuroshare Matlab Application Programming Interface (API) is the widely used interface for accessing physiological experiment data files.
The Neuroshare Matlab import functions allow users to easily import neural data files into
Matlab for further analysis. These functions were developed as part of an program funded by the National Institute for Neural Disorders and Stroke and it is currently being administered by Cyberkinetics, Inc. (formerly Bionic Technologies, LLC). The goals of the program are to create open Application Programming Interface (API) library and format standards for neurophysiological experiment data and create a set of free, open-source software tools for low-level handling and processing of neurophysiological data.
To access MC_Rack data files from the Neuroshare API, the data are mapped to the structure dictated by the Neuroshare API. This API is implemented in a Windows DLL (Dynamic Link Library) or Linux or Mac (Intel) shared library by a set of predefined functions.
MC_Rack files recorded with MC_Rack Version 4.4.6 or older are can be read with this version of the library. Up to now, not all possible data streams within a MC_Rack file are available in the Neuroshare API.
The nsMCDLibrary.dll is implemented according to the Neuroshare API Version 1.3.
This paper only discuss the adjustments for data files from Multi Channel Systems MCS GmbH data acquisition software MC_Rack. For the documentation of the Neuroshare API, please see http://neuroshare.sourceforge.net/.
Neuroshare.org is a site created to support the collaborative development of open library and data file format specifications for neurophysiology and distribute open-source data handling software tools for neuroscientists.
7
Matlab and Neuroshare
1.2 Installation of Neuroshare Library
To implement the Neuroshare software you first have to download the Neuroshare library from the MCS web site: http://www.multichannelsystems.com/downloads/software.
Choose the version you need for your computer.
Download the Neuroshare version you need and save the zip file in the respective folder.
Important: Please unpack the nsMCDLibrary_37. “zip” file!
8
Points to Discuss
The next step is most important: Unpack the nsMCDLibrary.zip file, otherwise the included information is not ready for use with Matlab!
All packages contain this documentation and the library for the respective system, example source files to access the Neuroshare library directly from your own program code, the sources for the “mexprog“ library that is needed for the interface to Matlab as well as the Matlab functions.
"mexprog" is the interface between the Neuroshare.dll and Matlab. There are already some compiled versions for different operating systems (OS) included. If there is need “mexprog“ could be compiled from within Matlab for you specific OS.
Operating System Package Name Neuroshare Library
Name
Windows 32 bit / 64 bit
Linux 32 bit
(build with Ubuntu 10.04 LTS) nsMCDLibrary_3.7.zip nsMCDLibrary.dll nsMCDLibrary64.dll nsMCDLibrary_Linux32_3.7.tar.gz nsMCDLibrary.so
Linux 64 bit
(build with Ubuntu 10.04 LTS) nsMCDLibrary_Linux64_3.7.tar.gz nsMCDLibrary.so
Mac OSX (Intel)
32 bit and 64 bit 'fat' binary nsMCDLibrary_MacOSX_3.7.tar.gz nsMCDLibrary.dylib
Just unzip the file anywhere on your computer.
The plain Matlab interface files could be directly used from within our package.
Important: Please set your search path in Matlab to the Matlab_Interface folder.
9
Matlab and Neuroshare
To do so, please start Matlab.
Open menu “File” and choose “Set Path”.
Click the button “Add Folder”.
Browse through the folders an set following path:
C:\Eigene Dateien\Downloads\nsMCDLibrary_3.7\Matlab\Matlab Import Filter\Matlab_Interface
10
Points to Discuss
MC_Rack has two different recording types. Both, continuous and triggered data, can be handled with the Neuroshare library. The mapping is a little bit different for each type, so the mapping is shown for each type separately.
2.1 Mapping of Continuous Data
Electrode Raw Data
Analog Raw Data
Filtered Data
Channel Tool Data
Digital Data elec anlg filt chtl digi
Analog Entity
Analog Entity
Analog Entity
Analog Entity
Analog Entity, each binary digit as Event Entity
Entity Type Number
2
2
2
2
2
1
3
1
Other continuous streams are not mapped up to now.
11
Matlab and Neuroshare
2.2 Mapping of Triggered Data
Electrode Raw Data
Analog Raw Data
Filtered Data
Channel Tool Data
Digital Data elec anlg filt chtl digi
Analog Entity and
Segment Entity
Analog Entity and
Segment Entity
Analog Entity and
Segment Entity
Analog Entity and
Segment Entity
Analog Entity and
Segment Entity, each binary digit as Event Entity
Entity Type Number
2
3
2
3
2
3
2
3
2
3
1
3
1
Please be aware that some streams are mapped to two entities. The contents are essentially the same. Other triggered streams are not mapped up to now.
Missing Streams
All other possible streams, for example average and other parameters, are not implemented up to now in the nsMCSLibrary.dll.
12
Points to Discuss
2.3 Entities
Each of the 16 bits of the digital data channel is represented as one event entity. Each change on the individual digital line results in a new event in the entity with the next index. The event information is in one 8 bit (byte) value. Its value is 1 for a change from 0 to 1 on the digital line and μ1 (255) for a change from 1 to 0 on the digital line.
Triggers are mapped to one event entity for each trigger stream. The event is represented in two 16 bit (word) values. The first one gives the slope of the Trigger, the second the Trigger value.
For manual triggers the second value gives the trigger number. If trial synchronization is used the trigger event contains another two 16 bit values. The 3 rd
one is the trial number and the 4 th
one is the stimulus number.
Raw electrode data, analog data and filtered data are mapped to analog entities. Each channel gives one analog entity in Neuroshare. The different gain is considered. Data is given in Volt of the original input.
The 16 bit of the digital data channel are represented in one analog entity as raw data with a range from 0 to 65535, with minimum step size of one. Each sample value is included in the entity.
For continuous data the first index is starting at time 0. Then all data are following with the next index for the next sample point. The time difference of each index is the reciprocal value of the sample rate.
For triggered data the indices are not always continuous in time. If you are reading many indices at one time, you get, according to the Neuroshare specifications, in pdwContCount the number of samples that are continuous.
Although the samples in an analog entity are indexed, they are not guaranteed to be continuous in time and may contain gaps between some of the indexes. When the requested data is returned, pdwContCount
contains the number of Analog items, starting from dwStartIndex, which do not contain a time gap [NeuroshareAPI-1-3.pdf].
For analog entities there is no timestamp directly included in the API for reading the data.
You get the timestamp with the function ns_GetTimeByIndex.
13
Matlab and Neuroshare
Spike streams are represented in segment entities. Spikes (or wave forms) are sampled independently for each channel. This means there is always only one source per segment entity.
The number of sources is always 1. Each original channel from MC_Rack data forms one entity in Neuroshare. The different gain is considered. Data is given in Volt of the original input.
For triggered data all analog entities are also represented as segment entities. One segment contains the data of one sweep for one channel.
2.3.4 Neural Event Entities
There are no streams in MC_Rack data that are mapped to neural event entities.
Considering the Neuroshare convention for titles of entities, the entities are named as follow:
8 letters: Stream name with:
-
4 letters name
-
4 digits stream number
Space
4 letters: HWID (Hardware ID)
Space
4 digits: Index of channel
Space
8 letters: Name of channel (aligned on the right side)
Event entities of digital data are named as following:
Space
2 digits sub channel for events of digital data
For example:
aaaa0000 0000 0000 xxxxxxxx 00 elec0001 0001 0000 21 digi0001 0063 0001 D1 digi0001 0063 0001 D1 02
14
The behavior of the Dll can be configured by a file in the ini-file format.
All parameters are in the section [Settings].
BaseIsPressedStart configures how times are interpreted.
0: times start at 0 for each file (default and old behavior)
1: times start at the time when the start button is pressed.
Example for the configuration file:
[Settings]
BaseIsPressedStart = 1
Location of the File
Windows: The configuration file is searched in the same directory and with the same name as the Dll has, but with the extension „.ini“ (nsMCDLibrary.ini)
Linux / Apple: Not implemented yet.
Points to Discuss
The function ns_GetLastErrorMsg is not implemented yet.
15
Matlab and Neuroshare
3 MCS Specific Matlab Functions
All functions listed in the following can be executed by mcs_ExampleScript.
mcs_ExampleScript might serve as example and shows how to work with the given functions.
mcs_ExampleScript generates all parameters needed to run and to perform the following
Matlab functions:
-
-
- mcs_Info.m mcs_GetEntities.m mcs_Graphic.m
mcs_ExampleScript uses three predefined Neuroshare functions (“ns_...”) and a modified
Neuroshare function that is described in the next section of the text.
mcs_SetLibrary('nsMCDlibrary.dll') will always be the first step. This function opens a Neuroshare shared Library and loads the appropriate DLL.
ns_GetLibraryInfo obtains information about the library.
ns_OpenFile opens a neural data file, specified by filename or pathway and returns a file called hFile, that contains an identification number. This is important when you want to call the following functions.
ns_GetFileInfo is a function that contains some information about the data file like FileType,
EntityCount, TimeStampResolution, TimeSpan, AppName, Time_Year, Time_Month, Time_Day,
Time_Hour, Time_Min, Time_Sec, Time_MilliSec, FileComment.FileType is given as a sequence of abbreviations.
It is a combination of several properties: Layout, continuous or not, recorded streams.
For example:
FileInfo = FileType: 'MEA cont Di,El,An'
The Channel Type is named according to the title given in MC_Rack (first two letters).
Channel Types of streams which are not mapped up to now can be neglected.
16
Points to Discuss
The table below shows possible designations. They can occur in various combinations.
Example of channel types of MC_Rack
Nomenclature for File Types
Layout
LIN
MEA
DMEA
Recording Mode Channel Type short Form Channel Type long Form
cont trig trig_ss
Conf
Di
El
An
Fi
Sp
Tr
Ch
Digital Data
Electrode Raw Data
Analog Raw Data
Spikes
Trigger
Channel Tool Data
17
Matlab and Neuroshare
mcs_SetLibrary is a further implementation of ns_SetLibrary. mcs_SetLibrary supplements
ns_SetLibrary through an optimized sequence of events if ns_SetLibrary is not able to open the required file. mcs_SetLibrary returns more information in the form of error and status messages and in case of failure, the function parse the Matlab path and tries to open the file using different paths.
Usage:
[ns_RESULT] = mcs_SetLibrary(filename)
Description:
Opens the dynamic linked library specified by filename or in case of failure tries to open it using a different path.
Parameters:
Filename Pointer to a null-terminated string that specifies the name of the file to open.
Return Values:
ns_RESULT This function returns 0 if the file is successfully opened. Otherwise the following error message is generated:'ns_SetLibrary does not find the library:... 'and maybe
'Try to open …' and 'Success' .
18
Points to Discuss
3.2 mcs_Info.m: Summary of Functionality
mcs_Info is a function to show information about the streams that are in a certain file given as stream, type, n, TimeSpan and infotext.
The output contains the stream name as a eight digits sequence, the type of entity, n is the number of channels per stream, TimeSpan gives you information about the duration of data collection and infotext contains optional information about the data type.
mcs_Info uses ns_GetFileInfo to receive the information EntityCount saved in FileInfo.
EntityCount is necessary to call the next function ns_GetEntityInfo and to get EntityLabel and EntityType as a part of entity. EntityLabel includes some information about the stream that is connected to EntityType in a structure entities.
The function returns a table with information if the number of output arguments is 0.
Otherwise the information is given as a matrix. That might be helpful if you like to work on with the given values.
Usage:
[varargout] = mcs_Info(hFile, varargin)
Description:
Generates information about entities. This information is returned in a structured output via CommandWindow (matrix or table).
Parameters:
hFile Handle/Identification number to an open file.
Varargin Variable length input argument list,"variable argument in".
Return Values:
- without return value: information is shown on the display as a table.
- with return value: cell matrix of this information.
19
Matlab and Neuroshare
mcs_GetEntities is a function to generate a vector of entity numbers of entities with a given characteristic.
mcs_GetEntities uses ns_GetFileInfo to produce the structure FileInfo. FileInfo contains information about EntityCount, needed to call ns_GetEntityInfo. ns_GetEntityInfo retrieves general entity information and type of entity saved in the structure EntityInfo that contains
EntityLabel, EntityType and ItemCount.
Usage:
[entities] = mcs_GetEntities (hFile,stream_name, varargin)
Description:
Generates a vector of entity numbers that belongs to the stream with the name stream_name and possible of a certain entity type given in varargin from the data file referenced by hFile.
Parameters:
hFile Handle/Identification number to an open file stream_name for example 'elec0001', 8 letter: stream name with: 4 letters name,
4 digits stream number. varargin Variable length input argument list, "variable argument in" (optional) number of entity type.
Return Values:
entities Array of entity numbers.
20
Points to Discuss
3.4 mcs_Graphic.m: Summary of Functionality
mcs_Graphic plots analog and triggered entities. mcs_Graphic uses ns_GetEntityInfo to get information about the EntityType. With this information, it is possible to switch between analog
(EntityType = 2) and segment (EntityType = 3) data.
In case of analog data, ns_GetAnalogInfo is called to get information about the location locX and locY.
In case of segment data, ns_GetSegmentInfo and ns_GetSegmentSourceInfo are called to get the location of the data as well.
In both cases mcs_Graphic manages x- and y-data shown as a plot.
Depending on chosen call of the function, you can select entities / channels of interest.
Therefore it is possible to pick them out using EntityID .
Usage:
mcs_Graphic(hFile, EntityID, firstItem, ItemCount).
Description:
Generates a graphical output for analog and segment data.
Parameters:
hFile Handle/Identification number to an open file.
EntityID Identification number(s) of the entity in the data file. firstItem Start. itemCount Number of items.
21
Matlab and Neuroshare
4 Toolboxes that use Neuroshare
For advanced users:
The toolboxes FIND (http://find.bccn.uni-freiburg.de/) and sigTOOL (http://sigtool.sourceforge.net/) use Neuroshare to access data.
They already contain the necessary Matlab interface to the Neuroshare Dll. If your FIND or sigTOOL installations have only an older version of the nsMCDLibrary.dll, just replace the nsMCDLibrary.dll with the newer one.
22
