Skip to content

Commit 38369e3

Browse files
mpsonntagmpsonntag
committed
[Matlab] Add basic nix.DataArray documentation
1 parent c8ab8b0 commit 38369e3

File tree

2 files changed

+189
-29
lines changed

2 files changed

+189
-29
lines changed

‎+nix/DataArray.m‎

Lines changed: 177 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,57 @@
1+
% nix.DataArray class that can store arbitrary n-dimensional data
2+
% along with further information.
3+
%
4+
% The DataArray is the core entity of the NIX data model, its purpose is to store
5+
% arbitrary n-dimensional data. In addition to the common fields id, name, type,
6+
% and definition the DataArray stores sufficient information to understand the
7+
% physical nature of the stored data.
8+
%
9+
% A guiding principle of the data model is to provide enough information to create a
10+
% plot of the stored data. In order to do so, the DataArray defines a property dataType
11+
% which provides the physical type of the stored data (for example 16 bit integer or
12+
% double precision IEEE floatingpoint number). The property unit specifies the SI unit
13+
% of the values stored in the DataArray whereas the label defines what is given in this
14+
% units. Together, both specify what corresponds to the the y-axis of a plot.
15+
%
16+
% In some cases it is much more efficient or convenient to store data not as floating
17+
% point numbers but rather as (16 bit) integer values as, for example, read from a data
18+
% acquisition board. In order to convert such data to the correct values, we follow the
19+
% approach taken by the comedi data-acquisition library (http://www.comedi.org) and
20+
% provide polynomCoefficients and an expansionOrigin.
21+
%
22+
% A DataArray can only be created from a Block entity. Do not use the
23+
% DataArray constructor.
24+
%
25+
% DataArray supports only the storage of numeric and logical data.
26+
%
27+
% nix.DataArray dynamic properties:
28+
% id (char): read-only, automatically created id of the entity.
29+
% name (char): read-only, name of the entity.
30+
% type (char): read-write, type can be used to give semantic meaning to an
31+
% entity and expose it to search methods in a broader context.
32+
% definition (char): read-write, optional description of the entity.
33+
% label (char): read-write, optional label of the raw data for plotting.
34+
% unit (char): read-write, optional unit of the raw data.
35+
% Supports only SI units.
36+
% expansionOrigin (double): read-write, the expansion origin of the
37+
% calibration polynom. 0.0 by default.
38+
% polynomCoefficients (double): read-write, The polynom coefficients for the
39+
% calibration. By default this is set to a
40+
% {0.0, 1.0} for a linear calibration with zero offset.
41+
% dataExtent ([double]): read-write, the size of the raw data.
42+
% The size of a DataArray can be changed with this
43+
% property, but only within the original dimensionality,
44+
% e.g. a 2D array must always remain a 2D array, but
45+
% can be modified in either of the two dimensions.
46+
%
47+
% nix.DataArray dynamic child entity properties:
48+
% dimensions access to all dimensions associated with a DataArray.
49+
% sources access to all first level nix.Source child entities.
50+
% sections access to all first level nix.Section child entities.
51+
%
52+
% See also nix.Source, nix.Section.
53+
%
54+
%
155
% Copyright (c) 2016, German Neuroinformatics Node (G-Node)
256
%
357
% All rights reserved.
@@ -7,15 +61,13 @@
761
% LICENSE file in the root of the Project.
862

963
classdef DataArray < nix.NamedEntity & nix.MetadataMixIn & nix.SourcesMixIn
10-
%DataArray nix DataArray object
1164

1265
properties (Hidden)
13-
% namespace reference for nix-mx functions
14-
alias = 'DataArray'
66+
alias = 'DataArray' % nix-mx namespace to access DataArray specific nix backend functions.
1567
end
1668

1769
properties (Dependent)
18-
dimensions % should not be dynamic due to complex set operation
70+
dimensions % should not be dynamic due to complex set operation.
1971
end
2072

2173
methods
@@ -37,6 +89,14 @@
3789
% -----------------
3890

3991
function dimensions = get.dimensions(obj)
92+
% Get all Dimensions associated with this DataArray.
93+
%
94+
% Returns: ([nix.Dimension]) A list of all associated Dimensions.
95+
%
96+
% Example: dims = currDataArray.dimensions;
97+
%
98+
% See also nix.RangeDimension, nix.SampledDimension, nix.SetDimension.
99+
40100
dimensions = {};
41101
fname = strcat(obj.alias, '::dimensions');
42102
currList = nix_mx(fname, obj.nixhandle);
@@ -58,32 +118,93 @@
58118
end
59119

60120
function r = appendSetDimension(obj)
121+
% Append a new SetDimension as last entry to the list of existing
122+
% dimension descriptors of the invoking DataArray.
123+
%
124+
% Used to provide labels for dimensionless data e.g. when stacking
125+
% different signals. In the example the first dimension would
126+
% describe the measured unit, the section dimension the time,
127+
% the third dimension would provide labels for three different
128+
% signals measured within the same experiment and packed into
129+
% the same 3D DataArray.
130+
%
131+
% Returns: (nix.SetDimension) The newly created SetDimension.
132+
%
133+
% Example: dim = currDataArray.appendSetDimension();
134+
%
135+
% See also nix.SetDimension.
136+
61137
fname = strcat(obj.alias, '::appendSetDimension');
62138
h = nix_mx(fname, obj.nixhandle);
63139
r = nix.Utils.createEntity(h, @nix.SetDimension);
64140
end
65141

66142
function r = appendSampledDimension(obj, interval)
143+
% Append a new SampledDimension as last entry to the list of
144+
% existing dimension descriptors of the invoking DataArray.
145+
%
146+
% Used to describe the regularly sampled dimension of data.
147+
%
148+
% interval (double): The sampling interval of the Dimension to create.
149+
%
150+
% Returns: (nix.SampledDimension) The newly created SampledDimension.
151+
%
152+
% Example: stepSize = 5;
153+
% dim = currDataArray.appendSampledDimension(stepSize);
154+
%
155+
% See also nix.SampledDimension.
156+
67157
fname = strcat(obj.alias, '::appendSampledDimension');
68158
h = nix_mx(fname, obj.nixhandle, interval);
69159
r = nix.Utils.createEntity(h, @nix.SampledDimension);
70160
end
71161

72162
function r = appendRangeDimension(obj, ticks)
163+
% Append a new SampledDimension as last entry to the list of
164+
% existing dimension descriptors of the invoking DataArray.
165+
%
166+
% Used to describe the irregularly sampled dimension of data.
167+
%
168+
% ticks ([double]): The ticks of the RangeDimension.
169+
%
170+
% Returns: (nix.RangeDimension) The newly created RangeDimension.
171+
%
172+
% Example: dim = currDataArray.appendRangeDimension([1 10 21 15]);
173+
%
174+
% See also nix.SampledDimension.
175+
73176
fname = strcat(obj.alias, '::appendRangeDimension');
74177
h = nix_mx(fname, obj.nixhandle, ticks);
75178
r = nix.Utils.createEntity(h, @nix.RangeDimension);
76179
end
77180

78181
function r = appendAliasRangeDimension(obj)
182+
% Append a new RangeDimension that uses the data stored in the invoking
183+
% DataArray as ticks.
184+
% This works only(!) if the DataArray is 1D and the stored data is numeric.
185+
%
186+
% Returns: (nix.RangeDimension) The newly created RangeDimension.
187+
%
188+
% Example: dim = currDataArray.appendAliasRangeDimension();
189+
%
190+
% See also nix.RangeDimension.
191+
79192
fname = strcat(obj.alias, '::appendAliasRangeDimension');
80193
h = nix_mx(fname, obj.nixhandle);
81194
r = nix.Utils.createEntity(h, @nix.RangeDimension);
82195
end
83196

84197
function r = openDimensionIdx(obj, idx)
85-
% Getting the dimension by index starts with 1
86-
% instead of 0 compared to all other index functions.
198+
% Returns the Dimension entity for the specified dimension of the data.
199+
%
200+
% idx (double): The index of the respective Dimension.
201+
%
202+
% Returns: (nix.Dimension) The corresonding Dimension.
203+
%
204+
% Example: dim = currDataArray.openDimensionIdx(2);
205+
%
206+
% See also nix.RangeDimension, nix.SampledDimension, nix.SetDimension.
207+
87208
fname = strcat(obj.alias, '::openDimensionIdx');
88209
dim = nix_mx(fname, obj.nixhandle, idx);
89210
switch (dim.dimensionType)
@@ -97,11 +218,24 @@
97218
end
98219

99220
function r = deleteDimensions(obj)
221+
% Remove all Dimensions from the invoking DataArray.
222+
%
223+
% Returns: (logical) True if the Dimensions were removed,
224+
% False otherwise.
225+
%
226+
% Example: check = currDataArray.deleteDimensions();
227+
100228
fname = strcat(obj.alias, '::deleteDimensions');
101229
r = nix_mx(fname, obj.nixhandle);
102230
end
103231

104232
function r = dimensionCount(obj)
233+
% Get the number of nix.Dimensions associated with the invoking DataArray.
234+
%
235+
% Returns: (uint) The number of Dimensions.
236+
%
237+
% Example: dc = currDataArray.dimensionCount();
238+
105239
r = nix.Utils.fetchEntityCount(obj, 'dimensionCount');
106240
end
107241

@@ -110,6 +244,15 @@
110244
% -----------------
111245

112246
function r = readAllData(obj)
247+
% Returns an array with the complete raw data stored in the
248+
% DataArray.
249+
%
250+
% The returned data is read-only, changes will not be written to file.
251+
%
252+
% Returns: (var) The complete raw data.
253+
%
254+
% Example: data = currDataArray.readAllData();
255+
113256
fname = strcat(obj.alias, '::readAll');
114257
data = nix_mx(fname, obj.nixhandle);
115258
r = nix.Utils.transposeArray(data);
@@ -119,6 +262,14 @@
119262
%-- If a DataArray has been created as boolean or numeric,
120263
%-- provide that only values of the proper DataType can be written.
121264
function [] = writeAllData(obj, data)
265+
% Writes raw data to the invoking DataArray.
266+
%
267+
% DataType and extent of the written data has to
268+
% match the invoking DataArray.
269+
%
270+
% Example: dataSet = ones(15, 15, 15);
271+
% currDataArray.writeAllData(dataSet);
272+
122273
if (isinteger(obj.readAllData) && isfloat(data))
123274
disp('Warning: Writing Float data to an Integer DataArray');
124275
end
@@ -147,20 +298,31 @@
147298
end
148299

149300
function r = datatype(obj)
301+
% Returns the datatype of the data stored by the invoking DataArray.
302+
%
303+
% Example: dt = currDataArray.datatype;
304+
150305
fname = strcat(obj.alias, '::dataType');
151306
r = nix_mx(fname, obj.nixhandle);
152307
end
153308

154-
% Set data extent enables to increase the original size
155-
% of a data array within the same dimensions.
156-
% e.g. increase the size of a 2D array [5 10] to another
157-
% 2D array [5 11]. Changing the dimensions is not possible
158-
% e.g. changing from a 2D array to a 3D array.
159-
% Furthermore if the extent shrinks the size of an array
160-
% or remodels the size of an array to a completely different
161-
% shape, existing data that does not fit into the new shape
162-
% will be lost!
163309
function [] = setDataExtent(obj, extent)
310+
% Change the shape of the invoking DataArray.
311+
%
312+
% Set data extent enables to increase the original size
313+
% of a DataArray within the same dimensions.
314+
% e.g. increase the size of a 2D array [5 10] to another
315+
% 2D array [5 11]. Changing the dimensions is not possible
316+
% e.g. changing from a 2D array to a 3D array.
317+
% Furthermore if the extent shrinks the size of an array
318+
% or remodels the size of an array to a completely different
319+
% shape, existing data that does not fit into the new shape
320+
% will be lost!
321+
%
322+
% extent ([double]): shape of the DataArray.
323+
%
324+
% Example: currDataArray.setDataExtent([12 15]);
325+
164326
fname = strcat(obj.alias, '::setDataExtent');
165327
nix_mx(fname, obj.nixhandle, extent);
166328
end

0 commit comments

Comments
 (0)