ns_converter Manual Ver /03/22

Transcription

1 ns_converter Manual Ver /03/22

2 Introduction Copyright Applicable format list Restricted to 32-bit Windows How to convert Preparation Conversion File formats Format of MAT-file Format of CSV-file Format of XLS-file History Contact 2

3 Introduction This is the ns_converter manual. ns_converter converts neurophysiological data into the Neuroshare format ( 1) with ns_createfile class library ( 2). ns_converter can only be applied to a finite set of file formats ( 3). (EEGLAB( 4) is needed for some file format conversion.) ns_converter is a set of Matlab functions. ns_converter is OS-independent, except some functions ( 5). ns_converter was tested on Matlab R2010a, using Windows 7 Professional. 1 Neuroshare format : The file format defined by the project to create a standard format for neurophysiological data. Please see for more detail. 2 ns_createfile class library : The library (a set of Matlab functions) to make a Neuroshare format file. You can download it from 3 Applicable formats : Please see Applicable format list. 4 EEGLAB: The Matlab toolbox for processing electrophysiological data. 5 OS dependent functions : Some functions can run on only 32-bit Windows. Please see Restriced to 32-bit Windows for more detail. 3

4 Copyright ns_converter is free but copyright software, distributed under the terms of the GNU General Public License as published by the Free Software Foundation. Further details on copyleft can be found at No formal support or maintenance is provided or implied. 4

5 Applicable format list ns_converter can convert the following file formats. ext. description note.bdf BioSemi file Need EEGLAB.cnt Neuroscan file Need EEGLAB.csv CSV (Comma Separated Values) There s a rule of format of file. Please see Format of CSV-file..edf European data format Need EEGLAB.map Alpha Omega file Restricted to 32-bit Windows.mat Matlab MAT file There s a rule of name of variables. Please see Format of MAT-file..mcd Multi Channel Systems file Restricted to 32-bit Windows.nev Brackrock Microsystems file Restricted to 32-bit Windows.nex Nex Technologies (Neuroexplorer) file Restricted to 32-bit Windows.ns* Brackrock Microsystems file Restricted to 32-bit Windows.plx Plexon file Restricted to 32-bit Windows.rdf ERPSS (Event-Related Potential Software System) file Need EEGLAB.sma Snap-Master file Need EEGLAB.vhdr Brainvision file Need EEGLAB.xls Microsoft Excel file There s a rule of format of file. Please see Format of XLS-file. 5

6 Restricted to 32-bit Windows ns_converter uses DLLs that are available on the web page of Neuroshare Project ( to read some of the file formats. These DLLs can only run on 32-bit Windows, so the functions to convert the files that need the DLLs can only run on 32-bit Windows. The following formats require the 32-bit Windows DLLs: ext..map.mcd.nev.nex.ns*.plx description Alpha Omega file Multi Channel Systems file Brackrock Microsystems file Nex Technologies file Brackrock Microsystems file Plexon file 6

7 How to convert The following outlines the steps to convert neurophysiological data files into the Neuroshare file format using ns_converter. Preparation ns_converter needs ns_createfile class library. If you haven t gotten it yet, please download it from and configure it according to the readme.txt attached with the distribution. Some types of file formats require a 32-bit Windows machine. Please see Restricted to 32-bit Windows. Some types of file formats require EEGLAB. Please see Applicable format list, and obtain it from Please add the directory containing the unzipped ns_converter_[ver].zip to the Matlab path. 7

8 Conversion 1. Enter > ns_converter in the Matlab command window and run it. 2. Select the source file from the dialog that you want to convert into the Neuroshare format. 3. A Neuroshare file that has the same file name as the source file only with a.nsn extension added to it, will be created in the same directory as the source file. 8

9 If the directory for ns_createfile class library hasn t been added to the Matlab path, a dialog will appear to ask you for the location. Please select the directory for ns_createfile that was created in the Preparation step. If the directory for EEGLAB hasn t been added to the Matlab path and it is needed to convert your file, a dialog will appear to ask you for the location. Please select the directory for EEGLAB that was created in the Preparation step. 9

10 You can specify a source file name and an output file name as arguments to ns_converter. > ns_converter([source_file], [output_file]) In this case, the dialog to select a source file doesn t appear. 10

11 File formats ns_converter can convert the following information into a Neuroshare file. information Date of experiment Experiment title Experiment description Data Sampling rate Channel name Channel description format String (yyyy/mm/dd HH:MM:SS) String (less than 32 letters) String (less than 256 letters) later Real number (in Hz) NaN, in case of timestamp data String (less than 32 letters per channel) String (less than 128 letters per channel) The following types of data can be converted by ns_converter. type description format Time-series data Analog data obtained at a constant sampling rate Real number (measured value) Timestamp data Time information Real number (elapsed time from the start time in secs) Time: Real number Event data Information about events (elapsed time from the start time in secs) at a specific time Event: Whole number of String (don t be allowed to mix within a channel) Analog data with ID, Data: Real number (measured value) Time-series data recorded at the sampling with ID ID: Whole number rate Some formats specify how information should be structured. Please follow the formatting rules for applicable file types. 11

12 Format of Mat file MAT-file has to include the information contained in the following variables. Name Description Format chdata Neurophysiological data channels [1 1] matrix of chdata cells Please see: chdata definition chheader Header information for data channels [1 1] matrix of chheader structures Please see: chheader definition fileinfo File information [1 1] fileinfo structure Please see: fileinfo definition Structure Formats Format of the chdata structure The chdata structure is a [1 1] matrix of data cells, with the format of the cells depending on the type of channel, as explained below. Field Name Description Format ch1 channel 1 data [1 1] structure of one of the types explained below : chn channel n data [1 1] structure of one of the types explained below As with the chheader structure, the type and number of fields for each data cell depends on the type of channel (neurosharetype; e.g., event, analog, etc ). Event channel type(event data): Event Entity [Case : neurosharetype : 1] Field Name Description Format timestamp number of seconds from start time [1 n] numeric values defined in the fileinfo structure value value [1 n] char array or numeric value 12

13 Analog channel type(timeseries data): Analog channels represent time-series data. If the time-series data has gaps along the time-axis, m in the starttime and value matrices will be greater than other, otherwise m=1. Analog Entity [Case : neurosharetype : 2] Field Name Description Format starttime Starting time (seconds relative to [m 1] numeric value starting time in fileinfo) value value [m n] numeric value Segment channel type(timeseries data with ID): If the time-series data has gaps along the time-axis, m in the starttime, unitid, and value matrices will be greater than other, otherwise m=1. Segment Entity [Case : neurosharetype : 3] Field Name Description Format starttime Starting timestamp (seconds relative to starting [m 1] numeric value time in fileinfo) unitid unit identification [m 1] numeric value value value [m n] numeric value Neural Event channel type(timestamp data): Neural Event Entity [Case : neurosharetype : 4] Field Name Description Format timestamp Timestamp (seconds relative to starting time in fileinfo) [1 n] numeric value 13

14 Format of the chheader structure The chheader structure is a [1 1] matrix of data cells, with the format of the cells depending on the type of channel, as explained below. Field Name Description Format ch1 channel 1 header [1 1] structure of one of the types explained below : chn channel n header [1 1] structure of one of the types explained below As with the chdata structure, the type and number of fields for each data cell depends on the type of channel (neurosharetype; e.g., event, analog, etc ). Event channel type(event data): Event Entity [Case : neurosharetype : 1] Field Name Description Format chtype Channel type [1 n] char array comment Free-text comments [1 n] char array title Channel title [1 n] char array neurosharetype Numeric type of neuroshare entity (1) [1 1] numeric value description Channel description [1 n] char array Analog channel type(timeseries data) Analog Entity [Case : neurosharetype : 2] Field Name Description Format chtype channel type [1 n] char array comment Free-text comments [1 n] char array title channel title [1 n] char array neurosharetype Numeric type of neuroshare entity (2) [1 1] numeric value 14

15 description Channel description [1 n] char array samplingrate Sampling rate [Hz] [1 1] numeric value unitofdata Data units [1 n] char array locationx X coordinate of source in meters [1 1] numeric value locationy Y coordinate of source in meters [1 1] numeric value locationz Z coordinate of source in meters [1 1] numeric value locationuserdef Manufacturer-specific position [1 1] numeric value information (e.g., electrode number in a tetrode) highfreqcutoff High frequency cutoff in Hz [1 1] numeric value highfreqcutofforder Order of the filter used for high [1 1] numeric value frequency cutoff highfreqcutofffiltertype Type of filter used for high frequency [1 n] char array cutoff lowfreqcutoff Low frequency cutoff in Hz [1 1] numeric value lowfreqcutofforder Order of the low frequency cutoff filter [1 1] numeric value lowfreqcutofffiltertype Type of filter used for low frequency cutoff [1 n] char array Segment channel type(timeseries data with ID): Segment Entity [Case : neurosharetype : 3] Field Name Description Format chtype channel type [1 n] char array comment Free text comments [1 n] char array title Channel title [1 n] char array neurosharetype Numeric type of neuroshare [1 1] numeric value entity (3) unitofdata Data units [1 n] char array samplingrate Sampling rate [Hz] [1 1] numeric value headerbysource Header for segment sources, as defined in the following structure [1 1] structure source 1 locationx X coordinate of source in meters [1 1] numeric value : locationy Y coordinate of source in meters [1 1] numeric value source m locationz Z coordinate of source in meters [1 1] numeric value 15

16 locationuserdef Manufacturer-specific position [1 1] numeric value information (e.g., number in a tetrode) highfreqcutoff High frequency cutoff in Hz [1 1] numeric value highfreqcutofforder Order of the filter used for high [1 1] numeric value frequency cutoff highfreqcutofffiltertype Type of filter used for high [1 n] char array frequency cutoff lowfreqcutoff Low frequency cutoff in Hz [1 1] numeric value lowfreqcutofforder Order of the filter used for low [1 1] numeric value frequency cutoff lowfreqcutofffiltertype Type of filter used for low [1 n] char array frequency cutoff description Source description [1 n] char array Neural Event channel type(timestamp data): Neural Event Entity [Case : neurosharetype : 4] Field Name Description Format chtype Channel type [1 n] char array comment Free-text comments [1 n] char array title Channel title [1 n] char array neurosharetype Numeric type of neuroshare entity (4) [1 1] numeric value description Channel description [1 n] char array sourceid Source ID [1 1] numeric value unitid Unit ID [1 1] numeric value 16

17 Format of fileinfo structure The fileinfo structure is a [1 1] matrix of data cells, with the format of the cells depending on the type of channel, as explained below. Field Name Description Format date time of experiment yyyy/mm/dd HH:MM:SS title experiment title [1 n] char array description experiment description [1 n] char array 17

18 Format of CSV-file CSV-file has to keep the following format. 1: Date of experiment 2: Experiment title, Experiment description 3: Channel name (ch1), Channel name (ch2), 4: Channel desc. (ch1), Channel desc. (ch2), 5: Sampling rate (ch1), Sampling rate (ch2), 6: Data (ch1, sample1), Data (ch2, sample1), 7: Data (ch1, sample2), Data (ch2, sample2), : : : In the case of Event data (a set of Elapsed Times and Events) and Time-series data with ID (a set of Measured Values and IDs), you should add a marker ( # for Event data, % for Time-series data with ID) to the channel name in order to specify that this column is not a different channel, but the same channel as the former column. Event data : 3: Ch name (ch1), #Ch name (ch1), Ch name (ch2) : 6: Elapsed Time, Event, Data (ch2, sample1), : : : : Time-series data with ID : 3: Ch name (ch1), %Ch name (ch1), Ch name (ch2) : 6: Measured Value, ID, Data (ch2, sample1), : : : 18

19 Specify NaN for points that have no data Sample files are in the SampleData directory (CSV_sample_***.csv) 19

20 Format of XLS-file XLS-files have to be in the following format. The order and the location of data in the XLS-file is not fixed, since you specify where information is placed when the XLS-file is converted. information format Date of experiment Single cell, [1 x 1] Experiment title Single cell, [1 x 1] Experiment description Single cell, [1 x 1] Data Array of cells, [# of sample x # of channel] Sampling rate Array of cells, [1 x # of channel] Channel name Array of cells, [1 x # of channel] Channel description Array of cells, [1 x # of channel] In case of Event data (a set of Elapsed Times and Events) and Time-series data with ID (a set of Measured Values and IDs), you should add a marker ( # for Event data, % for Time-series data with ID) to channel name in order to specify that this column is not a different channel, but the same channel as the former column. Please refer to Format of CSV-file for examples. Specify NaN for points that have no data Sample files are in the SampleData directory (XLS_sample_***.xls) 20

21 History Ver /03/22 Changed Mat file format. Ver /04/04 Fixed bug. Change Contact info. Ver /08/24 Can convert by using EEGLAB Ver /07/01 21

22 Contact Brainliner Developer Team ATR Intl. Computational Neuroscience Labs 22