Functions and CALL Routines

LEXCOMB Function

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

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

Syntax
Arguments
Details
	The Basics
	Number of Combinations
	LEXCOMB Processing
Comparisons
Examples
	Example 1: Generating Distinct Combinations in Lexicographic Order
	Example 2: Generating Distinct Combinations in Lexicographic Order: Another Example
See Also

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

Number of Combinations

When all of the variables have non-missing, unequal values, then the number of combinations is COMB(n,k). If the number of variables that have missing values is m, and all the non-missing values are unequal, then LEXCOMB produces COMB(n-m,k) combinations because the missing values are omitted from the combinations.

When some of the variables have equal values, the exact number of combinations is difficult to compute, but COMB(n,k) provides an upper bound. You do not need to compute the exact number of combinations, provided that your program leaves the loop when LEXCOMB returns a value that is less than zero.

LEXCOMB Processing

On the first execution of the LEXCOMB 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.
LEXCOMB returns 1.

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

The next distinct combination of the non-missing 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 LEXCOMB returns j.

If you execute the LEXCOMB function after generating all the distinct combinations, then LEXCOMB returns -1.

If you execute the LEXCOMB 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 LEXCOMB function with a first argument of j, you will not get the j^th combination (except when j is 1). To get the j^th combination, you must execute the LEXCOMB function j times, with the first argument taking values from 1 through j in that exact order.

Comparisons

The LEXCOMB function generates all distinct combinations of the non-missing values of n variables taken k at a time in lexicographic order. The ALLCOMB function generates all combinations of the values of k variables taken k at a time in a minimum change order.

Examples

Example 1: Generating Distinct Combinations in Lexicographic Order

The following example uses the LEXCOMB function to generate distinct combinations in lexicographic order.

data _null_;
   array x[5] $3 ('ant' 'bee' 'cat' 'dog' 'ewe');
   n=dim(x);
   k=3;
   ncomb=comb(n,k);
   do j=1 to ncomb+1;
      rc=lexcomb(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   ant bee cat    rc=1
    2   ant bee dog    rc=3
    3   ant bee ewe    rc=3
    4   ant cat dog    rc=2
    5   ant cat ewe    rc=3
    6   ant dog ewe    rc=2
    7   bee cat dog    rc=1
    8   bee cat ewe    rc=3
    9   bee dog ewe    rc=2
   10   cat dog ewe    rc=1
   11   cat dog ewe    rc=-1

Example 2: Generating Distinct Combinations in Lexicographic Order: Another Example

The following is another example of using the LEXCOMB function.

data _null_;
   array x[5] $3 ('X' 'Y' 'Z' 'Z' 'Y');
   n=dim(x);
   k=3;
   ncomb=comb(n,k);
   do j=1 to ncomb+1;
      rc=lexcomb(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 Z    rc=2
    4   Y Y Z    rc=1
    5   Y Z Z    rc=2
    6   Y Z Z    rc=-1

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