This helpfile defines a small dataset and shows what the TURF command           
does when various turf options are used on the dataset.                         
                                                                                
These examples show the command text that the TURF command expects.  The        
commands in each of these examples could have been constructed by using         
the TURF menus.                                                                 
                                                                                
This section was last updated on Jan 17, 2007.                                  
                                                                                
               *******************************                                  
               *  a simple dataset, used     *                                  
               *  in some examples that      *                                  
               *  show various TURF options  *                                  
               *******************************                                  
                                                                                
The following dataset has a case identifier (case.id), a case weight            
(www), and the responses to five variables.  The responses are zeros,           
ones and two twos.  This dataset is used to show various TURF options.          
                                                                                
The twos are treated differently from ones only when the                        
RESPONSE.WEIGHTS option is in use.                                              
                                                                                
 -----------------file ddd--------------                                        
 case.id  www    v1    v2    v3    v4    v5                                     
                                                                                
    9001    1     1     1     0     0     0                                     
    9002    1     1     1     0     0     0                                     
    9003    1     1     1     0     0     0                                     
    9004    1     1     1     0     0     0                                     
                                                                                
    9005    1     1     1     0     0     0                                     
    9006    1     1     1     0     0     0                                     
    9007    1     0     1     0     0     0                                     
    9008    1     0     0     1     0     0                                     
                                                                                
    9009    1     0     0     1     0     0                                     
    9010    1     0     0     1     0     0                                     
    9011    1     0     0     1     0     0                                     
    9012    1     0     0     0     1     0                                     
                                                                                
    9013    1     0     0     0     1     0                                     
    9014    1     0     0     0     1     0                                     
    9015    3     0     0     0     0     2                                     
    9016    3     0     0     0     0     2                                     
                                                                                
               *******************************                                  
               *  example 1:                 *                                  
               *  a TURF run using defaults  *                                  
               *******************************                                  
                                                                                
   turf ddd [drop case.id  www], size 3, reach.results rrr $                    
   list rrr $                                                                   
                                                                                
This command uses PPL (P-STAT Programming Language) to drop the first           
two variables, leaving five items for the turf analysis.  Using [keep v1        
to v5] would have done the same thing.                                          
                                                                                
SIZE 3 tells the command to look at the items in groups of 3.                   
REACH.RESULTS RRR creates a file named RRR that identifies the best             
groups.  That file is then listed.                                              
                                                                                
Ten groups will be tested: v1-v2-v3, v1-v2-v4, etc through v3-v4-v5.  We        
are looking for the group that has at least one positive response for           
the largest number of cases. In other words, which group of three items         
REACH the most cases ?                                                          
                                                                                
The best combination uses variables v2, v3, and v4, which reach 14 of           
the 16 cases. The FREQ score for that combination is also 14.                   
                                                                                
V1 is not included because it adds nothing once v2 is selected.  V1-v2-         
v3 have the highest number of of responses, but do not reach as many            
different cases as the group of v2-v3-v4.  The twos in cases 9015 and           
9016 on v5 are treated as ones.                                                 
                                                                                
               *************************************                            
               *  example 2:                       *                            
               *  a TURF run using case weighting  *                            
               *************************************                            
                                                                                
   turf ddd [drop case.id ],  size 3,  reach.results rrr,                       
                              case.weights www $                                
   list rrr $                                                                   
                                                                                
Here, WWW is not dropped because it is needed in the command.  We are           
seeking the group of three variables that has the largest WEIGHTED              
number of reached cases. Cases 9015 and 9016 are the only cases with a          
caseweight of other than one, so they are the ones affected by case-            
weights in this example.                                                        
                                                                                
The best group is v2-v3-v5, which reach 17 weighted cases.  V2 and V3           
provide 11 cases (all of which had unit weights).  Adding v4 would pro-         
vide 3 more, but adding v5 increases the weighted reach count by 6,             
since each of those two cases has a caseweight of three on WWW.  The            
FREQ score for that combination is also 17.                                     
                                                                                
               *****************************************                        
               *  example 3:                           *                        
               *  a TURF run using response weighting  *                        
               *  and a threshold of more than one     *                        
               *****************************************                        
                                                                                
   turf ddd [drop case.id  www],  size 3,  reach.results rrr,                   
                                  response.weights,                             
                                  reach.threshold 2 $                           
   list rrr $                                                                   
                                                                                
In examples 1 and 2, the responses to the items were treated in a zero          
versus nonzero manner.  Using RESPONSE.WEIGHTS causes the actual                
response values to contribute to the reach scores.  In addition, using          
REACH.THRESHOLD 2 causes a case to be reached only when its reach score         
for a given group is 2 or more.                                                 
                                                                                
The best group in this example is v1-v2-v5, which reached 8 cases.              
Cases 1 through 6 were reached by a response of 1 to both v1 and v2;            
cases 15 and 16 were reached because of responses of 2 on v5.  The FREQ         
score for that combination is 16.                                               
                                                                                
               **************************************                           
               *  example 4:                        *                           
               *  a TURF run using item weighting   *                           
               *  and a threshold of more than one  *                           
               **************************************                           
                                                                                
   /* create a file containing a weight value of 2 for item v3 */               
   make work1, vars name:c weight;                                              
   v3 2                                                                         
   $                                                                            
                                                                                
   turf ddd [drop case.id  www],  size 3,                                       
                                  reach.results   rrr,                          
                                  item.weights    work1,                        
                                  reach.threshold 2 $                           
   list rrr $                                                                   
                                                                                
Normally each item has a weight of one; each has the same contribution          
to a reach score. It is possible, however, to make some items worth more        
than other, possible reflecting, for example, differences in costs of           
the items.                                                                      
                                                                                
In this example, item v3 is weighted.  This is conveyed in file WORK1           
whose record defines a weight of 2 for item v3.  This causes responses          
on v3 to be worth twice what they would otherwise be worth. As in exam-         
ple 3, a threshold of 2 is used.                                                
                                                                                
The best group in this example is v1-v2-v3, which reach 10 cases.  Cases        
1 through 6 achieve a reach score of 2 using items v1 and v2.  Cases 8          
through 11 have reach scores of 2 because of the item weight given to           
v3.  The FREQ score for that combination is 20.