*! Version 2.2 9Dec2022

Title

compuse -- Compare variable(s) in memory to identically named variable(s) on disk

Syntax

compuse
varlist
using filename
[if] [in]
,
sortvars
[options]

Options

Required "option"
sortvars(varlist) Variables present both in memory and on disk
which uniquely identify the sort order used to identify obserations to be compared.
This is the only required option

General options
MEMory(string) suffix to be appended to each variable name in memory to distinguish
it from the identically named variable on disk. (For backward compatibility, new(string) is a synonym.)
Default is to add the suffix _Master.

DISk(string) suffix to be appended to each variable name on disk to distinguish
it from the identically named variable in memory. (For backward compatibility, old(string) is a synonym.)
Default is to add the suffix _Using.

program(prog_name) name of the program used to compare the -master- to the -using- variables.
The default is to use Stata's compare, but the user might instead to choose to use compare2.

reldif option for computing the relative differences between
the two versions of the same variable, only useful
with the option program(compare2).

saving(filename,[replace]) Specify the name of a file to which the merged data,
including the sort variables specified in sortvars(varlist)
and the varlist variables with _Master and _Using suffixes,
are to be saved to disk. Default is to discard this merged data file.
The suboption replace permits compuse to overwrite
an existing data file of the same name.

verbose Annotate the output in the results window and log.

Options affecting the scatter plot comparing -master- to -using- versions of numerical variables
marker(varname) Specify a variable to be used
to label observations in the scatter plot of the master data file values
against the using data file values of the same variables.

xlog use a log scale for the horizontal axis on which the "using" variable
from disk is represented.

ylog use a log scale for the vertical axis on which the "master" variable
in memory is represented.

rescale Use the community-contributed program rescale to improve the legibiility of the axis labels.
This option rescales the units on both axes by a power of 10 and adds a note indicating the rescaled units.
Data saved by saving(filename,[replace]) is unchanged. The default is no rescaling.

saving(filename,[replace]) When this option is specified to save the merged data,
(as described under "General options" above), compuse also saves to disk all the created scatter plots.
The name of each of the saved scatter plot files is -filename_X.gph-, where -X- is the name of the variable compared.
The suboption replace permits compuse to overwrite existing graphics files on disk.

gr7 use Stata's version 7 graphics system to construct a scatter plot
comparing the memory to the disk variable. Default is to use scatter.
gr7 is faster than Stata's modern scatter command and
accommodates many of the above options.

scatopts(options) options passed through to the scatter or gr7 command.

byvars(help varlist:byvarlist) tables comparing the memory
to the disk version of the varlist variables are computed for each combination
of the byvarlist variables. Has no effect on the comparison plots.

* Any unrecognized options are passed to the twoway command
and thus must apply to both the scatter and the line graphs.
(Specifying any title option here supplants compuse's default title of the same type.
To append additional text to any of compuse's default titles,
specify the suboption suffix.)

Options affecting the table comparing -master- to -using- versions of string variables
tabopts(options) options passed through to the tabulate twoway command.

if and in are applied to both the master and using data prior to any comparisons; see [U] if, [U] in.

by is NOT allowed; see [D] by.

Description

compuse (think "compare using") is an extension to Stata's compare and cf commands.
Stata's compare command will only compare variables that are currently in memory, and thus have different names.
compuse instead safely compares one or more variables in memory
to identically named variables saved in a Stata -dta- file on disk.

After first preserving (see preserve) the data currently in memory,
compuse compares a list of variables in memory to
identically named variables located on disk in a file specified
by the using directive.
compuse, uses Stata's
compare program (or the user's selected
alternative equivalent program) to report the differences
and similarities between the memory and the disk versions
of each designated variable. In order to assure
that the data in memory is sorted the same way as the data
on disk and that comparable observations are compared,
the user must provide identifying
variables in the option sortvars(varlist).

When comparing numerical variables, compuse produces a scatter plot
of the memory or "master" version (the value in memory)
against the disk or "using" version (the value on disk in the "using" file).
Changed observations stand out by appearing above or below
the 45 degree line in the plot. By specifying the
option marker(varname), the user can label individual
observations of interest.

When comparing string variables, compuse produces a cross-tabulation
in which matching observations are on the main diagonal.

In order to compare versions of the same variable that are in memory
and on disk, compuse creates a temporary data set consisting only of
the variables being compared, the sort variable(s) and a marker variable,
if one has been specified. In this merged data set, in order to distinguish
the version of a variable that was in memory from the version
that was on disk, compuse appends a suffix (by default, "_Master") to the memory version
and a different suffix (by default, "_Using") to the disk version.
The user can select different suffixes with the options memory(suffix) and disk(suffix).
(For backward compatibility, new(string) and old(string) still work.)
By saving(filename,[replace]) this merged data to disk, the user
can conduct other analyses of the differences between the two versions of the variables.

On termination, compuse
restores the data in memory to its condition prior to compuse's execution.
Specifying the option saving(filename,[replace]) instructs compuse
to save the merged data file in filename.dta and the scatter plots
depicting the match beween master and using versions of each variable before it
restores the original data.

Example

Setup

. webuse fullauto, clear

Create a string variable named -quality- from the 1977 repair record

. decode rep77 , gen(quality)

Save this version of the data to disk.

. tempfile otherfile

. save `otherfile'

Abitrarily modify 40% of the observations of the variable -price-.

. replace price = price * (1 + uniform()) if uniform() > .6

Create a new version of -quality- from the 1978 repair record.

. drop quality

. decode rep78, gen(quality)

Compare versions of -price- on a scatter plot and of -quality- in a cross-tab. Use -verbose- option.

. compuse price quality using `otherfile' , sortvars(order) marker(make) verbose

Restrict comparisons to foreign cars.

. compuse price quality using `otherfile' if foreign , sortvars(order) marker(make) verbose

Use log scales to improve the legibility of the scatter plot.

. compuse price quality using `otherfile', sortvars(order) marker(make) xlog ylog verbose

Change the color scheme, add more text to the note and omit the -verbose- option.

. compuse price using `otherfile', sortvars(order) marker(make) scheme(s1rcolor) xlog ylog note("More text for the note", suffix)

Save the merged data for further analysis.

. compuse price qual using `otherfile', sortvars(order) marker(make) saving(mergedta, replace)

. dir mergedta.dta

. use mergedta, clear

. describe

. summarize

. tab make if qual_Master~=qual_Using

. erase mergedta.dta

Authors

Mattias Lundberg
and Mead Over
coded the first version of this program around the year 2000.

Mead Over added additional
functionality and improved the help file in May, 2016. If you observe any
problems, contact him at:
Email: MOver@CGDev.org.