Skip to content

Commit cd482c4

Browse files
achilleas-kachilleas-k
authored
Merge pull request #165 from mpsonntag/documentation
Add Documentation Very good.
2 parents d22fb4e + 299da6e commit cd482c4

35 files changed

+3464
-543
lines changed

‎+nix/Block.m‎

Lines changed: 515 additions & 21 deletions
Large diffs are not rendered by default.

‎+nix/DataArray.m‎

Lines changed: 179 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,59 @@
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+
% info (struct): Entity property summary. The values in this structure are detached
48+
% from the entity, changes will not be persisted to the file.
49+
%
50+
% nix.DataArray dynamic child entity properties:
51+
% dimensions access to all dimensions associated with a DataArray.
52+
% sources access to all first level nix.Source child entities.
53+
%
54+
% See also nix.Source, nix.Section.
55+
%
56+
%
157
% Copyright (c) 2016, German Neuroinformatics Node (G-Node)
258
%
359
% All rights reserved.
@@ -7,15 +63,13 @@
763
% LICENSE file in the root of the Project.
864

965
classdef DataArray < nix.NamedEntity & nix.MetadataMixIn & nix.SourcesMixIn
10-
%DataArray nix DataArray object
1166

1267
properties (Hidden)
13-
% namespace reference for nix-mx functions
14-
alias = 'DataArray'
68+
alias = 'DataArray' % namespace for DataArray nix backend function access.
1569
end
1670

1771
properties (Dependent)
18-
dimensions % should not be dynamic due to complex set operation
72+
dimensions % should not be dynamic due to complex set operation.
1973
end
2074

2175
methods
@@ -37,6 +91,14 @@
3791
% -----------------
3892

3993
function dimensions = get.dimensions(obj)
94+
% Get all Dimensions associated with this DataArray.
95+
%
96+
% Returns: ([nix.Dimension]) A list of all associated Dimensions.
97+
%
98+
% Example: dims = currDataArray.dimensions;
99+
%
100+
% See also nix.RangeDimension, nix.SampledDimension, nix.SetDimension.
101+
40102
dimensions = {};
41103
fname = strcat(obj.alias, '::dimensions');
42104
currList = nix_mx(fname, obj.nixhandle);
@@ -58,32 +120,93 @@
58120
end
59121

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

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

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

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

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

99222
function r = deleteDimensions(obj)
223+
% Remove all Dimensions from the invoking DataArray.
224+
%
225+
% Returns: (logical) True if the Dimensions were removed,
226+
% False otherwise.
227+
%
228+
% Example: check = currDataArray.deleteDimensions();
229+
100230
fname = strcat(obj.alias, '::deleteDimensions');
101231
r = nix_mx(fname, obj.nixhandle);
102232
end
103233

104234
function r = dimensionCount(obj)
235+
% Get the number of nix.Dimensions associated with the invoking DataArray.
236+
%
237+
% Returns: (uint) The number of Dimensions.
238+
%
239+
% Example: dc = currDataArray.dimensionCount();
240+
105241
r = nix.Utils.fetchEntityCount(obj, 'dimensionCount');
106242
end
107243

@@ -110,6 +246,15 @@
110246
% -----------------
111247

112248
function r = readAllData(obj)
249+
% Returns an array with the complete raw data stored in the
250+
% DataArray.
251+
%
252+
% The returned data is read-only, changes will not be written to file.
253+
%
254+
% Returns: (var) The complete raw data.
255+
%
256+
% Example: data = currDataArray.readAllData();
257+
113258
fname = strcat(obj.alias, '::readAll');
114259
data = nix_mx(fname, obj.nixhandle);
115260
r = nix.Utils.transposeArray(data);
@@ -119,6 +264,14 @@
119264
%-- If a DataArray has been created as boolean or numeric,
120265
%-- provide that only values of the proper DataType can be written.
121266
function [] = writeAllData(obj, data)
267+
% Writes raw data to the invoking DataArray.
268+
%
269+
% DataType and extent of the written data has to
270+
% match the invoking DataArray.
271+
%
272+
% Example: dataSet = ones(15, 15, 15);
273+
% currDataArray.writeAllData(dataSet);
274+
122275
if (isinteger(obj.readAllData) && isfloat(data))
123276
disp('Warning: Writing Float data to an Integer DataArray');
124277
end
@@ -147,20 +300,31 @@
147300
end
148301

149302
function r = datatype(obj)
303+
% Returns the datatype of the data stored by the invoking DataArray.
304+
%
305+
% Example: dt = currDataArray.datatype;
306+
150307
fname = strcat(obj.alias, '::dataType');
151308
r = nix_mx(fname, obj.nixhandle);
152309
end
153310

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!
163311
function [] = setDataExtent(obj, extent)
312+
% Change the shape of the invoking DataArray.
313+
%
314+
% Set data extent enables to increase the original size
315+
% of a DataArray within the same dimensions.
316+
% e.g. increase the size of a 2D array [5 10] to another
317+
% 2D array [5 11]. Changing the dimensions is not possible
318+
% e.g. changing from a 2D array to a 3D array.
319+
% Furthermore if the extent shrinks the size of an array
320+
% or remodels the size of an array to a completely different
321+
% shape, existing data that does not fit into the new shape
322+
% will be lost!
323+
%
324+
% extent ([double]): shape of the DataArray.
325+
%
326+
% Example: currDataArray.setDataExtent([12 15]);
327+
164328
fname = strcat(obj.alias, '::setDataExtent');
165329
nix_mx(fname, obj.nixhandle, extent);
166330
end

‎+nix/DataType.m‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
% nix.DataTypes provides access to the DataTypes supported by NIX.
2+
%
13
% Copyright (c) 2016, German Neuroinformatics Node (G-Node)
24
%
35
% All rights reserved.
@@ -7,7 +9,6 @@
79
% LICENSE file in the root of the Project.
810

911
classdef DataType
10-
% DataTypes supported by nix.
1112

1213
enumeration
1314
Bool;

‎+nix/Dynamic.m‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
% Class implements methods to dynamically assign properties.
2+
%
3+
% Utility class, do not use out of context.
4+
%
5+
%
16
% Copyright (c) 2016, German Neuroinformatics Node (G-Node)
27
%
38
% All rights reserved.
@@ -7,8 +12,6 @@
712
% LICENSE file in the root of the Project.
813

914
classdef Dynamic
10-
% Dynamic class (with static methods hehe)
11-
% implements methods to dynamically assigns properties
1215

1316
methods (Static)
1417
function addProperty(obj, prop, mode)

‎+nix/Entity.m‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,11 @@
1+
% Base class for nix entities.
2+
%
3+
% Class provides access to the info property and handles the lifetime
4+
% of a nix entitiy.
5+
%
6+
% Utility class, do not use out of context.
7+
%
8+
%
19
% Copyright (c) 2016, German Neuroinformatics Node (G-Node)
210
%
311
% All rights reserved.
@@ -7,8 +15,6 @@
715
% LICENSE file in the root of the Project.
816

917
classdef Entity < dynamicprops
10-
% Entity base class for nix entities
11-
% handles object lifetime
1218

1319
properties (Hidden)
1420
nixhandle
@@ -32,6 +38,8 @@
3238
end
3339

3440
function r = updatedAt(obj)
41+
% Provides the time the entity was last updated.
42+
3543
r = nix_mx('Entity::updatedAt', obj.nixhandle);
3644
end
3745

0 commit comments

Comments
 (0)