help trellis
-------------------------------------------------------------------------------

Title

     Produces a Trellis Plot

Syntax

        trellis [varlist] [, options]

    options               Description
    -------------------------------------------------------------------------
    Main
      by(varname varname)  specifies the two variables that determine the
                            array of graphs.
      labels               specifies that the value labels for the
                            by-variables are used as titles.
      function(string)     specifies the command to draw each graph in the
                            trellis.
      fopt(graph_options)  specifies the options applied to each graph in the
                            matrix.
      singleopt(string)    specifies the options applied to a single
                            identified graph.
      sr(#)                specifies the row of the single identified graph.
      sc(#)                specifies the column of the identified single
                            graph.
      graph combine options 
                            additional options from graph combine.
    -------------------------------------------------------------------------

Description

    This command creates a trellis plot using graph combine. This trellis
    plot is an array of the same graph type by the levels of two factor
    variables.  It is a convenient way to represent the graphic of interest
    and whether it changes with respect to two other variables.

    The individual graph type can be any of STATA's graphic commands, even
    the matrix plot.  Any of the options of the graph can be specified and in
    addition any options for the graph combine command.

    The latest version of this command can be found at the SSC website or by
    the following command ssc install trellis, replace.


Options

        +------+
    ----+ Main +-------------------------------------------------------------

    by(varname varname) specifies the two variables that determine the array
        of graphs.

    labels specifies that the value labels for the by-variables are used as
        titles.

    function(string) specifies the command to draw each graph in the trellis.
        This can be a simple scatter graph of two variables twoway scatter x
        y or much more complicated commands shown in the examples

    fopt(graph_options) specifies the options applied to each graph in the
        matrix.

    singleopt(string) specifies the options applied to a single identified
        graph.

    sr(#) specifies the row of the single identified graph.

    sc(#) specifies the column of the identified single graph.

Examples

    The trellis command can be as complex as the user specifies so only a few
    of the options can be demonstrated. NOTE you must click on the webuse
    command below to load up the data for the trellis commands to work.

** webuse bdendo  (MUST load data first) **

Scatter plots        : trellis, by(gall ob) f(twoway scatter age duration)
Line plots           : trellis, by(gall ob) f(twoway line age duration) fopt(so
> rt)
Box plot             : trellis, by(gall ob) f(graph box duration)
Box plot (grouped)   : trellis, by(gall ob) f(graph box duration) fopt(over(age
> grp))
HBox plot (grouped)  : trellis, by(gall ob) f(graph hbox duration) fopt(over(ag
> egrp))
Scatter Matrix       : trellis, by(gall ob) f(graph matrix age agegrp duration)
Dot plot (grouped)   : trellis, by(gall ob) f(graph dot age duration) fopt(over
> (agegrp))
Bar chart (grouped)  : trellis, by(gall ob) f(graph bar age duration) fopt(over
> (agegrp))
Horizontal Bar chart : trellis, by(gall ob) f(graph hbar age duration) fopt(ove
> r(agegrp))
Pie chart            : trellis, by(gall ob) f(graph pie age duration) 
Histogram            : trellis, by(gall ob) f(histogram age)
Sunflower plot       : trellis, by(gall ob) f(sunflower duration age) fopt(lege
> nd(off))
QQ plot              : trellis, by(gall ob) f(qnorm age) 


** webuse nhanes2f MUST use this dataset for the following examples **

    Scatter plot with 2 y-variables

    trellis, by(health region) f(twoway scatter copper zinc iron)
    fopt(legend(off))

    Same plot except each individual graph is now plotted by race.  The graph
    needs a few more options to look perfect but it demonstrates the
    flexibility

    trellis, by(health region) f(twoway scatter copper zinc iron)
    fopt(xtitle("") by(race, im(0 0 0 0) noixlabel noiylabel note("")
    legend(off) ) legend(off))

    The data from the previous graph are better represented by the box plot
    below

    trellis, by(health region) f(graph box copper zinc iron) fopt(legend(off)
    over(race))

    Another added complexity is that you can combine mulitple graphing
    functions and display a single legend.

    trellis, by(health region) f(twoway (scatter zinc copper iron, ms(p
    p))||(mspline zinc iron,n(40) clw(*3))||(mspline copper iron,n(40)
    clw(*3))) sr(2) sc(3) singleopt(legend(on ring(0) pos(1) col(1)))
    fopt(legend(off))

    The same data represented by boxplots.

    trellis,by(health region) f(graph box copper zinc iron) fopt(legend(off)
    ylab(50 175 300) yscale(r(50,310))) sr(2) sc(2) singleopt(legend(on
    ring(0) pos(1) col(1) bm(tiny) symx(*0.2) keyg(*0.2) region(m(zero)
    lw(none))) yscale(r(50,310)))

    Only the race Other is displayed and the box plots are further divided by
    sex. This highlights what happens when there are graphs with no
    information

    trellis if race==3, by(health region) f(graph box copper zinc iron)
    fopt(over(sex) legend(off) ylab(50 175 300) yscale(r(50,310)))

    Now add labels for health and region

    trellis if race==3, labels by(health region) f(graph box copper zinc
    iron) fopt(over(sex) legend(off) ylab(50 175 300) yscale(r(50,310)))

Author

Adrian Mander, MRC Human Nutrition Research, Cambridge, UK.  Email
adrian.mander@mrc-hnr.cam.ac.uk

Also see

Related commands

graph twoway.