{smcl}
{hline}
help for {cmd:mmerge}{right:[jw]  Feb 26, 2002}
{hline}

{title:Easy and safe merging of datasets}

    Basic syntax

{p 8 12}{cmd:mmerge} {it:match-variable(s)} {cmd:using} {it:filename} 
    [{cmd:,} 
        {{cmdab:si:mple} | {cmdab:ta:ble}}
        {cmdab:um:atch(}{it:varlist}{cmd:)} 
        {cmdab:uk:eep(}{it:varlist}{cmd:)} 
    ]

    Full Syntax

{p 8 12}{cmd:mmerge} {it:match-variable(s)} {cmd:using} {it:filename} 
    [{cmd:,} 
        {bind:{ {cmdab:t:ype(}{it:type_value}{cmd:)} {cmdab:unm:atched(}{it:unmatched_value}{cmd:)} | {cmdab:si:mple} | {cmdab:ta:ble} }} 
        {cmdab:m:issing(}{it:m_value}{cmd:)} 
        {cmdab:nol:abel} 
        {cmd:replace} 
        {cmd:update} 
        {cmd:_merge(}{it:varname}{cmd:)} 
        {cmdab:nosh:ow}
        {bind:{ {cmdab:uk:eep(}{it:varlist}{cmd:)} | {cmdab:ud:rop(}{it:varlist}{cmd:)} }}
        {cmd:uif(}{it:exp}{cmd:)} 
        {cmdab:um:atch(}{it:varlist}{cmd:)}
        {bind:{ {cmdab:un:ame(}{it:stub}{cmd:)} | {cmdab:uren:ame(}{it:rename_specs}{cmd:)} }}
        {cmdab:ul:abel(}{it:stub}{cmd:)} 
    ]

{p 8 8}where

{tab}    {it:type_value}      = { {cmdab:a:uto} | {cmd:1:1} | {cmd:1:n} | {cmd:n:1} | {cmd:n:n} | {cmdab:sp:read} }

{tab}    {it:unmatched_value} = { {cmdab:b:oth} | {cmdab:n:one} | {cmdab:m:aster} | {cmdab:u:sing} }

{tab}    {it:missing_value}   = { {cmdab:non:e} | {cmdab:v:alue} | {cmdab:nom:atch} }

{tab}    {it:rename_specs}    = {it:oldname newname} [{cmd:\} {it:oldname newname} {cmd:\} ...]


{title:Description}

{p}{cmd:mmerge} is an extension of {cmd:merge} that makes matched merging 
{hi:safe}. It requires users to specify the type of match to be performed; 
{cmd:mmerge} verifies that the requirements hold. It also makes merging 
{hi:easy}, though that may not be obvious at a first look at the full 
syntax diagram. Look at the examples first!


{title:Detailed description}

{it:Safety features}

{p 2 4}- The safety of merging crucially depends on the requirement that 
users should specify whether the match-variables form a key in the master 
and using data.  A key uniquely defines observations and does not contain 
missing values.{p_end}
{p 2 4}- In contrast with {cmd:merge}, the resulting data after {cmd:mmerge} 
is {hi:independent} of the order of observations in master and using data.  
As a consequence, you are not required to sort the data yourself.{p_end}
{p 2 4}- {cmd:merge} distinguishes between unmatched records due to missing 
values in the match variables ({cmd:_merge=-1,-2}) and to non-missing 
values ({cmd:_merge=1,2}). Here 1/-1 and 2/-2 refer to unmatched obs 
originating in the master and using data respectively.{p_end}
{p 2 4}- {cmd:mmerge} displays names of variables that occur in both master 
and using data.{p_end}

{it:Convenience features}

{p 2 4}- The master and using data are automatically sorted{p_end}
{p 2 4}- A {cmd:_merge} variable in master or using data will be 
         silently overwritten; this is not so bad as {cmd:mmerge} automatically 
         tabulates {cmd:_merge}{p_end}
{p 2 4}- The match-variable(s) of the using data can be named differently from
         the master data{p_end}
{p 2 4}- Selection of observations and variables in the using dataset is
         facilitated{p_end}
{p 2 4}- Prefixing strings to the names (and labels) of variables in the using
         data is supported{p_end}
{p 2 4}- Full renaming of variables in the using data is supported{p_end}
{p 2 4}- Value labels are added for the {cmd:_merge} variable 
         (label name {cmd:__MERGE}){p_end}


{title:Options to specify special cases}

{p 0 4}{cmd:simple} specifies matched merging in which the master and using 
    data supposedly describe the same objects, fully identified by the match 
    variables;, i.e., the match variables form a key in the master and 
    using data.

{p 4 4}{cmd:simple} is equivalent to specifying options {cmd:type(1:1)} and 
    {cmd:unmatched(both)}, and invoking {inp:assert _merge==3} upon the 
    completion of {cmd:mmerge}.

{p 0 4}{cmd:table} specifies a "table lookup merge", in which the master data 
    contains data on objects of type A (e.g., households) that contain an 
    object of type B (e.g., a city), identified by the match-variables (e.g., 
    the city of residence), while the using data contains descriptions of 
    type B (cities). Thus, the match variables should form a key in the using 
    data.

{p 4 4}{cmd:table} is equivalent to specifying options 
    {cmd:type{n:1} unmatched(master)}.

{p 4 4}In a future version of {cmd:mmerge}, I may support additional 
    "special types of matched merging".


{title:Options for matching}

{p 0 4}{cmd:types(}{it:str}{cmd:)} specifies whether the match variables are 
keys in master and using data. Valid values are

{p 8 20}{cmd:1:1}{space 9}key in the master and using data{p_end}
{p 8 20}{cmd:1:n}{space 9}key in master data{p_end}
{p 8 20}{cmd:n:1}{space 9}key in using data{p_end}
{p 8 20}{cmd:n:n}{space 9}no keys; {cmd:mmerge} performs a relational join via {cmd:joinby}{p_end}

{p 8 20}{cmd:spread}{space 5}
    {cmd:mmerge} determines which of {cmd:1:n} or {cmd:n:1} holds{p_end}
{p 8 20}{cmd:auto}{space 8}{cmd:mmerge} determines the match-type. (default){p_end}

{p 4 4}While {cmd:auto} is easy, you are strongly advised to specify your 
    knowledge of the relationship between the master and using data via 
    one of the other values.  This allows {cmd:mmerge} to test whether your 
    understanding is consistent with the data.

{p 4 4}{cmd:missing(}{it:str}{cmd:)} specifies how missing values in the 
    match variables are treated.  Valid values are

{p 8 20}{cmd:none}{space 7}
    missing values not allowed in the match vars (default){p_end}
{p 8 20}{cmd:value}{space 6}
    missing values are treated as ordinary values{p_end}
{p 8 20}{cmd:nomatch}{space 4}
    missing values of the match vars in the master should {hi:not} match 
    missing values in the match-vars of the using data.{p_end}


{title:Options for merging}

{p 0 4}{cmd:unmatched(}{it:str}{cmd:)} specifies whether non-matching 
    observations in the master and using data are included in the 
    merge result. Valid values are

{p 8 20}{cmd:none}{space 8}only completely maching obs are retained{p_end}
{p 8 20}{cmd:both}{space 8}non-matching obs from master and using are included (default){p_end}
{p 8 20}{cmd:master}{space 6}non-matching obs from master are included{p_end}
{p 8 20}{cmd:using}{space 7}non-matching obs from using are included{p_end}

{p 0 4}{cmd:nolabel} prevents Stata from copying the value label definitions 
    from the disk dataset.  Even if you do not specify this option, in no event 
    do label definitions from disk replace those already in meory.

{p 0 4}{cmd:update} varies the action merge takes when an observation is 
    matched.  By default, the master data is held inviolate--values from 
    the master data are retained when the same variables are found in both 
    datasets.  If {cmd:update} is specified, however, the values from the 
    using data are retained in cases where the master data constains missing.

{p 0 4}{cmd:replace}, allowed with update only, specified that even in the 
    case when the master data contains nomissing values, they are to be 
    replaced with corresponding values from the using data when corresponding 
    data are not equal.  A nonmissing value, however, will never be replaced 
    with a missing value.

{p 0 4}{cmd:_merge(}{it:varname}{cmd:)} specifies the name of the variable 
    that will mark the source of the resulting observation.  The default is 
    {cmd:_merge(_merge)}.

{p 0 4}{cmd:noshow} specifies that the report on the files and the contents 
    of {cmd:_merge} is suppressed.


{title:Options for manipulating the using data ("u"-options)}

{p 0 4}{cmd:ukeep(}{it:varlist}{cmd:)}
{cmd:udrop(}{it:varlist}{cmd:)}
    specifies a varlist in the using data that has to be kept (dropped) 
    before being merged into the master data.  It is not valid to specify 
    both {cmd:ukeep} and {cmd:udrop}.  If neither is specified, all 
    variables of the using data are used.  The match variable(s) need not 
    be specified in {cmd:ukeep}; they are automatically included in 
    {cmd:ukeep} (excluded from {cmd:udrop}).

{p 0 4}{cmd:uif(}{it:exp}{cmd:)} specifies that only the observations in the 
    using data that meet expression {it:exp} are to be used.  Properness of 
    the key in the using data is determined {hi:after} {it:uif} is processed.

{p 0 4}{cmd:umatch(}{it:varlist}{cmd:)} specifies the names of the match 
    variables in the using data.  The {cmd:umatch} variables are associated 
    with the match variables in the specified order.  Clearly, the number 
    of match variables in {cmd:umatch} should be the same as the number of 
    matching variables in the master.

{p 4 4}{cmd:mmerge} renames the {cmd:umatch} variables to the master match 
    variable names after {cmd:ukeep}/{cmd:udrop} have been processed, but 
    before {cmd:urename} is processed. An error occurs if there are naming 
    conflicts.

{p 0 4}{cmd:urename(}{it:speclist}{cmd:)} specifies a list of "oldname newname" 
    clauses to be applied to the using data, separated by a backslash {cmd:\}.  
    Note that {cmd:urename} is applied {hi:after} {cmd:ukeep}/{cmd:udrop}, and 
    hence {cmd:ukeep}/{cmd:udrop} should use the original names.  It is not 
    allowed to rename the match variables here.  Use {cmd:umatch} instead.

{p 0 4}{cmd:uname(}{it:stub{cmd:)} specifies a stub prefixed to the names of 
    the variables imported from the using data, truncated at 32 characters.  
    {cmd:uname} may not be combined with {cmd:urename}.

{p 0 4}{cmd:ulabel(}{it:stub}{cmd:)} specifies a stub to be prefixed to the 
    variable labels of the imported variables from the using data.


{title:Examples}

{p 0 4}1.  You have two datasets ({cmd:auto1} and {cmd:auto2}) with properties 
of cars, identified by the variable {cmd:make} in both files.  You can merge 
the two datasets with

	{inp:. use auto1}
	{inp:. mmerge make using auto2, type(1:1) unmatched(both)}

{p 4 4}to obtain a dataset on all cars represented in either of the data sets.
Since {cmd:both} is the default value of the option {cmd:unmatched}, it could 
actually have been omitted.  To obtain a dataset that does not include cars 
that occur in only of the datasets, issue the command

	{inp:. mmerge make using auto2, type(1:1) unmatched(none)}

{p 4 4}If the identifier in {cmd:auto2} was named {cmd:brand},

	{inp:. mmerge make using auto2, type(1:1) umatch(brand)}

{p 4 4}If you had been convinced that the auto1 and auto2 describe the same 
cars, you could have specified {cmd:simple} instead of {cmd:type(1:1)} and 
{cmd:unmatched(both)}.  Then, in addition, {cmd:mmerge} would verify that 
your conviction holds true, displaying an error message otherwise.


{p 0 4}2.  You have a data set of individuals (indiv) and a dataset of 
households ({cmd:hhold}) with key {cmd:hhid}.  The variable {cmd:hhid} is 
also in dataset {cmd:indiv} to specify the household to which individuals 
belong.  You want to add the household level variables to the individuals. 
This is an example of "table lookup merging",

	{inp:. use indiv}
	{inp:. mmerge hhid using hhold, table}

{p 4 4}One might also have typed

	{inp:. mmerge hhid using hhold, type(n:1)}
	
{p 4 4}Alternatively, you could switch the role of {cmd:indiv} and {cmd:hhold},

	{inp:. use hhold}
	{inp:. mmerge hhid using indiv, type(1:n)}

{p 4 4}If you are a bit like me, you'll be easily confused between {cmd:1:n} 
and {cmd:n:1}.  You can ask {cmd:mmerge} to settle the issue for you with 
the match type {cmd:spread}.

	{inp:. use indiv}
	{inp:. mmerge hhid using hhold, type(spread)}

{p 4 4}Typically, {cmd:hhold} contains many variables, and you only want to 
import some of them, say the city of residence ({cmd:city}) and number of 
kids ({cmd:nkids}).  This is faciliated by the {cmd:ukeep} option.

	{inp:. use indiv}
	{inp:. mmerge hhid using hhold, table ukeep(city nkids)}


{title:Saved results}

{cmd:mmerge} saves in {cmd:r()}

    scalar

        {cmd:mobs}      number of obs in master data
        {cmd:mvar}      number of vars (incl match vars) in master data
        {cmd:mkey}      boolean: match vars form key in master data
        {cmd:uobs}      number of obs in using data
        {cmd:uvar}      number of vars (incl match vars) in using data
        {cmd:ukey}      boolean: match vars form key in using data

    local

        {cmd:mfile}     full name of master data
        {cmd:mmatch}    names of matching vars in master data
        {cmd:ufile}     full name of using data
        {cmd:umatch}    (original) names of matching vars in using data
        {cmd:common}    common variables (excl match vars) in master and using


{title:Author}

{p}This commands was written by Jeroen Weesie, Dept of Sociology, Utrecht 
University.  I want to acknowledge stimulating discussions with Bill Gould, 
Chris Snijders, and Fred Wolfe.  Comments and suggestions are welcomed.


{title:Also See}

 Manual:  {hi:[U] 25 Commands for combining data}
          {hi:[R] merge}
          {hi:[R] joinby}

On-line:  {help append}    Append datasets -- add cases
          {help cross}     Form every pairwise combination of two datasets
          {help fillin}    Rectangularize dataset
          {help joinby}    Form all pairwise combinations within groups
          {help merge}     Merge datasets -- add variables
