*! Help file version 2.1 4Nov2022 for version 2.62 of superscatter

*! By Mead Over (mover@cgdev.org), based on the help file for scatter_hist by Keith Kranker.

Title

superscatter -- Scatter plot with marginal distributions and other optional enhancements

Syntax

superscatter
y_variable x_variable [if] [in]
[,
options]

Options

Combined Plot
detail display additional statistics

iscale([*]#) size of text and markers

altshrink alternative scaling of text, etc.

title_options titles to appear on combined graph

region_options outlining, shading, aspect ratio

commonscheme put graphs on common scheme

scheme(schemename) overall look

nodraw suppress display of combined graph

name() specify name for combined graph

saving(filename, [replace asis]) save the combined
graph in a file. To specify the directory where the file is to be saved,
precede the filename by the path and specify the file extension. For example,
to save the file in the subdirectory "output" of the working directory, the
option would read saving(.\output\filename.gph).

Shared X- and Y- axes
{y|x}scale() log scales, range, appearance

{y|x}label() major ticks plus labels

{y|x}tick() major ticks only

{y|x}mlabel() minor ticks plus labels

{y|x}mtick() minor ticks only

{y|x}title() specify axis title

Histogram
hist_method the method used to draw histogram, where hist_method
is one of {density|fraction|frequency|percent}

Kernel
kdensity display the kernel density (and suppress the histogram)

kdxoptions(options) specify any options specific to the twoway kdensity on the x-axis

kdyoptions(options) specify any options specific to the twoway kdensity on the x-axis

Lines
means quarter the scatter plot into four quadrants defined by the means of the x and y variables

medians quarter the scatter plot into four quadrants defined by the medians of the x and y variables

terciles overlay a 3 by 3 grid on the scatter plot, with cells defined by the terciles of the x and y variables

quartiles overlay a 4 by 4 grid on the scatter plot, with cells defined by the quartiles of the x and y variables

line45 overlay a 45 degree line on the scatter plot

opt45(options) Only relevant if line45 is specified.
Allows options to control the look of the 45 degree line. See connect_options.

Tabulate
tabulate(statistic) the statistic is one of {count|cell|row|col}

tabformat(format) the numerical format for the displayed statistics.

matname(name) The displayed statistics are returned in a matrix called r(name)

textplace(compass_direction) Specifies a location for statistic placement within each grid cell.
Default is c for center. Possible alternative locations are the compass directions: n, s, e, w.
See compassdirstyle

textsize(size) Specifies the size of the text within each grid cell.
See textsizestyle

Subset options
hilite(condition) Observations meeting the logical condition
are highlighted by superimposing a second plot of only that subset of observations
using a different symbol or color.
Does not affect the sample used for other superscatter options.

hiliteoptions(string) Specify msymbol and mcolor
options specific to the highlighted observations.

hide(condition) From the primary scatter plot, suppress observations
that meet the logical condition. Does not affect the sample used for other
superscatter options.

sample(percentage) Randomly select a percentage of the observations
for display. The default is 100.
Does not affect the sample used for other superscatter options.

Fitted line
fittype(fittype) Add a plot of a fitted regression line to the
scatter plot. Available options for fittype are described
below.

fitoptions(string) Specify options for the fitted regression plot.
Available options vary by choice of fittype as described
below.
Only relevant if fittype(fittype) is specified.

fitsample(condition) This option allows the user to exclude from
the estimation sample for fittype some of the observations that are
displayed in the scatter plot and histograms.
Observations are excluded from the estimation if they do not meet
the specified logical condition.
Only relevant if fittype(fittype) is specified.
Does not affect the sample used for other superscatter options.

Ellipse
ellipse Add a plot of a confidence ellipse to the scatter plot.

elevel(real) Specify a confidence level as a percentage. Default is 50.

estat(stat) Map the confidence level into the size of the confidence ellipse
using either an F-statistic (the default) or a Chi^2 statistic by specifying
either of {Chi2|Fstat}.

epattern(pattern) Specify a pattern for the line defining the ellipse.
Default is solid.

ecolor(color) Specify a color of the line defining the ellipse.

ewidth(width) Specify the thickness of the line defining the ellipse.

Scaling both axes
sqrt Scale both axes on a square-root scale, with appropriate axis labels.

log10pluszero Scale both axes on a log10 scale, with appropriate axis labels.

log10plusone Add 1.0 to both the x and y values before taking their logarithms to the base 10
and scaling the axes accordingly. This option allows the display of zero values on a log scale at the cost
of possibly distorting the rest of the data.

Other twoway scatter options
* Other options may (optionally) be declared. These will be passed to the scatter command.

Description

superscatter creates a graph that is a scatter plot of the y_variable against the x_variable.
On the margins of the scatter plot are displayed graphs of the marginal distributions of the two
variables. The user can choose to display the marginal distributions
as either histograms (the default) or as kernel densities. The hilite and
hide options used together allow the user to plot selected observations using
a different marker symbol or color.

Optionally the user can also overlay the marginal distributions and the scatter plots with lines
drawn at the means, medians, terciles or quartiles of the two distributions.
These lines form a grid of four cells (if the option medians or means is chosen),
nine cells (with option terciles) or sixteen cells (with option quartiles).

If one of the means, medians, terciles or quartiles options is selected,
the user can specify the tabulate(statistic) option which displays the specified statistic
as added text wihin each cell of the grid formed by the lines.
The statistic can be a count of the observations in each cell of the grid or the percentage of observations
in the cell with respect to the row, column or all the data.

Axis scaling: Superscatter offers three options for scaling the axes,
log10pluszero, log10plusone and sqrt. superscatter's approach to scaling
the axes of this scatter plot is to first generate temporary versions of the x- and y-variables that have
been transformed according to the chosen scaling rule. Then Superscatter constructs the scatter plot
and the marginal distributions of these transformed variables and adorns the graph with
axis tick marks and labels that correspond to the untransformed variables.

By choosing the fittype(fittype) option, the user can superimpose the scatter plot on a fitted line
with or without a confidence interval. If one of the axis scaling options
log10pluszero, log10plusone or sqrt has also been specified,
this line is fitted to the transformmed data, not to the raw data. Superscatter
thus avoids the annoyingly kinked or otherwise deformed
fitted line that can occur when combining a fitted line with Stata's standard axis scaling options.

Use of some of these options will generate a legend which distorts the shape of the
the main plotregion. (This happens, because the default placement of the legend
squeezes the vertical dimension of the scatter plot.)
To fix this problem, either suppress the legend by specifying legend(off)
or specify that the legend be displayed inside the plotregion by specifying
legend(ring(0)).

This command automates the process outlined in the help file of graph combine (see "Advanced use").
It offers the user the additional options for scaling the axes and for adding grid lines, grid statistics,
a fitted regression line or an ellipse to the scatter plot and for highlighting observations.

Discussion of Options

Combined Plot

See graph combine for these option descriptions. The options imargin and graphregion
should not be declared.

Shared X- and Y- axes

See axis options for option descriptions. The sub-options nogrid and gmax
should not be declared as sub-options for xlabel().
The sub-options alt and reverse should not be declared as sub-options
for xlabel() or ylabel()

Histogram

Select the method used to draw histogram. Declare at most one of the following options:

density - draw as density; the default

fraction - draw as fractions

frequency - draw as frequencies

percent - draw as percents

See twoway histogram for option descriptions.

Kernel Density

Display kernel density estimates of the marginal distributions instead of histograms.

kdensity - display the kernel density (and suppress the histogram)

kdxoptions(options) - specify any options specific to the twoway kdensity command on the x-axis

kdyoptions(options) - specify any options specific to the twoway kdensity command on the y-axis

See twoway kdensity for option descriptions.

Line options

Overlay on the scatter plot a grid of lines which partition the observations
into bins:

means - quarter the scatter plot into four quadrants defined by the means of the x and y variables

medians - quarter the scatter plot into four quadrants defined by the medians of the x and y variables

terciles - overlay a 3 by 3 grid on the scatter plot, with cells defined by the terciles of the x and y variables

quartiles - overlay a 4 by 4 grid on the scatter plot, with cells defined by the quartiles of the x and y variables

The means, medians or quartiles are computed by the summarize command, while
the terciles are computes with the centile command.

detail - report the results of the summarize and centile commands.

Tabulate options

Combined with one of the line options, the tabulate(statistic) option
computes and displays within each grid cell one of four statistics.
superscatter then returns these
statistics on the x- and y-variables in r() macros where
they can be retrieved by the user. The option detail shows the
same information in Stata's results window.

detail - output the statistics displayed in the cells of the grid
to the Stata results window (and to a log, if one is open)

The four statistics available for each cell are::

tabulate(count) - display the number of observations in the cell of the grid

tabulate(cell) - display the percentage of all the observations in this cell of the grid

tabulate(row) - display the percentage of the row observations in this cell of the grid

tabulate(col) - display the percentage of the column observations in this cell of the grid

The following options control the appearance of the tabulate statistics overlaid on the scatter plot:

tabformat(format) - the numerical format for the displayed statistics.
The default format for the tabulate(count) option is %~15s, which centers the frequency count within the cell.
Otherwise, the default format for the percentages is %4.1f, which the user might want to override to display more or fewer decimals.

matname(name) - The displayed statistics are returned in a matrix called r(name)

textplace(compass_direction) - Specifies a location for text placement wihin each grid cell.
Default is c for center. Possible alternative locations are the compass directions: n, s, e, w

textsize(size) - Specifies the size of the text wihin each grid cell

Subset options

Several options are available for hiding, highlighting or selecting subsets of
observations in the scatter plot. The options hilite(condition) and
hide(condition) can be used separately or together. Using only hilite(condition)
without hide(condition) will superimpose a second marker on
the selected observations. Specifying the hide(condition) option
with the same logical condition suppresses the primary marker
so that the selected observations are plotted with only the highlighting
marker.

sample(percentage) - When the number of observations is so large that points
are indistinguishable in the scatter plot, this option randomly selects a percentage of the
observations for display. If the option is omitted all observations are displayed.
(That is the default for this option is 100%.) Since the subset of observations
displayed by the sample(percentage) option is random,
selecting this option may distort the shape of the scatter plot.
Furthermore, unless Stata's set seed option is used to specify the seed
for the random selection process, sample(percentage) will alter the
scatter randomly on each execution. Selecting this option has no effect,
however, on the shapes of either of the marginal distributions.

Fitted line options

Add a plot of a fitted regression line to the scatter plot. The syntax is fittype(fittype)
where fittype must be one of the following:

lfit - a linear regression of the y variable on the x variable

lfitci - a linear regression of the y variable on the x variable, with confidence interval

qfit - a quadratic regression of the y variable on the x variable

qfitci - a quadratic regression of the y variable on the x variable, with confidence interval

fpfit - a fractional polynomial regression of the y variable on the x variable

fpfitci - a fractional polynomial regression of the y variable on the x variable, with confidence interval

mspline - a median spline regression of the y variable on the x variable

lowess - a lowess regression of the y variable on the x variable

fitoptions(string)

Specify options for the fitted regression plot.
Available options vary by choice of fittype as described
above.
To pass options to the selected stimation command,
place them within estopt(regress options).
For example, to fit a linear regression
without a constant, and depict the fitted line with a thick line, specify
fitoptions(estopt(noconst) lwidth(vthick)).
Only relevant if fittype(fittype) is specified.

fitsample(condition)

By default the estimation command specified by fittype
uses the sample identified by superscatter's [if] [in] options.
Specifying the fitsample(condition) option further constrains the
estimation sample to exclude observations not meeting the specified logical condition.
Only relevant if fittype(fittype) is specified.
Does not affect the sample used for other superscatter options.

Ellipse options

By specifying the option ellipse, the user can overlay a confidence ellipse on the scatter plot.
Under the assumption that the joint distribution of the two variables in varlist
is bivariate normal, the ellipse includes elevel percent of the probability mass
of the joint distribution. The area encompassed by the ellipse can be expanded
either by using option estat(string) to select the Chi^2 statistic instead of the F-statistic
or by using the elevel(real) option to specify a confidence level higher than the default of 50%.

The option ellipse returns statistics on the x- and y-variables
in r() macros where they can be retrieved by the user.

Options ellipse and fittype(fittype) can be combined.
Both of these options generate default legends. The user can override these defaults by specifying
customized legends on the command line. When specifying a legend, use the ring(0) option
in order to keep the frequencey distribution for the y-variable aligned with
the vertical dimension of the scatter plot.

Scaling both axes

Since economic variables often have skewed distributions, a convex transformation
of the variables such as the logarithm or the square root can be a useful technique
for revealing more information about the variables in a scatter plot.
The standard options axis-scale options xscale(log) and yscale(log) are available for
expressing only one of the two axes on a log scale. The option log10pluszero
produces the same result as specifying both of these two options. The option log10plusone
adds 1.0 to the values of the variables on the x- and y-axes in order to display points that
have a zero value on one of the two axes. A third option in this group, the option sqrt,
also displays the zero values, with the axes scaled as the square-root of the original variables.

Other twoway scatter options

Sometimes the default axes of the marginal distributions do not align with
the default axes of the scatter plot. To check for proper alignment,
use one of superscatter's line options,
such as means. If the two marginal distribution graphs are properly
aligned with the scatter plot, the vertical and horizontal lines forming
a crosshairs in the scatter line should each line with a line marking the
means of the marginal distributions. To fix axis alignment problems,
use the standard graph twoway options
xscale(range()), yscale(range()), xlabel() and ylabel()
to align the axes. See examples 11, 12 and 13.

Other options may (optionally) be declared.
These will be passed to the scatter command. For example, you might declare
marker_options,
marker_label_options, or
jitter_options.

See twoway scatter for a complete list of options.

These options are not restricted by the program;
however, some (such as by) will cause major problems
and some should not be used. Experiment with options to see
which work for you.

Examples

First set up the data by clicking on "click to set up data". Then
click on any of the examples for a demonstration of that feature of
superscatter.

. set more off

. sysuse lifeexp, clear

. qui gen loggnp = log10(gnppc)

. label var loggnp "Log base 10 of GNP per capita"

. qui gen us_gnp0 = country if country=="United States" | country=="Haiti" | country=="Brazil" | country=="Jamaica" | country=="Armenia" | gnppc>=.

. label var us_gnp0 "Labels of selected countries"

. describe

. summarize, detail

(click to set up data)

Now that the data has been prepared, execute any of the following examples by clicking on the
associated hotlink. The first example recreates an example in Stata's manual entry for
graph_combine.

. * Border the scatter plot with histograms.

. superscatter lexp loggnp, name(_example1, replace)

(click to run example 1)

. * Same plot with various optional cosmetic touches.

. superscatter lexp loggnp, percent color(dkorange) mlabel(us_gnp0) m(s) msize(small) xtitle("GNP per capita (log)") name(_example2, replace)

(click to run example 2)

Example 3 demonstrates the use of the medians and tabulate(count) options.
The medians option divides the data into four quadrants, each of which in principle
contains a quarter of the observations. The tabulate(count) option gives the number
of observations in each quarter. Surprisingly, the number in the top half is much less
than the number in the bottom half of the scatter plot.

In this atypical data, nine observations on the variable life-expectancy
in the complete sample and 8 of those used in the scatterplot are exactly equal
to the median value of 73 years. In computing the cell counts,
superscatter arbitrarily assigns the observations exactly at the median value to cells below the median.
In this situation, this assignment leads to a marked imbalance, with 38 observations below
median life-expectancy and only 25 above it. The marginal distributions
are unaffected by this imbalance.

This issue is unlikely to arise with variables measured with more precision,
because with more preciely measured variables there is unlikely to be
more than one observation at the median value. For example,
loggnp on the horizontal dimension of the plots in this example has only one median value.

. * Replace the histograms with kernel density plots and add median lines and cell counts.

. superscatter lexp loggnp, kdensity medians tabulate(count) matname(tabout) detail name(_example3, replace)

. * List the statistics used to construct the tabulations.

. return list

. matrix list r(tabout)

(click to run example 3)

Superscatter offers multiple options for superimposing information on the scatter plot,
several of which generate a legend. Without user intervention, the legend so generated
appears immediately below the scatter plot, shortening its vertical dimension
so that it no longer aligns with the marginal distribution depicted to the left of
the vertical axis. Example 4 shows how the user can move the legend to the interior
of the scatter plot and restore its alignment with the marginal distribution.

. * To the bordered plot of example 1, add the fitted regression line and position the legend.

. superscatter lexp loggnp, means fittype(lfitci) fitoptions(lwidth(vthick)) legend(ring(0) cols(1) pos(5)) ytitle(Life Expectancy) name(_example4, replace)

(click to run example 4)

. * Overlay the scatter plot with a bivariate normal confidence ellipse.

. superscatter lexp loggnp, ellipse quartiles ytitle(Life Expectancy) name(_example5, replace)

. * List the descriptive statistics used to construct the ellipse.

. return list

(click to run example 5)

. * Overlay the scatter plot with both an ellipse and a fitted line.

. superscatter lexp loggnp, means fittype(lfit) fitoptions(lwidth(vthick)) ellipse ytitle(Life Expectancy) name(_example6, replace)

(click to run example 6)

A scatter plot is a useful way of comparing two versions of the same variable. Using this
demonstration data, we compare the life-expectancy a country might be expected to have based on its GNP per capita
(it's "predicted" life expectancy) to its actual life-expectancy.
First, we estimate a regression of 1998 life-expectancy on the log of 1998 GNP per capita and use
Stata's predict command to estimate each country's predicted 1998 life-expectancy.
Then we use superscatter with the line45 option to compare each country's
prediected 1998 life-expectancy to its actual 1998 life-expectancy. Countries above the
45 degree line had disappointing health sector performance in 1998, because their life-expectancies
were lower than would have been predicted based on their GNP. Haiti is a particularly striking outlier.
While it is one of the poorest countries in the world, its low GNP would predict
a life expectancy of about 66 years. In contrast its actual life expectancy was
only 55 in 1988, 11 years lower than would be predicted from its poverty alone.
(In 1988, Haiti's estimated life expectancy was reduced by the worst AIDS epidemic
in the western hemisphere.) Other countries below the prediction line, including Brazil,
performed worse than expected from their measured GNP per capita. On the other hand,
countries such as Armenia and Jamaica performed better than expected.

. *	Use a 45 degree line to compare observed to predicted life expectancy.

. regress lexp loggnp

. predict lexp_hat, xb

. lab var lexp_hat "Fitted value of life expectancy"

. local textadds `"text(78 68 "Observed greater" "than predicted") text(58 68 "Observed less" "than predicted") "'

. superscatter lexp lexp_hat, line45 opt45(lwidth(vthick)) legend(off) mlabel(us_gnp0) legend(ring(0) pos(5) col(1) order(2 "Countries" 1 "Predicted life" "Expectancy")) xtitle(Predicted Life Expectancy) ytitle(Observed Life Expectancy) xlabel(65(5)80) \`textadds' name(_example7, replace)

(click to run example 7)

When plotting skewed distributions, it is often useful to transform the axis
scales in order to spread out the data points at the end of the scale where most of the data
is concentrated. In examples 1 through 5 this is achieved by plotting the
logarithm of GNP rather than its actual value on the horizontal axis.
Instead of transforming the skewed GNP per capita variable,
as is done above, one could instead specify the option xscale(log), but
the resulting histogram of the marginal distribution on the x-axis is distorted
by the stretching. The analagous option for the y-axis, yscale(log), has no effect on
superscatter, because Stata has
disabled
this option for histograms.

Superscatter provides three convex transformation options all of
which apply the same transformation to both the variables being plotted.
These three options are most useful when both plotted variables are non-negative
and right-skewed, as is often the case with economic data. The three additional
options are sqrt, log10pluszero and log10plusone.
Of these, the sqrt
option and the log10plusone both accommodate zeros in the underlying data.
Here's an example of the application of the sqrt option.

. * Scale both axes by the square-root.

. superscatter lexp gnppc, sqrt ytitle(Life Expectancy on square-root scale) xtitle(GNP per capita on square-root scale) name(_example8, replace)

(click to run example 8)

superscatter emulates scatter's xscale(log) and yscale(log) options in
labeling the scaled axes with the appropriate unscaled values of the plotted variables.
For the sqrt option, axis labels are rounded to values with integer square roots.
For the log10pluszero and log10plusone options, axis labels
are rounded to powers of 10.
With the sqrt option, superscatter will properly relabel the axes
when the maximum of each of the two plotted variables
exceeds the minimum by at least a factor of 4.
For the two options that transform using the base 10 logarithm,
log10pluszero and log10plusone,
superscatter will produce the most pleasing axis labels
when the maxima of the two variables exceed their minima by several orders of magnitude.

The choice between the log10pluszero and log10plusone options
is guided by whether the user needs to display values that are equal to, or slightly
less than, zero. In the example data the variable popgrowth ranges from
-0.5 to 3.0, with 8 of its 68 values non-positive. Of these 8 observations,
all but one is non-missing for the x-axis variable, gnppc. Thus,
with the log10pluszero option, 7 countries are omitted from the plot
constructed by superscatter.

. *	Scaling both axes using the option -logh10pluszero- omits 7 observations.

. superscatter popgrowth gnppc, log10pluszero ytitle(Population growth rates > 0 on log scale) xtitle(GNP per capita on log scale) mlabel(us_gnp0) mlabangle(45) name(_example9a, replace)

(click to run example 9a)

The graph shows that the population growth rate for the United States
in 1988 was 1.0 percent per year.

Now in order to display the other seven observations, while retaining
the logarithmic scaling, we instead use the option log10plus0ne.

. * Scale both axes by log to the base 10 after adding 1.0 to the variable.

. superscatter popgrowth gnppc, log10plusone ytitle(Population growth rates > -1 on log scale) xtitle(GNP per capita on log scale) mlabel(us_gnp0) mlabangle(45) name(_example9b, replace)

(click to run example 9b)

The log10plus0ne is also useful for revealing observations with
zero values.

. *	Create a version of gnppc with zeros replacing missing values.

. gen gnp0 = gnppc

. replace gnp0 = 0 if gnppc >=.

. label var gnp0 "Zero-filled GNP per capita"

. * Scale both axes by log to the base 10 after adding 1.0 to the variable.

. superscatter popgrowth gnppc, log10plusone ytitle(Population growth rates > -1 on log scale) xtitle(GNP per capita on log scale) mlabel(us_gnp0) mlabangle(45) name(_example9b, replace)

(click to run example 9c)

The option hilite can be combined with the option hide to display
a subset of the points using a different symbol. As noted above, to prevent the
legend from interfering with the alignment of the y-axis and the marginal distribution
of the y-variable, either suppress the legend with legend(off} or
specify that it appear within the plot area using the option ring(0).

. * Highlight the North American countries, add a legend and custom yaxis labels.

. superscatter lexp gnp0, hilite(region==2) hide(region==2) legend(order(1 "North America" 2 "Other regions") ring(0) pos(4) col(1)) name(_example10, replace)

(click to run example 10)

Sometimes one or both of the axes of the scatter plot is misaligned relative
to the corresponding axis of the marginal distribution on the x- and y-axes.
Here's an example of this misalignment which uses Stata's auto example data.
(This and the following examples can be run without first loading the lifeexp sample data.)
By adding the means option, we see that superscatter constructs a horizontal
line at the value 6,165.257 on the y-axis of the scatter plot and also marks the
same mean in the marginal distribution of the variable price on main axis of the histogram.
For proper interpretation of the ovrall graph, these lines should align with one another, but they do not.
The x-axis of the scatter plot and the marginal distribution of the variable mpg
are also misaligned.

. * Demonstrate superscatter's occasional misalignment of axes.

. sysuse auto, clear

. summarize price mpg

. superscatter price mpg, means name(_example11, replace)

(click to run example 11)

One strategy for fixing this alignment problem is to explicitly specify
the labels on the problematic axis or axes like this:

. * Use the axis scale option to fix the alignment problem.

. sysuse auto, clear

. superscatter price mpg, means xlabel(15(5)40) ylabel(5000 10000 15000) name(_example12, replace)

(click to run example 12)

Another strategy for fixing this alignment problem is to explicitly specify
the range on the problematic axis or axes.
Here, to make the labels of the y-axis histogram legible, we use the
option frequency.

. * Use the axis scale(range()) option to fix the alignment problem.

. sysuse auto, clear

. superscatter price mpg, means freq xscale(range(10 40)) yscale(range(0 15000)) name(_example13, replace) title(Example 13)

(click to run example 13)

Stored results

superscatter stores no results unless the option ellipse and or
the option tabulate is specified.

Ellipse results

If ellipse is specified, superscatter stores the following in r():

Macros

r(estat) User-selected test statistic used to determine the size
of the ellipse for a selected value of elevel

Scalars

r(N) number of observations in scatter and in computation of the ellipse properties

r(y_mean) mean of y-variable

r(y_sd) standard deviation of y-variable

r(x_mean) mean of x-variable

r(x_sd) standard deviation of x-variable

r(rho) correlation coefficient

r(elevel) confidence level for construction of the ellipse

r(ndf) numerator degrees-of-freedom for F- or Chi^2 statistic

r(ddf) denominator degrees-of-freedom for F- or Chi^2 statistic

r(critval) for the selected test-statistic and the selected confidence level,
this critical value determines the size of the constructed ellipse

Tabulate results

If option tabulate is specified, superscatter stores the following in r():

Macros

r(cells2text) Text of the option used internally by superscatter to add tabulated statistics
to the graph twoway scatter command.

Matrices (returned only if option matname is specified)

r(name) Statistics displayed by tabulate option

Authors

This program starts from Keith Kranker's 2015 package scatter_hist
which is available from his repository on GitHub
here.

Mead Over added additional
functionality in May, 2015 - November, 2022. Contact him at
MOver@CGDev.Org if you observe any
problems.