*! version 1.2.0 30sep2022

help grmatgroups

Title

grmatgroups -- Scatter Plot Matrix with different marker looks according to another variable

Syntax

grmatgroups varlist [if] [in], over(varname) [options]

required option

over(varname) specifies variable by which the markers are distinguished

other options

missing treat missing values of over() var as normal values

half  only print plots below the diagonal

markeroptions(marker_info) specifies look of the markers at given values of the over() var

lab:el(rule_or_values) specifies look of the axis labels

sc:ale(rule_or_values) specifies scale of the axis labels

mlabsize(textsizestyle) size of text in diagonal fields, ie. varnames

mlabcolor(colorstyle) color of text in diagonal fields

scheme(scheme) overall look (note: some schemes are not compatible)

legend(legend_options) options regarding contents and look of legend

position(clockposstyle) where to put the legend in final graph

ring(ringposstyle) where to put the legend in final graph

span legend is centered relative to the whole graph area

title_options titles to appear on final graph

nodraw suppress display of graph

name(name, ...)  specify name for final graph

saving(filename, ...) save final graph in file

Description

grmatgroups returns a matrix of scatter plots, similar to that produced by the command graph matrix, but with different markers according to an over() variable. Each value of the this variable is connected to a set of options which can be changed with markeroptions(). There will be one legend for the whole graph. The command depends on Vince Wiggins' which has to be installed before using this command (search grc1leg to find and install it).

Options

over(<varname>) specifies the variable according to which the markers shall look differently. The variable has to be numeric. If the over() variable is assigned value labels (see [D] label), these will be used for the legend of the main graph. If not, the underlying values will be printed in the legend.
The over() variable has to be numeric. If you want to use a string variable, please transform it first using [D] encode with the label option.

missing treat missing values of over() var as normal values. If your over() variable has two nonmissing values and one missing value, specifiying the option missing will lead to three different markers, the default will produce two different marker types.

half prints only the lower half of the matrix. Similar to half-option in graph matrix.

markeroptions(marker_info) specifies the look of the markers. markeroptions takes a marker_info argument which is defined as

# marker_options [# marker_options]

# denotes the rank of the over value for which the look options are to be changed. The space-separated list marker_options can contain all marker options that are specified under twoway scatter/marker_options.
Type for example markeroptions(1 msymbol(X) mcolor(navy) 2 msymbol(+) mcolor(maroon)). If the option is not specified, the command will use the default handling of the active scheme. Note that the numbering of the marker options is based not on the values themselves, but on their order. If your over() variable has two levels, 1 and 3, you still have to type markeroptions(1 ... 2 ...). Missing values are listed after nonmissing values.

label(label_info) works like axis_label_options.

Note: To achieve a common plot region size, grmatgroups works with invisible labels, which means that some of the suboptions are disallowed, namely alternate and angle. labstyle is allowed, but not recommended. To get rid of all axis labels, type xlabel(none) ylabel(none).

scale(scale_info) works like axis_scale_options.

mlabsize(textsizestyle) specifies the size of the variable labels in the diagonal plots of the matrix. If you want to change the text itself, please alter the variable label of the variable in question ([D] label).

mlabcolor(colorstyle) specifies the color of the variable labels in the diagonal plots of the matrix. If you want to change the text itself, please alter the variable label of the variable in question ([D] label).

scheme() sets a scheme. Note that most schemes lead to suboptimal results. I recommend s1color, s1mono, s2color or s2mono. Since most of what is defined by schemes is overwritten by the matrix look, anyways, schemes do not make much of a difference.

legend(legend_options) changes the contents and look of the legend. If you want to suppress the legend, type legend(off). If you want to change the position of the legend, please use the three arguments below which are specified outside of the legend option.

position(clockposstyle) changes the position of the legend in the final graph. See grc1leg for more information.

ring(ringposstyle) specifies where the legend sits in the final graph.

span centers the legend according to the whole graph. See Spanning for more information.

Remarks

So far, the command works well with the default schemes s2color and s1color, but not so well with user-written schemes, such as plottig, plotplain, or lean2. Since the program internally relies on twoway scatter, graph combine, and grc1leg, it is much slower than graph matrix.

The plots that are not at the margins of the final graph will deviate slightly in their aspect ratio. I have not found a solution for this while also drawing axis labels. If you prefer all plots having exactly the same size, you will have to suppress the axis labels.

Acknowledgments

Many thanks to Jonas Fischer and Maik Hamjediers for feedback.

Example

. sysuse auto, clear

. grmatgroups mpg weight price, over(foreign) ///

. markeroptions(1 msymbol(X) mcolor(maroon) 2 msymbol(+) mcolor(green))

Author

Dominik Flügel (mail@dominikfluegel.de)