Multichannel Systems MATLAB User Manual

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 [phone] - 0

Fax [phone]

[e-mail]

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 7

1.2 Installation of Neuroshare Library 8

2 Implementation Details 11

2.1 Mapping of Continuous Data 11

2.2 Mapping of Triggered Data 12

2.3 Entities 13

2.3.1 Event Entities 13

2.3.2 Analog Entities 13

2.3.3 Segment Entities 14

2.3.4 Neural Event Entities 14

2.4 Nomenclature for Entities 14

2.5 Configure Behavior 15

2.6 Missing 15

3 MCS Specific Matlab Functions 16

3.1 mcs_SetLibrary.m: Summary of Functionality 18

3.2 mcs_Info.m: Summary of Functionality 19

3.3 mcs_GetEntities.m: Summary of Functionality: 20

3.4 mcs_Graphic.m: Summary of Functionality 21

4 Toolboxes that use Neuroshare 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 nsMCDLibrary_3.7.zip nsMCDLibrary.dll

nsMCDLibrary64.dll

Linux 32 bit

nsMCDLibrary_Linux32_3.7.tar.gz nsMCDLibrary.so

(build with Ubuntu 10.04 LTS)

Linux 64 bit

nsMCDLibrary_Linux64_3.7.tar.gz nsMCDLibrary.so

(build with Ubuntu 10.04 LTS)

Mac OSX (Intel)

nsMCDLibrary_MacOSX_3.7.tar.gz nsMCDLibrary.dylib

32 bit and 64 bit 'fat' binary

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

2 Implementation Details

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

Stream Short Name Entity Type Entity Type Number

Electrode Raw Data elec Analog Entity 2

Analog Raw Data anlg Analog Entity 2

Filtered Data filt Analog Entity 2

Channel Tool Data chtl Analog Entity 2

Points to Discuss

Digital Data digi Analog Entity,

each binary digit as Event Entity

Spikes spks Segment Entity 3

Trigger trig Event Entity 1

Other continuous streams are not mapped up to now.

2
1

11

Matlab and Neuroshare

2.2 Mapping of Triggered Data

Stream Short Name Entity and Segment Type Entity Type Number

Analog Entity and

Electrode Raw Data elec

Analog Raw Data anlg

Filtered Data filt

Channel Tool Data chtl

Digital Data digi

Spikes spks Segment Entity 3

Trigger trig Event Entity 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.

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

2
3

2
3

2
3

2
3

2
3
1

Missing Streams

All other possible streams, for example average and other parameters, are not implemented
up to now in the nsMCSLibrary.dll.

12

2.3 Entities

2.3.1 Event 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
is the stimulus number.

2.3.2 Analog Entities

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.

Points to Discuss

rd

one is the trial number and the 4th one

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

2.3.3 Segment Entities

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.

2.4 Nomenclature for 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

2.5 Configure Behavior

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.

2.6 Missing Functions

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 Recording Mode Channel Type short Form Channel Type long Form

LIN cont Di Digital Data

MEA trig El Electrode Raw Data

DMEA trig_ss An Analog Raw Data

Conf Fi Filtered Data

Sp Spikes

Tr Trigger

Ch Channel Tool Data

17

Matlab and Neuroshare

3.1 mcs_SetLibrary.m: Summary of Functionality

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

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:

Points to Discuss

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

3.3 mcs_GetEntities.m: Summary of Functionality:

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

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:

Points to Discuss

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