Merge pull request #336 from VH-Lab/docs/tutorial_2.5

Docs/tutorial 2.5

Author: stevevanhooser

+ndi/calculator.m

@@ -44,13 +44,17 @@
             %
             % DOCS = RUN(NDI_CALCULATOR_OBJ, DOCEXISTSACTION, PARAMETERS)
             %
-            %
             % DOCEXISTSACTION can be 'Error', 'NoAction', 'Replace', or 'ReplaceIfDifferent'
             % For calculators, 'ReplaceIfDifferent' is equivalent to 'NoAction' because
             % the input parameters define the calculator.
             %
-            % Step 1: set up input parameters; they can either be completely specified by
-            % the caller, or defaults can be used
+            % This function is primarily intended to be called by external programs and users.
+            %
+
+
+
+              % Step 1: set up input parameters; they can either be completely specified by
+              % the caller, or defaults can be used
 
             docs = {};
             docs_tocat = {};
@@ -116,6 +120,10 @@
             %
             % Returns a list of the default search parameters for finding appropriate inputs
             % to the calculator.
+            % 
+            % This function is primarily intended as an internal function but is left exposed
+            % (not private) so that it can be used for debugging. But in general, user code should
+            % not call this function.
             %
             parameters.input_parameters = [];
             parameters.depends_on = vlt.data.emptystruct('name','value');
@@ -130,6 +138,10 @@
             % used as inputs to the calculator. PARAMETERS is a cell array of parameter
             % structures with fields 'input_parameters' and 'depends_on'.
             %
+            % This function is primarily intended as an internal function but is left exposed
+            % (not private) so that it can be used for debugging. But in general, user code should
+            % not call this function.
+            %
             % PARAMETERS_SPECIFICATION is a structure with the following fields:
             % |----------------------------------------------------------------------|
             % | input_parameters      | A structure of fixed input parameters needed |
@@ -225,6 +237,10 @@
             % If it finds any, it creates a query indicating that the 'depends_on' field
             % must match the specified name and value.
             %
+            % This function is primarily intended as an internal function but is left exposed
+            % (not private) so that it can be used for debugging. But in general, user code should
+            % not call this function.
+            %
             query = vlt.data.emptystruct('name','query');
             if isfield(parameters_specification.input_parameters,'depends_on')
                 for i=1:numel(parameters_specification.input_parameters.depends_on),
@@ -260,6 +276,11 @@
             % |------------------------|----------------------------------|
             %
             % in the abstract class, this returns empty
+            %
+            % This function is primarily intended as an internal function but is left exposed
+            % (not private) so that it can be used for debugging. But in general, user code should
+            % not call this function.
+            %
             myemptydoc = ndi.document(ndi_calculator_obj.doc_document_types{1});
             property_list_name = myemptydoc.document_properties.document_class.property_list_name;
             % class_name = myemptydoc.document_properties.document_class.class_name
@@ -306,6 +327,10 @@
             % It is necessary to "columnize" the substructures because Matlab does not not necessarily preserve that
             % orientation when data is written to or read from JSON.
             %
+            % This function is primarily intended as an internal function but is left exposed
+            % (not private) so that it can be used for debugging. But in general, user code should
+            % not call this function.
+            %
             if ~isempty(input_parameters1),
                 input_parameters1 = vlt.data.columnize_struct(input_parameters1);
             end;
@@ -328,6 +353,10 @@
             % can be overridden if additional criteria beyond an ndi.query are needed to
             % assess if a document is an appropriate input for the calculator.
             %
+            % This function is primarily intended as an internal function but is left exposed
+            % (not private) so that it can be used for debugging. But in general, user code should
+            % not call this function.
+            %
             b = 1; % base class behavior
         end; % is_valid_dependency_input()
 
@@ -338,8 +367,13 @@
             %
             % Perform the calculator and return an ndi.document with the answer.
             %
+            % This function is primarily intended as an internal function but is left exposed
+            % (not private) so that it can be used for debugging. But in general, user code should
+            % not call this function.
+            %
             % In the base class, this always returns empty.
             doc = {};
+
         end; % calculate()
 
         function h=plot(ndi_calculator_obj, doc_or_parameters, varargin)
@@ -351,6 +385,8 @@
             % the calculator has been performed in a manner that makes sense with
             % its input data. Useful for debugging / validating a calculator.
             %
+            % This function is intended to be called by external users and code.
+            %
             % Handles to the figure, the axes, and any objects created are returned in H.
             %
             % By default, this plot is made in the current axes.
@@ -414,6 +450,8 @@
             % Returns the help information for the document type for an NDI
             % calculator object.
             %
+            % This function is intended to be called by external users or code.
+            %
             text = ndi.calculator.docfiletext(class(ndi_calculator_obj), 'output');
         end; %doc_about()
 
@@ -425,6 +463,8 @@
             % Returns the help information for the document type for an NDI
             % calculator object.
             %
+            % This function is intended to be called by external users or code.
+            %
             text = ndi_calculator_obj.doc_about();
         end; % appdoc_description()
 
@@ -456,6 +496,7 @@
             % | suppress_title (0)        | 0/1 Should we suppress the title?    |
             % |---------------------------|--------------------------------------|
             %
+
             newfigure = 0;
             holdstate = 0;
             suppress_x_label = 0;

+ndi/query.m

@@ -77,7 +77,7 @@
             %   q = ndi.query('','isa','ndi.document.base') % match any ndi.document.base or subclass
 
             % Argument block identical to did.query to ensure consistent interface
-            arguments (Input)
+            arguments
                 field % Type checking depends on nargin, handled by superclass
                 % Operation is required if nargin >= 2, must be member of valid list
                 op (1,:) {mustBeMember(op, {'regexp', 'exact_string', 'contains_string', ...

docs/NDI-matlab/mkdocs-references.yml

@@ -164,6 +164,7 @@
             - ndi.database.fun.find_ingested_docs: 'NDI-matlab/reference/+ndi/+database/+fun/find_ingested_docs.m.md'
             - ndi.database.fun.findallantecedents: 'NDI-matlab/reference/+ndi/+database/+fun/findallantecedents.m.md'
             - ndi.database.fun.findalldependencies: 'NDI-matlab/reference/+ndi/+database/+fun/findalldependencies.m.md'
+            - ndi.database.fun.finddocs_elementEpochType: 'NDI-matlab/reference/+ndi/+database/+fun/finddocs_elementEpochType.m.md'
             - ndi.database.fun.finddocs_missing_dependencies: 'NDI-matlab/reference/+ndi/+database/+fun/finddocs_missing_dependencies.m.md'
             - ndi.database.fun.lookup_uberon_term: 'NDI-matlab/reference/+ndi/+database/+fun/lookup_uberon_term.m.md'
             - ndi.database.fun.ndi_document2ndi_object: 'NDI-matlab/reference/+ndi/+database/+fun/ndi_document2ndi_object.m.md'
@@ -277,6 +278,7 @@
           - ndi.docs.schemastructure2docstructure: 'NDI-matlab/reference/+ndi/+docs/schemastructure2docstructure.m.md'
         - element PACKAGE:
           - ndi.element.downsample: 'NDI-matlab/reference/+ndi/+element/downsample.m.md'
+          - ndi.element.missingepochs: 'NDI-matlab/reference/+ndi/+element/missingepochs.m.md'
           - ndi.element.oneepoch: 'NDI-matlab/reference/+ndi/+element/oneepoch.m.md'
           - ndi.element.oneepoch_bkup: 'NDI-matlab/reference/+ndi/+element/oneepoch_bkup.m.md'
           - ndi.element.timeseries: 'NDI-matlab/reference/+ndi/+element/timeseries.m.md'

docs/NDI-matlab/tutorials/analyzing_first_physiology_experiment/5_searching_ndi_databases.md

@@ -53,7 +53,7 @@ Here we see that [ndi.document](https://vh-lab.github.io/NDI-matlab/reference/%2
 
 ## 2.5.2 All [ndi.document](https://vh-lab.github.io/NDI-matlab/reference/%2Bndi/document.m/) objects have the fields `document_class` and `base`.
 
-The `document_class` fields contain critical information about the class, such as the file that contains its definition, its full class name and its short class name. In addition, document types can be composed of multiple document types. The [stimulus presentation](https://vh-lab.github.io/NDI-matlab/documents/stimulus/stimulus_presentation/) class has two superclasses: [ndi.document](https://vh-lab.github.io/NDI-matlab/documents/base/) and [ndi.document_epochid](https://vh-lab.github.io/NDI-matlab/documents/epochid/). This means that a [stimulus_presentation](https://vh-lab.github.io/NDI-matlab/documents/stimulus/stimulus_presentation/) document has its own fields, plus all of the fields from [ndi.document](https://vh-lab.github.io/NDI-matlab/documents/base/) documents and and [ndi.document_epochid](https://vh-lab.github.io/NDI-matlab/documents/epochid/) documents. 
+The `document_class` fields contain critical information about the class, such as the file that contains its definition and its class name. In addition, document types can be composed of multiple document types. The [stimulus presentation](https://vh-lab.github.io/NDI-matlab/documents/stimulus/stimulus_presentation/) class has two superclasses: [ndi.document](https://vh-lab.github.io/NDI-matlab/documents/base/) and [ndi.document_epochid](https://vh-lab.github.io/NDI-matlab/documents/epochid/). This means that a [stimulus_presentation](https://vh-lab.github.io/NDI-matlab/documents/stimulus/stimulus_presentation/) document has its own fields, plus all of the fields from [ndi.document](https://vh-lab.github.io/NDI-matlab/documents/base/) documents and and [ndi.document_epochid](https://vh-lab.github.io/NDI-matlab/documents/epochid/) documents. 
 
 Let's look at the data that specifies the superclasses:
 
@@ -108,8 +108,8 @@ results back to the database. The object [ndi.query](https://vh-lab.github.io/ND
 #### Code block 2.5.3.1. Type this into Matlab.
 
 ```matlab
-% search for document classes that contain the string 'stim'
-q_stim = ndi.query('document_class.class_name','contains_string','stim',''); 
+% search for document classes of type 'stimulus_presentation'
+q_stim = ndi.query('','isa','stimulus_presentation',''); 
 stim_docs = S.database_search(q_stim)
   % returns 35 matches for me