help chm
-------------------------------------------------------------------------------

Title

     chm -- Copy hard missings


Syntax

     Use as prefix

        chm varlist [, options] : command


     where command is one of

        generate [type] newvar[:lblname] =exp [if] [in]

        egen [type] newvar = fcn(arguments) [if] [in] [, egen_options]

        replace oldvar =exp [if] [in] [, nopromote]

        tabulate varname [if] [in] , generate (stubname) [tabulate_options]

        (if installed)
        center varlist [if] [in] [weight] [, center_options]


     Use as command

        chm varlist oldvar [if] [in] , replace [options]


     where oldvar is the variable to be replaced


    options                Description
    -------------------------------------------------------------------------
      mvc(mvc)             replace values in newvar/oldvar/stubname with mvc
      soft                 replace newvar/oldvar/stubname if varname has soft
                             missings (.)
      replace              replace values in oldvar; required option if chm
                             is used as command
      mi                   replace multiply imputed values with missings in
                             m>0
    -------------------------------------------------------------------------
    by is allowed, if command allows by.

    Syntax:
        by varlist [, by_options] : chm varlist [, chm_options] : command


Description

    chm copies hard missings (.a, ..., .z) from variables specified in
    varlist to newvar/oldvar/stubname. Existing hard missings in newvar
    (oldvar or stubname, respectively) are not replaced, meaning that if the
    second variable in varlist has hard missings, where the first also has
    hard missings, hard missing values are copied from the latter.

    Remarks: chm is useful if multiple imputation is planned. In mi
    environment, extended missing values (.a, ..., .z) are viewed as "hard
    missing" and are not imputed.


Options

    mvc(mvc) replaces values in newvar (oldvar or stubname) with mvc, where
        mvc is one of .a, ..., .z.

    soft additionally replaces values in newvar (oldvar or stubname) with
        soft missings (.), where variables in varlist have soft missings.
        Hard missings in newvar/oldvar/stubname are not replaced by soft
        missings.  If specified with mvc(mvc), mvc is used to replace values.

    replace is required if chm is used as command, because existing variables
        are altered. It is not allowed if chm is used as a prefix.

    mi copies hard missings from variables in the original dataset after
        multiple imputation. Each variable in varlist that has (hard) missing
        values in m=0, will be replaced with hard missing values in m>0. This
        option might be useful if imputations are done using ice (Royston
        2005), since all missing values (i.e. ., .a, ..., .z) will be
        imputed. The data must be in ice format, or flong style. The option
        may not be specified if chm is used as a prefix.


Examples

    Use as prefix

        . list

             +------+
             | var1 |
             |------|
          1. |    1 |
          2. |   .a |
          3. |    3 |
          4. |    . |
          5. |    5 |
             +------+

        . chm var1 : generate newvar = var1 * 10

        . list

             +---------------+
             | var1   newvar |
             |---------------|
          1. |    1       10 |
          2. |   .a       .a |
          3. |    3       30 |
          4. |    .        . |
          5. |    5       50 |
             +---------------+

        . chm var1 ,mvc(.m) : tabulate var1 ,generate(stubname)

        . list var1 stubname?

             +---------------------------------------+
             | var1   stubna~1   stubna~2   stubna~3 |
             |---------------------------------------|
          1. |    1          1          0          0 |
          2. |   .a         .m         .m         .m |
          3. |    3          0          1          0 |
          4. |    .          .          .          . |
          5. |    5          0          0          1 |
             +---------------------------------------+

        . chm var1 : replace var1 = 1

        . list var1

             +------+
             | var1 |
             |------|
          1. |    1 |
          2. |   .a |
          3. |    1 |
          4. |    1 |
          5. |    1 |
             +------+

    Use as command

        . chm newvar var1 ,replace soft

        . list var1 newvar

             +---------------+
             | var1   newvar |
             |---------------|
          1. |    1       10 |
          2. |   .a       .a |
          3. |    1       30 |
          4. |    .        . |
          5. |    1       50 |
             +---------------+


References

    Royston, P. (2005) Multiple imputation of missing values: update. Stata
    Journal 5 (2), 188-201.

                 
Author

    Daniel Klein, University of Bamberg, klein.daniel.81@gmail.com


Also see

    Online: replace, generate, egen, tabulate, mi
    if installed: center, ice