Save-Options.md

@@ -2,12 +2,158 @@
 
 ## errorSave
 
+function: errorSave
+
+**Description**  
+This function is used to warn the user that something went wrong in a program. This function should be used in every Experiment! It has to be called from within a catch-statement where it opens an error-warning and saves all workspace variables so that no data is lost. The workspace is saved to the file ErrorTermination_jjjjmmddhhmm.mat in the working directory.
+
+**Examples**
+~~~matlab
+1.	try
+	this is where your entire paradigm happens
+	error('test error')
+catch
+		errorSave
+	end
+~~~
+
 ## getBasicInformation 
 
+function: trial = getBasicInformation
+
+**Description**  
+Use this function to get basic information about the experimental computer, the user and the date and time when the experiment was started. Useful when several people run experiments on the same device.
+
+**Outputs**
+~~~
+   trial		a struct containing all possible information
+	.date		current date and time as six numerical values (year month day hour minute seconds)
+	.username	string containing current user name
+	.computer	string containing current computer name
+	.time		current date and time as scalar string (YYYYMMDDHHMMSS) (time of the function call)
+	.dbStack	struct containing the dbStack information of function that led to the current pause condition 
+		.file	filename (with extension) of file that getBasicInformation was called in
+		.name	function name (without extension) of function that getBasicInformation was called in
+		.line	function line number where getBasicInformation was called
+	.fctName	function name (MATLAB file that getBasicInformation was called in, e.g. myExperiment)
+	.fctCode	function code of function that getBasicInformation was called in as a vector of numbers 
+			use MATLAB internal functions native2unicode(trial.fctCode’) or char (trial.fctCode’) to read code as string
+~~~
+
 ## save2File
 
+function: [fileName,savePath] =  save2File(varargin)
+
+**Description**  
+Saves given variables to a MATLAB workspace file. This function is useful to save results into a workspace file that can be evaluated afterwards. The first arguments have to be the variables that should be stored in the workspace file. 
+
+save2File uses a default file name (year-month-day-hour-minute), if no optional arguments are used and saves the file into the current directory. 
+
+Additional arguments gain more control over the filename and the path. Existing files are untouched, even if the user enters the same filename again. Files are renamed automatically and a warning appears.
+
+**Inputs**  
+~~~  
+   variables		comma separated list of variables to be saved as strings
+~~~
+
+**Inputs-optional**
+~~~
+   varargin		'subject'	define the subject name, the next argument needs to be the subject name as string
+			'path'		define the file path, the next argument needs to be the path where the file has to be stored as string
+			'noTime'	removes the time from the default file name (year-month-day)
+			'noDateTime'	removes the date and time from the default file name. In this case a subject name is mandatory!
+			'gui'		no optional arguments! Opens a window to select filename and path with a mouse
+~~~
+
+**Outputs**
+~~~
+   fileName		name of the saved file (without extension *.mat)
+
+   savePath		name of the path where the file was saved
+~~~
+
+**Examples**
+~~~matlab
+1.	save2File(result, trial, iti);
+        % saves the variables result, trial and iti with the default name into the current directory
+
+2.	save2File(result, 'subject', '791', 'path', 'c:\result')
+        % saves the variable result with filename prefix "791" into the directory "c:\result"
+
+3.	save2File(result, answer, 'gui')
+        % saves the variables result and answer and opens a window to select the directory and 
+        % the filename.
+~~~
+
+**See also**  
+bioErrorSave, save, save2ExcelFile
+
 ## save2ExcelFile
 
+function: save2ExcelFile(filename, mat, varargin)
+
+**Description**  
+This is a wrapper function that allows OTBR Toolbox users to create Excel files either in MATLAB or in Octave on a Raspberry pi! To create Excel files in the Raspberry Pi the package IO has to be installed.
+
+**Inputs**
+~~~
+   filename		the full file name including path and extension
+   mat			a cell matrix containing the data that have to be written into the Excel file
+			each cell array represents one excel cell on the sheet
+			matrices and structs are not allowed as variable types, also within the cell array 
+			if your data is of that type covert it to a cell array before saving it
+~~~
+
+**Inputs-optional**
+~~~
+   varargin		‘sheetName’	renames Excel sheet, needs fourth argument sheetname
+				sheetname	defines the sheet name where the data are stored as string
+~~~
+
+**Examples**
+~~~matlab
+1.	save2ExcelFile('c:\MATLAB\result.xlsx', res);
+        % stores the variable res in an Excel file called result.xlsx
+
+2.	save2ExcelFile('c:\MATLAB\result.xlsx', res, 'sheetname', 'FirstExp');
+        % stores the variable res in an Excel file called result.xlsx the sheet name in Excel is  
+        % called FirstExp
+~~~
+
 ## getCode
 
+function: [cde] = getCode(funNme)
+
+**Description**  
+Returns the code of the named function (*.m file) as unit8. Hast to be casted to char for human reading.
+
+**Inputs**
+~~~
+   funNme		name of the function (*.m file) to read, enter as string
+~~~
+
+**Outputs**
+~~~
+   cde			the code in uint8, needs to be cast to char for human reading
+			use MATLAB internal functions native2unicode(cde’) or char (cde’) to read code as string
+~~~
+
+**See also**  
+saveCode
+
 ## saveCode
+
+function: [] = saveCode(fName, cde)
+
+**Description**  
+Use this function to save the output of getCode as *.m file.
+
+**Inputs**
+~~~
+   fName		file name for saving (*.m file) to read
+
+   cde			output from getCode
+~~~
+
+**See also**  
+getCode
\ No newline at end of file