LEXPERK Function

Generates all distinct permutations of the non-missing values of n variables taken k at a time in lexicographic order.

Category:	Combinatorial
Restriction:	The LEXPERK function cannot be executed when you use the %SYSFUNC macro.

Syntax

LEXPERK(count, k, variable-1, …, variable-n)

Required Arguments

count

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

k

is a numeric constant, variable, or expression with an integer value between 1 and n inclusive.

variable

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

Requirement	Initialize these variables before you execute the LEXPERK function.
Tip	After executing LEXPERK, the first k variables contain the values in one permutation.

Details

The Basics

Use the LEXPERK function in a loop where the first argument to LEXPERK takes each integral value from 1 to the number of distinct permutations of k non-missing values of the variables. In each execution of LEXPERK within this loop, k should have the same value.

Number of Permutations

When all of the variables have non-missing, unequal values, the number of permutations is PERM(n,k). If the number of variables that have missing values is m, and all the non-missing values are unequal, the LEXPERK function produces PERM(n-m,k) permutations because the missing values are omitted from the permutations. When some of the variables have equal values, the exact number of permutations is difficult to compute, but PERM(n,k) provides an upper bound. You do not need to compute the exact number of permutations, provided you exit the loop when the LEXPERK function returns a value that is less than zero.

LEXPERK Processing

On the first execution of the LEXPERK function, 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 non-missing values are assigned in ascending order to the first n-m arguments following count.
LEXPERK returns 1.

On subsequent executions, up to and including the last permutation, the following actions occur:

The next distinct permutation of k non-missing values is generated in lexicographic order.
If variable-1 through variable-i did not change, but variable-i did change, where j=i+1, then LEXPERK returns j.

If you execute the LEXPERK function after generating all the distinct permutations, then LEXPERK returns –1.

If you execute the LEXPERK function with the first argument out of sequence, then the results are not useful. In particular, if you initialize the variables and then immediately execute the LEXPERK function with a first argument of j, you will not get the j^th permutation (except when j is 1). To get the j^th permutation, you must execute the LEXPERK function j times, with the first argument taking values from 1 through j in that exact order.

Comparisons

The LEXPERK function generates all distinct permutations of the non-missing values of n variables taken k at a time in lexicographic order. The LEXPERM function generates all distinct permutations of the non-missing values of n variables in lexicographic order. The ALLPERM function generates all permutations of the values of several variables in a minimal change order.

Example

The following is an example of the LEXPERK function.

data _null_;
   array x[5] $3 ('X' 'Y' 'Z' 'Z' 'Y');
   n=dim(x);
   k=3;
   nperm=perm(n,k);
   do j=1 to nperm+1;
      rc=lexperk(j, k, of x[*]);
      put j 5. +3 x1-x3 +3 rc=;
      if rc<0 then leave;
   end;
run;

SAS writes the following output to the log:

    1   X Y Y    rc=1
    2   X Y Z    rc=3
    3   X Z Y    rc=2
    4   X Z Z    rc=3
    5   Y X Y    rc=1
    6   Y X Z    rc=3
    7   Y Y X    rc=2
    8   Y Y Z    rc=3
    9   Y Z X    rc=2
   10   Y Z Y    rc=3
   11   Y Z Z    rc=3
   12   Z X Y    rc=1
   13   Z X Z    rc=3
   14   Z Y X    rc=2
   15   Z Y Y    rc=3
   16   Z Y Z    rc=3
   17   Z Z X    rc=2
   18   Z Z Y    rc=3
   19   Z Z Y    rc=-1