Skip to content

Commit 9ef76e0

Browse files
mpsonntagmpsonntag
committed
[Matlab] Add basic Dimension documentation
- Dimension documentation. - Fix index bug in SampledDimension and RangeDimension.
1 parent a28f7d3 commit 9ef76e0

File tree

6 files changed

+180
-18
lines changed

6 files changed

+180
-18
lines changed

‎+nix/DataArray.m‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -122,7 +122,7 @@
122122
%
123123
% Used to provide labels for dimensionless data e.g. when stacking
124124
% different signals. In the example the first dimension would
125-
% describe the measured unit, the section dimension the time,
125+
% describe the measured unit, the second dimension the time,
126126
% the third dimension would provide labels for three different
127127
% signals measured within the same experiment and packed into
128128
% the same 3D DataArray.

‎+nix/RangeDimension.m‎

Lines changed: 75 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,42 @@
1+
% nix.RangeDimension class provides access to the RangeDimension properties.
2+
%
3+
% The RangeDimension covers cases when indexes of a dimension are mapped to other values
4+
% in a non-regular fashion. A use-case for this would be for example irregularly sampled
5+
% time-series or certain kinds of histograms. To achieve the mapping of the indexes an
6+
% array of mapping values must be provided. Those values are stored in the dimensions
7+
% ticks property. In analogy to the SampledDimension a unit and a label can be defined.
8+
%
9+
% An AliasRangeDimension is a special case of a RangeDimension that uses the data
10+
% stored in the invoking DataArray as ticks. This works only(!) if the DataArray
11+
% is 1D and the stored data is numeric.
12+
%
13+
% nix.RangeDimension dynamic properties
14+
% dimensionType (char): read-only, returns type of the dimension as string.
15+
% label (char): read-write, gets and sets the label of the dimension.
16+
% unit (char): read-write, gets and sets the unit of the dimension.
17+
% Only SI units are supported.
18+
% ticks ([double]): read-write, gets and sets the ticks of the dimension.
19+
% The ticks map the index of the data at the respective
20+
% dimension to other values. This can be used to store data
21+
% that is sampled at irregular intervals.
22+
% Note: Ticks must be ordered in ascending order.
23+
% isAlias (logical): read-only, returns True if the current Dimension is an
24+
% AliasRangeDimension, False otherwise.
25+
%
26+
% Examples: dt = currDataArray.dimensions{1}.dimensionType;
27+
%
28+
% getLabel = currDimension.label;
29+
% currDimension.dimensions{2}.label = 'Time';
30+
%
31+
% getUnit = currDimension.unit;
32+
% currDimension.unit = 'ms';
33+
%
34+
% getTicks = currDimension.ticks;
35+
% currDimension.ticks = [2 12 36 292];
36+
%
37+
% See also nix.DataArray.
38+
%
39+
%
140
% Copyright (c) 2016, German Neuroinformatics Node (G-Node)
241
%
342
% All rights reserved.
@@ -7,11 +46,9 @@
746
% LICENSE file in the root of the Project.
847

948
classdef RangeDimension < nix.Entity
10-
% RangeDimension nix RangeDimension object
1149

1250
properties (Hidden)
13-
% namespace reference for nix-mx functions
14-
alias = 'RangeDimension'
51+
alias = 'RangeDimension' % nix-mx namespace to access RangeDimension specific nix backend functions.
1552
end
1653

1754
methods
@@ -27,17 +64,51 @@
2764
end
2865

2966
function r = tickAt(obj, index)
67+
% Returns the entry of the RangeDimension at a given index.
68+
%
69+
% index (double): The index of interest.
70+
%
71+
% Returns: (double) The tick value at the given index or an
72+
% error if the index is out of range of the
73+
% dimensions tick array.
74+
%
75+
% Example: getTickValue = currDimension.tickAt(101);
76+
3077
index = nix.Utils.handleIndex(index);
3178
fname = strcat(obj.alias, '::tickAt');
3279
r = nix_mx(fname, obj.nixhandle, index);
3380
end
3481

3582
function r = indexOf(obj, position)
83+
% Returns the index of the requested position or tick value.
84+
%
85+
% If the provided position is not a value in the tick array, the
86+
% method will return the index of the next tick larger than
87+
% the provided value.
88+
%
89+
% position (double): Tick value of the requested index.
90+
%
91+
% Returns: (double) The index of the provided position.
92+
%
93+
% Example: getIndexOfTick = currDimension.indexOf(12);
94+
3695
fname = strcat(obj.alias, '::indexOf');
37-
r = nix_mx(fname, obj.nixhandle, position);
96+
idx = nix_mx(fname, obj.nixhandle, position);
97+
r = double(idx + 1); % convert index from c++ to Matlab style.
3898
end
3999

40100
function r = axis(obj, count, startIndex)
101+
% Returns an array of values for axis labeling.
102+
%
103+
% count (double): Number of tick values to be returned.
104+
% startIndex (double): Starting index for the returned tick values.
105+
%
106+
% Returns: ([double]) Axis labeling values array.
107+
%
108+
% Example: currDimension.ticks = [4 8 15 16 23 42];
109+
% getAxis = currDimension.axis(1, 5); %-- returns [23]
110+
% getAxis = currDimension.axis(3, 2); %-- returns [8 15 16]
111+
41112
if (nargin < 3)
42113
startIndex = 1;
43114
end

‎+nix/SampledDimension.m‎

Lines changed: 77 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,40 @@
1+
% nix.SampledDimension class provides access to the SampledDimension properties.
2+
%
3+
% Instances of the SampledDimension class are used to describe a dimension of data in
4+
% a DataArray that has been sampled in regular intervals. For example this can be
5+
% a time axis.
6+
% SampledDimensions are characterized by the label for the dimension, the unit in
7+
% which the sampling interval is given. If not specified otherwise the dimension
8+
% starts with zero offset.
9+
%
10+
% nix.SampledDimension dynamic properties
11+
% dimensionType (char): read-only, returns type of the dimension as string.
12+
% label (char): read-write, gets and sets the label of the dimension.
13+
% unit (char): read-write, gets and sets the unit of the dimension and its
14+
% sampling interval. Only SI units are supported.
15+
% samplingInterval (double): read-write, gets and sets the sampling interval
16+
% of the dimension.
17+
% offset (double): read-write, The offset defines at which position the sampling
18+
% was started. The offset is interpreted in the same unit as
19+
% the sampling interval.
20+
%
21+
% Examples: dt = currDataArray.dimensions{1}.dimensionType;
22+
%
23+
% getLabel = currDimension.label;
24+
% currDimension.dimensions{2}.label = 'Frequency';
25+
%
26+
% getUnit = currDimension.unit;
27+
% currDimension.unit = 'Hz';
28+
%
29+
% getSampling = currDimension.samplingInterval;
30+
% currDimension.samplingInterval = 200;
31+
%
32+
% getOffset = currDimension.offset;
33+
% currDimension.offset = 8;
34+
%
35+
% See also nix.DataArray.
36+
%
37+
%
138
% Copyright (c) 2016, German Neuroinformatics Node (G-Node)
239
%
340
% All rights reserved.
@@ -7,11 +44,9 @@
744
% LICENSE file in the root of the Project.
845

946
classdef SampledDimension < nix.Entity
10-
% SampledDimension nix SampledDimension object
1147

1248
properties (Hidden)
13-
% namespace reference for nix-mx functions
14-
alias = 'SampledDimension'
49+
alias = 'SampledDimension' % nix-mx namespace to access SampledDimension specific nix backend functions.
1550
end
1651

1752
methods
@@ -27,17 +62,55 @@
2762
end
2863

2964
function r = indexOf(obj, position)
65+
% Returns the index of the given position (data point).
66+
%
67+
% This method returns the index of the given position. Use this method for
68+
% example to find out which data point (index) relates to a given time.
69+
% Note: This method does not check if the position is within the
70+
% extent of the data!
71+
%
72+
% position (double): A data value e.g. a time.
73+
%
74+
% Returns: (double) The corresponding index.
75+
%
76+
% Example: getIndex = currDimension.indexOf(12);
77+
3078
fname = strcat(obj.alias, '::indexOf');
31-
r = nix_mx(fname, obj.nixhandle, position);
79+
idx = nix_mx(fname, obj.nixhandle, position);
80+
r = double(idx + 1); % convert index from c++ to Matlab style.
3281
end
3382

3483
function r = positionAt(obj, index)
84+
% Returns the position of this dimension at a given index.
85+
%
86+
% This method returns the position at a given index. Use this method for
87+
% example to find the position that relates to a certain index. Note: This
88+
% method does not check if the index is the extent of the data!
89+
%
90+
% index (double): Index of interest.
91+
%
92+
% Returns: (double) The respective position e.g. a time.
93+
%
94+
% Example: getPosition = currDimension.positionAt(236);
95+
3596
index = nix.Utils.handleIndex(index);
3697
fname = strcat(obj.alias, '::positionAt');
3798
r = nix_mx(fname, obj.nixhandle, index);
3899
end
39100

40101
function r = axis(obj, count, startIndex)
102+
% Returns an array of values for axis labeling, calculated by
103+
% the dimensions sampling interval.
104+
%
105+
% count (double): Number of values to be returned.
106+
% startIndex (double): Starting index for the returned values.
107+
%
108+
% Returns: ([double]) Axis labeling values array.
109+
%
110+
% Example: currDimension.samplingInterval = 200;
111+
% getAxis = currDimension.axis(3, 1); %-- returns [0 200 400]
112+
% getAxis = currDimension.axis(3, 5); %-- returns [800 1000 1200]
113+
41114
if (nargin < 3)
42115
startIndex = 1;
43116
end

‎+nix/SetDimension.m‎

Lines changed: 21 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,23 @@
1+
% nix.SetDimension class provides access to the SetDimension properties.
2+
%
3+
% Used to provide labels for dimensionless data e.g. when stacking different signals.
4+
% In the example the first dimension would describe the measured unit, the second
5+
% dimension the time, the third dimension would provide labels for three different
6+
% signals measured within the same experiment and packed into the same 3D DataArray.
7+
%
8+
% nix.SetDimension dynamic properties
9+
% dimensionType (char): read-only, returns type of the dimension as string.
10+
% labels ([char]): read-write, Character cell array to get and set
11+
% labels of the dimension.
12+
%
13+
% Examples: dt = currDataArray.dimensions{1}.dimensionType;
14+
%
15+
% labels = currDataArray.dimensions{2}.labels;
16+
% currDataArray.dimensions{2}.labels = {'sinus', 'cosinus'};
17+
%
18+
% See also nix.DataArray.
19+
%
20+
%
121
% Copyright (c) 2016, German Neuroinformatics Node (G-Node)
222
%
323
% All rights reserved.
@@ -7,11 +27,9 @@
727
% LICENSE file in the root of the Project.
828

929
classdef SetDimension < nix.Entity
10-
% SetDimension nix SetDimension object
1130

1231
properties (Hidden)
13-
% namespace reference for nix-mx functions
14-
alias = 'SetDimension'
32+
alias = 'SetDimension' % nix-mx namespace to access SetDimension specific nix backend functions.
1533
end
1634

1735
methods

‎+nix/Utils.m‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -178,7 +178,7 @@
178178
end
179179

180180
function r = handleIndex(idx)
181-
% Matlab uses 1-based indexing opposed to 0 based indexing in C++.
181+
% Matlab uses 1-based indexing opposed to 0-based indexing in C++.
182182
% handleIndex transforms a Matlab style index to a C++ style
183183
% index and raises the appropriate Matlab error in case of an
184184
% invalid subscript.

‎tests/TestDimensions.m‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
% TestDimensions provides tests for all supported nix.Dimension methods.
2+
%
13
% Copyright (c) 2016, German Neuroinformatics Node (G-Node)
24
%
35
% All rights reserved.
@@ -7,16 +9,14 @@
79
% LICENSE file in the root of the Project.
810

911
function funcs = TestDimensions
10-
% TestDimensions tests for Dimensions
11-
1212
funcs = {};
1313
funcs{end+1} = @testSetDimension;
1414
funcs{end+1} = @testSampleDimension;
1515
funcs{end+1} = @testRangeDimension;
1616
end
1717

18+
%% Test: SetDimension
1819
function [] = testSetDimension( varargin )
19-
%% Test: set dimension
2020
f = nix.File(fullfile(pwd, 'tests', 'testRW.h5'), nix.FileMode.Overwrite);
2121
b = f.createBlock('daTestBlock', 'test nixBlock');
2222
da = b.createDataArray('daTest', 'test nixDataArray', nix.DataType.Double, [1 2]);
@@ -49,8 +49,8 @@
4949
end;
5050
end
5151

52+
%% Test: SampledDimension
5253
function [] = testSampleDimension( varargin )
53-
%% Test: sampled dimension
5454
f = nix.File(fullfile(pwd, 'tests', 'testRW.h5'), nix.FileMode.Overwrite);
5555
b = f.createBlock('daTestBlock', 'test nixBlock');
5656
da = b.createDataArray('daTest', 'test nixDataArray', nix.DataType.Double, [1 2]);
@@ -102,8 +102,8 @@
102102
assert(d1.positionAt(10) == d1.offset + 9 * d1.samplingInterval);
103103
end
104104

105+
%% Test: RangeDimension
105106
function [] = testRangeDimension( varargin )
106-
%% Test: range dimension
107107
f = nix.File(fullfile(pwd, 'tests', 'testRW.h5'), nix.FileMode.Overwrite);
108108
b = f.createBlock('daTestBlock', 'test nixBlock');
109109
da = b.createDataArray('daTest', 'test nixDataArray', nix.DataType.Double, [1 2]);

0 commit comments

Comments
 (0)