diff --git a/+PlotID/@config/config.m b/+PlotID/@config/config.m
new file mode 100644
index 0000000000000000000000000000000000000000..efb0f4e3ca3a1e232375e2c04dad7cbfde6a2271
--- /dev/null
+++ b/+PlotID/@config/config.m
@@ -0,0 +1,80 @@
+classdef config < handle
+ %CONFIG class handles methods and attributes related to the config
+ %file
+ %handle class used for dynamicy property updates
+
+ properties (SetAccess = private)
+ mandatoryFields = {'Author', 'ProjectID'}
+ optionFields
+ configPath
+ end
+
+ properties (SetAccess = protected)
+ configData
+ configFileName
+ exportPath = ''
+ end
+
+ methods
+ function obj = config(configFileName)
+ %CONFIG Construct an instance of this class
+ % reads config data from config file, if an error occurs the
+ % wizard is started by the catch block
+ obj.configFileName = configFileName;
+ try
+ txt = fileread(obj.configFileName);
+ obj.configData = jsondecode(txt);
+ assert(checkConfig(obj));
+ if isfield(obj.configData,'ExportPath')
+ obj.exportPath = obj.configData.ExportPath;
+ obj.configData.options.Location = 'exportPath';
+ end
+ catch
+ msg = ['no valid config File with the filename ',...
+ obj.configFileName, ' found.' newline,...
+ 'Please enter the required information manually'];
+ disp(msg);
+ obj.configData = obj.wizard('initialise');
+ m = input('Do you want to save the config, Y/N [Y]:','s');
+ if ismember(m,{'Y','y'})
+ obj.writeConfig(fullfile(pwd));
+ end
+ end%try
+ obj.configPath = which(obj.configFileName);
+ end
+
+ function outputArg = checkConfig(obj)
+ %checkConfig validates the config file
+ % 1. Check if mandatory Fields are set
+ check = isfield(obj.configData,obj.mandatoryFields);
+ outputArg = all(check);
+
+ end
+
+ function writeConfig(obj,path)
+ %writeConfig writes the config file to path
+ % TODo;
+ fid = fopen(fullfile(path,obj.configFileName),'w');
+ txt = jsonencode(obj.configData,'PrettyPrint',true);
+ %fprintf does not write paths correctly !!!
+ fwrite(fid,txt);
+ fclose(fid);
+ end
+
+ function configData = addPublishOptions(obj,mode)
+ %addPublishOptions adds the publsih options to the config
+ %object depending on the mode
+ obj.configData.options = obj.plotID_options(mode);
+ cpath = fileparts(obj.configPath);
+ obj.writeConfig(cpath);
+ end
+
+ end
+
+ methods (Static)
+ configStruct = wizard(mode)
+ optionStruct = plotID_options(input)
+
+ end
+end
+
diff --git a/+PlotID/@config/plotID_options.m b/+PlotID/@config/plotID_options.m
new file mode 100644
index 0000000000000000000000000000000000000000..aaa2f918802ae73342e723c7304de88a9200750a
--- /dev/null
+++ b/+PlotID/@config/plotID_options.m
@@ -0,0 +1,28 @@
+function [options] = plotID_options(input)
+%PLOTID_OPTIONS gives you a struct with all the options defined in publish
+% Two modes are implemented default and debug
+
+options = struct();
+switch input
+ case 'default' %same as Arguments Block
+ options.Location = 'local'; % storage path
+ options.Method = 'individual';
+ options.ParentFolder = 'export';
+ options.ConfigFileName = 'config.json';%individual config names possible
+ options.CopyUserFCN = true;
+ options.CSV = false;
+ options.ShowMessages = true;
+ options.ForcePublish = false; %publish anyway
+ case 'debug'
+ options.Location = 'local'; % storage path
+ options.Method = 'individual';
+ options.ParentFolder = 'export';
+ options.ConfigFileName = 'config.json';%individual config names possible
+ options.CopyUserFCN = true;
+ options.CSV = true;
+ options.ShowMessages = true;
+ options.ForcePublish = true; %publish anyway
+end
+
+end
+
diff --git a/+PlotID/@config/wizard.m b/+PlotID/@config/wizard.m
new file mode 100644
index 0000000000000000000000000000000000000000..dfca28602c445863be8357af07681520206355d8
--- /dev/null
+++ b/+PlotID/@config/wizard.m
@@ -0,0 +1,39 @@
+function config = wizard(mode)
+%wizard creates config files depending on the selected mode
+% initilise ask only for the input that is neccessary to run plotID
+
+config = struct();
+switch mode
+ case 'initialise'
+ config.Author = inputRequired('your Name');
+ config.ProjectID = inputRequired('your Project Number');
+
+ msg = ['Do you want to add an export path?' newline,...
+ 'Otherwise your files will be stored locally.' newline,...
+ 'You can add this later by rerunning the initiliasation.'];
+ disp(msg);
+ m = input('Do you want to add an export path? Y/N [Y]:','s');
+
+ if ismember(m,{'Y','y'})
+ config.ExportPath = uigetdir();
+ end
+ otherwise
+ error('wizard mode undefined in CLASS config');
+end %switch
+
+end
+
+function usrTxt = inputRequired(msg)
+%Input Dialog that repeats if left empty
+inputRequired = true;
+while inputRequired
+ prompt = ['Please enter ', msg , ': '];
+ inpt = input(prompt,'s');
+ if isempty(inpt)
+ disp('Input must not be empty!');
+ else
+ usrTxt = inpt;
+ inputRequired = false;
+ end
+end
+end
\ No newline at end of file
diff --git a/+PlotID/@userDLG/userDLG.m b/+PlotID/@userDLG/userDLG.m
new file mode 100644
index 0000000000000000000000000000000000000000..7b82f79cd84dfb8102cdd84412971710b8ad6765
--- /dev/null
+++ b/+PlotID/@userDLG/userDLG.m
@@ -0,0 +1,103 @@
+classdef userDLG
+ %userDLG the userDLG Class is responsible for the user dialog
+ % error handeling, user messages and warnings will be provided from
+ % this class, depending on the user options and error type.
+ % This reduces messaging overhead and code length in PlotID.Publish()
+
+ properties
+ configError = false
+ scriptPublished = false
+ rdFilesPublished = false
+ figurePublished = false
+ msg = ''
+ end
+
+ properties (SetAccess = protected)
+ success = false
+ showMessages {mustBeNumericOrLogical}
+ forcePublish {mustBeNumericOrLogical}
+ ID %plotID
+ end
+
+ methods
+ function obj = userDLG(ID,options)
+ %CATCHERROR Construct an instance of this class
+ if isempty(ID)
+ ID = '';
+ end
+ obj.ID = ID;
+ obj.showMessages = options.ShowMessages;
+ obj.forcePublish = options.ForcePublish;
+ end
+
+ function output = get.success(obj)
+ % checks if all publish operations are true
+ obj.success = all([obj.scriptPublished; obj.rdFilesPublished;...
+ obj.figurePublished]);
+ output = obj.success;
+ end
+
+ function obj = set.msg(obj,message)
+ %setmsg sets a message text
+ obj.msg = message;
+ end
+
+ function [status] = userDialog(obj,dialogMessage, errorMessage)
+ %userDialog displays Y/N user input
+ % if the user selects no an Error will be thrown
+ m = '';
+ while ~ismember(m,{'Y','y','n','N'})
+ m = input([dialogMessage,', Y/N [Y]? '],'s');
+ end
+ if ismember(m,{'Y','y'})
+ status = true;
+ else
+ obj.error(errorMessage)
+ end
+ end
+
+ function [] = userMSG(obj,message)
+ %userMSG user message without priority
+ % MSG will only be displaye if ShowMessages is true
+ if obj.showMessages
+ disp(message);
+ end
+ end
+
+ function [] = error(obj,message)
+ %error handles critical errors
+ % critical errors will always result in a matlab error
+
+ %ToDO: Add function(s) before termination
+ error(message);
+ end
+
+ function [] = softError(obj,message)
+ %softError handles soft errors
+ % soft errors can be changed to warning if ForcePublish is
+ % selected by the user
+ if obj.forcePublish
+ warning(message);
+ else
+ error(message);
+ end
+ end
+ end
+
+ methods(Static)
+ function [status] = userQuestion(dialogMessage)
+ %userQuestion displays Y/N user input
+ m = '';
+ while ~ismember(m,{'Y','y','n','N'})
+ m = input([dialogMessage,', Y/N [Y]? '],'s');
+ end
+ if ismember(m,{'Y','y'})
+ status = true;
+ else
+ status = false;
+ end
+ end
+ end %static
+
+end % class
+
diff --git a/+PlotID/Publish.m b/+PlotID/Publish.m
index 79ecc2b1799132e3890d2924bf90ec8b46a64d01..f134cc04ea24c06c6e8b92b3072cdd93627d1f23 100644
--- a/+PlotID/Publish.m
+++ b/+PlotID/Publish.m
@@ -1,46 +1,105 @@
-function Publish(DataPaths, ID, figure, options)
-%Publishes saves plot, data and measuring script
+function Publish(DataPaths,scriptPath, figure, options)
+%%Publish(DataPaths,scriptPath, ID, figure, options) saves plot, data and measuring script
+%
+% DataPaths contains the path(s) to the research data, for multiple files
+% use a cell array
+% scriptPath contains the path to the script, this can be provided with
+% the simple call of scriptPath = [mfilename('fullpath'),'.m']
+%
+% Options:
% Location sets the storage location. 'local' sets the storage location
-% to the current folder (an export folder will be created), 'server' is a
+% to the current folder (an export folder will be created), 'manual' opens
+% a explorer window, where you can choose the folder. If you define a export
+% path in the config file, this will used per default.
% remote path, that is defined in the config file.
% Two Methods are implemented 'individual' stores the data for
% each plot while 'centralized' uses a data folder and uses reference links
% to the original data (hdf5 only).
-% ParentFolder is the folder Name where the exported data is stored if an
+% 'ParentFolder' is the folder Name where the exported data is stored if an
% path is used, PlotId will use this path a storagePath
+% 'ConfigFileName' is needed for handling multiple config files (see example)
+% 'CSV' turns a summary table of all exports on or off
+%
+% DebugOptions:
+% 'ShowMessage' and 'ForcePublish' are mainly for debugging.
+% 'ShowMessage' will display Messages for every step of PlotID,
+% 'ForcePublish' will publish even if one step was not successful (not recommended)
arguments
- DataPaths
- ID (1,:) {mustBeNonzeroLengthText} % ID must be provided
+ DataPaths {mustBeDataPath} % location of the data-file(s)
+ scriptPath (1,:) {mustBeFile} % location of the matlab script
figure (1,:) {mustBeFigure} % Checks if figure is a figure object
options.Location {mustBeMember(options.Location ,{'local','server','manual','CI-Test'})} = 'local' % storage path
options.Method {mustBeMember(options.Method ,{'individual','centralized'})} = 'individual'
- options.ParentFolder (1,:) {mustBeText} = 'export'
- options.CopyUserFCN (1,1) {mustBeNumericOrLogical} = true
- options.CSV (1,1) {mustBeNumericOrLogical} = false
+ options.ParentFolder (1,:) {mustBeText} = 'PlotID_export' % name of the ParentFolder
+ options.ConfigFileName (1,:) {mustBeText} = 'config.json' %individual config names possible
+ options.CopyUserFCN (1,1) {mustBeNumericOrLogical} = true
+ options.CSV (1,1) {mustBeNumericOrLogical} = true
+ options.ShowMessages(1,1) {mustBeNumericOrLogical} = false
+ options.ForcePublish (1,1) {mustBeNumericOrLogical} = false %publish anyway
+
+end
+
+%% argument validation
+%catch string and non cell inputs in DataPaths
+if ~iscell(DataPaths)
+ DataPaths = {DataPaths}; %Cell array
+end
+
+% strings will cause problems, therefore chars are used
+for i=1:numel(DataPaths)
+ if isstring(DataPaths{i})
+ DataPaths{i} = char(DataPaths{i});
+ end
+end
+
+if isstring(scriptPath)
+ scriptPath = char(scriptPath);
end
%catch multiple figures in fig
if numel(figure) > 1
figure = figure(1);
- msg = ['Publish is designed for handeling one figure at once' newline,...
+ msg = ['Publish is designed for handling one figure at once' newline,...
'- publishes uses only the first figure.' newline , ...
'Consider an external for loop for multi figure export as provided in example.m'];
warning(msg);
end
-%% read config file
-try
- txt = fileread('config.json');
- config = jsondecode(txt);
- configError = false;
-catch
- msg = ['Error while reading the config file' newline,...
- ' publishing on server not possible'];
+% catch missing .m extension
+[~,~, scriptExt] = fileparts(scriptPath);
+if isempty(scriptExt)
+ scriptPath = [scriptPath,'.m'];
+end
+
+%get ID from Figure
+ID = figure.Tag;
+
+if isempty(ID)
+ % no ID found, user dialog for folder name
+ ID = inputdlg(['No ID defined- ' newline,...
+ 'Please enter a folder name to continue:'],'Please enter a folder name');
+ ID = ID{1};
+ msg = ['No ID found - consider to use the TagPlot function before ',...
+ 'you publish ', newline, 'your files will be stored in ' , ID];
warning(msg);
- configError = true;
end
+%% read config file
+% there is only one config Object (handleClass)
+configObj = PlotID.config(options.ConfigFileName);
+% read user options from config and set them for Publish
+if isfield(configObj.configData, 'options')
+ fldnames = fieldnames(configObj.configData.options);
+ for ii=1:numel(fldnames)
+ field = fldnames{ii};
+ options.(field) = configObj.configData.options.(field);
+ end
+end
+
+% error and MSG handling object
+dlgObj = PlotID.userDLG(ID,options);
+
%% storage location
switch options.Location
case 'local'
@@ -48,43 +107,75 @@ switch options.Location
storPath = options.ParentFolder;
else
% use the script path as export path
- scriptPath = fileparts(DataPaths.script);
- storPath = fullfile(scriptPath,options.ParentFolder);
+ scriptLocation = fileparts(scriptPath);
+ storPath = fullfile(scriptLocation,options.ParentFolder);
+ end
+ case 'exportPath'
+ if isfolder(configObj.exportPath)
+ storPath = configObj.exportPath;
+ else
+ msg = ['Your Export folder ', storPath, newline,...
+ 'does not exist, check the config file - publishing not possible!'];
+ dlgObj.error(msg);
+ end
+ case 'server' %legacy
+ if dlgObj.configError
+ msg = ['Error while reading the config file' newline,...
+ ' publishing on server not possible'];
+ dlgObj.error(msg);
end
- case 'server' %from config File
- storPath = config.ServerPath;
+ storPath = configObj.configData.ServerPath;
case 'manual' %UI
storPath = uigetdir();
- case 'CI-Test'
+ case 'CI-Test' %only for CI tests
storPath = fullfile(pwd,'CI_files',options.ParentFolder);
end
-folderName = char(ID);
-%% Create Data-Directory
+folderName = ['.',char(ID)]; % hidden folder
+folderNameV = char(ID); %visible Folder
+
+%% Create data directory
+overwriteDir = false;
+% if invisible Folder exists, delete it (publish was not successful before)
if isfolder(fullfile(storPath,folderName))
- error(['Folder ',folderName, ' exists - Plot was already published ']);
-elseif mkdir(fullfile(storPath,folderName))
-else
- error('Directory could not be created - check remote path and permissions');
+ rmdir(fullfile(storPath,folderName),'s')
+end
+% if folder already published: ask User
+if isfolder(fullfile(storPath,folderNameV))
+ msg = ['Folder ',folderNameV, ' exists - Plot was already published '];
+ disp(msg);
+ dialogMsg = 'Do you want to overwrite the existing files';
+ overwriteDir = dlgObj.userQuestion(dialogMsg);
+ if ~overwriteDir % USR does not want to overwrite
+ warning('PlotID has finished without an export');
+ disp('rerun TagPlot if you need a new ID or consider overwriting.');
+ return; %terminate
+ end
+end
+% create the folder
+if ~mkdir(fullfile(storPath,folderName))
+ dlgObj.error('Directory could not be created - check remote path and permissions');
end
disp(['publishing of ', ID, ' started']);
-%% Create a Copy of the script and user functions(optional)
+%% Create a copy of the script and user functions(optional)
% script
-PlotID.createFileCopy({[DataPaths.script,'.m']},folderName,storPath,ID, 'script');
+[~, status, msg] = PlotID.createFileCopy({scriptPath},folderName,storPath,ID, 'script');
+dlgObj.scriptPublished =status;
+dlgObj.userMSG(msg);
% user functions
-[fList,pList] = matlab.codetools.requiredFilesAndProducts(DataPaths.script);
+[fList,pList] = matlab.codetools.requiredFilesAndProducts(scriptPath);
if options.CopyUserFCN
- fList = fList(~ismember(fList,[DataPaths.script,'.m'])); % rmv script from list
+ fList = fList(~ismember(fList,scriptPath)); % rmv script from list
fList = fList(~contains(fList,'config.json')); % rmv config.json from list
- fList = PlotID.removePltIdFiles(fList); % Do not copy files that are part of plot ID
+ fList = PlotID.removePltIdFiles(fList); % Do not copy files that are part of PlotID
if ~isempty(fList)
PlotID.createFileCopy(fList,folderName,storPath,ID,'userFcn');
end
end
-%% Research data handeling
+%% Research data handling
switch options.Method
case 'centralized'
DataFolderName = 'data';
@@ -96,95 +187,140 @@ switch options.Method
currentPath = fullfile(storPath);
%list all files
- fList = dir(fullfile(storPath,DataFolderName, '**\*.*'));
+ fList = dir(fullfile(storPath,DataFolderName, ['**',filesep,'*.*']));
%get list of files and folders in any subfolder
fList = fList(~[fList.isdir]); %remove folders from list
fList = struct2table(fList);
% Check if the new plot is based on the original data-set
% copy the data(once)
- for i=1:numel(DataPaths.rdata)
+ for i=1:numel(DataPaths)
% check if identical file exists (status = 1)
- [~, idx] = PlotID.fileCompare(DataPaths.rdata{i},fList);
+ [~, idx] = PlotID.fileCompare(DataPaths{i},fList);
% create Linked HDF5 files for identical files
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.createLinkedHDF5(relativeSourcePath{1,1},storPath,ID);
+ linkedHDFPath = fullfile(storPath,folderName);
+ PlotID.createLinkedHDF5(relativeSourcePath{1,1},linkedHDFPath);
end
else % no identical file exists
%Copy the file in data and create the links (if hdf5)
- [dataPath] = PlotID.createFileCopy(DataPaths.rdata{i},'data',storPath,ID,'dataCentral');
- relativeDataPath = strrep(dataPath,currentPath,'');
+ [dataPath, status, msg] = PlotID.createFileCopy(DataPaths{i},'data',storPath,ID,'dataCentral');
+ pathToData = strrep(dataPath,currentPath,'');
%WIP
- if contains(DataPaths.rdata{i},{'.h5','.hdf5'}) % Linking only for HDF5
+ if contains(DataPaths{i},{'.h5','.hdf5'}) % Linking only for HDF5
% and create also linked files in the plot folder
- PlotID.createLinkedHDF5(relativeDataPath,storPath,ID);
+ linkedHDFPath = fullfile(storPath,folderName);
+ [status] = PlotID.createLinkedHDF5(pathToData,linkedHDFPath);
end %if
end %if
end %for
clear DataFolderName
case 'individual'
% Create a copy of the research data
- PlotID.createFileCopy(DataPaths.rdata,folderName,storPath,ID, 'data');
+ [~, status, msg] = PlotID.createFileCopy(DataPaths,folderName,storPath,ID, 'data');
end
+%temporary:
+dlgObj.rdFilesPublished = status;
+dlgObj.userMSG(msg);
+
%% Write Config File
+exportPath = fullfile(storPath,folderName);
+configObj.writeConfig(exportPath);
-if ~configError %config File must exist
- % copy config file
- configPath = PlotID.createFileCopy('config.json',folderName,...
- storPath,ID, 'data');
-else
- configPath = fullfile(storPath,folderName,'config.json');
- config = struct();
- if ispc
- config.author = getenv('USERNAME');
- end
-end
% add further Metadata
-config.ProjectID = ID;
-config.CreationDate = datestr(now);
-config.MatlabVersion = version;
-config.ToolboxVersions = pList;
-
-%write config
-fid = fopen(char(configPath),'w');
-txt = jsonencode(config,'PrettyPrint',true);
+meta = struct();
+if ispc
+ meta.author = getenv('USERNAME');
+end
+meta.ProjectID = ID;
+meta.CreationDate = datestr(now);
+meta.MatlabVersion = version;
+meta.ToolboxVersions = pList;
+
+% write meta
+metaPath = fullfile(storPath,folderName,'plotID_data.json');
+fid = fopen(char(metaPath),'w');
+txt = jsonencode(meta,'PrettyPrint',true);
fprintf(fid,txt);
fclose(fid);
%% Export the Plot
try
- PlotName = [ID,'_plot']; % plotname
- RemotePath = fullfile(storPath ,folderName, PlotName);
- % Matlab figure
- savefig(figure,RemotePath);
- % the png should only be a preview
- exportgraphics(figure,[RemotePath,'.png'],'Resolution',300);
+ PlotName = [ID,'_plot']; % plotname
+ RemotePath = fullfile(storPath ,folderName, PlotName);
+ % Matlab figure
+ savefig(figure,RemotePath);
+ % the png should only be a preview
+ exportgraphics(figure,[RemotePath,'.png'],'Resolution',300);
+ dlgObj.figurePublished = true;
catch
- warning('Plot export was not successful')
+ dlgObj.softError('Plot export was not successful');
end
-disp(['publishing of ', ID , ' done']);
+%% final renaming and error/warning handling
+% if no error occurred or if force publish is activated, rename the hidden
+% folder to a non hidden one, otherwise delete it.
+if dlgObj.success || options.ForcePublish
+ oldPath = fullfile(storPath,folderName);
+ newPath = strrep(oldPath,'.',''); %remove dot
+ if overwriteDir
+ rmdir(newPath,'s');
+ dlgObj.userMSG(['old export ', folderNameV, ' deleted']);
+ end
+ status = movefile(oldPath,newPath); %rename directory
+end
-% CSV EXport
+%% CSV export
if options.CSV
T = table();
- T.research_Data = DataPaths.rdata'; T.PlotID(:) = {ID};
- T.Script_Name(:) = {[DataPaths.script,'.m']};
- T.Storage_Location(:) = {storPath};
+ T.research_Data = DataPaths'; T.PlotID(:) = {ID};
+ T.Author(:) = {configObj.configData.Author};
+ T.Script_Name(:) = {scriptPath};
+ T.Storage_Location(:) = {newPath};
T.Date(:) = {datestr(now)};
- T = movevars(T,'PlotID','before',1);
- writetable(T, fullfile(storPath, 'overview_table.csv'),'WriteMode','append');
+ T = movevars(T,{'PlotID','Author'},'before',1);
+ writetable(T, fullfile(storPath, 'PlotID_overview.csv'),'WriteMode','append');
+end
+
+if status
+ disp(['publishing of ', ID , ' to ', newPath, ' done']); %always displayed on success
+else % publish was not successful!
+ dlgObj.error(['publishing of ', ID , ' failed'])
end
+
end %function
+%% Argument Validation Functions
function tf = mustBeFigure(h)
%checks if input is a figure object
tf = strcmp(get(h, 'type'), 'figure') & isa(h, 'matlab.ui.Figure');
end
+
+function mustBeDataPath(DataPaths)
+%checks if input is a valid DataPath object
+ if ~iscell(DataPaths)
+ DataPaths = {DataPaths};
+ end
+ tf = zeros(1,numel(DataPaths));
+
+ for i=1:numel(DataPaths)
+ tf(i) = ~isfile(DataPaths{i});
+ end
+
+ if any(tf)
+ eidType = 'mustBeDataPath:notaValidFilePath';
+ msgType = 'DataPaths must contain file-path(s)';
+ throwAsCaller(MException(eidType,msgType))
+ end
+end
+
diff --git a/+PlotID/TagPlot.m b/+PlotID/TagPlot.m
index 4a5965803f3f57eb5de1da8fce1ed84d070c5a0e..d940a5dc29e9cc7b4869e9f86eab8721b37437ed 100644
--- a/+PlotID/TagPlot.m
+++ b/+PlotID/TagPlot.m
@@ -2,55 +2,57 @@ function [figs, IDs] = TagPlot(figs, options)
%TagPlot adds IDs to figures
% The ID is placed visual on the figure window and as Tag (property of figure)
% TagPlot can tag multiple figures at once.
-% If a single Plot is taged IDs is a char, otherwise it is a cell array of
+% If a single Plot is tagged IDs is a char, otherwise it is a cell array of
% chars
% options.ProjectID is the project number (string or char), if empty the ID from the
% config file is used
%
-% The ID is placed on the 'east' per default, if you want it somwhere
+% The ID is placed on the 'east' per default, if you want it somewhere
% else, use the 'Location' option. 'north','east','south','west' are
% predefined, otherwise use the 'custom' option and provide the desired
% 'Position' (relative to your x- and y-axis limits)
+% 'ConfigFileName' is the config-file which is used for the ProjectID
+% If you use multiple config files you need to use this option.
arguments
figs (1,:) {mustBeFigure}
options.ProjectID (1,:) {mustBeText}= ''
- options.Fontsize (1,1) {mustBeInteger} = 8
- options.Location (1,:) {mustBeText} = 'east'
+ options.Fontsize (1,1) {mustBeInteger} = 8
+ 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} = .02 % relative distance
options.Position (1,2) {mustBeVector} = [1,0.4] % default for east
- options.Rotation (1,1) {mustBeInteger} = 0
+ options.Rotation (1,1) {mustBeReal} = NaN
+ options.ConfigFileName (1,:) {mustBeText} = 'config.json'
end
if isempty(options.ProjectID)
- try
- txt = fileread('config.json');
- config = jsondecode(txt);
- catch
- config =struct;
- config.ProjectID = '';
- warning("No ProjectID was definded and no config.json could be found");
-
- end
-
- if ~isempty(config.ProjectID)
- options.ProjectID = config.ProjectID;
- else
- warning('no project options.ProjectID defined')
- end
+ configObj = PlotID.config(options.ConfigFileName);
+ configData = configObj.configData;
+ options.ProjectID = configData.ProjectID;
end
switch options.Location
case 'north'
- options.Position = [0.4,0.95];
- options.Rotation = 0;
+ y = 1 - options.DistanceToAxis
+ options.Position = [0.4,y];
+ Rotation = 0;
case 'east'
- options.Position = [1,0.4];
- options.Rotation = 90;
+ x = 1 - options.DistanceToAxis;
+ options.Position = [x,0.4];
+ Rotation = 90;
case 'south'
- options.Position = [0.4,.02];
- options.Rotation = 0;
+ y = 0 + options.DistanceToAxis;
+ options.Position = [0.4,y];
+ Rotation = 0;
case 'west'
- options.Position = [.05,0.4];
- options.Rotation = 90;
+ x = 0 + options.DistanceToAxis;
+ options.Position = [x,0.4];
+ Rotation = 90;
+ case 'southeast'
+ y = 0 + options.DistanceToAxis;
+ options.Position = [0.8, y];
+ Rotation = 0;
case 'custom'
% Check if Position is valid
if ~all(0 <= options.Position & options.Position <= 1)
@@ -62,6 +64,10 @@ switch options.Location
options.Location = 'east'; options.Position = [1,0.4];
end
+if ~isnan(options.Rotation)
+ Rotation = options.Rotation;
+end
+
IDs = cell(numel(figs),1);
for n = 1:numel(figs)
@@ -72,10 +78,10 @@ for n = 1:numel(figs)
ylim =get(axes,'YLim');
xlim =get(axes,'XLim');
%ID
- position = [options.Position(1)*xlim(2), options.Position(2)*ylim(2)];
+ position = [options.Position(1), options.Position(2)];
text(axes,position(1),position(2), IDs{n},'Fontsize',options.Fontsize,...
- 'Rotation',options.Rotation, 'VerticalAlignment','bottom','Color',...
- 0.65*[1 1 1],'BackgroundColor','w');
+ 'Rotation',Rotation, 'VerticalAlignment','bottom','Color',...
+ options.Color,'BackgroundColor','w', 'Units', 'normalized');
set(figs(n),'Tag', IDs{n});
end
diff --git a/+PlotID/createFileCopy.m b/+PlotID/createFileCopy.m
index 061f10903343ccde4ea33ea666f93b19f414cb79..9787b19dcd37e842f18440b1ad1cc3ff7e5f4b0d 100644
--- a/+PlotID/createFileCopy.m
+++ b/+PlotID/createFileCopy.m
@@ -1,10 +1,10 @@
-function [storagePaths] = createFileCopy(filePaths,folderName,storPath,ID,type)
+function [storagePaths, status, msg] = createFileCopy(filePaths,folderName,storPath,ID,type)
% Creates a copy of the files (can be used for multiple paths in a cell array)
% folderName is the name of the exporting folder
% returns the storage paths were files were stored
if ~iscell(filePaths)
- %fixes Issue if Filepath is a char and not a cell array
+ %fixes Issue if filepath is a char and not a cell array
filePaths = {filePaths};
end
@@ -68,9 +68,11 @@ try
copyfile(FileNameAndLocation,RemotePath);
storagePaths{i} = RemotePath;
end
- disp([type, ' sucessfully published']);
+ status = true;
+ msg =([type, ' successfully published']);
catch
- warning([type,' export was not sucessful'])
+ status = false;
+ warning([type,' export was not successful'])
if exist('errorMSG')
error(errorMSG);
end
diff --git a/+PlotID/createLinkedHDF5.m b/+PlotID/createLinkedHDF5.m
index 8fecfaed42b86014895c16a9bdd9a03eb554bec5..ab893d8106293e62a82b0aad4e45c3cc044e3ae0 100644
--- a/+PlotID/createLinkedHDF5.m
+++ b/+PlotID/createLinkedHDF5.m
@@ -1,7 +1,7 @@
function [status] = createLinkedHDF5(SourceFile,TargetPath,ID)
%createLinkedHDF5 creates a HDF file that references the Sourcefile
% TargetPath is the storage location, ID the foldername
-% Status returns true if the function was sucessfull
+% Status returns true if the function was successfull
plist_id = 'H5P_DEFAULT';
diff --git a/.gitignore b/.gitignore
index 708bea6b2032d70640c74a197d183a115ff0bdda..871929a2b92a067f2d04cbc62aa7b9f9298a5cd8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,5 @@
# config file changes
-config.json
+config*.json
# Windows default autosave extension
*.asv
@@ -29,7 +29,8 @@ codegen/
# Personal test files
test*.m
-test123_data.h5
+test*.h5
+cleanUP.m
# files that are created in example.m
@@ -37,10 +38,11 @@ testdata_2.h5
testdata2.h5
test_data.mat
export/*
+Examples/export/*
+unused*/*
# Octave session info
octave-workspace
-test_data.mat
#logs
log.txt
diff --git a/CITATION.cff b/CITATION.cff
new file mode 100644
index 0000000000000000000000000000000000000000..54312fbdd41a9d06ba6cc453bb3d2cd71a5474fb
--- /dev/null
+++ b/CITATION.cff
@@ -0,0 +1,19 @@
+cff-version: 1.2.0
+title: >-
+ plotID a toolkit for connecting research data and
+ figures
+message: >-
+ developed at the Chair of Fluid System, Techische
+ Universität Darmstadt within the framework of the NFDI4Ing consortium Funded by the German Research Foundation (DFG) - project number 442146713
+type: software
+authors:
+ - given-names: Jan
+ family-names: Lemmer
+ email: jan.lemmer@fst.tu-darmstadt.de
+ affiliation: 'Chair of Fluid Systems, TU Darmstadt'
+ orcid: 'https://orcid.org/0000-0002-0638-1567'
+ - given-names: Martin
+ family-names: Hock
+ email: martin.hock@fst.tu-darmstadt.de
+ affiliation: 'Chair of Fluid Systems, TU Darmstadt'
+ orcid: ' https://orcid.org/0000-0001-9917-3152'
diff --git a/CI_files/default_test.m b/CI_files/default_test.m
index 505c360ea8fde4390434772eeece053120d15f0e..726c59ad33b93aa35ee1e1300eceadbfe322a5d8 100644
--- a/CI_files/default_test.m
+++ b/CI_files/default_test.m
@@ -1,72 +1,126 @@
function [result] = default_test()
-%UNTITLED2 This is a simple test if Plot ID works for the default settings
+%default_test() This is a simple test if Plot ID works for the default settings
% Detailed explanation goes here
clear; clc; close all;
+% set path
+% starting path of gitlab runner is in CI_files
+if contains(pwd,'CI_files')
+ cd .. % move one directory up
+end
+
+addpath('CI_files');
+
% clean up, if previous run failed
try
- delete CI_files/export/* CI_files/*.mat CI_files/*.h5
- rmdir('CI_files/export','s');
+ delete(['CI_files' filesep 'export' filesep '*']);
+ delete(['CI_files' filesep '*.mat']);
+ delete(['CI_files' filesep '*.h5']);
+ rmdir(['CI_files' filesep 'export'],'s');
end
-ProjectID = 'Test01';
-%% Data
-% some random data
-x = linspace(0,7);
-y = rand(1,100)+2;
-dataset1 = 'test_data.mat';
-save('CI_files/test_data.mat','x','y');
-% some data as .h5
-x1 = linspace(0,2*pi);
-y1 = sin(x1)+2;
-
-% define file path & name
-fpath = "CI_files/testdata_2.h5";
-dataset2 = 'testdata_2.h5';
-
-% 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)
-
-%% Plotting
-
-fig(1) =figure('visible','off');
-plot(x,y,'-k');
-hold on
-plot(x1,y1,'-r');
+% initialise
+numberOfTests = 2;
+testResults = zeros(numberOfTests,1);
+
+%start log
+fid = fopen(fullfile('CI_files','log.txt'),'w');
+txt = ['default test started ' newline];
+fprintf(fid,txt);
+
+% create Config for CI-Tests
+fid1 = fopen(fullfile('CI_files','CI_config.json'),'w');
+configData.Author = 'CI-Test'; configData.ProjectID = 'CI-001';
+txt = jsonencode(configData,'PrettyPrint',true);
+%fprintf does not write paths correctly !!!
+fwrite(fid1,txt);
+fclose(fid1);
+
+try
+ ProjectID = 'Test01';
+ %% Data
+ % some random data
+ x = linspace(0,7);
+ y = rand(1,100)+2;
+ dataset1 = fullfile('CI_files','test_data.mat');
+ save(dataset1,'x','y');
+ % some data as .h5
+ x1 = linspace(0,2*pi);
+ y1 = sin(x1)+2;
+
+ % define file path & name
+ fpath = fullfile("CI_files","testdata2.h5");
+ dataset2 = fullfile('CI_files','testdata2.h5');
+
+ % 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)
+
+ %% Plotting
+
+ fig(1) =figure('visible','off');
+ plot(x,y,'-k');
+ hold on
+ plot(x1,y1,'-r');
+ msg = 'simple_test succeed stage 1';
+catch
+ testResults(1) = 1; %test fails
+ msg = 'simple_test failed in Stage 1';
+ warning(msg);
+end
+
+fprintf(fid,[msg newline]);
%% Tag the plot
try
- [figs, ID] = PlotID.TagPlot(fig,'ProjectID', ProjectID);
+ [figs, ID] = PlotID.TagPlot(fig,'ConfigFileName', 'CI_config.json');
%% call a dummy function
- a=1;
- a = example_fcn(a);
+ %a=1;
+ %a = example_fcn(a);
%% publishing
% The functions needs the file location, the location of the data and the
% figure
- path.script = mfilename('fullpath'); % filename of the m.script
+ script = [mfilename('fullpath'),'.m']; % filename of the m.script
% file name of the data
- path.rdata = {dataset1,dataset2} ; % don't forget the extension
-
- PlotID.Publish(path, ID, figs, 'Location', 'CI-Test')
- result = true;
-
- % clean up
- delete CI_files/export/* CI_files/*.mat CI_files/*.h5
- rmdir('CI_files/export','s');
-
- clear; clc;
-
+ rdata = {dataset1,dataset2} ; % don't forget the extension
+
+ PlotID.Publish(rdata,script, figs, 'Location', 'CI-Test',...
+ 'ConfigFileName', 'CI_config.json');
+
+ msg = 'simple_test succeed Stage 2';
+
catch
- result = false;
- warning('simple_test failed');
+ testResults(2) = 1; %fail
+ msg = 'simple_test failed in Stage 2';
+ warning(msg);
+end
+fprintf(fid,[msg newline]); %log
+
+%% Test result
+if any(testResults)
+ result = 1; %fail
+ warning('test failed');
+else
+ result = 0; % pass
+ disp('test succeed');
+end
+
+fclose(fid);
+
+% final clean up
+try
+ delete(['CI_files' filesep 'export' filesep '*']);
+ delete(['CI_files' filesep '*.mat']);
+ delete(['CI_files' filesep '*.h5']);
+ rmdir(['CI_files' filesep 'export'],'s');
+ delete(fullfile('CI_files','CI_config.json'));
end
end
diff --git a/Examples/PlodID_advanced.m b/Examples/PlodID_advanced.m
new file mode 100644
index 0000000000000000000000000000000000000000..310e4285b2e73d37900f1dd284531641564662e5
--- /dev/null
+++ b/Examples/PlodID_advanced.m
@@ -0,0 +1,33 @@
+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
diff --git a/Examples/PlotID_centralized.m b/Examples/PlotID_centralized.m
new file mode 100644
index 0000000000000000000000000000000000000000..33209f2d2a3864d40672f763136ac23666e84eda
--- /dev/null
+++ b/Examples/PlotID_centralized.m
@@ -0,0 +1,25 @@
+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
diff --git a/Examples/PlotID_config.m b/Examples/PlotID_config.m
new file mode 100644
index 0000000000000000000000000000000000000000..5612f7aef31b4f851861bdc6a2df726a0de4ee13
--- /dev/null
+++ b/Examples/PlotID_config.m
@@ -0,0 +1,29 @@
+%% 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')
diff --git a/Examples/PlotID_example_fcn.m b/Examples/PlotID_example_fcn.m
new file mode 100644
index 0000000000000000000000000000000000000000..3237c8d4a386aefaac82f38d5c45fbcbaf9a26f0
--- /dev/null
+++ b/Examples/PlotID_example_fcn.m
@@ -0,0 +1,6 @@
+function [outputArg1] = PlotID_example_fcn(inputArg1)
+%PlotID_example_fcn is just a dummy function
+outputArg1 = inputArg1;
+
+end
+
diff --git a/Examples/createExampleData.m b/Examples/createExampleData.m
new file mode 100644
index 0000000000000000000000000000000000000000..d2a1359313f054f289352c0aa85d265278fad5ad
--- /dev/null
+++ b/Examples/createExampleData.m
@@ -0,0 +1,38 @@
+function [x,y, fpath] = createExampleData(option)
+%CREATEEXAMPLEDATA creates x,y data needed for the PlotID examples
+% fpath contains the file path of the example data
+% there are two options, the option 'matlab' creates a matlab file and the
+% hdf option a hdf5 file
+
+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
+
diff --git a/Initialisation.m b/Initialisation.m
new file mode 100644
index 0000000000000000000000000000000000000000..a30816b8aa0e8d8405695d7de19ba46713650cf2
--- /dev/null
+++ b/Initialisation.m
@@ -0,0 +1,25 @@
+%% This is the PlotID Initialisation file
+% Please run this script before using PlotID
+
+%% Section 1 Config File
+% To make things easy, you should use the config file. The following wizard
+% will help you create one:
+writeConfig = true;
+
+% Ask User if current config should be overwritten
+if isfile('config.json')
+ m = input('Do you want to overwrite the current config file, Y/N [Y]:','s');
+ writeConfig = ismember(m,{'Y','y'});
+end
+
+if writeConfig
+ config = PlotID.config.wizard('initialise');
+ fid = fopen('config.json','w');
+ txt = jsonencode(config,'PrettyPrint',true);
+ fwrite(fid,txt);
+ fclose(fid);
+end
+
+%%
+clc
+disp('Initialisition done.')
diff --git a/PlotID_example.m b/PlotID_example.m
new file mode 100644
index 0000000000000000000000000000000000000000..92099efa2997dd5dba4fd14bde1bb89f31314199
--- /dev/null
+++ b/PlotID_example.m
@@ -0,0 +1,74 @@
+%% Example Script
+% This Script is mend to demonstrate the capabilities of the PlotID tool.
+% please run Initilisation.m before first time use
+
+%% Clear and set environment
+clear; clc; close all;
+addpath('Examples');
+
+%% Data (only necessary for this example)
+[x, y, datapath] = createExampleData('matlab');
+
+%% 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]);
+
+% -------------- 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
+
+% Syntax:
+% fig = PlotID.TagPlot(fig);
+% [figs, IDs] = PlotID.TagPlot(figs);
+% [figs, IDs] = PlotID.TagPlot(figs, options);
+
+[fig1, ID] = PlotID.TagPlot(fig1);
+
+% you can influence the design and position of the Tag with the following
+% Name-Value Arguments: 'Fontsize', 'Color', 'Location',
+% 'DistanceToAxis','Position','Rotation'
+
+fig2 = figure; plot(x,y,'-k'); box off; 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');
+
+% You can find the description to all options in the readme
+
+%% ---- 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).
+
+% Syntax:
+% Publish(DataPaths,scriptPath, figure)
+% Publish(DataPaths,scriptPath, figure, options)
+
+% Path of the m.script that you use for creating your plot.
+scriptPath = [mfilename('fullpath'),'.m'];
+
+% file paths of the datasets used for the plot (don't forget the extension)
+% note: use absolute paths for best practice
+% datapath = 'test_data.mat';
+locations = datapath;
+
+%call publish
+PlotID.Publish(locations,scriptPath, fig2)
+
+% Your plot, script and all the data that your provide are now published.
+
+% ---------------------------------
+%% 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
diff --git a/README.md b/README.md
index 83e88a152b92188d60874df012febdad41e3bce5..929ac878932aafd14616caa66ecc8e6cfceb1796 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,7 @@
**PlotID**
-`PlotID` is a toolkit that labels your plots and figures and copies all associated data (research data, plotting script, user-functions and a copy of the figure) to the desired location.
-
-This version of `PlotID` is build for `MATLAB`.
-
+`PlotID` is a toolkit that labels your plots and figures and copies all associated data (research data, plotting script, user-functions and a copy of the figure) to the desired location.\
+This version of `PlotID` is build for `MATLAB`. \
`PlotID` provides two core functions **TagPlot** and **Publish** which are described in detail below.
Feel free to give feedback and feature requests or to take part in the development process.
@@ -11,20 +9,29 @@ Feel free to give feedback and feature requests or to take part in the developme
[TOC]
# Quick User Guide
-`PlotID` works in two Steps:
+**Requirements:** MATLAB R2021a or newer
-1. tagging the plot
-`[figs, IDs] = plotId.TagPlot(figs, options)`
+**First use:**
+1. Put your PlotID folder in you [userpath](https://uk.mathworks.com/help/matlab/ref/userpath.html) on Windows this is
+`C:\Users\USERNAME\Documents\MATLAB`. \
+When using a diffrent folder, make sure the folder is on your [search path](https://uk.mathworks.com/help/matlab/matlab_env/add-remove-or-reorder-folders-on-the-search-path.html).
+2. Run `Initialisation.m` and follow the command line instructions.\
+The **ProjectID** is your custom project number, it well be the prefix of the ID created by `PlotID` (e.g. JL-001). Save your config file.
-2. publishing the plot and the associated data
-`plotID.Publish(DataPaths, ID, figure, options)`
+**Intended use:**\
+`PlotID` works in two Steps:
-`DataPaths.script = mfilename('fullpath');` contains the filename of the m.script
+1. Tag the plot
+`[figs, IDs] = PlotId.TagPlot(figs, options)`
-`DataPaths.rdata = {dataset1, dataset2};` file names of the datasets (they most be at the path)
+2. Publish the plot and the associated data
+`PlotID.Publish(DataPaths,scriptPath, figure, options)`
-You should either set a ProjectID in the config.json (copy & rename the 'example-config.json' to 'config.json'), or pass it as option 'ProjectID' to the TagPlot function.
+`scriptPath` contains the path to the script, this can be provided with the simple call of `scriptPath = [mfilename('fullpath'),'.m']` \
+`DataPaths` contains the path(s) to the research data, for multiple files you can use a cell arrays (they must be at the path). \
+`figure` is the figure that should be published.
+
# PlotID.TagPlot()
`[figs, IDs] = TagPlot(figs, options)`
@@ -63,7 +70,7 @@ FriendlyID Changes the Hex Number to a human friendly *datetime* and *dateStr*.
# PlotID.Publish()
-`Publish(DataPaths, ID, figure, options)` \
+`Publish(DataPaths,scriptPath, figure, options)` \
Publishes saves plot, data and measuring script
Location sets the storage location. 'local' sets the storage location to the current folder (an export folder will be created), 'server' is a remote path, that is defined in the config file. Two Methods are implemented 'individual' stores the data for each plot while 'centralized' uses a data folder and uses reference links to the original data (hdf5 only). ParentFolder is the folder Name where the exported data is stored if a path is used, PlotId will use this path a storagePath
@@ -90,7 +97,7 @@ An overview of all published plots and the associated data will be stored in a c
Creates a copy of the files (can be used for multiple paths in a cell array). folderName is the name of the exporting folder
## createLinkedHDF ()
`[status] = createLinkedHDF5(SourceFile,TargetPath,ID)` \
-createLinkedHDF5 creates a HDF file that references the Sourcefile. TargetPath is the storage location, ID the foldername, Status returns true if the function was sucessfull.
+createLinkedHDF5 creates a HDF file that references the Sourcefile. TargetPath is the storage location, ID the foldername, Status returns true if the function was successfull.
## fileCompare()
`[status, id] = fileCompare(filename,fileList)` \
fileCompare checks if file1 is (binary) identical to a file in filelist, it returns a sttus and the id of the identical file. The function uses the windows system function fc or the unix function diff (not tested).
@@ -99,14 +106,54 @@ fileCompare checks if file1 is (binary) identical to a file in filelist, it retu
removePltIdFiles removes functions that are part of PlotID out of flist.
# How to use the .config file
-The config file is a JSON-File. At the moment two options can be set in the config file, the project ID and the remote Path.
+The config file is a JSON-File. The config file stores user data and options of `PlotID`. It will be created when you use PlotID for the first time. Follow the Instructions to create the file. _Note:_ for basic usage no manual changes on the config file are required. \
+
+**Note:** If you mess up your config-file simply delete it, PlotID will create a new one the next time you use it.
+
+## Define an export path
+If you define an export path in the config.json this path is used as location for the exported data.
+## Store custom options for Publish
+**add custom publish options to the config file** \
+you can define your custom options for publish in the config file. **Important:** They will always have priority against Name-Value pairs!
+
+
+```
+configFileName = 'config.json';
+configObj = PlotID.config(configFileName);
```
-{
- "ProjectID": "your ProjectID",
- "ServerPath": "\\\\Server\\Folder1\\Subfolder"
-}
+This method adds the default config to your config file
```
+configObj.addPublishOptions('default');
+```
+
+You can change the options 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
+
+<details><summary> Expand </summary>
+It is possible to use individual config files for each project (configP1.json, configP2.json, ...) \
+
+1. Create a new config file programatically
+```
+customConfigFileName = 'configP1.json';
+configObj = PlotID.config(customConfigFileName);
+configObj.addPublishOptions('default');
+```
+
+2. 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')
+```
+
+</details>
+
+# Aknowledgements
+The authors would like to thank the Federal Government and the Heads of Government of the Länder, as well as the Joint Science Conference (GWK), for their funding and support within the framework of the NFDI4Ing consortium. Funded by the German Research Foundation (DFG) - project number 442146713.
# Known Issues
# FAQs
diff --git a/example.m b/example.m
deleted file mode 100644
index 04aa8c11aebc102d0810c7e23681ad1ba473d943..0000000000000000000000000000000000000000
--- a/example.m
+++ /dev/null
@@ -1,117 +0,0 @@
-%% Example Script
-% This Script is meant to demonstrate the capabilities of the PlotID tool.
-
-%% Clear Environment
-clear; clc; close all;
-
-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
-
-% Creating Random Data to use as data-file
-x = linspace(0,7); y = rand(1,100)+2;
-dataset1 = 'test_data.mat';
-
-% Use absolute paths for good practise
-dataset1 = fullfile(pwd,dataset1);
-save(dataset1,'x','y');
-
-% some data for the .h5 file
-x1 = linspace(0,2*pi); y1 = sin(x1)+2;
-
-% define filepath & name
-dataset2 = 'testdata2.h5';
-dataset2 = fullfile(pwd,dataset2);
-fpath = dataset2;
-
-% 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)
-
-%% 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);
-p = betacdf(0.5,1,1); % to test toolboxes
-
-%% 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 1: single plot based on two data-sets
-
-%% 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);
-
-%% Publishing
-% Second part of plotID
-% The functions needs the file location of the script, the location of the
-% data and the figure and can take several options (see readme).
-
-path.script = mfilename('fullpath'); % filename of the m.script
-% file names of the datasets
-
-%(defined above:) dataset1 = 'test_data.mat'; dataset2 = 'testdata2.h5'
-path.rdata = {dataset1,dataset2} ; % don't forget the extension
-
-%call publishing
-PlotID.Publish(path, ID, fig(1), 'Location', 'local' ,'Method','individual')
-
-%% 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
-path.script = mfilename('fullpath'); % filename of the m.script
-% file names of the datasets
-path.rdata = {dataset2} ; % don't forget the extension
-
-% publsihing via a for-loop
-for i=1: numel(fig)
- PlotID.Publish(path, IDs{i}, fig(i), 'Location', 'local',...
- 'Method','individual');
-end
-
-%% 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
-
-fig2 =figure;
-plot(x,y,'-k');
-hold on
-plot(x1,y1,'-r');
-
-[fig2, ID] = PlotID.TagPlot(fig2,'ProjectID', ProjectID);
-
-PlotID.Publish(path, ID, fig2, 'Location', 'local','Method','centralized')
diff --git a/example_fcn.m b/example_fcn.m
deleted file mode 100644
index 418f15ca734ac8423bdda5a6ead2c32af6820e22..0000000000000000000000000000000000000000
--- a/example_fcn.m
+++ /dev/null
@@ -1,6 +0,0 @@
-function [outputArg1] = example_fcn(inputArg1)
-%TEST_2 just a dummy function
-outputArg1 = inputArg1;
-
-end
-