CALL ALLPERM Routine

Generates all permutations of the values of several variables in a minimal change order.

Category:

Combinatorial

Syntax

CALL ALLPERM(count, variable–1<, variable–2 ...> );

Required Arguments

count

specifies an integer variable that ranges from 1 to the number of permutations.

variable

specifies either all numeric variables, or all character variables that have the same length. The values of these variables are permuted.

Restriction	Specify no more than 18 variables.
Requirement	Initialize these variables before you call the ALLPERM routine.

Details

CALL ALLPERM Processing

Use the CALL ALLPERM routine in a loop where the first argument to CALL ALLPERM takes each integral value from 1 to the number of permutations. On the first call, the argument types and lengths are checked for consistency. On each subsequent call, the values of two consecutive variables are interchanged.

Note: You can compute the number of permutations by using the PERM function. See PERM Function for more information.

If you call the ALLPERM routine and the first argument is out of sequence, the results are not useful. In particular, if you initialize the variables and then immediately call the ALLPERM routine with a first argument of K, your result will not be the Kth permutation (except when K is 1). To get the Kth permutation, you must call the ALLPERM routine K times, with the first argument taking values from 1 through K in that exact order.

ALLPERM always produces N! permutations even if some of the variables have equal values or missing values. If you want to generate only the distinct permutations when there are equal values, or if you want to omit missing values from the permutations, use the LEXPERM function instead.

Using the CALL ALLPERM Routine with Macros

You can call the ALLPERM routine when you use the %SYSCALL macro. In this case, the variable arguments are not required to be the same type or length. If %SYSCALL identifies an argument as numeric, then %SYSCALL reformats the returned value.

If an error occurs during the execution of the CALL ALLPERM routine, then both of the following values are set:

&SYSERR is assigned a value that is greater than 4.
&SYSINFO is assigned a value that is less than -100.

If there are no errors, then &SYSERR is set to zero, and &SYSINFO is set to one of the following values:

0 if count=1
J if 1<count<=N! and the values of variable-J and variable-K were interchanged, where J+1=K
-1 if count>N!

Comparisons

SAS provides three functions or CALL routines for generating all permutations:

ALLPERM generates all possible permutations of the values, missing or nonmissing, of several variables. Each permutation is formed from the previous permutation by interchanging two consecutive values.
LEXPERM generates all distinct permutations of the nonmissing values of several variables. The permutations are generated in lexicographic order.
LEXPERK generates all distinct permutations of K of the nonmissing values of N variables. The permutations are generated in lexicographic order.

ALLPERM is the fastest of these functions and CALL routines. LEXPERK is the slowest.

Examples

Example 1: Using CALL ALLPERM in a DATA Step

The following example generates permutations of given values by using the CALL ALLPERM routine.

data _null_;
   array x [4] $3 ('ant' 'bee' 'cat' 'dog'); 
   n=dim(x);
   nfact=fact(n); 
   do i=1 to nfact;   
      call allperm(i, of x[*]);
      put i 5. +2 x[*];
   end;
run;

SAS writes the following output to the log:

    1  ant bee cat dog
    2  ant bee dog cat
    3  ant dog bee cat
    4  dog ant bee cat
    5  dog ant cat bee
    6  ant dog cat bee
    7  ant cat dog bee
    8  ant cat bee dog
    9  cat ant bee dog
   10  cat ant dog bee
   11  cat dog ant bee
   12  dog cat ant bee
   13  dog cat bee ant
   14  cat dog bee ant
   15  cat bee dog ant
   16  cat bee ant dog
   17  bee cat ant dog
   18  bee cat dog ant
   19  bee dog cat ant
   20  dog bee cat ant
   21  dog bee ant cat
   22  bee dog ant cat
   23  bee ant dog cat
   24  bee ant cat dog

Example 2: Using CALL ALLPERM with Macros

The following is an example of the CALL ALLPERM routine that is used with macros. The output includes values for the %SYSINFO macro.

%macro test;            
   %let x1=ant;            
   %let x2=-.1234;            
   %let x3=1e10;            
   %let x4=hippopotamus;            
   %let nperm=%sysfunc(perm(4));            
   %do j=1 %to &nperm+1;               
      %syscall allperm(j, x1, x2, x3, x4);
      %let jfmt=%qsysfunc(putn(&j,5.));               
      %put &jfmt:   &x1 &x2 &x3 &x4 sysinfo=&sysinfo;            
   %end;         
%mend;
               
%test;