**[G-3]** *addplot_option* -- Option for adding additional twoway plots to command

__Syntax__

*command* ... [**,** ... **addplot(***plot* ... [**||** *plot* ... [...]] [**,** **below**]**)**
...]

where *plot* may be any subcommand of **graph twoway**, such as **scatter**, **line**,
or **histogram**.

__Description__

Some commands that draw graphs (but do not start with the word **graph**) are
documented in the other reference manuals. Many of those commands allow
the **addplot()** option. This option allows them to overlay their results
on top of **graph** **twoway** plots; see **[G-2] graph twoway**.

__Option__

**addplot(***plots* [**,** **below**]**)** specifies the rest of the **graph** **twoway**
subcommands to be added to the **graph** **twoway** command issued by
*command*.

**below** is a suboption of the **addplot()** option and specifies that the
added plots be drawn before the plots drawn by the command. Thus
the added plots will appear below the plots drawn by *command*.
The default is to draw the added plots after the command's plots
so that they appear above the command's plots. **below** affects
only the added plots that are drawn on the same x and y axes as
the command's plots.

__Remarks__

Remarks are presented under the following headings:

Commands that allow the addplot() option
Advantage of graph twoway commands
Advantages of graphic commands implemented outside graph twoway
Use of the addplot() option

__Commands that allow the addplot() option__

**graph** commands never allow the **addplot()** option. The **addplot()** option is
allowed by commands outside **graph** that are implemented in terms of **graph**
**twoway**.

For instance, the **histogram** command -- see **[R] histogram** -- allows
**addplot()**. **graph** **twoway** **histogram** -- see **[G-2] graph twoway histogram** --
does not.

__Advantage of graph twoway commands__

The advantage of **graph** **twoway** commands is that they can be overlaid, one
on top of the other. For instance, you can type

**. graph twoway scatter** *yvar* *xvar* **||** **lfit** *yvar* *xvar*

and the separate graphs produced, **scatter** and **lfit**, are combined. The
variables to which each refers need not even be the same:

**. graph twoway scatter** *yvar* *xvar* **||** **lfit** *y2var* *x2var*

__Advantages of graphic commands implemented outside graph twoway__

Graphic commands implemented outside **graph** **twoway** can have simpler
syntax. For instance, the **histogram** command has an option, **normal**, that
will overlay a normal curve on top of the histogram:

**. histogram** *myvar***, normal**

That is easier than typing

**. summarize** *myvar*
**. graph twoway histogram** *myvar* **||**
**function** **normden(x,`r(mean)',`r(sd)'),** **range(***myvar***)**

which is the **graph** **twoway** way of producing the same thing.

Thus the trade-off between **graph** and non**graph** commands is one of greater
flexibility versus easier use.

__Use of the addplot() option__

The **addplot()** option attempts to give back flexibility to non**graph**
graphic commands. Such commands are, in fact, implemented in terms of
**graph** **twoway**. For instance, when you type

**. histogram** ...

or you type

**. sts graph** ...

the result is that those commands construct a complicated **graph** **twoway**
command

**-> graph twoway** *something_complicated*

and then run that for you. When you specify the **addplot()** option, such
as in

**. histogram** ...**, addplot(***your_contribution***)**

or

**. sts graph, addplot(***your_contribution***)**

the result is that the commands construct

**-> graph twoway** *something_complicated* **||** *your_contribution*

Let us assume that you have survival data and wish to visually compare
the Kaplan-Meier (that is, the empirical survivor function) with the
function that would be predicted if the survival times were assumed to be
exponentially distributed. Simply typing

**. sysuse cancer, clear**

**. quietly stset studytime, fail(died) noshow**

**. sts graph**
*(**click to run**)*

will obtain a graph of the empirical estimate. To obtain the exponential
estimate, you might type

**. quietly streg, distribution(exponential)**

**. predict S, surv**

**. graph twoway line S _t, sort**
*(**click to run**)*

To put these two graphs together, you can type

**. sts graph, addplot(line S _t, sort)**
*(**click to run**)*

The result is just as if you typed

**. sts graph || line S _t, sort**

if only that were allowed.