{smcl}
{hline}
help for {hi:xi3}
{hline}

{title:Interaction expansion, enhanced}

{p}The {cmd:xi3} command is the same as the {cmd:xi} command, except that it allows 
3 way interactions, any combination of continuous and categorical variables, and 
performs additional coding schemes beyond indicator coding, and can create codings that
allow for testing simple contrasts and simple effects.  Its syntax is much like the
{cmd:xi} command.

{p 8 14}{cmd:xi3} [{cmd:,} {cmdab:pre:fix(}{it:string}{cmd:)}] {it:term(s)}

{p 8 14}{cmd:xi3} [{cmd:,} {cmdab:pre:fix(}{it:string}{cmd:)}] {cmd::}
		{it:any_stata_command} {it:varlist_with_terms}  {it:...}

{p}where a term is a mixture of continuous (Con) and categorical (Cat) variables
of the form:

{col 9}Main Effects
{col 9}Con{col 29}{it:varname}
{col 9}Cat{col 29}{cmd:prefix.}{it:varname}

{col 9}Two Way Interactions
{col 9}Cat by Cat{col 29}{cmd:prefix.}{it:varname1}{cmd:*prefix.}{it:varname2}
{col 9}Cat by Con{col 29}{cmd:prefix.}{it:varname1}{cmd:*}{it:varname2}
{col 9}Con by Cat{col 29}{it:varname1}{cmd:*prefix.}{it:varname2}
{col 9}Con by Con{col 29}{it:varname1}{cmd:*}{it:varname2}

{col 9}Three Way Interactions
{col 9}Cat by Cat by Cat{col 29}{cmd:prefix.}{it:varname1}{cmd:*prefix.}{it:varname2}{cmd:*prefix.}{it:varname3}
{col 9}Cat by Cat by Con{col 29}{cmd:prefix.}{it:varname1}{cmd:*prefix.}{it:varname2}{cmd:*}{it:varname3}
{col 12}...
{col 9}Con by Con by Con{col 29}{it:varname1}{cmd:*}{it:varname2}{cmd:*}{it:varname3}

{p}and you can also request simple effects for two way interactions using the {cmd:@} operator{p_end}

{col 9}Cat by Cat{col 29}{cmd:prefix.}{it:varname1}{cmd:@prefix.}{it:varname2}
{col 9}Con by Cat{col 29}{it:varname1}{cmd:@prefix.}{it:varname2}

{p}{hi:Additional Coding Schemes}

{p}The {cmd:xi3} command allows additional prefixes beyond {cmd:i.}{it:varname}.
These prefixes create a number of additional coding schemes, as described below.

{p}Please note: Starting with version 1.0 (April 7, 2003) the prefixes s, d, and f have been replaced with g, e, and a (respectively).  
This now permits the s., d. and f. prefixes to be used as time series operators reflecting seasonal differences, backward differencing, and
forward differencing (respectively).{p_end}

{p 5 17}{cmd:i.}varname - Indicator (dummy) coding: compares each level to the omitted group {p_end}
{p 5 17}{cmd:c.}varname - Centered indicator (dummy) coding {p_end}
{p 5 17}{cmd:g.}varname - reference Group coding: compares each level to a reference group {p_end}
{p 5 17}{cmd:e.}varname - Effect coding: deviations from the grand mean{p_end}
{p 5 17}{cmd:h.}varname - Helmert coding:         compares levels of a variable with the mean of subsequent levels{p_end}
{p 5 17}{cmd:r.}varname - Reverse Helmert coding: compares levels of a variable with the mean of previous levels{p_end}
{p 5 17}{cmd:a.}varname - Adjacent differences:          each level vs. the next level{p_end}
{p 5 17}{cmd:b.}varname - Backward adjacent differences: each level vs. the previous level {p_end}
{p 5 17}{cmd:o.}varname - Orthogonal polynomial contrasts u.varname - User defined coding scheme{p_end}

{p}{hi:Omitted Categories for Additional Coding Schemes}{p_end}

{p}The {cmd:refgroup} command is included with {cmd:xi3} to allow you to
select the reference group (also called the omitted category).  This is simply
a shorthand for using {inp:char {it:varname}[omit] {it:#}}.  The syntax of {cmd:refgroup}
is{p_end}

{col 9}{cmd:refgroup} {it:varname} {cmd:#}

{p}The following describes how omitted categories are handled using each
coding scheme.{p_end}

{p 5 5}{hi:Indicator coding}.  The choice of the omitted category works 
just like the original {cmd:xi} program, i.e. the first category is omitted
unless you use {inp:char {it:varname}[omit] {it:#}} or 
{inp:char _dta[omit] "prevalent"} (see {help xi:help xi} for more information).
Note that {inp:char _dta[omit] "prevalent"} is ignored for all of the other
other coding schemes.{p_end}



{p 5 5}{hi:Simple and Deviation coding}.  By default, the first category is the omitted
category and you can use {inp:char {it:varname}[omit] {it:#}} to choose a different level
to be omitted.{p_end}

{p 5 5}{hi:Helmert and Forward Difference coding}. For these coding schemes
the last category is always omitted (because the last category cannot be compared
to subsequent categories.{p_end}

{p 5 5}{hi:Reverse Helmert and Backward Difference coding}. For these coding schemes
the first category is always omitted (because the first category cannot be compared
to prior categories.{p_end}

{p 5 5}{hi:Orthogonal Polynomial coding}. The kth level is omitted.{p_end}

{p 5 5}{hi:User Defined coding}.  The user defines {it:k-1} contrasts to be
tested, as described in the section Creating User Defined Coding below.{p_end}

{p}{hi:Creating User Defined Coding}{p_end}

{p}It may be easiest to describe user defined coding via an example.
Say you have a variable {hi:ses} with 3 levels, and you wish to form 2 comparisons.
The first will compare level 1 with levels 2 and 3, and the second will compare
levels 1 and 3.  The comparison coefficients for these two comparisons would be.

{p 5 5}comparison 1: {inp:1 -.5 -.5}{p_end}
{p 5 5}comparison 2: {inp:1   0  -1}{p_end}

{p}You indicate these comparisions like this{p_end}

{p 5 5}{inp:. char ses[user] (1 -.5 -.5 \ 1 0 -1)}{p_end}

{p}{hi: Simple Comparisons and Simple Effects}

{p}Say you wanted to specify {hi:deviation} contrasts on {hi:varname1} at
each level of {hi:varname2}, along with {hi:simple} contrasts on {hi:varname2}.
 You can use {cmd:@} like this to request that coding.{p_end}

{p 5 5}{inp:d.varname1@s.varname2}{p_end}

{p}For example to perform {hi:forward difference} conrasts on {hi:ses}
at each level of {hi:female} and {hi:simple} coding on female, you
could type{p_end}

{p 5 5}{inp:. xi3 f.ses@s.female}{p_end}

{p}The terms that would be created are listed below along with their
interpretation.  

{hi:_Ises_1} {col 20}ses(1 vs. 2)
{hi:_Ises_2} {col 20}ses(2 vs. 3)
{hi:_Ifemale_1} {col 20}female(1 vs. 0)
{hi:_IsesWfem_1_1} {col 20}ses(1 vs. 2) @ female==0
{hi:_IsesWfem_2_1} {col 20}ses(2 vs. 3) @ female==0
{hi:_IsesWfem_1_2} {col 20}ses(1 vs. 2) @ female==1
{hi:_IsesWfem_2_2} {col 20}ses(2 vs. 3) @ female==1

{p}As you see, the lower order effects {hi:_Ises_1 _Ises_1} and {hi:_Ifemale_1}
are created as though you had used an interaction.  But the terms
{hi: _IsesWfem_1_1 _IsesWfem_2_1 _IsesWfem_1_2} and {hi:_IsesWfem_2_2} reflect simple
effects of {hi:ses} at the levels of {hi:female}.  For example {hi: _IsesWfem_1_1}
is the effect of low ses vs. middle ses for males, and {hi: _IsesWfem_1_2}
is the effect of middle ses vs. high ses for males.{p_end}

{p}If you wanted to form the simple effect of {hi:ses} for males, you would use the
{cmd:test} command to test {hi:_IsesWfem_1_1} and {hi:_IsesWfem_1_2}, for example{p_end}

{p 5 5}{inp:. test _IsesWfem_1_1 _IsesWfem_1_2}{p_end}

{p}Note that when you use {cmd:xi3} to create the coding scheme, it creates
both the main effects for {hi:female} and for {hi:ses} and for the simple
contrasts of {hi:ses} at each level of {hi:female}.  However, if you include all
of these terms in an estimation model, it will be overparameterized.  Instead, you
wish to drop, in this example, the main effect of {hi:ses} since that effect is also
contrained in the simple effects.  When you use {cmd:xi3} with a command, it 
automatically drops the {hi:ses} main effects, although those variables are
created, see example below.

{p 5 5}{inp:. xi3 : regress write f.ses@s.female}{p_end}

{text}f.ses             _Ises_1-3           (naturally coded; _Ises_3 omitted)
s.female          _Ifemale_0-1        (naturally coded; _Ifemale_0 omitted)
f.ses@s.female    _IsesWfem_#_#       (simple effects of ses at female)
{result}
      Source |       SS       df       MS              Number of obs =     200
-------------+------------------------------           F(  5,   194) =    5.67
       Model |  2278.24419     5  455.648837           Prob > F      =  0.0001
    Residual |  15600.6308   194  80.4156228           R-squared     =  0.1274
-------------+------------------------------           Adj R-squared =  0.1049
       Total |   17878.875   199   89.843593           Root MSE      =  8.9675

------------------------------------------------------------------------------
       write |      Coef.   Std. Err.      t    P>|t|     [95% Conf. Interval]
-------------+----------------------------------------------------------------
  _Ifemale_1 |   5.566752   1.366513     4.07   0.000     2.871622    8.261882
_IsesWfe~1_1 |  -2.953191   2.659325    -1.11   0.268    -8.198093     2.29171
_IsesWfe~2_1 |  -3.308877   2.117528    -1.56   0.120    -7.485208    .8674534
_IsesWfe~1_2 |      -1.75   2.046537    -0.86   0.394    -5.786318    2.286318
_IsesWfe~2_2 |  -4.715517   2.109094    -2.24   0.027    -8.875215   -.5558195
       _cons |   52.45513   .6832567    76.77   0.000     51.10756    53.80269
------------------------------------------------------------------------------{text}

Having done this test, we can test the simple effects of {hi:ses} for
males like this.

{p 5 5}{inp:. test  _IsesWfem_1_1 _IsesWfem_2_1}{p_end}
{text}
 ( 1)  _IsesWfem_1_1 = 0.0
 ( 2)  _IsesWfem_2_1 = 0.0
{result}
       F(  2,   194) =    2.61
            Prob > F =    0.0765

{text}
and the simple effects of {hi:ses} for females like this.

{p 5 5}{inp:. test  _IsesWfem_1_2 _IsesWfem_2_2}{p_end}
{text}
 ( 1)  _IsesWfem_1_2 = 0.0
 ( 2)  _IsesWfem_2_2 = 0.0
{result}
       F(  2,   194) =    4.25
            Prob > F =    0.0157
{text}

{title:Also see}

{p 1 14}Manual:  {hi:[U] 23 Estimation and post-estimation commands},{p_end}
	  {hi:[R] xi}
{p 0 19}On-line:  help for {help est}, {help postest}{p_end}