-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathNlx2MatCSC_v3_help.m
183 lines (183 loc) · 8.87 KB
/
Nlx2MatCSC_v3_help.m
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
% Help for file Nlx2MatCSC_v3.dll
%
% Purpsose
% The purpose of this program is to extract Neuralynx data from a file and load it into the matlab environment with any combination of fields
% from the file within a time or record range or using a time or record list.
%
% Composition
% This program is a matlab mex file compilation of matlab and C++ source code.
% C++ source code is used to read in data from a file and then input the
% data into the matlab enviroment in the form of matlab arrays or matrices.
%
% Note: All Timestamps are in microseconds.
%
% NumFields = 5;
% Field List
% 1. Timestamps
% 2. Channel Numbers
% 3. Sample Frequency
% 4. Number of Valid Samples
% 5. Samples
%
% NumModes = 5;
% Extraction Modes
% 1. Extract All - This will extract every record from the file into the matlab environment;
% 2. Extract Record Index Range = This will extract every Record whos index is within a range specified by Paramter 5.
% 3. Extract Record Index List = This will extract every Record whos index in the file is the same index that is specified by Paramter 5.
% 4. Extract Timestamp Range = This will extract every Record whos timestamp is within a range specified by Paramter 5.
% 5. Extract Timestamp List = This will extract every Record with the same timestamp that is specified by Paramter 5.
%
% Input Parameters
%
% Parameter1 - Input File Name and Path
% Requirements
% 1. The file must be a Neuralynx CSC(Continuously Sampled Channel) data file.
% 2. The filename must be a string and a row vector.
% Example:
% Filename = 'C:\TestDirector\TestFile.ncs'
%
% Parameter2 - Field Selection Array - This denotes which fields to extract into matlab, any combination is possible.
% Requirements
% 1. The Array must contain only 1's and 0's. A 1 will extract the field, a 0 will not extract the field.
% 2. The Array must be of size NumFields.
% Example: We want to extract fields for Timestamps and Samples Only.
% FieldSelection(1) = 1;
% FieldSelection(2) = 0;
% FieldSelection(3) = 0;
% FieldSelection(4) = 0;
% FieldSelection(5) = 1;
%
% Parameter3 - Extract Header Value - This value indicates whether to extract the header from the file into the matlab environment (if one exists).
% Requirements
% 1. The value must be a 1 or a 0. A 1 will extract the header, a 0 will not extract the header.
% Example: We want to extract the header.
% ExtractHeader = 1;
%
% Parameter4 - Extraction Mode - This value indicates what records to extract from the file. See Extract Modes Above for Description.
% Requirements
% 1. The value must be in the range 1..NumModes.
% Example: We want to extract all the records from the file into matlab.
% ExtractMode = 1;
%
% Parameter5 - Extraction Mode Array - This array indicates what records to extract from the file. Each Selection requires a different array. They are as follows:
% 1. Extract All - This mode does not require an Array, this parameter should be left blank.
% 2. Extract Record Index Range.
% Requirements
% 1. The Array must have 2 elements only.
% 2. The 2 elements must be in increasing order.
% Example: We wish to extract the first 10 records from the file.
% ModeArray(1) = 0;
% ModeArray(2) = 9;
% 3. Extract Record Index List.
% Requirements
% 1. The Array may have any number of elements( its recommended that the size does not exceed the number of records in the file ).
% 2. The elements must be in increasing order.
% Example: We wish to extract the 1st, 5th and 10th record from the file.
% ModeArray(1) = 0;
% ModeArray(2) = 4;
% ModeArray(3) = 9;
% 4. Extract Timestamp Range.
% Requirements
% 1. The Array must have 2 elements only.
% 2. The 2 elements must be in increasing order.
% Example: We wish to extract records with time range 10000000 to 20000000.
% ModeArray(1) = 10000000;
% ModeArray(2) = 20000000;
% 5. Extract Timestamp List.
% Requirements
% 1. The Array may have any number of elements( its recommended that the size does not exceed the number of records in the file ).
% 2. The elements must be in increasing order.
% Example: We wish to extract records with the timestamps 10000000, 15000000 and 20000000
% ModeArray(1) = 10000000;
% ModeArray(2) = 15000000;
% ModeArray(3) = 20000000;
%
%
% Output Parameters
%
% The 6 variables Nlx2MatCSC_v3.dll outputs are as follows:
% TimeStamps, ChannelNumbers, SampleFrequencies, NumberValidSamples, Samples and NlxHeader in that order.
% TimeStamps, ChannelNumbers, SampleFrequencies and NumberValidSamples are one dimensional matrices,
% while Samples is a 2 Dimensional matrix.
% NlxHeader is a one dimensional cell array, while all others are numeric.
% For multidimensional matrices, data is output in vertical form for each element.
%
% Note: NlxHeaders are Neuralynx Headers generated by Neuralynx Software, however they may not always be present in a Neuralynx file.
% If a NlxHeader is not found an empty cell matrix is returned.
%
%
% The number of output parameters depends on the number of fields selected to extract from the file plus the extraction of the header(if selected).
%
% Field and Header Variables - The number of field variables must exactly match the number of fields chosen from parameter 2.
%
% Example: If we continue with the example from Parameter2 and we know that we want the Timestamp and Samples fields extracted, the output will be as follows:
%
% [TimestampVariable, SamplesVariable, HeaderVariable] = Function( Filename, FieldSelection, ExtractHeader, ExtractMode );
%
% Example: We want to extract all fields, no header and use record list extraction mode.
%
% FieldSelection(1) = 1;
% FieldSelection(2) = 1;
% FieldSelection(3) = 1;
% FieldSelection(4) = 1;
% FieldSelection(5) = 1;
%
% ExtractHeader = 0;
%
% ExtractMode = 3;
%
% ModeArray(1) = 0;
% ModeArray(2) = 4;
% ModeArray(3) = 9;
%
% [Timestamp, ChanNum, SampleFrequency, NumValSamples, Samples] = Function( Filename, FieldSelection, ExtractHeader, ExtractMode, ModeArray );
%
%
% Matlab Tips
%
% Some helpful matlab usage tips and commands( commands will be written inside single quotes ' ':
%
% 'whos' - This command will list all current matlab variables, their dimensions and byte sizes. For Example:
%
% >> whos
% Name Size Bytes Class
%
% ChannelNumbers 1x101 808 double array
% NlxHeader 17x1 2366 cell array
% NumberValidSamples 1x101 808 double array
% SampleFrequencies 1x101 808 double array
% Samples 512x101 413696 double array
% TimeStamps 1x101 808 double array
% ans 1x1 8 double array
%
% Grand total is 52535 elements using 419302 bytes
%
%
% Indexing Matrices - Using the colon(:) operator.
% The colon operator can be used to access all data in a specified dimension. For Example:
% If you wanted to access all 512 Samples from the above display for record 50. The following
% syntax would be required.
%
% >> Samples( :,50 );
%
% This will list all 512 values for record number 50 vertically.
%
% Formating numeric data display.
% When timestamps become large matlab defaults to a scientific notation of numeric values.
% In order to view the complete values use the following command: 'format long g' For Example:
%
% >> TimeStamps(2)
%
% ans =
%
% 1.0000e+013
%
% >> format long g
% >> TimeStamps(2)
%
% ans =
%
% 10000000000000
%
% >>
%