Documentation: Restructure documentation based on Diátaxis framework

+io/+config/+enum/ConfigurationProfile.m

@@ -0,0 +1,19 @@
+classdef ConfigurationProfile < handle
+%CONFIGURATIONPROFILE Dataset configuration profiles recognised by MatNWB.
+%
+%  Use these enumeration members when selecting chunking/compression presets
+%  via NwbFile.applyDatasetSettingsProfile, or nwbExport.  Profiles map to 
+%  JSON files in the ``configuration`` folder:
+%
+%    * ``default`` – general-purpose balance of size and performance.
+%    * ``cloud`` – tuned for object storage and remote streaming access.
+%    * ``archive`` – favors compact, long-term storage.
+%    * ``none`` – opt out of applying a profile entirely.
+
+    enumeration
+        none
+        default
+        cloud
+        archive
+    end
+end

+io/+config/readDatasetConfiguration.m

@@ -1,4 +1,4 @@
-function datasetConfig = readDatasetConfiguration(profile)
+function datasetConfig = readDatasetConfiguration(profile, options)
 % READDATASETCONFIGURATION Reads the default dataset configuration from a JSON file.
 %
 % Syntax:
@@ -20,22 +20,61 @@
 %
 %    % Load the default dataset configuration
 %    datasetConfig = io.config.readDatasetConfiguration();
+%    disp(datasetConfig);
+%
+% Example 2 - Load dataset configurations from a specific file ::
+%
+%    datasetConfig = io.config.readDatasetConfiguration("FilePath", "configuration_file.json");
 %    disp(datasetConfig);
 
     arguments
-        profile (1,1) string {mustBeMember(profile, [ ...
-            "default", ...
-            "cloud", ...
-            "archive"
-            ])} = "default"
+        profile (1,1) io.config.enum.ConfigurationProfile = "default"
+        options.FilePath string {mustBeJsonFileOrEmpty} = string.empty
     end
 
-    filename = sprintf('%s_dataset_configuration.json', profile);
+    if profile == io.config.enum.ConfigurationProfile.none && isempty(options.FilePath)
+        datasetConfig = [];
+        return
+    end
 
-    configFilePath = fullfile(misc.getMatnwbDir, 'configuration', filename);
+    % If FilePath is specified, we use that file
+    if ~isempty(options.FilePath)
+        configFilePath = options.FilePath;
+    else
+        filename = sprintf('%s_dataset_configuration.json', profile);
+        configFilePath = fullfile(misc.getMatnwbDir, 'configuration', filename);
+    end  
+
     datasetConfig = jsondecode(fileread(configFilePath));
     datasetConfig = datasetConfig.datasetSpecifications;
 
     datasetConfig = io.config.internal.applyCustomMatNWBPropertyNames(datasetConfig);
     datasetConfig = io.config.internal.flipChunkDimensions(datasetConfig);
 end
+
+function mustBeJsonFileOrEmpty(value)
+%MUSTBEJSONFILEOREMPTY Validate that input is a JSON file path or empty
+%
+%   mustBeJsonFileOrEmpty(VALUE) throws an error if VALUE is not empty and
+%   not a character vector or string scalar ending with '.json' (case-insensitive).
+
+    arguments
+        value string
+    end
+
+    if isempty(value)
+        return
+    end
+
+    assert(isscalar(value), ...
+        "NWB:validator:mustBeJsonFileOrEmpty:InvalidInput", ...
+        "Value must be a string scalar, character vector, or empty.");
+
+    assert(endsWith(value, ".json", "IgnoreCase", true), ...
+        "NWB:validator:mustBeJsonFileOrEmpty:InvalidFileType", ...
+        "Value must end with '.json'.");
+
+    assert(exist(value, "file") == 2, ...
+        "NWB:validator:mustBeJsonFileOrEmpty:FileMustExist", ...
+            "Value must be the name of an existing json file.")
+end

+io/+config/resolveDatasetConfiguration.m

@@ -0,0 +1,48 @@
+function datasetConfig = resolveDatasetConfiguration(input)
+% resolveDatasetConfiguration - Resolves the dataset configuration based on the input.
+%
+% Syntax:
+%   datasetConfig = io.config.resolveDatasetConfiguration(input) 
+%   This function resolves NWB dataset configurations from the specified input, 
+%   which can be a file path or a structure. If no input is provided, it 
+%   uses the default NWB dataset configuration profile.
+%
+% Input Arguments:
+%   input {mustBeStringOrStruct} - A value to resolve configurations for,
+%   which can either be a string representing the file path to the
+%   configurations or a struct containing the configurations directly.
+%
+% Output Arguments:
+%   datasetConfig - The NWB dataset configurations, returned as a structure.
+
+    arguments
+        input {mustBeStringOrStruct} = struct.empty
+    end
+
+    if isempty(input)
+        disp('No dataset settings provided, using default dataset settings profile.')
+        datasetConfig = io.config.readDatasetConfiguration();
+
+    elseif ischar(input) || (isstring(input) && isscalar(input))
+        input = string(input);
+        if isfile(input)
+            datasetConfig = io.config.readDatasetConfiguration("FilePath", input);
+        else
+            datasetConfig = io.config.readDatasetConfiguration(input);
+        end
+
+    elseif isstruct(input)
+        datasetConfig = input;
+    end
+end
+
+function mustBeStringOrStruct(value)
+    isValid = isempty(value) || ...
+        ischar(value) || (isstring(value) && isscalar(value)) || ...
+        isstruct(value);
+
+    assert(isValid, ...
+        'NWB:ResolveDatasetSettings:InvalidInput', ...
+        ['Expected datasetSettings to be a string (profile name or filename) ' ...
+        'or a struct (already loaded settings).'])
+end

+tests/+unit/+io/+config/ApplyDatasetConfigurationTest.m

@@ -274,5 +274,24 @@ function testApplyCustomMatNWBPropertyNames(testCase)
             testCase.verifyTrue( isfield(updatedConfig, 'VectorData_data') );
             testCase.verifyTrue( isfield(updatedConfig, 'GrayscaleImage_data') );
         end
+
+        function testNwbFileApplyDatasetSettingsProfile(testCase)
+            nwbFile = tests.factory.NWBFile();
+
+            largeSeries = types.core.TimeSeries( ...
+                'data', rand(64, 100000), ...
+                'data_unit', 'n/a', ...
+                'timestamps', 1:100000);
+
+            nwbFile.acquisition.set('data', largeSeries);
+
+            datasetConfig = nwbFile.applyDatasetSettingsProfile('cloud');
+
+            resultPipe = nwbFile.acquisition.get('data').data;
+            testCase.verifyTrue(isa(resultPipe, 'types.untyped.DataPipe'), ...
+                'applyDatasetSettings should configure datasets using named profile');
+            testCase.verifyTrue(isstruct(datasetConfig), ...
+                'applyDatasetSettings should return the dataset configuration that was applied');
+        end
     end
 end

+tests/+unit/+io/+config/FunctionsTest.m

@@ -0,0 +1,46 @@
+classdef FunctionsTest < matlab.unittest.TestCase
+% FunctionsTest - Test inputs and outputs of functions in io.config namespace
+
+    methods (Test)
+        function testReadDatasetConfiguration(testCase)
+            % Test with no inputs:
+            defaultDatasetConfig = io.config.readDatasetConfiguration();
+            testCase.verifyClass(defaultDatasetConfig, 'struct')
+
+            % Test with configuration profile name
+            cloudDatasetConfig = io.config.readDatasetConfiguration('cloud');
+            testCase.verifyClass(cloudDatasetConfig, 'struct')
+            testCase.verifyNotEqual(cloudDatasetConfig, defaultDatasetConfig)
+
+            % Test with configuration profile name "none"
+            noConfig = io.config.readDatasetConfiguration('none');
+            testCase.verifyEmpty(noConfig')
+
+            % Test with filepath input
+            filename = 'default_dataset_configuration.json';
+            configFilePath = fullfile(misc.getMatnwbDir, 'configuration', filename);
+            defaultDatasetConfigFromFile = io.config.readDatasetConfiguration('FilePath', configFilePath);
+            testCase.verifyEqual(defaultDatasetConfigFromFile, defaultDatasetConfig)
+        end
+
+        function testResolveDatasetConfiguration(testCase)
+            % Test with no inputs (capture command window output):
+            C = evalc("defaultDatasetConfigA = io.config.resolveDatasetConfiguration()"); %#ok<NASGU>
+            testCase.verifyClass(defaultDatasetConfigA, 'struct')
+
+            % Test with structure input, i.e already loaded configuration
+            defaultDatasetConfigB = io.config.resolveDatasetConfiguration(defaultDatasetConfigA);
+            testCase.verifyEqual(defaultDatasetConfigB, defaultDatasetConfigA)
+
+            % Test with profile name
+            defaultDatasetConfigC = io.config.resolveDatasetConfiguration("default");
+            testCase.verifyEqual(defaultDatasetConfigC, defaultDatasetConfigA)
+
+            % Test with filepath input
+            filename = 'default_dataset_configuration.json';
+            configFilePath = fullfile(misc.getMatnwbDir, 'configuration', filename);
+            defaultDatasetConfigD = io.config.resolveDatasetConfiguration(configFilePath);
+            testCase.verifyEqual(defaultDatasetConfigD, defaultDatasetConfigA)
+        end
+    end
+end

+tests/+unit/nwbExportTest.m

@@ -156,6 +156,25 @@ function testExportTimeseriesWithoutStartingTimeRate(testCase)
                 'NWB:CustomConstraintUnfulfilled')
         end
 
+        function testExportAppliesDatasetSettingsOption(testCase)
+            nwb = tests.factory.NWBFile();
+            largeSeries = types.core.TimeSeries( ...
+                'data', rand(64, 100000), ...
+                'data_unit', 'n/a', ...
+                'timestamps', 1:100000);
+
+            nwb.acquisition.set('export_data', largeSeries);
+
+            nwbFilePath = testCase.getRandomFilename();
+            nwbExport(nwb, nwbFilePath, 'DatasetSettingsProfile', 'cloud');
+
+            configuredData = nwb.acquisition.get('export_data').data;
+            testCase.verifyTrue(isa(configuredData, 'types.untyped.DataPipe'), ...
+                'nwbExport should configure datasets when DatasetSettings option is provided');
+            testCase.verifyTrue(isfile(nwbFilePath), ...
+                'nwbExport should still write the requested file');
+        end
+
         function testEmbeddedSpecs(testCase)
 
             % Install extensions, one will be used, the other will not. 

NwbFile.m

@@ -90,6 +90,99 @@ function export(obj, filename, mode)
             end
         end
 
+        function datasetConfig = applyDatasetSettingsProfile(obj, profile, options)
+        % APPLYDATASETSETTINGSPROFILE - Configure datasets using predefined settings profile
+        %
+        % Syntax:
+        %  nwb.applyDatasetSettingsProfile(profile) applies a dataset
+        %  configuration profile to the nwb-file ``nwb``. Available profiles:
+        %  "default", "cloud", "archive". This will configure datasets in
+        %  the NwbFile object for chunking and compression.
+        % 
+        % Input Arguments:
+        %  - obj (NwbFile) - 
+        %    An instance of the NwbFile class.
+        % 
+        %  - profile (ConfigurationProfile) - 
+        %    Specifies the settings profile to use. Default is "none".
+        %
+        % Name-Value Arguments:
+        %  - OverrideExisting (logical) - 
+        %    This boolean determines if existing DataPipe objects in the
+        %    file will be reconfigured with the provided options. Default is
+        %    false. **Important**: This does not work for DataPipes that has
+        %    previously been exported to file.
+        % 
+        % Output Arguments:
+        %  - datasetConfig - 
+        %    (Optional) The configuration settings applied to the dataset.
+        %
+        % See also:
+        %   io.config.enum.ConfigurationProfile
+        %   NwbFile.applyDatasetSettings
+
+            arguments
+                obj (1,1) NwbFile
+                profile (1,1) io.config.enum.ConfigurationProfile
+                options.OverrideExisting (1,1) logical = false
+            end
+
+            datasetConfig = io.config.readDatasetConfiguration(profile);
+            nvPairs = namedargs2cell(options);
+            obj.applyDatasetSettings(datasetConfig, nvPairs{:});
+            if ~nargout
+                clear datasetConfig
+            end
+        end
+
+
+        function datasetConfig = applyDatasetSettings(obj, settingsReference, options)
+        % APPLYDATASETSETTINGS - Configure datasets using NWB dataset settings
+        %
+        % Syntax:
+        %  nwb.applyDatasetSettings(settingsReference) applies a dataset
+        %  configuration profile to the nwb-file ``nwb``. This method
+        %  accepts the filename of a custom configuration profile or a
+        %  structure representing a configuration profile.
+        % 
+        % Input Arguments:
+        %  - obj (NwbFile) - 
+        %    An instance of the NwbFile class.
+        % 
+        %  - settingsReference (string | struct) - 
+        %    The filename of a custom configuration profile or an in-memory
+        %    structure representing a configuration profile.
+        %
+        % Name-Value Arguments:
+        %  - OverrideExisting (logical) - 
+        %    This boolean determines if existing DataPipe objects in the
+        %    file will be reconfigured with the provided options. Default is
+        %    false. **Important**: This does not work for DataPipes that has
+        %    previously been exported to file.
+        % 
+        % Output Arguments:
+        %  - datasetConfig - 
+        %    (Optional) The configuration settings applied to the dataset.
+        %
+        % See also:
+        %   io.config.enum.ConfigurationProfile
+        %   NwbFile.applyDatasetSettingsProfile
+
+            arguments
+                obj (1,1) NwbFile
+                settingsReference
+                options.OverrideExisting (1,1) logical = false
+            end
+
+            datasetConfig = io.config.resolveDatasetConfiguration(settingsReference);
+
+            nvPairs = namedargs2cell(options);
+            io.config.applyDatasetConfiguration(obj, datasetConfig, nvPairs{:});
+            if ~nargout
+                clear datasetConfig
+            end
+        end
+
         function o = resolve(obj, path)
             if ischar(path)
                 path = {path};