{smcl}
{* 24feb2005}{...}
{cmd:help recode} {right:dialog:  {bf:{dialog recode}}}
{hline}

{title:Title}

{p2colset 5 19 21 2}{...}
{p2col :{hi:[D] recode} {hline 2}}Recode categorical variables{p_end}
{p2colreset}{...}


{title:Syntax}

{phang}Basic syntax{p_end}
{p 8 16 2}
{cmd:recode} {varlist} {cmd:(}{it:rule}{cmd:)} 
[{cmd:(}{it:rule}{cmd:)} {it:...}]
[{cmd:,} {opth gen:erate(newvar)}]

{phang}Full syntax{p_end}
{p 8 16 2}
{cmd:recode} {varlist} {cmd:(}{it:erule}{cmd:)} 
[{cmd:(}{it:erule}{cmd:)} {it:...}] {ifin}
[{cmd:,} {it:options}]

{phang}
where the most common forms for {it:rule} are

{center:{c TLC}{hline 16}{c TT}{hline 13}{c TT}{hline 27}{c TRC}}
{center:{c |} {it:rule}           {c |} Example     {c |} Meaning                   {c |}}
{center:{c LT}{hline 16}{c +}{hline 13}{c +}{hline 27}{c RT}}
{center:{c |} {it:#} {cmd:=} {it:#}          {c |} 3 = 1       {c |} 3 recoded to 1            {c |}}
{center:{c |} {it:#} {it:#} {cmd:=} {it:#}        {c |} 2 . = 9     {c |} 2 and . recoded to 9      {c |}}
{center:{c |} {it:#}{cmd:/}{it:#} {cmd:=} {it:#}        {c |} 1/5 = 4     {c |} 1 through 5 recoded to 4  {c |}}
{center:{c |} {opt nonm:issing} {cmd:=} {it:#} {c |} nonmiss = 8 {c |} all other nonmissing to 8 {c |}}
{center:{c |} {opt mis:sing} {cmd:=} {it:#}    {c |} miss = 9    {c |} all other missings to 9   {c |}}
{center:{c BLC}{hline 16}{c BT}{hline 13}{c BT}{hline 27}{c BRC}}

{phang}
where {it:erule} has the form

{p 8 17 2}
{it:element} [{it:element ...}] {cmd:=} {it:el} [{cmd:"}{it:label}{cmd:"}]

{p 8 20 2} 
{opt nonm:issing =} {it:el} [{cmd:"}{it:label}{cmd:"}]

{p 8 17 2}
{opt mis:sing =} {it:el} [{cmd:"}{it:label}{cmd:"}]

{p 8 14 2}
{cmd:else} | {cmd:*} {cmd:=} {it:el} [{cmd:"}{it:label}{cmd:"}]

{phang}
{it:element} has the form

{p 8 12 2}
{it:el} | {it:el}{cmd:/}{it:el}

{phang}
and {it:el} is

{p 8 11 2}
{it:#} | {cmd:min} | {cmd:max}

{phang}
The keyword rules {cmd:missing}, {cmd:nonmissing}, and {cmd:else} must be the
last rules specified.  {cmd:else} may not be combined with {cmd:missing} and
{cmd:nonmissing}.

{synoptset 20 tabbed}{...}
{synopthdr}
{synoptline}
{syntab :Options}
{synopt :{opth gen:erate(newvar)}}generate {it:newvar} containing transformed
variables; default is to replace existing variables{p_end}
{synopt :{opt pre:fix(str)}}generate new variables with {it:str} prefix{p_end}
{synopt :{opt l:abel(name)}}specify a name for the value label defined by the
transformation rules{p_end}
{synopt :{opt copy:rest}}copy out-of-sample values from original
variables{p_end}
{synopt :{opt t:est}}test that rules are invoked and do not overlap{p_end}
{synoptline}
{p2colreset}{...}


{title:Description}

{pstd}
{cmd:recode} changes the values of numeric variables according to
the rules specified.  Values that do not meet any of the conditions of the
rules are left unchanged, unless an {it:otherwise} rule is specified.

{pstd}
A range {it:#1}{cmd:/}{it:#2} refers to {it:all} (real and integer)
values between {it:#1} and {it:#2}, including the boundaries {it:#1} and
{it:#2}.  This interpretation of {it:#1}{cmd:/}{it:#2} differs from that in
{help numlist:numlists}. 

{pstd}
{cmd:min} and {cmd:max} provide a convenient way to refer to the minimum and
maximum for each variable in {varlist} and may be used in both the from-value
and the to-value parts of the specification.  Combined with {cmd:if} and
{cmd:in}, the minimum and maximum are determined over the restricted dataset.

{pstd}
The keyword rules specify transformations for values not changed by
the previous rules:

{p2colset 9 26 27 2}{...}
{p2col: {opt nonm:issing}}all nonmissing values not changed by the rules{p_end}
{p2col: {opt mis:sing}}all missing values ({cmd:.}, {cmd:.a}, {cmd:.b},..., {cmd:.z}) not changed by the rules{p_end}
{p2col: {cmd:else}}all nonmissing and missing values not changed by the rules{p_end}
{p2col: {cmd:*}}synonym for {cmd:else}
{p2colreset}{...}

{pstd}
{cmd:recode} provides a convenient way to define value labels for the
generated variables during the definition of the transformation, reducing the
risk of inconsistencies between the definition and value labeling of
variables.  Value labels may be defined for integer values and for the
extended {help missing:missing values} ({cmd:.a}, {cmd:.b},..., {cmd:.z}), but
not for noninteger values and or for sysmiss ({cmd:.}).

{pstd}
While this is not shown in the syntax diagram, the parentheses around the
{it:rule}s and keyword clauses are optional if you transform only a
single variable and if you do not define value labels.


{title:Options}

{dlgtab:Options}

{phang}
{opt generate(newvar)} specifies the names of the variables that will contain
the transformed variables.  {opt into()} is a synonym for {opt generate()}.
Values outside the range implied by {opt if} or {opt in} are set to missing
({cmd:.}), unless the option {opt copyrest} is specified.

{pmore}
If {opt generate()} is not specified, the input variables are overwritten;
values outside the {opt if} or {opt in} range are not modified.  Overwriting
variables is dangerous (you cannot undo changes, value labels may be wrong,
etc.), so we strongly recommend specifying {opt generate()}.

{phang}
{opt prefix(str)} specifies that the recoded variables be returned in new
variables formed by prefixing the names of the original variables with
{it:str}.

{phang}
{opt label(name)} specifies a name for the value label defined from the
transformation rules.  {opt label()} may only be defined with {opt generate()}
(or its synonym, {opt into()}) and {opt prefix()}.  If a single variable is
recoded, the label name defaults to {newvar} unless a label with that name
already exists.

{phang}
{opt copyrest} specifies that out-of-sample values be copied from the original
variables.  In line with other data management commands, {cmd:recode} defaults
to setting {newvar} to missing ({cmd:.}) outside the observations selected by
the {opt if} {it:exp} and {opt in} {it:range}.

{phang}
{opt test} specifies that Stata test whether rules are ever invoked or that
rules overlap; for example, {cmd:(1/5=1) (3=2)}.


{title:Examples}

{phang}{cmd:. recode x (1=2) (2=1), gen(nx)}

{phang}{cmd:. recode x1 x2 (1 2 3/5=1) (6/10=2), gen(nx1 nx2)}

{phang}{cmd:. recode x1 x2 (1 2 3/5=1) (6/10=2), pre(n)}

{phang}{cmd:. recode x (1=6) (2=5) (3=4) (4=3) (5=2) (6=1) (nonmiss=0) (miss=.), gen(nx)}

{phang}{cmd:. recode x (min/0 = 0) (1/max = 1), gen(y)}

{phang}{cmd:. recode age (min/19=1) (20/29=2) (30/39=3) (40/49=4) (50/max=5), gen(cage)}

{phang}{cmd:. recode z {it:...} if sex==1, gen(rz) copy}

{phang}{cmd:. recode _all (.=.) (missing =.a)}

{phang}{cmd:. recode _all (.=.) (.a = .a) (missing =.a)}

{phang}{cmd:. recode x (1 2=1 low) (3=2 medium) (4 5=3 high) (nonmiss=9) (miss=.), gen(z)}

{phang}{cmd:. recode x y (1 2 = 1 low) (3 = 2 medium) (4 5 = 3 high) (nonmissing = 9 "something else") (missing = .), gen(Rx Ry) label(Cat3)}

{txt}{phang}Tip:  Long {cmd:recode} commands may conveniently be written using
the line continuation {cmd:///}.  For example
{cmd}

    . recode x y (1 2 = 1 low)  ///
                 (3   = 2 medium)  ///
                 (4 5 = 3 high)  ///
                 (nonmissing = 9 "something else")  ///
                 (missing = .)  ///
               , gen(Rx Ry) label(Cat3){txt}


{title:Also see}

{psee}
Manual:  {bf:[D] recode}

{psee}
Online:  {helpb generate}, {helpb mvencode}
{p_end}