.-
help for ^trinary^
.-

Extensions to generate to implement three-way logic
---------------------------------------------------

	^egen^ [type] newvar ^=^ fcn^(^stuff^)^ [^if^ exp] [^in^ range]
		       [^,^ options]


Description
-----------

(This is the general specification copied from the help for ^egen^.)

^egen^ creates newvar of the optionally specified storage type equal to
fcn^(^stuff^)^.  Depending on fcn^( )^, stuff refers to an expression, varlist,
or a numlist and the options are similarly function dependent.

Note that ^egen^ may change the sort order of your data.


^egen^ functions
--------------

(The option ^by(^byvarlist^)^ means that computations are performed 
separately for each group defined by byvarlist.)

  ^rtvor(^varlist^)^ [^, lib^eral]
    creates the (row) three-valued OR result of the variables in varlist.
    
  ^rtvand(^varlist^)^ [^, lib^eral]
    creates the (row) three-valued AND result of the variables in varlist.
    
  ^tvor(^exp^)^ [^, by(^varlist^) lib^eral]
    creates a constant (within ^varlist^) containing the three-valued OR result
    of the values in exp.
 
  ^tvand(^exp^)^ [^, by(^varlist^) lib^eral]
    creates a constant (within ^varlist^) containing the three-valued AND result
    of the values in ^exp^.

  ^tvnot(^exp^)^
    creates the three-valued logical negation of ^exp^.
    
    
All of these will impose a default type of byte on the result.

Note that NOT is a unary operation, and therefore tvnot does not perform any
combining of values.  It is neither a row-wise nor column-wise operation.

OR and AND are ostensibly binary operations, but since they are associative
(even in their three-valued versions), they can take an arbitrary number of
inputs.  Essentially...

 The OR result is true if any input is true.  It is false if all inputs are
 false.  It is missing if there is is at least one missing input and all
 other inputs are either false or missing.

 The AND result is false if any input is false.  It is true if all inputs are
 true.  It is missing if there is is at least one missing input and all
 other inputs are either true or missing.
 
The ^lib^eral option changes this somewhat.  This causes the operation to be
performed on only the nonmissing inputs.  It yields missing only if all
inputs are missing.  This is appropriate for reducing a multitude of similar
indicators to one.

Finally note that, while these functions greatly simplify the construction
of three-valued logic expressions, they can only do one type of operation
at a time.  So more complex expressions need to be built up in stages.
For example, the three-valued logic equivalent of
 
 gen byte k = a & (b | c | d)

would be...

 tempvar t1
 egen `t1' = rtvor(b c d)
 egen k = rtvand(a `t1')


Author
------

	David Kantor
		Institute for Policy Studies
		Johns Hopkins University
	dkantor@@jhunix.hcf.jhu.edu


Also see
--------


 Manual:  [R] egen
On-line:  help for @egen@, @functions@, @varlist@