help labvalch3
-------------------------------------------------------------------------------

Title

     labvalch3 -- Change text in value labels


Syntax

        labvalch3 [lblname-list] , transformation-option [ options ]


    options                Description
    -------------------------------------------------------------------------
    transformation-options
      upper                change value labels to uppercased characters
      lower                change value labels to lowercased characters
      prefix(stub)         prefix value labels with stub
      suffix(stub)         suffix value labels with stub
      subst(this that)     in value labels change this to that
      before(before)       remove before and any text following
      after(after)         remove after and any text preceding
      noexclude            do not remove before or after
      strfcn(strfcn(args)) apply string function strfcn(args) to value labels
      symbol(char)         use char as placeholder in args.

    selection-options
      valid(numlist)       change value labels associated with valid numbers
      invalid(numlist)     do not change value labels associated with invalid
                             numbers
    -------------------------------------------------------------------------


Description

    labvalch3 changes text in value labels specified in lblname-list. If
    lblname-list is not specified, all value labels in memory are changed.

    If more than one transformation option is specified, labvalch3 applies
    options in the following order.

        1. before or after select text
        2. all occurrences of this are changed to that
        3. value labels are changed to upper- or lowercased characters
        4. string function strfcn(args) is applied
        5. prefix and/or suffix is added

    Reminder: modifiactions affect all variables that have the same value
    label as one of the value labels (or variables - see Remarks) in
    lblname-list attached.


Options

        +------------------------+
    ----+ Transformation options +-------------------------------------------

    upper changes value labels to uppercased characters. May not be specified
        with lower.

    lower changes value labels to lowercased characters. May not be specified
        with upper.

    prefix(stub) prefixes value labels with stub. May be combined with
        suffix().

    suffix(stub) suffixes value labels with stub. May be combined with
        prefix().

    subst(this that) substitutes all occurrences of this in value labels with
        that. Use double quotes if this or that contain embedded spaces. that
        may be empty (""), meaning remove this. Value labels in which this is
        not found are left unchanged.

    before(before) removes before and any text following from value labels.
        Thus, value labels will be changed to contain any text preceding
        before. Value labels in which before is not found are left unchanged.
        May not be specified with after.

    after(after) removes after and any text preceding from value labels.
        Thus, value labels will be changed to contain any text following
        after. Value labels in which after is not found are left unchanged.
        May not be specified with before.

    noexclude prevents labvalch3 from removing before or after from value
        labels. Specifying before(e) noexclude will change value label
        Domestic to Dome. Specifying before(e) will change value label
        Domestic to Dom.

    strfcn(strfcn(args)) applies any string function to value labels. In args
        use placeholder @ to refer to value labels. The general from of this
        option is strfcn(strfcn("@" [, args])).

    symbol(char) uses char as placeholder for value labels in args. Default
        placeholder is @. May only be specified with strfcn.

        +-------------------+
    ----+ Selection Options +------------------------------------------------

    valid(numlist) changes value labels associated with numbers specified in
        numlist.

    invalid(numlist) does not change value labels associated with numbers
        specified in numlist.


Remarks

    Also this is no longer shown in the syntax diagram, lblname-list is
    actually namelist and allows variable names. Thus, the syntax diagram
    reads

        labvalch3 [lblname-list|varlist] , transformation-option [ options ]

    The reason this is no longer shown, is that specifying variable names to
    refer to value label names violates Stata conventions. If variable foo
    has value label foobar attached, specifying foo in varlist, modifies
    value label foobar. The modifications also affect variable bar, if bar
    has value label foobar attached. I thank Daniel Possenriede for bringing
    this to may attention again.


Examples

        . sysuse auto
        . labvalch3 origin ,suffix(" Automobile")
        . labvalch3 foreign ,subst("Automobile" "Car")
        . labvalch3 ,upper
        . labvalch3 ,strfcn(proper("@"))
        . labvalch3 origin ,before(e) valid(1)

        
Acknowledgments

    This ado was suggested by Dimitriy V. Masterov on Statalist.

    The name labvalch3 is in line with labvalch from labutil package (see
    labutil) by Nick Cox, who also originated the tranformation options in
    his labvarch.

    Number 3 is chosen as a follow up on the ad hoc solution labvalch2 by
    Eric Booth (available under the link above). Also, labvalch3 changes the
    third element in label define lblname # label.


Author

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

Also see


    Online: label, string functions

    if installed: labvalch, labnoeq, strrec, labvarch, labutil2