Skip to content

Commit b641982

Browse files
mpsonntagmpsonntag
committed
[Matlab] Add basic SourcesMixIn documentation
1 parent c3fa071 commit b641982

File tree

1 file changed

+107
-7
lines changed

1 file changed

+107
-7
lines changed

‎+nix/SourcesMixIn.m‎

Lines changed: 107 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,12 @@
1+
% Mixin Class for entities that can be associated with a nix.Source entity.
2+
%
3+
% In order to describe the provenance of data some entities of the NIX data model
4+
% can be associated with nix.Source entities. This class serves as a base class
5+
% for those.
6+
%
7+
% See also nix.Source, nix.Group, nix.DataArray, nix.Tag, nix.MultiTag.
8+
%
9+
%
110
% Copyright (c) 2016, German Neuroinformatics Node (G-Node)
211
%
312
% All rights reserved.
@@ -7,8 +16,6 @@
716
% LICENSE file in the root of the Project.
817

918
classdef SourcesMixIn < handle
10-
% SourcesMixIn
11-
% mixin class for nix entities that can be related with sources
1219

1320
properties (Abstract, Hidden)
1421
alias
@@ -20,37 +27,130 @@
2027
end
2128

2229
function r = sourceCount(obj)
30+
% Get the number of direct child nix.Sources.
31+
%
32+
% Returns: (uint) The number of child Sources.
33+
%
34+
% Example: sc = currEntity.sourceCount();
35+
%
36+
% See also nix.Source.
37+
2338
r = nix.Utils.fetchEntityCount(obj, 'sourceCount');
2439
end
2540

26-
% hasSource supports only check by id, not by name
2741
function r = hasSource(obj, idEntity)
42+
% Check if a nix.Source exists as a direct child of the invoking Entity.
43+
%
44+
% idEntity (char/nix.Source): ID of the Source or the Source itself.
45+
%
46+
% Returns: (logical) True if the Source exists, false otherwise.
47+
%
48+
% Example: check = currEntity.hasSource('some-source-id');
49+
% check = currFile.blocks{1}.tags{1}.hasSource(newSourceEntity);
50+
%
51+
% See also nix.Source.
52+
2853
has = nix.Utils.parseEntityId(idEntity, 'nix.Source');
2954
r = nix.Utils.fetchHasEntity(obj, 'hasSource', has);
3055
end
3156

32-
function [] = addSource(obj, entity)
33-
nix.Utils.addEntity(obj, 'addSource', entity, 'nix.Source');
57+
function [] = addSource(obj, idEntity)
58+
% Add an existing nix.Source to the referenced list of the invoking Entity.
59+
%
60+
% idEntity (char/nix.Source): The ID of an existing Source,
61+
% or a nix.Source entity.
62+
%
63+
% Example: currEntity.addSource('23bb8a99-1812-4bc6-a52c-45e96864756b');
64+
% currFile.blocks{1}.groups{1}.addSource(newSourceEntity);
65+
%
66+
% See also nix.Source.
67+
68+
nix.Utils.addEntity(obj, 'addSource', idEntity, 'nix.Source');
3469
end
3570

3671
function [] = addSources(obj, entityArray)
72+
% Set the list of referenced Sources for the invoking Entity.
73+
%
74+
% Previously referenced Sources that are not in the
75+
% references cell array will be removed.
76+
%
77+
% entityArray ([nix.Source]): A cell array of nix.Sources.
78+
%
79+
% Example: currEntity.addSources({source1, source2});
80+
%
81+
% See also nix.Source.
82+
3783
nix.Utils.addEntityArray(obj, 'addSources', entityArray, 'nix.Source');
3884
end
3985

40-
function r = removeSource(obj, del)
41-
r = nix.Utils.deleteEntity(obj, 'removeSource', del, 'nix.Source');
86+
function r = removeSource(obj, idEntity)
87+
% Removes the reference to a nix.Source from the invoking Entity.
88+
%
89+
% This method removes the association between the Source and the
90+
% Entity, the Source itself will not be removed from the file.
91+
%
92+
% idEntity (char/nix.Source): id of the Source to be removed
93+
% or the Source itself.
94+
%
95+
% Returns: (logical) True if the reference to the Source
96+
% has been removed, false otherwise.
97+
%
98+
% Example: check = currEntity.removeSource('23bb8a99-1812-4bc6-a52c');
99+
% check = currFile.blocks{1}.groups{1}.removeSource(newSourceEntity);
100+
%
101+
% See also nix.Source.
102+
103+
r = nix.Utils.deleteEntity(obj, 'removeSource', idEntity, 'nix.Source');
42104
end
43105

44106
function r = openSource(obj, idName)
107+
% Retrieves an existing Source from the invoking Entity.
108+
%
109+
% idName (char): Name or ID of the Source.
110+
%
111+
% Returns: (nix.Source) The nix.Source or an empty cell,
112+
% if the Source was not found.
113+
%
114+
% Example: getSource = currEntity.openSource('23bb8a99-1812-4bc6-a52c');
115+
% getSource = currFile.blocks{1}.tags{1}.openSource('subTrial2');
116+
%
117+
% See also nix.Source.
118+
45119
r = nix.Utils.openEntity(obj, 'openSource', idName, @nix.Source);
46120
end
47121

48122
function r = openSourceIdx(obj, index)
123+
% Retrieves an existing nix.Source from the invoking Entity,
124+
% accessed by index.
125+
%
126+
% index (double): The index of the Source to read.
127+
%
128+
% Returns: (nix.Source) The Source at the given index.
129+
%
130+
% Example: getSource = currEntity.openSourceIdx(1);
131+
%
132+
% See also nix.Source.
133+
49134
idx = nix.Utils.handleIndex(index);
50135
r = nix.Utils.openEntity(obj, 'openSourceIdx', idx, @nix.Source);
51136
end
52137

53138
function r = filterSources(obj, filter, val)
139+
% Get a filtered cell array of all Source entities
140+
% referenced by the invoking Entity.
141+
%
142+
% filter (nix.Filter): The nix.Filter to be applied.
143+
% val (char): Value that is applied with the selected
144+
% filter.
145+
%
146+
% Returns: ([nix.Source]) A cell array of Sources filtered according
147+
% to the applied nix.Filter.
148+
%
149+
% Example: getSources = currEntity.filterSources(...
150+
% nix.Filter.type, 'ephys_data');
151+
%
152+
% See also nix.Source, nix.Filter.
153+
54154
r = nix.Utils.filter(obj, 'sourcesFiltered', filter, val, @nix.Source);
55155
end
56156
end

0 commit comments

Comments
 (0)