Merge branch 'dev/example' into 'development'

Implements #73, cleans up example file,

See merge request !37

+PlotID/@config/config.m

@@ -6,7 +6,8 @@ classdef config < handle
       
     properties (SetAccess = private)
         mandatoryFields = {'Author', 'ProjectID'} 
-        optionFields 
+        optionFields
+        configPath
     end
     
     properties (SetAccess = protected)
@@ -28,7 +29,7 @@ classdef config < handle
                   obj.exportPath = obj.configData.ExportPath;
                   obj.configData.options.Location = 'exportPath';
               end
-            catch 
+             catch 
                 msg = ['no valid config File with the filename ',...
                     obj.configFileName, ' found.' newline,...
                     'Please enter the required information manually'];
@@ -39,7 +40,7 @@ classdef config < handle
                    obj.writeConfig(fullfile(pwd));
                 end
             end%try
-            
+            obj.configPath = which(obj.configFileName);
         end
         
         function outputArg = checkConfig(obj)
@@ -64,8 +65,10 @@ classdef config < handle
             %writeConfig writes the config file to path
             %   TODo;            
            obj.configData.options = obj.plotID_options(mode);
-        end
-            
+           cpath = fileparts(obj.configPath); 
+           obj.writeConfig(cpath);
+        end         
+         
         function outputArg = method1(obj,inputArg)
             %METHOD1 Summary of this method goes here
             %   Detailed explanation goes here
@@ -76,7 +79,8 @@ classdef config < handle
     
     methods (Static)
         configStruct = wizard(mode)
-        optionStruct = plotID_options(input)
+        optionStruct = plotID_options(input)       
+
     end
 end
 

+PlotID/Publish.m

@@ -58,6 +58,12 @@ if numel(figure) > 1
     warning(msg);
 end
 
+% catch missing .m extension
+[~,~, scriptExt] = fileparts(scriptPath);
+if isempty(scriptExt)
+    scriptPath = [scriptPath,'.m'];
+end
+
 %get ID from Figure
 ID = figure.Tag;
 
@@ -183,6 +189,9 @@ switch options.Method
             if any(idx)
                 fList.path = fullfile(fList.folder,fList.name);
                 sourcePath = fList{idx,'path'};
+                if ~iscell(sourcePath)
+                    sourcePath = {sourcePath};
+                end
                 relativeSourcePath = strrep(sourcePath,currentPath,'');
                                 
                 if contains(sourcePath,{'.h5','.hdf5'}) % Linking only for HDF5

+PlotID/TagPlot.m

@@ -18,7 +18,7 @@ arguments
     options.Color (1,3)  {mustBeNonnegative} = 0.65*[1 1 1] % grey
     options.Location (1,:) {mustBeMember(options.Location,{'north','east',...
         'southeast','south','west','custom'})} = 'east'
-    options.DistanceToAxis {mustBeReal} = .01 % relative distance
+    options.DistanceToAxis {mustBeReal} = .02 % relative distance
     options.Position (1,2) {mustBeVector} = [1,0.4] % default for east
     options.Rotation (1,1) {mustBeReal} = NaN
     options.ConfigFileName (1,:) {mustBeText} = 'config.json'

.gitignore

 # config file changes
-config.json
+config*.json
 
 # Windows default autosave extension
 *.asv
@@ -38,6 +38,7 @@ testdata_2.h5
 testdata2.h5
 test_data.mat
 export/*
+Examples/export/*
 unused*/*
 
 # Octave session info

Examples/PlodID_advanced.m

+clear; close all; clc;
+%%  Tag and export multiple plots
+% here the work flow for tagging and exporting multiple plots is shown
+
+% plots and data
+fig(1) = figure;
+[x1, y1, datapath1] = createExampleData('matlab');
+plot(x1,y1,'-b'); box off; hold on; set(gca, 'TickDir', 'out', 'YLim', [0,4]);
+
+fig(2) = figure;
+[x2, y2, datapath2] = createExampleData('hdf');
+plot(x2,y2,'-r'); box off; set(gca, 'TickDir', 'out', 'YLim', [0,4]);
+
+%% 1. Tag both plots 
+[fig, IDs] = PlotID.TagPlot(fig);
+
+% data locations
+script = [mfilename('fullpath'),'.m']; % filename of the m.script
+% file names of the datasets
+rdata =  {datapath1, datapath2} ; 
+
+%% 2. publish via a for-loop
+for i=1: numel(fig)
+    PlotID.Publish(rdata{i}, script, fig(i));
+end
+
+%% Debugging
+% Publish has two options that helps you with debugging:
+% you can activate messages from each step of Publish with
+% 'ShowMessages', true
+% you can force publish to skip "Soft errors" with the option
+% 'ForcePublish', true 
+% and check the output folder
\ No newline at end of file

Examples/PlotID_centralized.m

+clear; close all; clc;
+%%  multiple plots from the same data-set (centralized method)
+% A central data folder is used for saving the research data files, the
+% subfolders contain linked hdf5-files (if hdf5 is used) otherwise the data
+% will only be in the data folder.
+
+% This is recommended, if many plots are made from the same data set.
+% Attention, the linked HDF5 will not work when a subfolder was moved or the data
+% folder was deleted
+
+[x, y, datapath] = createExampleData('hdf');
+scriptPath = [mfilename('fullpath'),'.m'];
+
+fig1 = figure;
+plot(x,y,'-k'); 
+[fig1, ID] = PlotID.TagPlot(fig1);
+
+PlotID.Publish(datapath,scriptPath, fig1, 'Method','centralized')
+
+% Second figure based on the same data set as fig1
+fig2 = figure;
+plot(x.^2,y,'-r'); 
+[fig2, ID] = PlotID.TagPlot(fig2);
+
+PlotID.Publish(datapath,scriptPath, fig2, 'Method','centralized')
\ No newline at end of file

Examples/PlotID_config.m

+%% Working with one config file
+
+%% add custom publish options to the config file
+% you can define custom options in the config file:
+
+configFileName = 'config.json';
+configObj = PlotID.config(configFileName);
+
+% This method adds the default config to your config file
+configObj.addPublishOptions('default');
+% You can change this in the json file, but be carefull no
+% argumentValidation will be done on options from the config file!
+
+%% Working with multiple (project dependend) config files
+% it is possible to use individual config files for each project
+% configP1.json, configP2.json ... 
+
+% Create a new config file programatically 
+customConfigFileName = 'configP1.json';
+configObj = PlotID.config(customConfigFileName);
+configObj.addPublishOptions('default');
+
+% Use the custom Config
+% you need to provide the name of your custom config file to tagplot as
+% well as to publish by using the Name-Value Pair:
+% 'ConfigFileName','YOURNAME.json'
+
+% [figs, IDs] = PlotID.TagPlot(figs, 'ConfigFileName','configP1.json');
+% Publish(DataPaths,scriptPath, 'ConfigFileName','configP1.json')

Examples/PlotID_example_fcn.m

+function [outputArg1] = PlotID_example_fcn(inputArg1)
+%PlotID_example_fcn is just a dummy function
+outputArg1 = inputArg1;
+
+end
+

Examples/createExampleData.m

+function [x,y, fpath] = createExampleData(option)
+%CREATEEXAMPLEDATA creates x,y Data needed for all PlotID Examples
+%  fpath contains the file path of the example data
+
+switch option
+    case 'hdf'
+        if isfile('test_hdf_data.h5')
+           % hdf files can not simply be overwritten
+            delete test_hdf_data.h5;
+        end        
+        % some data for the .h5 file
+        x = linspace(0,2*pi); y = sin(x)+2;
+
+        % define filepath & name
+        dataset = 'test_hdf_data.h5';
+        dataset = fullfile(pwd,dataset);
+        fpath = dataset;
+
+        % create hdf5 file and dataset > write data to hdf5 file / dataset
+        h5create(fpath, "/x", size(x), "Datatype", class(x))
+        h5create(fpath, "/y", size(y), "Datatype", class(y))
+        h5write(fpath, "/x", x)
+        h5write(fpath, "/y", y)
+    case 'matlab'
+        % Creating Random Data to use as data-file
+        x = linspace(0,7); y = rand(1,100)+2;
+        dataset = 'test_data.mat';
+        % Use absolute paths for good practise
+        fpath = fullfile(pwd,dataset);
+        save(dataset,'x','y');
+    otherwise
+        error('option not defined')
+end
+
+end
+

PlotID_example.m

 %% Example Script
 % This Script is meant to demonstrate the capabilities of the PlotID tool.
-
-%% Clear Environment
+% please run Initilisation.m before first time usage 
+%% Clear an set Environment
 clear; clc; close all;
+addpath('Examples');
 
-try
-    delete testdata2.h5;
-end
-
-%% Set ProjectID
-% ProjectID can also be set in the config file 
-
-% Leave empty for using the ID from the config file
-ProjectID = 'Example';
+%% Data (only necessary for this example)
+[x, y, datapath] = createExampleData('matlab');
 
-%% Data
-% only necessary for this example
-
-% Creating Random Data to use as data-file
-x = linspace(0,7); y = rand(1,100)+2;
-dataset1 = 'test_data.mat';
+%% Plotting
+% This is still part of a normal script to produce plots.
+% Make sure to save each figure in a variable to pass it to PlotID-functions.
+fig1 = figure;
+plot(x,y,'-k'); box off; set(gca, 'TickDir', 'out', 'YLim', [0,4]);
 
-% Use absolute paths for good practise
-dataset1 = fullfile(pwd,dataset1);
-save(dataset1,'x','y');
+%% Basic Usage
+% PlotID Implementation starts here.
+%% 1. Tag the plot
+% TagPlot adds visible ID(s) to the figure(s) and to the figures property 'Tag'
+% every time you run tagPlot you will get an new ID
 
-% some data for the .h5 file
-x1 = linspace(0,2*pi); y1 = sin(x1)+2;
+% Syntax: 
+% fig = PlotID.TagPlot(fig);
+% [figs, IDs] = PlotID.TagPlot(figs);
+% [figs, IDs] = PlotID.TagPlot(figs, options);
 
-% define filepath & name
-dataset2 = 'testdata2.h5';
-dataset2 = fullfile(pwd,dataset2);
-fpath = dataset2;
+[fig1, ID] = PlotID.TagPlot(fig1);
 
-% create hdf5 file and dataset > write data to hdf5 file / dataset
-h5create(fpath, "/x1", size(x1), "Datatype", class(x1))
-h5create(fpath, "/y1", size(y1), "Datatype", class(y1))
-h5write(fpath, "/x1", x1)
-h5write(fpath, "/y1", y1)
+% you can influence the design and position of the Tag with the following
+% Name-Value Arguments: 'Fontsize', 'Color', 'Location',
+% 'DistanceToAxis','Position','Rotation' 
 
-%% function calls
-% Place for post-processing of the data, or additional related code.
-% example_fcn is a dummy function to show the functionality
-a = 1; a = example_fcn(a); 
-% Uncomment to include the Statistics and Machine learning Toolbox
-% p = betacdf(0.5,1,1); % to test toolboxes
+fig2 = figure; plot(x,y,'-k'); box off; set(gca, 'TickDir', 'out', 'YLim', [0,4]);
 
-%% Plotting
-% This is still part of a normal script to produce plots.
-% Make sure to save each figure in a variable
-% to pass it to PlotID-functions.
-fig(1) = figure;
-plot(x,y,'-k');
-box off; hold on;
-plot(x1,y1,'-r');
-set(gca, 'TickDir', 'out', 'YLim', [0,4]);
+% Example: blue tag with fontsize 12 in the south
+[fig2, ID] = PlotID.TagPlot(fig2, 'FontSize', 12, 'Color', [0 0 1],...
+    'Location','south');
 
-%% Example 1: single plot based on two data-sets
+% You can find the description to all options in the readme
 
-%% Tag the plot
-% PlotID Implementation starts here.
-% TagPlot adds a visible ID to the figure(s) and to the figures property
-% 'Tag'
-% [fig, ID] = PlotID.TagPlot(fig, 'ProjectID', ProjectID);
-[fig, ID] = PlotID.TagPlot(fig);
-%% Publishing
+%% 2. Publishing
 % Second part of plotID 
+% Exports your Plot, the research Data and the associated scripts to a
+% folder named with your ID
+
 % The functions needs the file location of the script, the location of the
 % data and the figure and can take several options (see readme). 
 
-% filename of the m.script, extension must be added!
-scriptPath = [mfilename('fullpath'),'.m']; 
-
-% file names of the datasets
-
-%(defined above:) dataset1 = 'test_data.mat'; dataset2 = 'testdata2.h5'
-locations =  {dataset1,dataset2} ; % don't forget the extension
-locations =  {string(dataset1),dataset2};
-
-%call publishing
-PlotID.Publish(locations,scriptPath, fig(1), 'Location', 'local' ,'Method','individual')
+% Syntax: 
+% Publish(DataPaths,scriptPath, figure)
+% Publish(DataPaths,scriptPath, figure, options)
 
-%% Example 2: multiple plots plot, all based on dataset2 (hdf5)
-% for individual data-sets, use an appropriate array
-
-fig(2) = figure;
-plot(x,y,'-b');
-box off; hold on;
-plot(x1,y1,'--k');
-set(gca, 'TickDir', 'out', 'YLim', [0,4]);
-
-% tag both plots 
-[fig, IDs] = PlotID.TagPlot(fig,'ProjectID', ProjectID);
-
-% data locations
-script = [mfilename('fullpath'),'.m']; % filename of the m.script
-% file names of the datasets
-rdata =  dataset2 ; % don't forget the extension
+% Path of the m.script that you use for creating your plot.
+scriptPath = [mfilename('fullpath'),'.m']; 
 
-% publsihing via a for-loop
-for i=1: numel(fig)
-    PlotID.Publish(rdata, script, fig(i), 'Location', 'local',...
-        'Method','individual');
-end
+% file paths of the datasets used for the plot (don't forget the extension)
+% datapath = test_data.mat 
+locations =  datapath; 
 
-%% Second Plot with identical data to test centralized method
-% A central data folder is used for saving the research data files, the
-% subfolders contain linked hdf5-files (if hdf5 is used). This is
-% recommended, if many plots are made from the same data set.  Attention,
-% the linked HDF5 will not work when a subfolder was moved or the data
-% folder was deleted
+%call publish
+PlotID.Publish(locations,scriptPath, fig2)
 
-fig2 =figure;
-plot(x,y,'-k');
-hold on
-plot(x1,y1,'-r');
+% your plot, script and all the data that your provide are now published
 
-[fig2, ID] = PlotID.TagPlot(fig2,'ProjectID', ProjectID);
 
-PlotID.Publish(locations,scriptPath, fig2, 'Location', 'local','Method','centralized')
+%% Further examples and help
+% You find more examples in the Examples folder:
+% Advanced Usage 
+% Working with HDF5-files
+% Using a central data folder
+% How to use advanced config-files
\ No newline at end of file

example_fcn.m

-function [outputArg1] = example_fcn(inputArg1)
-%TEST_2 just a dummy function
-outputArg1 = inputArg1;
-
-end
-