CALL LEXPERM Routine

Generates all distinct permutations of the nonmissing values of several variables in lexicographic order.

Category:	Combinatorial
Restriction:	This function is not supported in a DATA step that runs in CAS.
Interaction:	When invoked by the %SYSCALL macro statement, CALL LEXPERM removes the quotation marks from its arguments. For more information, see Using CALL Routines and the %SYSCALL Macro Statement.
Note:	Argument types for arguments that are updated must match in CALL routines. All argument types must be CHAR, VARCHAR, or NUMERIC. If the argument types do not match, a warning is issued to the log.

Table of Contents

Syntax

CALL LEXPERM(count, variable-1 <, …, variable-N>);

Required Arguments

count

specifies a numeric variable that has an integer value 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 by LEXPERM.

Requirement	Initialize these variables before you call the LEXPERM routine.

Details

Determine the Number of Distinct Permutations

These variables are defined for use in the equation that follows:

N: specifies the number of variables that are being permuted (that is, the number of arguments minus one).
M: specifies the number of missing values among the variables that are being permuted.
d: specifies the number of distinct nonmissing values among the arguments.
N_i: for i=1 through i=d, N_i specifies the number of instances of the ith distinct value.

The number of distinct permutations of nonmissing values of the arguments is expressed as follows:

$table with 1 row and 1 column , row1 column 1 , p equals . fraction open , n sub 1 , plus , n sub 2 , plus . . . plus , n sub d , close . factorial , over n sub 1 , factorial , n sub 2 , factorial . . . , n sub d , factorial end fraction . less than equals n factorial , end table. Click image for alternative formats.$

CALL LEXPERM Processing

Use the CALL LEXPERM routine in a loop where the argument count accepts each integral value from 1 to P. You do not need to compute P provided you exit the loop when CALL LEXPERM returns a value that is less than 0.

For 1=count<P, the following actions occur:

The argument types and lengths are checked for consistency.
The M missing values are assigned to the last M arguments.
The N-M nonmissing values are assigned in ascending order to the first N-M arguments following count.
CALL LEXPERM returns 1.

For 1<count<=P, the following actions occur:

The next distinct permutation of the nonmissing values is generated in lexicographic order.
If variable-1 through variable-I did not change, but variable-J did change, where J=I+1, then CALL LEXPERM returns J.

For count>P, CALL LEXPERM returns –1.

If the CALL LEXPERM routine is executed with the first argument out of sequence, the results might not be useful. In particular, if you initialize the variables and then immediately execute CALL LEXPERM with a first argument of K, you do not get the Kth permutation (except when K is 1). To get the Kth permutation, you must execute CALL LEXPERM K times. The first argument accepts values from 1 through K in that exact order.

Using the CALL LEXPERM Routine with Macros

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

If an error occurs during the execution of the CALL LEXPERM routine, 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, &SYSERR is set to 0 and &SYSINFO is set to one of the following values:

1 if 1=count<P
1 if 1<count<=P and the value of variable-1 changed
J if 1<count<=P and variable-1 through variable-I did not change, but variable-J did change, where J=I+1
–1 if count>P

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 LEXPERM in a DATA Step

The following example uses the DATA step to generate all distinct permutations of the nonmissing values of several variables in lexicographic order.

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

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

SAS writes the following results to the log:

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

Example 2: Using CALL LEXPERM with Macros

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

%macro test;
   %let x1=ant;
   %let x2=baboon;
   %let x3=baboon;
   %let x4=hippopotamus;
   %let n=4;
   %let nperm=%sysfunc(perm(4));
   %do j=1 %to &nperm;
      %syscall lexperm(j, x1, x2, x3, x4);
      %let jfmt=%qsysfunc(putn(&j, 5.));
      %put &jfmt: &x1 &x2 &x3 &x4 sysinfo=&sysinfo;
      %if &sysinfo<0 %then %let j=%eval(&nperm+1);
   %end;
 %mend;
     
 %test;

%macro test;
   %let x1=ant;
   %let x2=baboon;
   %let x3=baboon;
   %let x4=hippopotamus;
   %let n=4;
   %let nperm=%sysfunc(perm(4));
   %do j=1 %to &nperm;
      %syscall lexperm(j, x1, x2, x3, x4);
      %let jfmt=%qsysfunc(putn(&j, 5.));
      %put &jfmt: &x1 &x2 &x3 &x4 sysinfo=&sysinfo;
      %if &sysinfo<0 %then %let j=%eval(&nperm+1);
   %end;
 %mend;
     
 %test;