{smcl}
{* 21may2008}{...}
{cmd: help mergel}
{hline}

{title:Title} 
 
{pstd}{hi:mergel} - Less Irritating Merging

{title:Syntax} 
 
{pmore}
{cmdab:mergel} {it:mergevars} {cmd:using} {help altpath:{it:alt-path}} [{cmd:,} {it:options}]

{pstd}Where {it:mergevars} is

{pmore}{it:varname1} [{cmd:(}{it:varname1A}{cmd:)}] [{it:varname2} [{cmd:(}{it:varname2A}{cmd:)}]...]

{pmore}{it:varname#} is the name of a variable in the {hi:{it:Current Data}}

{pmore}{it: varname#A} is the name of the corresponding variable in another file, the {hi:{it:Merge File}} 

{synoptset 18 tabbed}{...}
{synopthdr}
{synoptline}
{synopt :{opt keep(evarlist)}}add/update (and perhaps rename) these variables from the {hi:{it:Merge File}}{p_end}
{synopt :{cmdab:a:ll}}append all extra (non-matching) records from the {hi:{it:Merge File}}{p_end}
{synopt :{cmdab:m:ulti}}allow each record in the {hi:{it:Current Data}} to match more than one record from the {hi:{it:Merge File}}{p_end}
{synopt :{cmdab:ch:oose()}}choose one record from each set of matching records in the {hi:{it:Merge File}}{p_end}
{synopt :{cmdab:e:xpress}}summarize results and drop {it:_merge} variable{p_end}
{synopt :{cmdab:o:nly}}drop records from the {hi:{it:Current Data}} that did not match{p_end}
{synopt :{cmd:onlynot}}drop records from the {hi:{it:Current Data}} that {it:did} match{p_end}
{synopt :{cmdab:p:erfect}}require that each record in the {hi:{it:Current Data}} has one and only one match in the {hi:{it:Merge File}}{p_end}
{synopt :{cmdab:case:sensitive}}use case-sensitive matching for string {it:mergevars}{p_end}
{synopt :{cmdab:replace}}replace {hi:{it:Current Data}} with data from the {hi:{it:Merge File}}{p_end}
{synopt :{cmdab:n:otes}}copy notes into the {hi:{it:Current Data}} from the {hi:{it:Merge File}}{p_end}
{synopt :{cmdab:stconfig()}}passes configuration information to StatTransfer{p_end}
{synoptline}
{p2colreset}{...}

{title:Description}

{pstd}{cmd:mergel} can be used when only a single {hi:{it:Merge File}} is to be merged into the {hi:{it:Current Data}}. {cmd:mergel} takes care of all necessary renaming, sorting, case conversion, and converting from string to numeric.
It will also merge from non-Stata files, if StatTransfer is available.

{pstd}{it: varname#A} only needs to be specified if it differs from {it:varname#}. 

{pstd}For matching records, missing data from one dataset will be replaced by non-missing data from the other dataset.

{pstd}Unless modified by options (see below), {cmd:mergel}:

{p 8 11 2}o- {bf:adds nothing} to the {hi:{it:Current Data}} except the {it:_merge} variable

{p 8 11 2}o- automatically tabulates the {it:_merge} variable

{p 8 11 2}o- allows several records in the {hi:{it:Current Data}} to "look up" the same single record in the {hi:{it:Merge File}}

{p 8 11 2}o- reports an error if a record in the {hi:{it:Current Data}} has more than one match in the {hi:{it:Merge File}}

{title:Options}

{phang}{opt keep(evarlist)} specifies {bf:variables} to be added or updated from the {hi:{it:Merge File}}, and optionally the names those variables should have in the {hi:{it:Current Data}}.
{it:evarlist} is a standard {varlist} with the addition of name-pairs of the form:

{pmore}{it:merge-file-varname}{cmd:->}{it:current-data-varname}

{pmore}That is, variables in {opt keep(evarlist)} may be renamed by individually listing their original names, and appending {cmd:->}{it:newname} to each original name.

{phang}{cmdab:a:ll} causes any unmatched {bf:records} from the {hi:{it:Merge File}} to be appended to the {hi:{it:Current Data}}.

{phang}{cmdab:m:ulti} allows a record in the {hi:{it:Current Data}} to match multiple records in the {hi:{it:Merge File}}. Records will be added to the {hi:{it:Current Data}} so that there is one for every match.

{pin}It doesn't matter whether records in the {hi:{it:Current Data}} are unique; if three records in the {hi:{it:Current Data}} match five records in the {hi:{it:Merge File}}, there will be fifteen records as a result of the merge.

{phang}{cmdab:ch:oose(}{{cmd:first}|{cmd:last}} [{varlist}]{cmd:)} selects a single record from multiple matches in the {hi:{it:Merge File}}. {varlist} specifies a sort order within each matching group of records,
and {cmd: first} or {cmd: last} specifies the corresponding record as the one to merge.
If {varlist} is not specified, the first or last record is chosen without additional sorting; this could be a random choice, if the {hi:{it:Merge File}} was not already sorted.

{phang}{cmdab:e:xpress}, in the absence of errors, produces abbreviated output and automatically drops the {it:_merge} variable. 

{phang2}{cmdab:o:nly} or {cmd:onlynot} can be used in addition to {cmdab:e:xpress}. Each keeps only a subset of the {hi:{it:Current Data}}: {cmdab:o:nly} keeps only records that matched, and {cmd:onlynot} keeps only records that did not match.

{pmore2}Note that unmatched records from the {hi:{it:Merge File}} are unaffected; they will be added if and only if {cmdab:a:ll} is specified.

{phang}{cmdab:p:erfect} overrides {cmdab:m:ulti}, {cmdab:e:xpress}, and {cmdab:o:nly}/{cmd:onlynot}. It requires every record in the {hi:{it:Current Data}} to have exactly one matching record in the {hi:{it:Merge File}}.

{pin}If {cmdab:a:ll} is specified along with {cmdab:p:erfect}, then a one-to-one match is required not only for every record in the {hi:{it:Current Data}}, but for every record in the {hi:{it:Merge File}} as well.
That is, the two files must be in exact one-to-one correspondence.

{pin}If there are no errors when {cmdab:p:erfect} is specified, there is no output, and the {it:_merge} variable is dropped.

{phang}{cmdab:case:sensitive} uses case-sensitive matching, rather than the default, case-insenstive matching. Either way, the values in the {hi:{it:Current Data}} are unchanged, and either way, a case mismatch in a {opt keep()} variable,
as opposed to a {it:mergevar}, will cause an error.

{phang}{cmdab:n:otes} causes any notes from the {hi:{it:Merge File}} to be copied into the {hi:{it:Current Data}}.

{phang}{opt stconfig(SToptions)} passes StatTransfer configuration information through to StatTransfer. The possible contents are the same as those for the {cmd:config()} option of {help callst}.

{title:Examples}

    {cmd:. mergel ssn using a spacey file name}

    {cmd:. mergel ssn using excelfile.xls, express only}

    {cmd:. mergel ssn (socnum) using otherfile, perfect}

{title:Also see}

{pstd}Online: help for {help merge}, {help joinby}

{pstd}Contact: {browse "mailto:elliott.lowy@va.gov":Elliott Lowy}