RE: st: bar graph axis color- frustrated

["Nick Cox" <n.j.cox@durham.ac.uk>]

I think two questions are bundled together in this thread. 

1. Given the syntax, is the help for -graph bar- (etc.) as clear as
possible? 

2. Given the problem tackled, is the syntax for -graph bar- (etc.) as
clear as possible? 

Ultimately, agreed poor marks under these headings are problems for
StataCorp. I think it's easier for them, like any program authors, to
improve if they get specific comments on precisely what's deemed unclear
and what should be done instead. 

On #2, what's perhaps missing is an explanation of why -graph
bar|hbar|dot- are so different in the first place. Part of the answer is
fairly obvious with a bit of thought but I don't think the rest of the
answer is so clear. 

A key underlying issue is simple to state but hard to optimise: syntax
for statistical graphics could be organised by statistical principles or
by graphical principles, and the classifications surely don't coincide.
A bar chart showing magnitudes you have already, a bar chart showing
frequencies that must be produced from the data, and a histogram for a
continuous distribution are cases in point: close in some ways, but not
in others. 

Nick 
n.j.cox@durham.ac.uk 

Kieran McCaul

OK, I agree, Nick.  Putting more examples into the documentation would
be unnecessary, but I do think that the documentation could be a little
clearer.

I rarely do bar graphs, but let's say I had to do one.

I first generate the bar graph with the minimal number of options set.
It looks OK, so now I start modifying it to get the final graph that I
want. 
 
One of the things I want to do is specify axes of a certain width and
colour.  Now I know how to do this for scattergrams, line graphs, etc,
so this should be no big deal, so naively I add in -xscale(lw(*2)
lc(red))-, but this doesn't work.

OK, so I look at the help file and I see "axis_options".  Fine, I look
at these.

There is nothing in there about the x-axis, other than the option
-xalternate-; everything else is about the y-axis.

How do I set the options for the x-axis?  Where do I look?  I'm not
going to believe that the programmers who wrote -graph bar- didn't
anticipate that someone would want to tinker with the look of the
x-axis, so I "know" the options will be in there.

So I go back up to the top of the help file and start reading it, line
by line, and eventually I find them: -axis(cat_axis_line_options)- is
one of the options of -yvaroptions-.

Now this seems a tad obscure to me.  If I'm looking for axis options and
I see a hyperlink called axis_options, then that's where I would go.
I'm hardly going to go looking in -yvaroptions-.

So, I think the help file could be a bit more helpful.  By all means
keep the x-axis options in -yvaroptions-, but I think that it would be
helpful to have a note in the -axis_options- that simply said something
like "If you want to alter the characteristics of the x-axis, go to the
options listed under -yvaroptions-".

Nick Cox

This isn't (meant to be) contentious, but the thread does underline that
none of half-a-dozen experienced Stata users knew the answer just like
that, including Michael Mitchell who has written an entire book on Stata
graphics. 

(I was asleep, but I wouldn't have known either.)

But the solution is documented and the tail statement in 

"yvaroptions(over_subopts) allows you to specify over_subopts for the
yvars.  This is seldom done."

appears to be quite correct. 

There is a fine line between answering all possible questions and
bloating the documentation further. Sometimes the longer your help
files, the less people are inclined to read through them. 

Kieran McCaul

it's really buried away, isn't it.

Changing the look of the category axis is really something I would
expect people would want to do.  Perhaps the Graphics Manual could be
updated to show a few examples.

*
*   For searches and help try:
*   http://www.stata.com/help.cgi?search
*   http://www.stata.com/support/statalist/faq
*   http://www.ats.ucla.edu/stat/stata/