gnuplot-beta

Suggestion to improve usability of plot command

[Keir M. <ke...@cs...>]

I have a simple suggestion to improve the usability of the plot command.
Currently, I am not a huge fan of the way point styles are specified; mainly
because I do not find having to memorize different plot styles as numbers
remotely intuitive. Also, it is very difficult to tell from the documentation
exactly how to plot squares or other points instead of crosses (for, i.e.
overplotting two scatter plots to see where points line up).

What am I suggesting? Instead of writing:

gnuplot> plot 'file1' with points 4 3
gnuplot> plot 'file2' with points 1 4

I suggest that we support (*in addition* not instead of) two new methods of
specifying plot styles, one which follows the convention of Matlab and Matplotlib
(Python's plotting package), and another which is so blatently obvious everyone
will understand it.

Note that in the above script, no one could possibly guess what 4 3 or 1 4
means if they are not a frequent gnuplot user. I actually did not figure out
that this was the command I was looking for until after several passes through
the documentation; I erroneously expected the command to be obvious.

1) The really obvious version
-----------------------------

gnuplot> plot 'file1' with points 'red squares'
gnuplot> plot 'file2' with points 'blue crosses'
gnuplot> plot 'file1' with points 'orange octagons'
gnuplot> plot 'file1' with points 'orange stippled-squares'
gnuplot> plot 'file1' with points 'violet filled-circles'

Supporting arbitrary colors would also be straightforward:

gnuplot> plot 'file1' with points '#4fa324 crossed-circles'

I realize this version is more verbose, but I bet occasional gnuplot users
(like myself) will never forget this syntax. Also, by having explicit examples
in the plot help, this will be clear. From my quick examination, there is no
obvious example that says:

To plot square symbols, do the following:
gnuplot> plot 'file1' with points 4 2
Note that I don't know if 2 is the correct style. Or if the first argument is
color or the second.

2) The MATLAB / Matplotlib convention
-------------------------------------

In MATLAB and Matplotlib, plotting works like:
>>> scatter(x, y, 'r>')
where the first character is a color and the second is a symbol. The above
example plots red right triangles.

The colors are:
        'b' : blue
        'g' : green
        'r' : red
        'c' : cyan
        'm' : magenta
        'y' : yellow
        'k' : black
        'w' : white

The symbols are:
        's' : square
        'o' : circle
        '^' : triangle up
        '>' : triangle right
        'v' : triangle down
        '<' : triangle left
        'd' : diamond
        'p' : pentagram
        'h' : hexagon
        '8' : octagon

I suggest gnuplot support, in the interest of lowering the amount of
information users need to memorize, the following:
gnuplot> plot 'file1' with points 'r>'

I believe that a) gnuplot's current point style syntax is unusable, and b)
because most scientific users use several plotting programs instead of just one
(because each one is lacking a different subset of features), it is valuable to
reduce the amount of knowledge required to shift from one program to another.

Thanks for listening,
Keir

p.s. I am not on the list, so please CC any replies to me.

Re: Suggestion to improve usability of plot command

[<br...@ph...>]

Keir Mierle wrote:
> I have a simple suggestion to improve the usability of the plot command.
> Currently, I am not a huge fan of the way point styles are specified; 

Not very surprisingly --- the syntax you use has never actually been 
documented, and has been deprecated for a *long* time now.  The current 
syntax, while still oriented towards numbers, is a lot clearer than

> gnuplot> plot 'file1' with points 4 3
> gnuplot> plot 'file2' with points 1 4

The problem with both your suggestions:

> gnuplot> plot 'file1' with points 'red squares'
> gnuplot> plot 'file2' with points 'blue crosses'
> gnuplot> plot 'file1' with points 'orange octagons'
[...]
> The symbols are:
>         's' : square
>         'o' : circle
>         '^' : triangle up

is the same: they completely ignore one central design principle of 
gnuplot: script compatibility across terminal drivers.  Your proposal
fails to address the question what gnuplot should do with a plot script 
that requests some point symbol the current driver simply can't generate.

Re: Suggestion to improve usability of plot command

[Daniel J S. <dan...@ie...>]

Hans-Bernhard Br=F6ker wrote:

>>gnuplot> plot 'file1' with points 'red squares'
>>gnuplot> plot 'file2' with points 'blue crosses'
>>gnuplot> plot 'file1' with points 'orange octagons'

Call this the Lucky Charms design principle.  (I probably used that joke =
already... for which many of you likely don't know that Lucky Charms is a=
 brand of cereal.)

I'm actually kind of partial to this syntax.  Could maybe even change it =
to read like

gnuplot> plot 'file1' with red square points

The one problem is that to describe some of these symbols can get lengthy=
, e.g., "filled square" vs. "empty square".  However, we could limit the =
number of symbol names to be six or eight, i.e., just "square" (could get=
 the filled square using the numbers).

>=20
> [...]
>=20
>>The symbols are:
>>        's' : square
>>        'o' : circle
>>        '^' : triangle up

or this.  Not as easy to remember, but condensed syntax.


> is the same: they completely ignore one central design principle of=20
> gnuplot: script compatibility across terminal drivers.  Your proposal
> fails to address the question what gnuplot should do with a plot script=
=20
> that requests some point symbol the current driver simply can't generat=
e.

The driver would map to another symbol and issue a warning.  (And we coul=
d write an algorithm so that it isn't mapped to an already used symbol nu=
mber.)

I keep a file on my computer with such numbers:

Symbol translation for Octave to "pslatex" terminal:

1 - plus
2 - x
3 - asterisk
4 - open square
5 - solid square
6 - open circle
7 - solid circle
8 - open triangle
9 - solid triangle

I don't know if the problem is so much the use of numbers for me.  The pr=
oblem is the fact that the numbers don't produce the same symbols across =
drivers.  Why couldn't those be mapped to be similar symbols?  It is very=
 frustrating to create a plot on the screen, then save it as PostScript t=
o find the symbols are different.  In that sense, I'd say gnuplot isn't s=
cript compatible.

Dan

Re: Suggestion to improve usability of plot command

[Keir M. <ke...@cs...>]

On Sat, Oct 07, 2006 at 02:55:40PM -0400, Daniel J Sebald wrote:
> Hans-Bernhard Br?ker wrote:
> 
> >>gnuplot> plot 'file1' with points 'red squares'
> >>gnuplot> plot 'file2' with points 'blue crosses'
> >>gnuplot> plot 'file1' with points 'orange octagons'
> 
> Call this the Lucky Charms design principle.  (I probably used that joke 
> already... for which many of you likely don't know that Lucky Charms is a 
> brand of cereal.)
> 
> I'm actually kind of partial to this syntax.  Could maybe even change it to 
> read like
> 
> gnuplot> plot 'file1' with red square points
> 
> The one problem is that to describe some of these symbols can get lengthy, 
> e.g., "filled square" vs. "empty square".  However, we could limit the 
> number of symbol names to be six or eight, i.e., just "square" (could get 
> the filled square using the numbers).

I actually wrote this as my proposed syntax first, but decided it would be too
controversial because 'red' could be a variable.

As long as a condensed syntax is available, then lengthy names are just fine.
When not excessively verbose, syntax which needs no documentation good.
 
> >>The symbols are:
> >>       's' : square
> >>       'o' : circle
> >>       '^' : triangle up
> 
> or this.  Not as easy to remember, but condensed syntax.

I became firmly convinced, when I heard a story from my friend David about
MATLAB plotting syntax (he is an IDL user): the first time he encountered it, a
friend of his was plotting some data in MATLAB. He said that at the end of the
plot command was this mysterious 'r.', yet when the plot came up he instantly
understood the syntax: red dots! Apparently this happened years ago, yet he
still remembers the syntax today. (And never uses MATLAB)
 
> >is the same: they completely ignore one central design principle of 
> >gnuplot: script compatibility across terminal drivers.  Your proposal
> >fails to address the question what gnuplot should do with a plot script 
> >that requests some point symbol the current driver simply can't generate.
> 
> The driver would map to another symbol and issue a warning.  (And we could 
> write an algorithm so that it isn't mapped to an already used symbol 
> number.)

Yes. I believe in keeping easy things easy, and hard things possible.
 
> I keep a file on my computer with such numbers:
> 
> Symbol translation for Octave to "pslatex" terminal:
> 
> 1 - plus
> 2 - x
> 3 - asterisk
> 4 - open square
> 5 - solid square
> 6 - open circle
> 7 - solid circle
> 8 - open triangle
> 9 - solid triangle
> 
> I don't know if the problem is so much the use of numbers for me.  The 
> problem is the fact that the numbers don't produce the same symbols across 
> drivers.  Why couldn't those be mapped to be similar symbols?  It is very 
> frustrating to create a plot on the screen, then save it as PostScript to 
> find the symbols are different.  In that sense, I'd say gnuplot isn't 
> script compatible.

I think this is a pretty convincing argument to adopt the new syntax, or
something like it; it sounds as though the existing system is actually worse!

Besides -- this is 2006. Which terminal that is frequently used by the majority
of users can't support all of the symbol types? I'm pretty baffled.  Besides,
if a user is writing a gnuplot script with color arguments, they can hardly
expect it to look amazing in black and white or grayscale.  I understand not
all terminals have colors, but there's no reason we can't do something
reasonable in the face of black and white. If they user wants gorgeous plots
that work in black and white and color, then they can use the old numeric
style.

Cheers,
Keir

Re: Suggestion to improve usability of plot command

[<br...@ph...>]

Keir Mierle wrote:
>> Keir Mierle wrote:
>>> I have a simple suggestion to improve the usability of the plot command.
>>> Currently, I am not a huge fan of the way point styles are specified; 

>> Not very surprisingly --- the syntax you use has never actually been 
>> documented, and has been deprecated for a *long* time now.  The current 
>> syntax, while still oriented towards numbers, is a lot clearer than

> This was not obvious to me in the documentation.  After digging around, I found
> an example of the new syntax hidden in the variable point size demo in the
> gnuplot 4.2 examples.

Interesting.  I really wonder how you managed to miss 'help plot with'.

> Now, having said that, let's take this from a new users (my) perspective. All
> I want to accomplish is to control the scatter plot symbols.
> 
>    1) I go to gnuplot.info. I click on the obvious Documentation link (good).

Bad first reflex.  Why is it so many people these days seems to assume 
that the obvious first place to search for documentation of some tool is 
the web?

>    2) A page with a bunch of information comes up about the different formats
>       available. Not clear exactly which link I should click; since I prefer
>       searchable HTML for documentation, 

Bad second reflex.  There's no such thing as searchable HTML.  Searching 
HTML is a job for a program that has nothing to do with the HTML 
document as such.  To make HTML documents searchable takes an extension 
to the web server --- we don't have that kind of control over our servers.

> Yet, *still*, nowhere does it say 'to plot with circles, use this 
> style.' I had to do trial and error to find the right symbol.

Of course it doesn't.  Because there's no such thing as a particular 
point symbol type that will generate circles on all terminals.  The 
reason for that being that there are terminals that can't do circles.

> I address this in my other follow-up. I would also like to mention that I feel
> when choices of symbol types are deliberate, it is unfortunate that gnuplot
> does not guarentee the same symbols across terminals.

It can't --- terminals are too different for that.

Re: Suggestion to improve usability of plot command

[<br...@ph...>]

Daniel J Sebald wrote:

> I don't know if the problem is so much the use of numbers for me.  The 
> problem is the fact that the numbers don't produce the same symbols 
> across drivers.  

These two are, actually, the same problem.  We use numbers *because* 
they're the lowest common denominator of that every terminal driver can 
use: a sequence of point types that will be used repeatedly as often as 
necessary.

> Why couldn't those be mapped to be similar symbols?  

Because terminal drivers' capabilities differ so much.

> It is very frustrating to create a plot on the screen, 

You're blinding yourself to the difference between "creating" and 
"fine-tuning" here.

> then save it as PostScript to find the symbols are different.

So don't do that then.  Ghostview & friends exist: use them.

> In that sense, I'd say gnuplot isn't script compatible.

Setting aside recent additions like 'linecolour', it is and always has 
been as compatible as it could possibly be: every terminal driver can 
use every plot script and process it, without warnings or errors.  The 
worst that can happen is that the output is harder to read than it was 
on the terminal it was designed for.

Re: Suggestion to improve usability of plot command

[Keir M. <ke...@cs...>]

> Keir Mierle wrote:
> >I have a simple suggestion to improve the usability of the plot command.
> >Currently, I am not a huge fan of the way point styles are specified; 
> 
> Not very surprisingly --- the syntax you use has never actually been 
> documented, and has been deprecated for a *long* time now.  The current 
> syntax, while still oriented towards numbers, is a lot clearer than

This was not obvious to me in the documentation.  After digging around, I found
an example of the new syntax hidden in the variable point size demo in the
gnuplot 4.2 examples.

Before I continue, I must say thank you for writing gnuplot, and for
documenting it. I realize documentation is a thankless job. It is odd to think
that the best comments one can hope for with documentation are none at all.

Now, having said that, let's take this from a new users (my) perspective. All
I want to accomplish is to control the scatter plot symbols.

   1) I go to gnuplot.info. I click on the obvious Documentation link (good).
   2) A page with a bunch of information comes up about the different formats
      available. Not clear exactly which link I should click; since I prefer
      searchable HTML for documentation, I click the HTML link under 'Official
      gnuplot Documentation'.
   3) In the official documentation, I accidentally page down past the table of
      contents, because it lacks numbers or subsections, which I expect in
      documentation table of contents.  I hit 'home' to go back to the top of
      the page when I realize I'm not finding what I want.
   4) I finally realize that the table of contents is the bulleted list 
      immediately following the big `gnuplot'. I click on Plotting.
   5) I see a bunch of text, none of which has any plots. There is no link to
      'plot' when the section mentions the plot command. Searching for 'plot'
      is ineffective, because the word is used so many times. At this point, I
      hit back a few times and go to the official gnuplot quick reference.
   6) After looking all over for an example with different points, I find, on
      the bottom of page 4, the following example:

          plot "data" with points 1 3

      My intuition says this is the command I want. Indeed, it is.

In all fairness, I went back and finally found the REAL table of contents,
which is above the 'gnuplot' table of contents and below the list of
contributors (in small text, with no title). I clicked Commands, then 'plot',
where it describes the plot command. Because I already knew I was looking for
'with', I clicked that. There it was. Yet, *still*, nowhere does it say 'to
plot with circles, use this style.' I had to do trial and error to find the
right symbol.

I understand that usability is hard. I am mailing the list with my experiences
in the hopes that gnuplot can improve, and the next person's experience will be
better. My father gave up on Gnuplot ages ago because he encountered similar
frustrations to my own; however, he silently moved on rather than engaging the
community.
 
> >gnuplot> plot 'file1' with points 4 3
> >gnuplot> plot 'file2' with points 1 4
> 
> The problem with both your suggestions:
> 
> >gnuplot> plot 'file1' with points 'red squares'
> >gnuplot> plot 'file2' with points 'blue crosses'
> >gnuplot> plot 'file1' with points 'orange octagons'
> [...]
> >The symbols are:
> >        's' : square
> >        'o' : circle
> >        '^' : triangle up
> 
> is the same: they completely ignore one central design principle of 
> gnuplot: script compatibility across terminal drivers.  Your proposal
> fails to address the question what gnuplot should do with a plot script 
> that requests some point symbol the current driver simply can't generate.

I address this in my other follow-up. I would also like to mention that I feel
when choices of symbol types are deliberate, it is unfortunate that gnuplot
does not guarentee the same symbols across terminals.

Gnuplot should simply make an expansive list of Standard Gnuplot Symbols, a
subset of which every terminal is required to implement.

Cheers,
Keir

Re: Suggestion to improve usability of plot command

[Petr M. <mi...@ph...>]

> This was not obvious to me in the documentation.  After digging around, I found
> an example of the new syntax hidden in the variable point size demo in the
> gnuplot 4.2 examples.
>
> Before I continue, I must say thank you for writing gnuplot, and for
> documenting it. I realize documentation is a thankless job. It is odd to think
> that the best comments one can hope for with documentation are none at all.
>
> Now, having said that, let's take this from a new users (my) perspective. All
> I want to accomplish is to control the scatter plot symbols.

A new user should read "Tutorials, learning, help" and to go through 
"Demos", all on the web page. Reading the complete documentation is not what 
a novice should do. This is valid for any other software tool as well.

---
PM

Re: Suggestion to improve usability of plot command

[Theo H. <th...@ph...>]

Keir Mierle wrote:
> I have a simple suggestion to improve the usability of the plot command.
> Currently, I am not a huge fan of the way point styles are specified; mainly
> because I do not find having to memorize different plot styles as numbers
> remotely intuitive. Also, it is very difficult to tell from the documentation
> exactly how to plot squares or other points instead of crosses (for, i.e.
> overplotting two scatter plots to see where points line up).
> 
> What am I suggesting? Instead of writing:
> 
> gnuplot> plot 'file1' with points 4 3
> gnuplot> plot 'file2' with points 1 4
> 
> I suggest that we support (*in addition* not instead of) two new methods of
> specifying plot styles, one which follows the convention of Matlab and Matplotlib
> (Python's plotting package), and another which is so blatently obvious everyone
> will understand it.
> 
> Note that in the above script, no one could possibly guess what 4 3 or 1 4
> means if they are not a frequent gnuplot user. I actually did not figure out
> that this was the command I was looking for until after several passes through
> the documentation; I erroneously expected the command to be obvious.
> 
> 1) The really obvious version
> -----------------------------
> 
> gnuplot> plot 'file1' with points 'red squares'
> gnuplot> plot 'file2' with points 'blue crosses'
> gnuplot> plot 'file1' with points 'orange octagons'
> gnuplot> plot 'file1' with points 'orange stippled-squares'
> gnuplot> plot 'file1' with points 'violet filled-circles'
[...]

First of all: after reading this thread, I'm surprised no one has 
mentioned the `test` command. From `help plot style`: "If you wish to 
choose the line or point type for a single plot, <line_type> and 
<point_type> may be specified. These are positive integer constants (or 
expressions) that specify the line type and point type to be used for 
the plot. Use `test` to display the types available for your terminal."

The "really obvious" syntax can be implemented using macros. See `help 
macros` for an example. It may be that a single command file containing 
macro definitions may be shared among many terminals (for example, the 
postscript-based ones), although certainly some terminals will demand 
their own macro definitions due to differing line- and point types. Feel 
free to contribute such macro definitions for commonly used terminals.

THeo