blabel_option.hlp

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

{smcl}
{* 04mar2005}{...}
{cmd:help blabel_option}
{hline}

{title:Title}

{p2colset 5 26 28 2}{...}
{p2col :{hi:[G] {it:blabel_option}} {hline 2}}Option for labeling bars{p_end}
{p2colreset}{...}


{title:Syntax}

{p 8 23 2}
{cmdab:gr:aph}
{c -(}{cmd:bar}|{cmd:hbar}{c )-}
...{cmd:,}
...
{cmdab:blab:el:(}{it:what} [{cmd:,} {it:where_and_how}]{cmd:)} ...

	{it:what}{col 40}description
	{hline 70}
	{cmd:none}{...}
{col 40}no label; the default
	{cmd:bar}{...}
{col 40}label is bar height
	{cmd:total}{...}
{col 40}label is cumulative bar height
	{cmd:name}{...}
{col 40}label is name of {it:yvar}
	{cmd:group}{...}
{col 40}label is first {cmd:over()} group
	{hline 70}

	{it:where_and_how}{col 40}description
	{hline 70}
	{cmdab:pos:ition:(}{cmd:outside}|{cmd:inside}|
		 {cmd:base}|{cmd:center)}{...}
{col 40}where to locate label on bar
	{cmd:gap(}{it:{help relativesize}}{cmd:)}{...}
{col 40}distance from position
	{cmd:format(}{help format:{bf:%}{it:fmt}}{cmd:)}{...}
{col 40}format if {cmd:bar} or {cmd:total}
	{it:{help textbox_options}}{...}
{col 40}look of label
	{hline 70}


{title:Description}

{pstd}
Option {cmd:blabel()} is for use with {cmd:graph} {cmd:bar} and {cmd:graph}
{cmd:hbar}.  It adds a label on top of or inside each bar.


{title:Options}

{phang}
{cmd:blabel(}{it:what}{cmd:,} {it:where_and_how}{cmd:)}
    specifies the label and where it is to be located relative to the bar.
    {it:where_and_how} is optional and is documented under
    {hi:Suboptions for use with blabel()} below.
    {it:what} specifies the contents of the label.

{phang}
    {cmd:blabel(bar)} specifies that the label be the height of the bar.  In

{phang3}
	    {cmd:. graph bar (mean) empcost, over(division) blabel(bar)}

{pmore}
    the labels would be the mean employee cost.

{phang}
    {cmd:blabel(total)} specifies that the label be the cumulative height
    of the bar.  {cmd:blabel(total)} is for use with {cmd:graph} {cmd:bar}'s
    {cmd:stack} option.  In

{phang3}
	    {cmd:. graph bar (sum) cost1 cost2, stack over(group) blabel(total)}

{pmore}
    the labels would be the total height of the stacked bar{hline 2}the sum of
    costs.  In addition, the {cmd:cost1} part of the stack bar would be
    labeled with its height.

{phang}
    {cmd:blabel(name)} specifies that the label be the name of the
    {it:yvar}.  In

{phang3}
	    {cmd:. graph bar (mean) y1 y2 y3 y4, blabel(name)}

{pmore}
     The labels would be "mean of y1", "mean of y2", ..., "mean of y4".
     Usually, you would also want to suppress the legend in this case and
     so would type

{phang3}
	    {cmd:. graph bar (mean) y1 y2 y3 y4, blabel(name) legend(off)}

{phang}
    {cmd:blabel(group)} specifies that the label be the name of the
    first {cmd:over()} group.  In

{phang3}
	    {cmd:. graph bar cost, over(division) over(year) blabel(group)}

{pmore}
    the labels would be the name of the divisions.  Usually, you would also
    want to suppress the appearance of the division labels on the axis:

{phang3}
	    {cmd:. graph bar cost, over(division, axis(off)) over(year) blabel(group)}


{title:Suboptions for use with blabel()}

{phang}
{cmd:position()}
    specifies where the label is to appear.

{pmore}
    {cmd:position(outside)} is the default.  The label appears just above
    the bar ({cmd:graph} {cmd:bar}) or just to its right ({cmd:graph}
    {cmd:hbar}).

{pmore}
    {cmd:position(inside)} specifies that the label appear inside the
    bar, at the top ({cmd:graph} {cmd:bar}) or at its rightmost extent
    ({cmd:graph} {cmd:hbar}).

{pmore}
    {cmd:position(base)} specifies that the label appear inside the bar, at
    the bar's base; at the bottom of the bar ({cmd:graph} {cmd:bar}); or at
    the left of the bar ({cmd:graph} {cmd:hbar}).

{pmore}
    {cmd:position(center)} specifies that the label appear inside the bar, at
    its center.

{phang}
{cmd:gap(}{it:relativesize}{cmd:)}
    specifies a distance by which the label is to be offset from its location
    ({cmd:outside}, {cmd:inside}, {cmd:base}, or {cmd:center}).
    The default is usually {cmd:gap(1.7)}.  Note that the {cmd:gap()} may be
    positive or negative, and you can specify, for instance,
    {cmd:gap(*1.2)} and {cmd:gap(*.8)} to increase or decrease the gap by
    20%; see {it:{help relativesize}}.

{phang}
{cmd:format(%}{it:fmt}{cmd:)}
    is for use with {cmd:blabel(bar)} and {cmd:blabel(total)}; it specifies
    the display format to be used to format the height value.  See
    {help format}.

{phang}
{it:textbox_options}
    are any of the options allowed with a textbox.  Important options include
    {cmd:size()}, which determines the size of the text; {cmd:box}, which
    draws a box around the text; and {cmd:color()}, which determines the color
    of the text.  See {it:{help textbox_options}}.


{title:Remarks}

{pstd}
{cmd:blabel()} serves two purposes:  to increase the information content of
the chart ({cmd:blabel(bar)} and {cmd:blabel(total)}) or to change how
bars are labeled ({cmd:blabel(name)} and {cmd:blabel(group)}).  Remarks are
presented under the headings

	{hi:Increasing the information content}
	{hi:Changing how bars are labeled}


{title:Increasing the information content}

{pstd}
Under the heading {hi:Multiple bars} in {helpb graph bar}, 
the following graph was drawn:

	{cmd}. graph bar (mean) tempjuly tempjan, over(region)
		bargap(-30)
		legend(label(1 "July") label(2 "January"))
		ytitle("Degrees Fahrenheit")
		title("Average July and January temperatures")
		subtitle("by regions of the United States")
		note("Source:  U.S. Census Bureau, U.S. Dept. of Commerce"){txt}
	  {it:({stata gr_example2 grbar1:click to run})}
{* graph grbar1, but do not represent in manual}{...}

{pstd}
To the above, we now add

		{cmd:blabel(bar, position(inside) format(%9.1f))}

{pstd}
which will add the average temperature to the bar, position the average
inside the bar, at the top, and format its value using %9.1f:

	{cmd}. graph bar (mean) tempjuly tempjan, over(region)
		bargap(-30)
		legend(label(1 "July") label(2 "January"))
		ytitle("Degrees Fahrenheit")
		title("Average July and January temperatures")
		subtitle("by regions of the United States")
		note("Source:  U.S. Census Bureau, U.S. Dept. of Commerce")
  {txt:{it:new} ->}        blabel(bar, position(inside) format(%9.1f) color(white)){txt}
	  {it:({stata gr_example2 grbar1lab:click to run})}
{* graph grbar1lab}{...}

{pstd}
We also specified the {it:textbox_option} {cmd:color(white)} to change the
color of the text; see {it:{help textbox_options}}.  Dark text on a dark
bar would have blended too much.


{title:Changing how bars are labeled}

{pstd}
Placing the labels on the bars works especially well with horizontal bar
charts:

	{cmd}. sysuse nlsw88, clear

	. graph hbar (mean) wage,
		 over(occ, axis(off) sort(1))
	       blabel(group, position(base) color(bg))
	       ytitle("")
		   by(union,
		       title("Average Hourly Wage, 1988, Women Aged 34-46")
		       note("Source:  1988 data from NLS, U.S. Dept. of Labor,
			     Bureau of Labor Statistics")
		     ){txt}
	  {it:({stata gr_example2 grblab1:click to run})}
{* graph grblab1}{...}

{pstd}
What makes moving the labels from the axis to the bars work so well
in this case is that it saves so much horizontal space.

{pstd}
In the above command, note the first two option lines:

		 {cmd}over(occ, axis(off) sort(1))
	       blabel(group, position(base) color(bg)){txt}

{pstd}
{cmd:blabel(group)} puts the occupation labels on top of the bars, and suboption
{cmd:position(base)} located the labels at the base of each bar.  We specified
{cmd:over(,axis(off))} to prevent the labels from appearing on the axis.

{pstd}
Let us run though all the options:

{phang2}
{cmd:over(occ, axis(off) sort(1))}{break}
     Specified that the chart be done over occupation, that the occupation
     labels not be shown on the axis, and that the bars be sorted by
     the first (and only) {it:yvar}, namely {cmd:(mean)} {cmd:wage}.

{phang2}
{cmd:ytitle("")}{break}
     Specified that the title on the numerical {it:y} axis (the horizontal
     axis in this horizontal case) be suppressed.

{phang2}
{cmd:by(union, title(...) note(...))}{break}
     Specified that the entire graph be repeated by values of variable 
     {cmd:union}, and specified that the title and note be added to the
     overall graph.  Had we specified the {cmd:title()} and {cmd:note()}
     options outside the {cmd:by()}, they would have been placed on each
     graph.


{title:Also see}

{psee}
Manual:  {bf:[G] {it:blabel_option}}

{psee}
Online:  {helpb graph bar}
{p_end}