{smcl}
{* 22jul2011}{...}
{cmd: help codescan}
{hline}

{title:Title} 
 
{pstd}{hi:codescan} - Create flags/counts/first dates/last dates based on codes in archive files

{title:Description}

{pstd}For a set of patients at particular times, {cmd:codescan} will create variables describing their experiences within a specified time window.

{pstd}For example, you could use {cmd:codescan} to identify heart-disease patients by specifying diagnosis and/or procedure codes that must have been recorded within a year prior to an index date.
Or, you could use {cmd:codescan} to note the dates of the first & last primary care visits (ie, stop codes) within a year of hospital discharge.

{pstd}{cmd:codescan} {it:scans} a set of data files ({it:archives}) for codes in specified combinations ({it:codesets}). It records its findings (for each {it:codeset}) in up to four variables:

{phang2}o- a 1/0 {it:flag} that shows whether the {it:codeset} was found or not.

{phang2}o- a {it:count} of how many times the {it:codeset} was found.

{phang2}o- the date of {it:first occurrence} of the {it:codeset}.

{phang2}o- the date of {it:last occurrence} of the {it:codeset}.

{pstd}{cmd:codescan} draws information from four sources:

{phang2}o- The patient ids and reference dates come from the data in memory.

{phang2}o- Substantive information about the patients (ie, codes and their dates) comes from the archive files.

{phang2}o- Some info about the archives is stored in a pair of configuration files.

{phang2}o- The rest - ie, what to look for and what to return - is specfied in the command, or alternatively in yet another file.

{title:Syntax} 

{pmore}
{cmdab:codescan} { {it:scanners} | {cmd:using} {help altpath:{it:alt-path}} } {cmd:,} {opt id:var(varname)} {opt date:var(varname)} {opt archfiles(altpath)} [{it:options}]

{pstd}Where {it:scanners} will be described later...

{pmore} {it:stub}{cmd:(} {varlist} { {cmd:==} | {cmd:!=} } {it:codelist} [{cmd:,} options] {cmd:)}

{synoptset 18 tabbed}{...}
{synopthdr}
{synoptline}
{synopt :{opt id:var(varname)}}{p_end}
{synopt :{opt date:var(varname)}}{p_end}
{synopt :{opt archfiles(altpath)}}{p_end}
{synopt :{opt day:range()}}{p_end}
{synopt :{opt flag}}{p_end}
{synopt :{opt count}}{p_end}
{synopt :{opt first}}{p_end}
{synopt :{opt last}}{p_end}
{synopt :{opt config(altpath)}}{p_end}
{synoptline}
{p2colreset}{...}
{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}