diff --git a/NwbFile.m b/NwbFile.m index e7dcddbc..71bf9478 100644 --- a/NwbFile.m +++ b/NwbFile.m @@ -1,18 +1,23 @@ classdef NwbFile < types.core.NWBFile - % NWBFILE Root object representing data read from an NWB file. - % - % Requires that core and extension NWB types have been generated - % and reside in a 'types' package on the matlab path. - % - % Example. Construct an object from scratch for export: - % nwb = NwbFile; - % nwb.epochs = types.core.Epochs; - % nwbExport(nwb, 'epoch.nwb'); - % - % See also NWBREAD, GENERATECORE, GENERATEEXTENSION +% NWBFILE - Root object representing an NWB file. +% +% Requires that core and extension NWB types have been generated +% and reside in a ``+types`` namespace on the MATLAB search path. +% +% Usage: +% Example 1 - Construct a simple NwbFile object for export:: +% +% nwb = NwbFile; +% nwb.epochs = types.core.Epochs; +% nwbExport(nwb, 'epoch.nwb'); +% +% See also: +% nwbRead, generateCore, generateExtension methods function obj = NwbFile(propValues) + % NWBFILE - Create an NWB File object + arguments propValues.?types.core.NWBFile propValues.nwb_version @@ -26,7 +31,7 @@ end function export(obj, filename, mode) - % export - Export NWB file object + % EXPORT - Export NWB file object arguments obj (1,1) NwbFile @@ -98,10 +103,14 @@ function export(obj, filename, mode) end function objectMap = searchFor(obj, typename, varargin) - % Searches this NwbFile object for a given typename + % searchFor - Search for for a given typename within the NwbFile object + % % Including the full namespace is optional. - % WARNING: The returned paths are resolvable but do not necessarily - % indicate a real HDF5 path. Their only function is to be resolvable. + % + % .. warning:: + % The returned paths are resolvable but do not necessarily + % indicate a real HDF5 path. Their only function is to be resolvable. + objectMap = searchProperties(... containers.Map,... obj,... diff --git a/generateCore.m b/generateCore.m index 7349b8e1..c2b8fe6e 100644 --- a/generateCore.m +++ b/generateCore.m @@ -1,27 +1,40 @@ function generateCore(version, options) - % GENERATECORE Generate Matlab classes from NWB core schema files - % GENERATECORE() Generate classes (Matlab m-files) from the - % NWB core namespace file. By default, generates off of the most recent nwb-schema - % release. - % - % GENERATECORE(version) Generate classes for the - % core namespace of the listed version. - % - % A cache of schema data is generated in the 'namespaces' subdirectory in - % the current working directory. This is for allowing cross-referencing - % classes between multiple namespaces. - % - % Output files are generated placed in a '+types' subdirectory in the - % current working directory. - % - % GENERATECORE(__, 'savedir', saveDirectory) Generates the core class - % files in the specified directory. - % - % Example: - % generateCore(); - % generateCore('2.2.3'); - % - % See also GENERATEEXTENSION +% GENERATECORE - Generate Matlab classes from NWB core schema files +% +% Syntax: +% GENERATECORE() Generate classes (Matlab m-files) from the +% NWB core namespace file. By default, generates off of the most recent +% nwb-schema release. +% +% GENERATECORE(version) Generate classes for the +% core namespace of the listed version. +% +% GENERATECORE(__, Name, Value) Generate classes based on optional +% name-value pairs controlling the output . +% +% A cache of schema data is generated in the ``namespaces`` subdirectory in +% the matnwb root directory. This is for allowing cross-referencing +% classes between multiple namespaces. +% +% Output files are placed in a ``+types`` subdirectory in the +% matnwb root directory directory. +% +% Usage: +% Example 1 - Generate core schemas for the latest version of NWB:: +% +% generateCore(); +% +% Example 2 - Generate core schemas for an older version of NWB:: +% +% generateCore('2.2.3'); +% +% Example 3 - Generate and save classes in a custom location:: +% +% % Generates the core class files in the specified directory. +% generateCore('savedir', saveDirectory) +% +% See also: +% generateExtension arguments version (1,1) string {matnwb.common.mustBeValidSchemaVersion} = "latest" diff --git a/generateExtension.m b/generateExtension.m index f4184350..7bf14c93 100644 --- a/generateExtension.m +++ b/generateExtension.m @@ -1,22 +1,37 @@ function generateExtension(namespaceFilePath, options) - % GENERATEEXTENSION Generate Matlab classes from NWB extension schema file - % GENERATEEXTENSION(extension_path...) Generate classes - % (Matlab m-files) from one or more NWB schema extension namespace - % files. A registry of already generated core types is used to resolve - % dependent types. - % - % A cache of schema data is generated in the 'namespaces' subdirectory in - % the current working directory. This is for allowing cross-referencing - % classes between multiple namespaces. - % - % Output files are generated placed in a '+types' subdirectory in the - % current working directory. - % - % Example: - % generateExtension('schema\myext\myextension.namespace.yaml', 'schema\myext2\myext2.namespace.yaml'); - % - % See also GENERATECORE - +% GENERATEEXTENSION - Generate Matlab classes from NWB extension schema file +% +% Syntax: +% GENERATEEXTENSION(extension_path...) Generate classes (Matlab m-files) +% from one or more NWB schema extension namespace files. A registry of +% already generated core types is used to resolve dependent types. +% +% A cache of schema data is generated in the ``namespaces`` subdirectory in +% the matnwb root directory. This is for allowing cross-referencing +% classes between multiple namespaces. +% +% Output files are placed in a ``+types`` subdirectory in the +% matnwb root directory directory. +% +% Input Arguments: +% - namespaceFilePath (string) - +% Filepath pointing to a schema extension namespace file. This is a +% repeating argument, so multiple filepaths can be provided +% +% - options (name-value pairs) - +% Optional name-value pairs. Available options: +% +% - savedir (string) - +% A folder to save generated classes for NWB/extension types. +% +% Usage: +% Example 1 - Generate classes for custom schema extensions:: +% +% generateExtension('schema\myext\myextension.namespace.yaml', 'schema\myext2\myext2.namespace.yaml'); +% +% See also: +% generateCore + arguments (Repeating) namespaceFilePath (1,1) string {mustBeYamlFile} end diff --git a/nwbClearGenerated.m b/nwbClearGenerated.m index 8e0c6cfd..3e8cbc9c 100644 --- a/nwbClearGenerated.m +++ b/nwbClearGenerated.m @@ -1,9 +1,35 @@ function clearedNamespaceNames = nwbClearGenerated(targetFolder, options) - %% NWBCLEARGENERATED clears generated class files. +% NWBCLEARGENERATED - Clear generated class files. +% +% Syntax: +% NWBCLEARGENERATED() Clear generated class files from the ``+types`` +% folder in the matnwb root directory. +% +% Input Arguments: +% - targetFolder (string) - +% Path name for folder containing generated classes in a ``+types`` +% namespace folder. Default value is the matnwb root directory +% +% - options (name-value pairs) - +% Optional name-value pairs. Available options: +% +% - ClearCache (logical) - +% Whether to clear the cached schema data in the ``namespaces`` folder. +% Default is ``false`` +% +% Usage: +% Example 1 - Clear all generated classes in the matnwb root directory:: +% +% nwbClearGenerated(); +% +% See also: +% generateCore, generateExtension + arguments targetFolder (1,1) string {mustBeFolder} = misc.getMatnwbDir() options.ClearCache (1,1) logical = false end + typesPath = fullfile(targetFolder, '+types'); listing = dir(typesPath); moduleNames = setdiff({listing.name}, {'+untyped', '+util', '.', '..'}); @@ -26,4 +52,4 @@ clearedNamespaceNames = strrep(clearedNamespaceNames, '+', ''); clearedNamespaceNames = string(clearedNamespaceNames); end -end \ No newline at end of file +end diff --git a/nwbExport.m b/nwbExport.m index 655d891d..a481cec7 100644 --- a/nwbExport.m +++ b/nwbExport.m @@ -1,19 +1,41 @@ function nwbExport(nwbFileObjects, filePaths, mode) - %NWBEXPORT Writes an NWB file. - % nwbRead(nwb, filename) Writes the nwb object to a file at filename. - % - % Example: - % % Generate Matlab code for the NWB objects from the core schema. - % % This only needs to be done once. - % generateCore('schema\core\nwb.namespace.yaml'); - % % Create some fake fata and write - % nwb = NwbFile; - % nwb.session_start_time = datetime('now'); - % nwb.identifier = 'EMPTY'; - % nwb.session_description = 'empty test file'; - % nwbExport(nwb, 'empty.nwb'); - % - % See also GENERATECORE, GENERATEEXTENSION, NWBFILE, NWBREAD +%NWBEXPORT - Writes an NWB file. +% +% Syntax: +% NWBEXPORT(nwb, filename) Writes the nwb object to a file at filename. +% +% Input Arguments: +% - nwb (NwbFile) - Nwb file object +% - filename (string) - Filepath pointing to an NWB file. +% +% Usage: +% Example 1 - Export an NWB file:: +% +% % Create an NWB object with some properties: +% nwb = NwbFile; +% nwb.session_start_time = datetime('now'); +% nwb.identifier = 'EMPTY'; +% nwb.session_description = 'empty test file'; +% +% % Write the nwb object to a file: +% nwbExport(nwb, 'empty.nwb'); +% +% Example 2 - Export an NWB file using an older schema version:: +% +% % Generate classes for an older version of NWB schemas: +% generateCore('2.5.0') +% +% % Create an NWB object with some properties: +% nwb = NwbFile; +% nwb.session_start_time = datetime('now'); +% nwb.identifier = 'EMPTY'; +% nwb.session_description = 'empty test file'; +% +% % Write the nwb object to a file: +% nwbExport(nwb, 'empty.nwb'); +% +% See also: +% generateCore, generateExtension, NwbFile, nwbRead arguments nwbFileObjects (1,:) NwbFile {mustBeNonempty} diff --git a/nwbRead.m b/nwbRead.m index 70ec5c6a..03b54791 100644 --- a/nwbRead.m +++ b/nwbRead.m @@ -1,21 +1,53 @@ function nwb = nwbRead(filename, flags, options) - %NWBREAD Reads an NWB file. - % nwb = NWBREAD(filename) Reads the nwb file at filename and returns an - % NWBFile object representing its contents. - % nwb = nwbRead(filename, 'ignorecache') Reads the nwb file without generating classes - % off of the cached schema if one exists. - % - % nwb = NWBREAD(filename, options) - % - % Requires that core and extension NWB types have been generated - % and reside in a 'types' package on the matlab path. - % - % Example: - % nwb = nwbRead('data.nwb'); - % nwb = nwbRead('data.nwb', 'ignorecache'); - % nwb = nwbRead('data.nwb', 'savedir', '.'); - % - % See also GENERATECORE, GENERATEEXTENSION, NWBFILE, NWBEXPORT +% NWBREAD - Read an NWB file. +% +% Syntax: +% nwb = NWBREAD(filename) Reads the nwb file at filename and returns an +% NWBFile object representing its contents. +% +% nwb = NWBREAD(filename, flags) Reads the nwb file using optional +% flags controlling the mode for how to read the file. See input +% arguments for a list of available flags. +% +% nwb = NWBREAD(filename, Name, Value) Reads the nwb file using optional +% name-value pairs controlling options for how to read the file. +% +% Input Arguments: +% - filename (string) - +% Filepath pointing to an NWB file. +% +% - flags (string) - +% Flag for setting the mode for the NWBREAD operation. Available options are: +% 'ignorecache'. If the 'ignorecache' flag is used, classes for NWB data types +% are not re-generated based on the embedded schemas in the file. +% +% - options (name-value pairs) - +% Optional name-value pairs. Available options: +% +% - savedir (string) - +% A folder to save generated classes for NWB types. +% +% Output Arguments: +% - nwb (NwbFile) - Nwb file object +% +% Usage: +% Example 1 - Read an NWB file:: +% +% nwb = nwbRead('data.nwb'); +% +% Example 2 - Read an NWB file without re-generating classes for NWB types:: +% +% nwb = nwbRead('data.nwb', 'ignorecache'); +% +% Note: This is a good option to use if you are reading several files +% which are created of the same version of the NWB schemas. +% +% Example 3 - Read an NWB file and generate classes for NWB types in the current working directory:: +% +% nwb = nwbRead('data.nwb', 'savedir', '.'); +% +% See also: +% generateCore, generateExtension, NwbFile, nwbExport arguments filename (1,1) string {matnwb.common.mustBeNwbFile}