README.md 9.91 KB
Newer Older
Lemmer, Jan's avatar
Lemmer, Jan committed
1
2
**PlotID**

Lemmer, Jan's avatar
Lemmer, Jan committed
3
4
`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`. \
Lemmer, Jan's avatar
Lemmer, Jan committed
5
6
7
8
9
10
11
`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.

 [TOC]

# Quick User Guide
Lemmer, Jan's avatar
Lemmer, Jan committed
12
**Requirements:** MATLAB R2021a or newer
Lemmer, Jan's avatar
Lemmer, Jan committed
13

Lemmer, Jan's avatar
Lemmer, Jan committed
14
**First use:**
15
1. Put your PlotID folder in you [userpath](https://uk.mathworks.com/help/matlab/ref/userpath.html) on Windows this is
Lemmer, Jan's avatar
Lemmer, Jan committed
16
17
`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).
Lemmer, Jan's avatar
Lemmer, Jan committed
18

Lemmer, Jan's avatar
Lemmer, Jan committed
19
20
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.
Lemmer, Jan's avatar
Lemmer, Jan committed
21

Lemmer, Jan's avatar
Lemmer, Jan committed
22
23
**Intended use:**\
`PlotID` works in two Steps:
Lemmer, Jan's avatar
Lemmer, Jan committed
24

Lemmer, Jan's avatar
Lemmer, Jan committed
25
1. Tag the plot
26
`[figs, IDs] = PlotID.TagPlot(figs, options)`
Lemmer, Jan's avatar
Lemmer, Jan committed
27

Lemmer, Jan's avatar
Lemmer, Jan committed
28
29
2. Publish the plot and the associated data
`PlotID.Publish(DataPaths,scriptPath,  figure, options)`
Lemmer, Jan's avatar
Lemmer, Jan committed
30

31
`scriptPath` contains either the path to the script, this can be provided with the simple call of `scriptPath = [mfilename('fullpath'),'.m']` or the script or function name that is used for creating your plot. \
32
`DataPaths` contains the path(s) to the research data, for multiple files you can use a cell array (We recommend using absolute paths). It is also possible to pass an arbitrary number of variables as struct. To generate all paths for a filetype try: `f=dir(/folderpath/*.mat); rdata=fullfile({f.folder},{f.name})`. \
Lemmer, Jan's avatar
Lemmer, Jan committed
33
`figure` is the figure that should be published.
34

Lemmer, Jan's avatar
Lemmer, Jan committed
35
**Minimal Example:**
Hock, Martin's avatar
Hock, Martin committed
36
37
38
39
40
41
42
43
44
45
```matlab
fig = figure;
plot(x,y);
[fig, IDs] = PlotID.TagPlot(fig);
script = [mfilename('fullpath'),'.m']; % This creates a path to the script this line is  called from
rdata =  {'\\fullpath\dataset01.mat', '\\fullpath\dataset02.h5'} ; % a single path does not need a cell array
PlotID.Publish(rdata, script, fig);
```


46
**For further insight, please take a look at the examples provided in the Example folder**.
47

48

Lemmer, Jan's avatar
Lemmer, Jan committed
49
50
51
52
53
54
55
56
57
58
59
# PlotID.TagPlot()
`[figs, IDs] = TagPlot(figs, options)`
**TagPlot** adds IDs to figures
The ID is placed visual on the figure window and as Tag (property of the figure)
**TagPlot** can tag multiple figures at once. If a single Plot is tagged, IDs is a char, otherwise it is a cell array of chars .

<details><summary>detailed description</summary>

_options_ \
you find the options for TagPlot below. The data type is in curled braces and the default value follows the equal sign.

60
61
62
- ProjectID  {mustBeText}= ''
- Fontsize {mustBeInteger} = 8
- Color  {mustBeNonnegative} = 0.65*[1 1 1]
Lemmer, Jan's avatar
Lemmer, Jan committed
63
- Location  {mustBeText} = 'east'
64
65
66
67
68
- Position  {mustBeVector} = [1,0.4]
- DistanceToAxis {mustBeReal} = .02
- Rotation  {mustBeInteger} = 0
- PinToLegend {mustBeNumericOrLogical} = false
- QRcode  {mustBeNumericOrLogical} = false
Lemmer, Jan's avatar
Lemmer, Jan committed
69
- QRsize {mustBeNonnegative} = 0.15
Lemmer, Jan's avatar
Lemmer, Jan committed
70
71
72

`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' of the figure per default, if you want it somwhere else, use the `'Location'` option. 'north', 'east', 'south', 'west' are predefined, otherwise use the `'custom'` option and provide the desired 'Position'  as a vector relative to your x- and y-axis limits `[relX, relY]` .
Lemmer, Jan's avatar
Lemmer, Jan committed
73
74
75

`options.PinToLegend` pins the ID to the figure's legend. If no legend was defined, plotID will create one.

Lemmer, Jan's avatar
Lemmer, Jan committed
76
77
78
79
80
81
82
</details>

## CreateID()
`function [ID] = CreateID(method)` \
CreateID Creates an identifier (char). It creates an (sometimes unique) identifier based on the selected method, if no method is selected method 1 will be the default method.

1. **UNIX Time in seconds as HEX** \
83
This is used by default due to its simplicity and it is human readable.
Lemmer, Jan's avatar
Lemmer, Jan committed
84
85
86
2. **random UUID from Java 128 bit.**\
Static factory to retrieve a type 4 (pseudo randomly generated) UUID. The UUID is generated using a cryptographically strong pseudo random number generator.

87
## friendlyID()
Lemmer, Jan's avatar
Lemmer, Jan committed
88
89
`[IDf,PrjID, Str] = friendlyID(ID)` \
FriendlyID Changes the Hex Number to a human friendly *datetime* and *dateStr*. `IDf` returns the ID as DateTime Object, `PrjID` returns the ProjectID, `Str` returns the timestamp as String. \
90
**This only works with ID method 1 (UNIX Time as Hex).**
Lemmer, Jan's avatar
Lemmer, Jan committed
91
92


93
# PlotID.Publish()
Lemmer, Jan's avatar
Lemmer, Jan committed
94
`Publish(DataPaths,scriptPath, figure, options)` \
95
Publishes saves plot, data and measuring script
96
Location sets the storage location. 'local' sets the storage location to the current folder (an export folder will be created), 'manual' will allow you to choose a folder via user dialogue. If you defined an export path in the config file, this will used per default (exportPath).
97

98
Two Methods are implemented: 'individual' stores the data for each plot with the plot while 'centralized' uses a single data folder and creates 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 as storagePath.
Lemmer, Jan's avatar
Lemmer, Jan committed
99
100
101
102

<details><summary>detailed description</summary>

_options_ \
103
You can find the possible options for publish below. The the possible parameters are listed in curled braces and the default value follows the equal sign at the end.
Lemmer, Jan's avatar
Lemmer, Jan committed
104
105

- Location {mustBeMember(options.Location ,{'local','server','manual','CI-Test'})} = 'local' \
106
'local' creates the folder in your current working path, 'server' will use a remote path that needs to be specified in the config file. 'manual' opens an UI window where the path must be selected, 'CI-Test' is for CI testing only.
Lemmer, Jan's avatar
Lemmer, Jan committed
107
- Method {mustBeMember(options.Method ,{'individual','centraliced'})} = 'individual'\
108
109
'individual' each folder contains the assigned data files. (recommended for small file sizes and for sharing fully functional packages).
'centralized' one 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 multiple 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.
Lemmer, Jan's avatar
Lemmer, Jan committed
110
- ParentFolder  {mustBeText} = 'export'\
111
Adjust the default parent folder name for exports.
Lemmer, Jan's avatar
Lemmer, Jan committed
112
113
114
- CopyUserFCN  {mustBeNumericOrLogical} = true \
All user functions that are used by script that calls publish will be exported per default as well. Set this to false (not recommended) to prevent this.
- CSV {mustBeNumericOrLogical} = false \
115
An overview of all published plots by ID and their associated data will be stored in a .csv file.
Lemmer, Jan's avatar
Lemmer, Jan committed
116
117
118
119
</details>

## createFileCopy ()
`[] = createFileCopy(filePaths,folderName,storPath,ID,type)`\
120
Creates a copy of  files (can be used for multiple paths in a cell array). folderName is the name of the exporting folder
Lemmer, Jan's avatar
Lemmer, Jan committed
121
122
## createLinkedHDF ()
`[status] = createLinkedHDF5(SourceFile,TargetPath,ID)` \
123
createLinkedHDF5 creates an HDF file that references the source file. TargetPath describes the storage location, ID the foldername, status returns 'true' if the function was successfull.
Lemmer, Jan's avatar
Lemmer, Jan committed
124
125
## fileCompare()
`[status, id] = fileCompare(filename,fileList)`  \
126
fileCompare checks if file1 is (binary) identical to a file in filelist, it returns a status and the id of the identical file. The function uses the windows system function fc or the unix function diff.
Lemmer, Jan's avatar
Lemmer, Jan committed
127
128
129
130
131
## removePltIdFiles()
`[fListClean] = removePltIdFiles(fList)` \
removePltIdFiles removes functions that are part of PlotID out of flist.

# How to use the .config file
132
The config file is a JSON-File. The config file stores user settings 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. \
Lemmer, Jan's avatar
Lemmer, Jan committed
133

134
**Note:** If you mess up your config-file simply delete it, PlotID will prompt you to create a new one the next time you use it.
Lemmer, Jan's avatar
Lemmer, Jan committed
135

Hock, Martin's avatar
Hock, Martin committed
136
137
138
## Default config.json


Lemmer, Jan's avatar
Lemmer, Jan committed
139
140
141
## Define an export path
If you define an export path in the config.json this path is used as location for the exported data.

142
143
144
145
146
147
148
149
150
151
## Example config.json

```
{
  "Author": "Name",
  "ProjectID": "XYZ01",
  "ExportPath": "C:\\project\\plot_ID"
}
```

Lemmer, Jan's avatar
Lemmer, Jan committed
152
153
154
155
156
157
158
159
## 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);
Lemmer, Jan's avatar
Lemmer, Jan committed
160
```
Lemmer, Jan's avatar
Lemmer, Jan committed
161
This method adds the default config to your config file
Lemmer, Jan's avatar
Lemmer, Jan committed
162
```
Lemmer, Jan's avatar
Lemmer, Jan committed
163
164
165
configObj.addPublishOptions('default');
```

166
You can change the options in the json file, but be careful no argumentValidation will be done on options from the config file!
Lemmer, Jan's avatar
Lemmer, Jan committed
167
168
169
170
171
172

## 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, ...) \

173
1. Create a new config file programatically
Lemmer, Jan's avatar
Lemmer, Jan committed
174
175
176
177
178
179
180
181
182
```
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'` :
Lemmer, Jan's avatar
Lemmer, Jan committed
183
184

```
Lemmer, Jan's avatar
Lemmer, Jan committed
185
186
 [figs, IDs] = PlotID.TagPlot(figs, 'ConfigFileName','configP1.json');
 Publish(DataPaths,scriptPath, 'ConfigFileName','configP1.json')
Lemmer, Jan's avatar
Lemmer, Jan committed
187
188
```

Lemmer, Jan's avatar
Lemmer, Jan committed
189
190
</details>

Lemmer, Jan's avatar
Lemmer, Jan committed
191
192
# 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.
Lemmer, Jan's avatar
Lemmer, Jan committed
193
194

# Known Issues
Lemmer, Jan's avatar
Lemmer, Jan committed
195
**Closed figure will cause error** Please do not cloase the figure, MATLAB deletes the object if you do so. \
Lemmer, Jan's avatar
Lemmer, Jan committed
196
**Centralized Method does not work on Linux systems**
Lemmer, Jan's avatar
Lemmer, Jan committed
197