Scripting > UNICOM Intelligence Function Library > List functions > Ran
 
Ran
This function returns a randomized copy of a list. The optional Count parameter defines how many items from the input list are included in the returned randomized list.
Syntax
Ran(List [, Count [, Seed]])
Parameters
List
Type: None
Array, collection, or Categorical value to operate on.
Count
Type: Long
Optional. Number of items to return. If omitted, negative, or greater than the number of input items, all items are returned.
Seed
Type: Long
Optional. The starting point to be used for the generation of the random ordering. The default is 0.
(return)
Type: None
An array consisting of a randomized copy of the input list.
Remarks
An error occurs if List is a collection that doesn't support the For Each...Next syntax. When List is a collection object, the return value is an array that contains copies of the objects in the collection and the input collection object is unchanged. Because the return value is an array, it does not have a Count property.
If Seed is supplied, it is used to reset the starting point for the random number generator, as in SetRandomSeed, before the randomization.
If Seed is not supplied or has a value of 0, the function will use the starting point stored for the random number generator by the mrScriptBasic engine or Evaluate component and passed as a hidden parameter.
Each time you call one of the randomization functions, the starting point stored for the random number generator is updated. This means that if you call the function repeatedly without specifying the Seed parameter, the sequence of results is determined by the changing value passed as a hidden parameter. Specifying the Seed parameter is a way of resetting this sequence. It also means that the randomization can be repeated. For example, if you use this function to randomize a category list in an interview, by using the same seed value you could present the category list in the same sequence should the interview be restarted.
The Ran function is similar to using the ran keyword in Quancept.
Examples
Ran is useful when you are cleaning data. For example, when a respondent has selected more than one category in response to a single response question, you can use Ran to select one of the responses randomly, as shown in the following snippet of mrScriptBasic code:
If time_spent.AnswerCount() > 1 Then
  time_spent = time_spent.Ran(1)
End If
The next example shows using Ran with a multiple response variable called remember (which is in the UNICOM Intelligence Data File version of the Museum sample data set) in an SQL query. The example uses the Ran function twice, both times it is used to return one response from the list of responses stored in the variable. However, the first time the Seed parameter is not specified and the second time it is.
SELECT Respondent.Serial,
remember,
Ran(remember, 1) AS Remember1,
Ran(remember, 1, 1) AS Remember2,
remember.AnswerCount() AS HowMany
FROM vdata
WHERE remember IS NOT NULL
Here is the result set for the first eight respondents:
Remember Remember1 Remember2 HowMany
---------------------------------------------- ------------------- ------------------- -------
1 {dinosaurs,fish_and_reptiles,fossils,mammals,m {fish_and_reptiles} {dinosaurs} 7
2 {dinosaurs,fish_and_reptiles,fossils,mammals,m {origin_of_species} {fish_and_reptiles} 8
3 {dinosaurs,fossils,birds,insects,whales,mammal {minerals} {other} 11
4 {dinosaurs,conservation,birds,mammals,minerals {other} {mammals} 6
5 {dinosaurs,birds,minerals,human_biology,evolut {birds} {minerals} 5
6 {dinosaurs,birds,whales,mammals,origin_of_spec {mammals} {dinosaurs} 7
7 {dinosaurs,birds,whales,mammals,minerals,botan {human_biology} {birds} 8
8 {dinosaurs,insects,human_biology} {human_biology} {dinosaurs} 3
The results in the Remember2 column are different from those in the Remember1 column, because the Seed parameter was used to specify a different starting point for the randomization. Although the results appear to be different in the Remember2 column for every case, in fact the choice of the category is based on the same random number each time. The reason the results appear to be different is that the cases have different numbers of responses. The HowMany column shows us how many responses have been selected in each row. We can see that:
In rows where 3 or 7 responses were chosen, Remember2 contains the first response.
In rows where 4 or 8 responses were chosen, Remember2 contains the second response.
In rows where 5 responses were chosen, Remember2 contains the third response.
In rows where 6 responses were chosen, Remember2 contains the fourth response.
This is because if N is the random number being used, then:
N mod 3 = 0N mod 4 = 1N mod 5 = 2N mod 6 = 3N mod 7 = 0N mod 8 = 1
For example, N might be 777.
For an example of using Ran when cleaning data in a DataManagementScript (DMS) file, see Example 1: More than one response to a single response question.
See also
RanSequence
List functions