Skip to content

Commit c3fa071

Browse files
mpsonntagmpsonntag
committed
[Matlab] Add basic nix.Source documentation
1 parent eb49435 commit c3fa071

File tree

3 files changed

+215
-50
lines changed

3 files changed

+215
-50
lines changed

‎+nix/Block.m‎

Lines changed: 25 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -70,12 +70,12 @@
7070
function r = createGroup(obj, name, type)
7171
% Create a new nix.Group entity associated with the invoking Block.
7272
%
73-
% name (char): The name of the Group, has to be unique within the file.
74-
% type (char): The type of the Group.
73+
% name (char): The name of the Group, has to be unique within the file.
74+
% type (char): The type of the Group.
7575
%
76-
% Returns: (nix.Group) The newly created Group.
76+
% Returns: (nix.Group) The newly created Group.
7777
%
78-
% Example: newGroup = currBlock.createGroup('subTrial2', 'ephys');
78+
% Example: newGroup = currBlock.createGroup('subTrial2', 'ephys');
7979
%
8080
% See also nix.Group.
8181

@@ -217,18 +217,18 @@
217217
function r = createDataArray(obj, name, type, datatype, shape)
218218
% Create a new nix.DataArray entity associated with the invoking Block.
219219
%
220-
% name (char): The name of the DataArray, has to be unique within the file.
221-
% type (char): The type of the DataArray.
222-
% datatype (nix.DataType): Provides the datatype of the data that the
223-
% DataArray will contain. It has to be a valid
224-
% nix.DataType.
225-
% shape (double): The dimensionality of the data that the DataArray will
220+
% name (char): The name of the DataArray, has to be unique within the file.
221+
% type (char): The type of the DataArray.
222+
% datatype (nix.DataType): Provides the datatype of the data that the
223+
% DataArray will contain. It has to be a valid
224+
% nix.DataType.
225+
% shape (double): The dimensionality of the data that the DataArray will
226226
% contain.
227227
%
228-
% Returns: (nix.DataArray) The newly created DataArray.
228+
% Returns: (nix.DataArray) The newly created DataArray.
229229
%
230-
% Example: newDataArray = currBlock.createDataArray('sessionData1', ...
231-
% 'epyhs_data', nix.DataType.Double, [12 15]);
230+
% Example: newDataArray = currBlock.createDataArray('sessionData1', ...
231+
% 'epyhs_data', nix.DataType.Double, [12 15]);
232232
% % allocates space for a 12x15 array of datatype double.
233233
%
234234
% See also nix.DataArray, nix.DataType.
@@ -263,13 +263,13 @@
263263
% successful creation, the contents of data will be written to the
264264
% DataArray.
265265
%
266-
% name (char): The name of the DataArray, has to be unique within the file.
267-
% type (char): The type of the DataArray, required.
268-
% data (var): Raw data the DataArray is supposed to contain.
266+
% name (char): The name of the DataArray, has to be unique within the file.
267+
% type (char): The type of the DataArray, required.
268+
% data (var): Raw data the DataArray is supposed to contain.
269269
%
270-
% Returns: (nix.DataArray) The newly created DataArray.
270+
% Returns: (nix.DataArray) The newly created DataArray.
271271
%
272-
% Example: newDataArray = currBlock.createDataArray('sessionData2', ...
272+
% Example: newDataArray = currBlock.createDataArray('sessionData2', ...
273273
% 'epyhs_data', rawDataVariable);
274274
%
275275
% See also nix.DataArray, nix.DataType.
@@ -371,12 +371,12 @@
371371
function r = createSource(obj, name, type)
372372
% Create a new nix.Source entity associated with the invoking Block.
373373
%
374-
% name (char): The name of the Source, has to be unique within the file.
375-
% type (char): The type of the Source.
374+
% name (char): The name of the Source, has to be unique within the file.
375+
% type (char): The type of the Source.
376376
%
377-
% Returns: (nix.Source) The newly created Source.
377+
% Returns: (nix.Source) The newly created Source.
378378
%
379-
% Example: newSource = currBlock.createSource('cell5', 'pyramidal');
379+
% Example: newSource = currBlock.createSource('cell5', 'pyramidal');
380380
%
381381
% See also nix.Source.
382382

@@ -481,7 +481,7 @@
481481
% Example: allSources = currBlock.findSources(2);
482482
% % will add all Sources until including the 2nd layer of Sources.
483483
%
484-
% See also nix.Section.
484+
% See also nix.Source.
485485

486486
r = obj.filterFindSources(maxDepth, nix.Filter.acceptall, '');
487487
end
@@ -502,7 +502,8 @@
502502
% val (char): Value that is applied with the selected
503503
% filter.
504504
%
505-
% Example: allSources = f.filterFindSources(2, nix.Filter.type, 'ephys');
505+
% Example: allSources = currBlock.filterFindSources(...
506+
% 2, nix.Filter.type, 'ephys');
506507
%
507508
% See also nix.Source, nix.Filter.
508509

‎+nix/Source.m‎

Lines changed: 168 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,26 @@
1+
% nix.Source class is used to describe the provenance of other entities
2+
% of the NIX data model.
3+
%
4+
% The Source entity is used to note the provenance of the data and offers the
5+
% option to bind simple, low level additional metadata.
6+
% One special feature of the Source is the possibility to reference other Sources as
7+
% children thus building up a tree of Sources.
8+
% This can, for example, be used to specify that a Source 'electrode array' contains
9+
% multiple electrodes as its child Sources.
10+
%
11+
% nix.Source dynamic properties:
12+
% id (char): read-only, automatically created id of the entity.
13+
% name (char): read-only, name of the entity.
14+
% type (char): read-write, type can be used to give semantic meaning to an
15+
% entity and expose it to search methods in a broader context.
16+
% definition (char): read-write, additional description of the entity.
17+
%
18+
% nix.Source dynamic child entity properties:
19+
% sources access to all nix.Source child entities.
20+
%
21+
% See also nix.Block, nix.DataArray, nix.Tag, nix.MultiTag, nix.Section.
22+
%
23+
%
124
% Copyright (c) 2016, German Neuroinformatics Node (G-Node)
225
%
326
% All rights reserved.
@@ -7,19 +30,17 @@
730
% LICENSE file in the root of the Project.
831

932
classdef Source < nix.NamedEntity & nix.MetadataMixIn
10-
% Source nix Source object
1133

1234
properties (Hidden)
13-
% namespace reference for nix-mx functions
14-
alias = 'Source'
35+
alias = 'Source' % nix-mx namespace to access Source specific nix backend functions.
1536
end
1637

1738
methods
1839
function obj = Source(h)
1940
[email protected](h);
2041
[email protected]();
2142

22-
% assign relations
43+
% assign child entities
2344
nix.Dynamic.addGetChildEntities(obj, 'sources', @nix.Source);
2445
end
2546

@@ -28,59 +49,198 @@
2849
% ------------------
2950

3051
function r = sourceCount(obj)
52+
% Get the number of direct child nix.Sources.
53+
%
54+
% Returns: (uint) The number of child Sources.
55+
%
56+
% Example: sc = currSource.sourceCount();
57+
3158
r = nix.Utils.fetchEntityCount(obj, 'sourceCount');
3259
end
3360

3461
function r = createSource(obj, name, type)
62+
% Create a new nix.Source entity associated with the invoking Source.
63+
%
64+
% name (char): The name of the Source, has to be unique within the file.
65+
% type (char): The type of the Source.
66+
%
67+
% Returns: (nix.Source) The newly created Source.
68+
%
69+
% Example: newSource = currSource.createSource('cell5', 'pyramidal');
70+
3571
fname = strcat(obj.alias, '::createSource');
3672
h = nix_mx(fname, obj.nixhandle, name, type);
3773
r = nix.Utils.createEntity(h, @nix.Source);
3874
end
3975

4076
function r = hasSource(obj, idName)
77+
% Check if a nix.Source exists as a direct child of the invoking Source.
78+
%
79+
% idName (char): Name or ID of the Source.
80+
%
81+
% Returns: (logical) True if the Source exists, false otherwise.
82+
%
83+
% Example: check = currSource.hasSource('some-source-id');
84+
% check = currFile.blocks{1}.sources{1}.hasSource('cell5');
85+
4186
r = nix.Utils.fetchHasEntity(obj, 'hasSource', idName);
4287
end
4388

44-
function r = deleteSource(obj, del)
45-
r = nix.Utils.deleteEntity(obj, 'deleteSource', del, 'nix.Source');
89+
function r = deleteSource(obj, idNameEntity)
90+
% Deletes a nix.Source and its children from the invoking Source.
91+
%
92+
% When a Source is deleted, all its sub-Sources
93+
% will be deleted recursively from the Source as well.
94+
%
95+
% idNameEntity (char/nix.Source): Name or id of the entity to
96+
% be deleted or the entity itself.
97+
%
98+
% Returns: (logical) True if the Source has been removed, false otherwise.
99+
%
100+
% Example: check = currSource.deleteSource('23bb8a99-1812-4bc6-a52c');
101+
% check = currSource.deleteSource('cell5');
102+
% check = currFile.blocks{1}.sources{1}.deleteSource(newSource);
103+
104+
r = nix.Utils.deleteEntity(obj, 'deleteSource', idNameEntity, 'nix.Source');
46105
end
47106

48107
function r = openSource(obj, idName)
108+
% Retrieves an existing direct Source from the invoking Source.
109+
%
110+
% idName (char): Name or ID of the Source.
111+
%
112+
% Returns: (nix.Source) The nix.Source or an empty cell,
113+
% if the Source was not found.
114+
%
115+
% Example: getSource = currSource.openSource('23bb8a99-1812-4bc6-a52c');
116+
% getSource = currFile.blocks{1}.sources{1}.openSource('cell5');
117+
49118
r = nix.Utils.openEntity(obj, 'openSource', idName, @nix.Source);
50119
end
51120

52121
function r = openSourceIdx(obj, index)
122+
% Retrieves an existing nix.Source from the invoking Source,
123+
% accessed by index.
124+
%
125+
% index (double): The index of the Source to read.
126+
%
127+
% Returns: (nix.Source) The Source at the given index.
128+
%
129+
% Example: getSource = currSource.openSourceIdx(1);
130+
53131
idx = nix.Utils.handleIndex(index);
54132
r = nix.Utils.openEntity(obj, 'openSourceIdx', idx, @nix.Source);
55133
end
56134

57135
function r = parentSource(obj)
136+
% Returns the parent Source of the invoking Source. Method performs a search,
137+
% may thus not be the most efficient way.
138+
%
139+
% Returns: (nix.Source) The parent Source if there is any,
140+
% an empty cell array otherwise.
141+
%
142+
% Example: getSource = currSource.parentSource();
143+
58144
r = nix.Utils.fetchObj(obj, 'parentSource', @nix.Source);
59145
end
60146

61147
function r = referringDataArrays(obj)
148+
% Returns all nix.DataArrays which referrence the invoking Source.
149+
%
150+
% Returns: ([nix.DataArray]) A cell array of all DataArray entities
151+
% referring to the invoking Source.
152+
%
153+
% Example: getSource = currSource.referringDataArrays();
154+
%
155+
% See also nix.DataArray.
156+
62157
r = nix.Utils.fetchObjList(obj, 'referringDataArrays', @nix.DataArray);
63158
end
64159

65160
function r = referringTags(obj)
161+
% Returns all nix.Tags which referrence the invoking Source.
162+
%
163+
% Returns: ([nix.Tag]) A cell array of all Tag entities
164+
% referring to the invoking Source.
165+
%
166+
% Example: getSource = currSource.referringTags();
167+
%
168+
% See also nix.Tag.
169+
66170
r = nix.Utils.fetchObjList(obj, 'referringTags', @nix.Tag);
67171
end
68172

69173
function r = referringMultiTags(obj)
174+
% Returns all nix.MultiTags which referrence the invoking Source.
175+
%
176+
% Returns: ([nix.MultiTag]) A cell array of all MultiTag entities
177+
% referring to the invoking Source.
178+
%
179+
% Example: getSource = currSource.referringMultiTags();
180+
%
181+
% See also nix.MultiTag.
182+
70183
r = nix.Utils.fetchObjList(obj, 'referringMultiTags', @nix.MultiTag);
71184
end
72185

73186
function r = filterSources(obj, filter, val)
187+
% Get a filtered cell array of all direct child Sources
188+
% of the invoking Source.
189+
%
190+
% filter (nix.Filter): the nix.Filter to be applied.
191+
% val (char): Value that is applied with the selected
192+
% filter.
193+
%
194+
% Returns: ([nix.Source]) A cell array of Sources filtered according
195+
% to the applied nix.Filter.
196+
%
197+
% Example: getSources = currSource.filterSources(nix.Filter.type, 'pyramidal');
198+
%
199+
% See also nix.Filter.
200+
74201
r = nix.Utils.filter(obj, 'sourcesFiltered', filter, val, @nix.Source);
75202
end
76203

77-
% maxdepth is an index where idx = 0 corresponds to the calling source
78204
function r = findSources(obj, maxDepth)
205+
% Get all Sources and their child Sources in the invoking Source recursively.
206+
%
207+
% This method traverses the trees of all Sources in the Source and adds all
208+
% Sources to the resulting cell array, until the maximum depth of the nested
209+
% Sources has been reached. The traversal is accomplished via breadth first
210+
% and adds the Sources accordingly.
211+
%
212+
% maxDepth (double): The maximum depth of traversal to retrieve nested
213+
% Sources. Should be handled like an index,
214+
% where idx = 0 corresponds to the calling source.
215+
%
216+
% Example: allSources = currSource.findSources(2);
217+
% % will add all Sources until including the 2nd layer of Sources.
218+
79219
r = obj.filterFindSources(maxDepth, nix.Filter.acceptall, '');
80220
end
81221

82-
% maxdepth is an index where idx = 0 corresponds to the calling source
83222
function r = filterFindSources(obj, maxDepth, filter, val)
223+
% Get all Sources and their child Sources in the invoking Source recursively.
224+
%
225+
% This method traverses the trees of all Sources of the invoking Source.
226+
% The traversal is accomplished via breadth first and can be limited in depth.
227+
% On each node or Source a nix.Filter is applied. If the filter returns true,
228+
% the respective Source will be added to the result list.
229+
%
230+
% maxDepth (double): The maximum depth of traversal to retrieve nested
231+
% Sources. Should be handled like an index,
232+
% where idx = 0 corresponds to the calling source.
233+
% filter (nix.Filter): The nix.Filter to be applied. Supports
234+
% the filters 'acceptall', 'id', 'ids',
235+
% 'name' and 'type'.
236+
% val (char): Value that is applied with the selected
237+
% filter.
238+
%
239+
% Example: allSources = currSource.filterFindSources(...
240+
% 2, nix.Filter.type, 'ephys');
241+
%
242+
% See also nix.Filter.
243+
84244
r = nix.Utils.find(obj, 'findSources', maxDepth, filter, val, @nix.Source);
85245
end
86246
end

0 commit comments

Comments
 (0)