Randomization-Tools.md

@@ -4,4 +4,109 @@ This chapter contains functions you can use to produce randomized outputs for sp
 
 ## randomOrder
 
+function: [rndm] = randomOrder(numitems,len,varargin)
+
+**Description**  
+This function is used to generate a vector of random numbers with length len and the values 1:numitems.  Randomization can be controlled by optional arguments.
+
+**Input**
+~~~
+   numitems		number of items (eg. stimuli) to be randomized
+   len			length of matrix (eg. number of trials)
+~~~
+
+**Input-Optional**
+~~~
+   varargin	‘ratio’		vector, used to specify the ratio of randomized items. 		 
+                                Values between 0-1. All entries must add up to 1. Make 		 
+                                sure that the ratio is compatible with the default value for 
+                                ‘maxRepeat’(3). Using this argument will cause a warning, to 
+                                disable it, add the argument ‘NoWarning’.
+					
+	        ‘maxRepeat’	specifies the maximal number of repetitions of each item. 		 
+                                Default is 3. Setting this value too low can lead to 			 
+                                uniformity of the output. Using this argument will cause 		 
+                                a warning, to 	disable it, add the argument ‘NoWarning’.
+
+	        ‘boolean’	returns boolean vector (true or false), not values 			 
+                                (1:numitems). Using this parameter will issue a warning 		                                                                
+                                when numitems is bigger than 2 (every value bigger than 		 
+                                2 will be converted to ‘true’). To disable it, add the argument 
+                                ‘NoWarning’.
+
+	        ‘normalized’	returns vector of random numbers chosen from a normal 		 
+                                distribution with mean MU and standard deviation 			 
+                                SIGMA. Necessary additional arguments: mu and sigma. 		 
+                                The first argument ‘numitems’ has no effect for this 		 
+                                argument!!! Any number is fine!!!
+
+	        ‘maxTries’	specifies the maximal number of tries to comply with the 		 
+                                criteria. Default is 50. Some criteria can be hard to match, 		 
+                                setting this value very high prevents the function from 		 
+                                terminating with an error when the criteria are set very 		 
+                                restrictive, but it can seriously affect performance. 			 
+                                Usually the criteria for the random vector should be 			 
+                                reconsidered rather than this value be adjusted.
+~~~
+
+**Output**
+~~~ 
+   rndm		randomized vector
+~~~
+
+**Examples**
+~~~matlab
+1.	randomOrder(2,6)
+        ans = [2 1 1 2 1 2]
+
+2.	randomOrder(2,10,'ratio',[.1 .9],'maxrepeat',10)
+        ans = [2 2 1 2 2 2 2 2 2 2]
+
+3.	randomOrder(2,6,'maxRepeat',1)
+        ans = [1 2 1 2 1 2]
+
+4.	randomOrder(2,6,'boolean')
+        ans = [0 1 0 0 1 1]
+
+5.	randomOrder(3,9)-1 
+        % when values between 0 and 2 are required
+        ans = [2 1 2 0 2 0 0 1 1]
+
+6.	randomOrder(1,5,'normalized',2,1)
+        ans = [2.0554  3.2538  -0.5200  2.5849  0.9919]
+~~~
+
+**See also**  
+randperm, rand, randn
+
 ## nBackBuffer
+
+function: out = nBackBuffer(len, n, numMatch)
+
+**Description**  
+Creates a buffer for n-back experiments
+
+**Input**
+~~~
+   len			length of buffer
+   n			n from n-back ;)
+   numMatch		number of matches
+~~~
+
+**Output**
+~~~
+   out			a struct with three fields
+	.buffer		contains the n-back buffer (can be used as indices for e.g. experimental stimuli)
+	.stimulus	indicates positions of stimuli that were displayed n features before the hits
+	.hit		indicates positions of hits
+~~~
+
+**Examples**
+~~~matlab
+1.	nback=nBackBuffer(10, 2, 3)
+        nback = 
+         struct with fields:
+          buffer:	[4 9 2 6 2 6 8 3 8 6]
+          stimulus:	[0 0 1 1 0 0 1 0 0 0]
+          hit:		[0 0 0 0 1 1 0 0 1 0]
+~~~
\ No newline at end of file