by_option.hlp

是一个经济学管理应用软件 很难找的 但是经济学学生又必须用到

{smcl}
{* 05mar2005}{...}
{cmd:help by_option}
{hline}
{* index by() tt option}{...}

{title:Title}

{p2colset 5 22 24 2}{...}
{p2col :{hi:[G] {it:by_option}} {hline 2}}Option for repeating graph command{p_end}
{p2colreset}{...}


{title:Syntax}

	{it:by_option}{col 41}description
	{hline 70}
	{cmd:by(}{it:varlist}[{cmd:,} {it:suboptions}]{cmd:)}{...}
{col 41}repeat for by-groups
	{hline 70}
	{cmd:by()} is {it:unique}; see {help repeated options}.

	{it:suboptions}{col 41}description
	{hline 70}
	{cmd:total}{...}
{col 41}add total group
	{cmdab:miss:ing}{...}
{col 41}add missing group(s)
	{cmdab:colf:irst}{...}
{col 41}display down columns
	{cmdab:r:ows:(}{it:#}{cmd:)} | {cmdab:c:ols:(}{it:#}{cmd:)}{...}
{col 41}display in {it:#} rows or {it:#} columns
	{cmdab:hol:es:(}{it:{help numlist}}{cmd:)}{...}
{col 41}positions to leave blank
	{cmd:iscale(}[{cmd:*}]{it:#}{cmd:)}{...}
{col 41}size of text and markers

	{cmdab:com:pact}{...}
{col 41}{col 41}synonym for {cmd:style(compact)}
	{cmd:style(}{it:{help bystyle}}{cmd:)}{...}
{col 41}overall style of presentation
	[{cmdab:no:}]{cmdab:edge:label}{...}
{col 41}label {it:x} axes of edges
	[{cmdab:no:}]{cmdab:r:escale}{...}
{col 41}separate {it:y} and {it:x} scales for each group
	[{cmdab:no:}]{cmdab:yr:escale}{...}
{col 41}separate {it:y} scale for each group
	[{cmdab:no:}]{cmdab:xr:escale}{...}
{col 41}separate {it:x} scale for each group
	[{cmdab:no:}]{cmdab:iy:axes:}{...}
{col 41}show individual {it:y} axes
	[{cmdab:no:}]{cmdab:ix:axes:}{...}
{col 41}show individual {it:x} axes
	[{cmdab:no:}]{cmdab:iyt:ick:}{...}
{col 41}show individual {it:y}-axes ticks
	[{cmdab:no:}]{cmdab:ixt:ick:}{...}
{col 41}show individual {it:x}-axes ticks
	[{cmdab:no:}]{cmdab:iyl:abel:}{...}
{col 41}show individual {it:y}-axes labels
	[{cmdab:no:}]{cmdab:ixl:abel:}{...}
{col 41}show individual {it:x}-axes labels
	[{cmdab:no:}]{cmdab:iytit:le:}{...}
{col 41}show individual {it:y}-axes titles
	[{cmdab:no:}]{cmdab:ixtit:le:}{...}
{col 41}show individual {it:x}-axes titles
	{cmdab:im:argin:(}{it:{help marginstyle}}{cmd:)}{...}
{col 41}margin between graphs

	{it:{help by_option##legend_option:legend_option}}{...}
{col 41}show legend and placement of legend
	{it:{help title_options}}{...}
{col 41}overall titles
	{it:{help region_options}}{...}
{col 41}overall outlining, shading, and aspect
	{hline 70}
{pin}
Note that the {it:title_options} and {it:region_options} on the command
on which {cmd:by()} is appended will become the titles and regions for
the individual by-groups.


{title:Description}

{pstd}
Option {cmd:by()} draws separate plots within a single graph.
{it:varlist} may be a numeric or a string variable.


{title:Option}

{phang}
{cmd:by(}{it:varlist}[{cmd:,} {it:suboptions}]{cmd:)}
    specifies that the {cmd:graph} command be repeated for each
    unique set of values of {it:varlist} and that the resulting individual
    graphs be arrayed into a single graph.


{title:Suboptions}

{phang}
{cmd:total} specifies that, in addition to the graphs for each by-group, a
    graph be added for all by-groups combined.

{phang}
{cmd:missing} specifies that, in addition to the graphs for each by-group,
    graph(s) be added for missing values of {it:varlist}.
    Missing is defined as {cmd:.}, {cmd:.a}, ..., {cmd:.z} for numeric
    variables and {cmd:""} for string variables.

{phang}
{cmd:colfirst} specifies that the individual graphs be arrayed
    down the columns rather than across the rows.  That is, if there
    were four groups, the graphs would be displayed

		default                  {cmd:colfirst}
		  1  2                    1    3
		  3  4                    2    4

{phang}
{cmd:rows(}{it:#}{cmd:)} and {cmd:cols(}{it:#}{cmd:)} are alternatives.
    They specify that the resulting graphs be arrayed as
    {it:#} rows and however many columns are necessary, or as {it:#}
    columns and however many rows are necessary.  The default is

	    {cmd:cols(}{it:c}{cmd:)}, {it:c} = ceil(sqrt({it:G}))

{pmore}
    where {it:G} is the total number of graphs to be presented and
    ceil() is the function that rounds nonintegers up to the next
    integer.  For instance, if four graphs are to be displayed, the result
    will be presented in a 2{it:x}2 array.  If five graphs are to be
    displayed, the result will be presented as a 2{it:x}3 array because
    ceil(sqrt(5))==3.

{pmore}
    {cmd:cols(}{it:#}{cmd:)} may be specified as larger or smaller
    than {it:c}; {it:r} will be
    the number of rows implied by {it:c}.
    Similarly, {cmd:rows(}{it:#}{cmd:)}
    may be specified as larger or smaller than {it:r}.

{phang}
{cmd:holes(}{it:numlist}{cmd:)}
    specifies which positions in the array are to be left unfilled.
    Consider drawing a graph with three groups and assume that
    the three graphs are being displayed in a 2{it:x}2 array.  By default,
    the first group will appear in the graph at (1,1), the second in
    the graph at (1,2), and the third in the graph at (2,1).  Nothing
    will be displayed in the (2,2) position.

{pmore}
    Specifying {cmd:holes(3)} would cause position (2,1) to be left blank,
    so the third group would appear in (2,2).

{pmore}
    The numbers that you specify in {cmd:holes()} correspond to the position
    number,

	     1  2      1  2  3      1  2  3  4      1  2  3  4  5
	     3  4      4  5  6      5  6  7  8      6  7  8  9 10
		       7  8  9      9 10 11 12     11 12 13 14 15
				   12 14 15 16     16 17 18 19 20
						   21 22 23 24 25    {it:etc.}

{pmore}
    The above is the numbering when {cmd:colfirst} is not specified.  If
    {cmd:colfirst} is specified, the positions are transposed:

	     1  3      1  4  7      1  5  9 13      1  6 11 16 21
	     2  4      2  5  8      2  6 10 14      2  7 12 17 22
		       3  6  9      3  7 11 15      3  8 13 18 23
				    4  8 12 16      4  9 14 19 24
						    5 10 15 20 25    {it:etc.}

{phang}
{cmd:iscale(}{it:#}{cmd:)}
and
{cmd:iscale(*}{it:#}{cmd:)}
    specify a size adjustment (multiplier) to be used to scale the text and
    markers.

{pmore}
    By default, {cmd:iscale()} gets smaller and smaller the larger is
    {it:G}, the number of by-groups and hence the number of graphs
    presented.
    The default is parameterized as a multiplier
    f({it:G}){hline 2}0<f({it:G})<1,
    f'({it:G})<0{hline 2}that is used to multiply {cmd:msize()},
    {c -(}{cmd:y}|{cmd:x}{c )-}{cmd:label(,labsize())}, and the like.
    The size of everything except the overall titles, subtitles, captions, and
    notes is affected by {cmd:iscale()}.

{pmore}
    If you specify {cmd:iscale(}{it:#}{cmd:)}, the number you
    specify is substituted for f({it:G}).  {cmd:iscale(1)} means
    text and markers should appear at the same size as they would were each
    graph drawn separately.  {cmd:iscale(.5)} displays text and
    markers at half that size.  We recommend you specify a number between 0
    and 1, but you are free to specify numbers larger than 1.

{pmore}
    If you specify {cmd:iscale(*}{it:#}{cmd:)}, the number you
    specify is multiplied by f({it:G}) and that product is used to scale
    text and markers.  {cmd:iscale(*1)} is the default.
    {cmd:iscale(*1.2)} means text and markers should appear
    20% larger than {cmd:graph,} {cmd:by()} would usually choose.
    {cmd:iscale(*.8)} would make them 20% smaller.

{phang}
{cmd:compact}
    is a synonym for {cmd:style(compact)}.  It makes no difference which you
    type.  See the description of the {cmd:style()} option below, and
    see {help by_option##remarks8:By-styles} under {hi:Remarks}.

{phang}
{cmd:style(}{it:bystyle}{cmd:)}
     specifies the overall look of the by-graphs.  The style determines
     whether individual graphs have their own axes and labels or if instead
     the axes and labels are shared across graphs arrayed in the same
     row or in the same column, how close the graphs are to be placed to each
     other, etc.  The other options documented below will allow you to change
     the way the results are displayed, but the {it:bystyle} specifies the
     starting point.

{pmore}
    You need not specify {cmd:style()} just because there is something
    you want to change.  You specify {cmd:style()} when another style exists
    that is exactly what you desire or when another style would allow you to
    specify fewer changes to obtain what you want.

{pmore}
    See {it:{help bystyle}} for a list of by-style choices.
    The suboptions listed below modify the by-style:

{phang}
{cmd:edgelabel} and {cmd:noedgelabel}
     specify whether the last graphs of a column that do not appear in the
     last row are to have their {it:x} axes labeled.
     See {help by_option##remarks9:Labeling the edges} under {hi:Remarks} below.

{phang}
{cmd:rescale},
{cmd:yrescale}, and
{cmd:xrescale}
(and
{cmd:norescale},
{cmd:noyrescale}, and
{cmd:noxrescale})
    specify that the scales of each graph be allowed to differ (or forced to
    be the same).  Whether
    {it:X} or {cmd:no}{it:X} is the default is determined by
    {cmd:style()}.

{pmore}
    Usually,
    {cmd:no}{it:X} is the default and
    {cmd:rescale}, {cmd:yrescale}, and {cmd:xrescale} are the options.
    By default, all the graphs will share the same scaling for their
    axes.  Specifying {cmd:yrescale} will allow the
    {it:y} scales to differ across the graphs, specifying
    {cmd:xrescale} will allow the {it:x} scales to differ, and
    specifying {cmd:rescale} is equivalent to specifying {cmd:yrescale} and
    {cmd:xrescale}.

{phang}
{cmd:iyaxes} and {cmd:ixaxes} (and {cmd:noiyaxes} and {cmd:noixaxes})
    specify whether the {it:y} axes and {it:x} axes are to be displayed with
    each individual graph.  The default with most styles and schemes is to
    place {it:y} axes on the leftmost graph of each row and to place {it:x}
    axes on the bottommost graph of each column.  The {it:y} and {it:x}
    axes include the default ticks and labels but exclude the axes titles.

{phang}
{cmd:iytick} and {cmd:ixtick} (and {cmd:noiytick} and {cmd:noixtick})
    are seldom specified.  If you specified {cmd:iyaxis} and then wanted to
    suppress the ticks, you could also specify {cmd:noiytick}.  In the rare
    event where specifying {cmd:iyaxis} did not result in the ticks being
    displayed (because of how the style or scheme works), specifying
    {cmd:iytick} would cause the ticks to be displayed.

{phang}
{cmd:iylabel} and {cmd:ixlabel} (and {cmd:noiylabel} and {cmd:noixlabel})
    are seldom specified.  If you specified {cmd:iyaxis} and then wanted to
    suppress the axes labels, you could also specify {cmd:noiylabel}.  In the
    rare event where specifying {cmd:iyaxis} did not result in the labels being
    displayed (because of how the style or scheme works), specifying
    {cmd:iylabel} would cause the labels to be displayed.

{phang}
{cmd:iytitle} and {cmd:ixtitle} (and {cmd:noiytitle} and {cmd:noixtitle})
    are seldom specified.  If you specified {cmd:iyaxis} and then wanted
    to add the {it:y}-axes titles (which would make the graph very
    busy), you could also specify {cmd:iytitle}.  In the rare event where
    specifying {cmd:iyaxis} resulted in the titles being displayed (because
    of how the style or scheme works), specifying {cmd:noiytitle} would
    suppress displaying the title.

{phang}
{cmd:imargin(}{it:marginstyle}{cmd:)}
    specifies the margins between the individual graphs.

{phang}
{marker legend_option}{...}
{it:legend_option} used within {cmd:by()} sets whether the legend is
    drawn and the legend's placement; see 
    {hi:{help by_option##use_of_legends:Use of legends with by()}} below.
    Note that the {cmd:legend()} option is normally {it:merged-implicit}, but
    when used inside {cmd:by()}, it is {it:unique}; see {help repeated_options}.


{title:Remarks}

{pstd}
Remarks are presented under the headings

	{help by_option##remarks1:Typical use}
	{help by_option##remarks2:Placement of graphs}
	{help by_option##remarks3:Treatment of titles}
	{help by_option##remarks4:by() uses subtitle() within graph}
	{help by_option##remarks5:Placement of the subtitle()}
	{help by_option##remarks6:by() uses the overall note()}
	{help by_option##remarks7:Use of legends with by()}
	{help by_option##remarks8:By-styles}
	{help by_option##remarks9:Labeling the edges}
	{help by_option##remarks10:Specifying separate scales for the separate plots}
	{help by_option##remarks11:History}


{marker remarks1}{...}
{title:Typical use}

{pstd}
One often has data that divides into different groups{hline 2}person data where
the persons are male or female or in different age categories (or both),
country data where the countries can be categorized into different regions of
the world, or, as below, automobile data where the cars are foreign or
domestic.  If you type

	{cmd:. scatter mpg weight}
	  {it:({stata "gr_example auto: scatter mpg weight":click to run})}
{* graph mpgweight}{...}

{pstd}
you obtain a scatterplot of mpg versus weight.  If you add {cmd:by(foreign)} as
an option, you obtain two graphs, one for each value of foreign:

	{cmd:. scatter mpg weight, by(foreign)}
	  {it:({stata "gr_example auto: scatter mpg weight, by(foreign)":click to run})}
{* graph mpgweightby}{...}

{pstd}
If you add the {cmd:total} suboption, another graph will be added representing
the overall total:

	{cmd:. scatter mpg weight, by(foreign, total)}
	  {it:({stata "gr_example auto: scatter mpg weight, by(foreign, total)":click to run})}
{* graph mpgweightbyt}{...}

{pstd}
In this case, there were three graphs to be presented and {cmd:by()} chose
to display them in a 2{it:x}2 array, leaving the last position empty.