help grcomb
-------------------------------------------------------------------------------


Title

    grcomb -- create and combine several single graphs into one



Syntax

        grcomb graph command var1[*#] var2[*#] var3[*#] var4[*#] [...] [if] [
                in] , varblock(#) [order(abab|aabb) name(name[, replace])
                draw feedback graph options]


    by is not allowed.
    Weights are not allowed.


Description

    grcomb allows you to generate, in a single command, several graphs of the
    same type and using the same options; to optionally display them; and to
    combine them into a single graph window. It is a wrapper for Stata's
    built-in graph commands, in particular the graph combine command.

    grcomb options will now be further described using the following two
    examples. In each example, it is supposed that you want to combine three
    single graphs into a combined graph:

    (1)
    scatter a1 b, jitter(8)
    scatter a2 b, jitter(8)
    scatter a3 b, jitter(8)

    This is achieved by
    grcomb scatter a1 b a2 b a3 b, v(2) jitter(8)

    (2)
    scatter a1 b1, jitter(8)
    scatter a2 b2, jitter(8)
    scatter a3 b3, jitter(8)

    This is achieved by
    grcomb scatter a1 b1 a2 b2 a3 b3, v(2) jitter(8)


Options

    var*# replaces var with # copies of itself in grcomb's varlist. The
        purpose of this option will become clear shortly.

    varblock(#) specifies the number of variables for a single graph command.
        In both examples (1) and (2), the single scatter commands each take
        two variables as arguments. Therefore, varblock is 2 in both cases.
        If the single graph commands were histogram, varblock would be 1,
        since histograms take only one variable as argument.

    order(abab|aabb) specifies the order of the variables in grcomb's
        varlist. The default is order(abab) and is exemplified by both
        examples (1) and (2), where the variables for the single graph
        commands sequentially follow each other in grcomb's varlist (e.g. in
        (2), a1 is plotted against b1, a2 is plotted against b2, and a3 is
        plotted against b3). Specifiying order(aabb) requires the variables
        to be listed in the order a1 a2 a3 b1 b2 b3 (example (2)). The point
        of this option is to allow simplifying the varlist to a* b* (or maybe
        a? b?).  I.e. given that a1-a3 and b1-b3 are the only variables
        starting with letters "a" and "b", respectively, the grcomb command
        in example (2) can be shortened to grcomb scatter a* b*, v(2)
        order(aabb) jitter(8). Example (1), in turn, could be simplified to
        grcomb scatter a* b*3, v(2) order(aabb) jitter(8), since, by way of
        cashing in option var*#, b*3 expands to b b b. (Don't confuse the
        wildcard asterisk ,*' with the multiply operator ,*' of option
        var*#.)

    name(name[, replace]) lets you enter a name for the combined graph and
        optionally replace any previous graph of the same name. But grcomb
        automatically names your graphs for you, so you don't usually need
        this option.

    draw displays the single graphs. If you omit this option, display of the
        single graphs (e.g. the three scatter plots in examples (1) and (2))
        is suppressed.

    feedback shows feedback on grcomb's progress in terms of the number of
        single graph commands it has processed.

    graph options include all the options possible with the single graph
        command. In examples (1) and (2), this would be the jitter(8) option.
        You can specify here any number of options that are allowed with the
        single graph command you've chosen.


Remarks

    grcomb may run into trouble if you have a variable in your data set with
    the same name as (one of the words of) your single graph command. It will
    recognize this for the first word of your single graph command, but not
    for any potential subsequent words.

    Example:
    If you have a variable scatter in your data set and you type grcomb
    scatter var1 var2 var3 var4, v(2), grcomb will catch the error and ask
    you to remove or rename variable scatter. However, if you type grcomb
    twoway scatter var1 var2 var3 var4, v(2), grcomb will crash without any
    helpful error message.

    grcomb gives unique names to both the single and the combined graphs it
    produces, so that none of the graphs produced by any single or
    consecutive calls to grcomb will be overwritten. (If you must know, the
    names correspond to the number of seconds expired since midnight,
    prefixed with the letter "g".)

    By default, grcomb uses the altshrink option of Stata's graph combine
    command. At present, there's nothing you can do to change this (except
    editing out the word "altshrink" from "grcomb.ado".)


Examples

    Plotting temperature vs pressure for five timepoints

        Awkward version:
        . grcomb scatter temperature1 pressure1 temperature2 pressure2
            temperature3 pressure3 temperature4 pressure4 temperature5
            pressure5, v(2)

        Elegant version:
        . grcomb scatter temperature* pressure*, v(2) order(aabb)

    Displaying single graphs, and feedback
    . grcomb spineplot education sex incomeclass sex, v(2) draw f

    Graph commands with different numbers of arguments

        Combine 3 histograms:
        . grcomb hist age height bmi, v(1) bins(10) percent

        Combine 2 scatterplots:
        . grcomb scatter sales returns year nemploy nlayoff year, v(3)

    Multi-word graph commands
    . grcomb graph twoway bar income nchildren education*2, v(2) order(aabb)


Author

    Alex Gamma, University Hospital of Psychiatry, Zurich, Switzerland.
    Email: alex.gamma@uzh.ch


Also see

    Manual: [G] graph combine

    Online: [G] graph_combine, spineplot (if installed)