-------------------------------------------------------------------------------
help for tuples
-------------------------------------------------------------------------------

Selecting all possible tuples from a list 

        tuples list [, [asis | varlist] display max(#) ]


Description

    tuples produces a set of local macros, each containing a list of the
    items defining a tuple selected from a given list. By default the set of
    macros is complete, other than the tuple containing no selections. By
    default the given list is tried as a variable list, but if it is not a
    variable list any other kind of list is acceptable, except that no other
    kind of expansion takes place.


Remarks 

    Given a list of n items, tuples produces 2^n - 1 macros, named tuple1
    upwards, which are all possible distinct singletons (each individual
    item); all possible distinct pairs; and so forth. Thus given frog toad
    newt, local macros tuple1 through tuple7 contain

    newt
    toad 
    frog 
    toad newt 
    frog newt 
    frog toad 
    frog toad newt 

    Here n = 3, 2^n - 1 = 7 = comb(3,1) + comb(3,2) + comb(3,3).

    Note that no tuple is the empty tuple with no selections. Users wishing
    to cycle over a set of tuples including the empty tuple can exploit the
    fact that the local macro tuple0 is undefined, and so empty (unless the
    user has previously defined it explicitly), so that tuple0 can invoked
    with the correct result.

    As usual, double quotes may be used to bind. Thus "a b c" d e is a list
    of three items, not five.

    Remember that the number of possible macros will explode with the number
    of items supplied. For example, if 10 items are supplied, there will be
    1023 macros. The number of macros created by tuples is returned in local
    macro ntuples.

    The algorithm used is naive and will be slow for above n ~ 10.

    Note: As of January 2011, this command is declared to supersede the
    author's selectvars.


Options 

    asis specifies that a list should be treated as is, and thus not
        unabbreviated as a varlist.

    varlist specifies that the list supplied should be a varlist, so that it
        is an error if the list is not in fact a varlist.

        asis and varlist are incompatible.

    display specifies that tuples should be displayed.

    max(#) specifies a maximum value for the number of items in a tuple.


Examples

    . sysuse auto, clear
    . tuples headroom trunk length displacement
    . gen rsq = .
    . gen predictors = ""
    . qui forval i = 1/`ntuples' {
    .         regress mpg `tuple`i''
    .         replace rsq = e(r2) in `i'
    .         replace predictors = "`tuple`i''" in `i'
    . }
    . gen p = wordcount(predictors) if predictors != ""
    . sort p rsq
    . l predictors rsq in 1/`ntuples'
 

    . tuples 1 2 3 4


Author

    Nicholas J. Cox, Durham University
    n.j.cox@durham.ac.uk


Acknowledgments 

    Sebastian Orbe reported a problem which led to a bug fix.