[GRASS-dev] r.colors confusion with "color", "rules", and "raster" options

GRASS GRASS developer
1

Hi,

the manual of 6.4 r.colors says:
"The rules color table type will cause r.colors to read color table
specifications from standard
input (stdin) and will build the color table accordingly.
"

r.colors help | grep rules
...
   color Type of color table
           options: aspect,aspectcolr,bcyr,bgyr,byg,byr,curvature,
                    differences,elevation,etopo2,evi,grey,grey1.0,grey255,
                    gyr,ndvi,population,rainbow,ramp,ryb,ryg,sepia,slope,
                    srtm,terrain,wave,random,grey.eq,grey.log,rules
...
            rules: create new color table based on user-specified rules
...
   rules Path to rules file

but:

r.colors map=gpcp_1dd_p1d.2002_sum color=rules rules=color_tab.col
ERROR: "color", "rules", and "raster" options are mutually exclusive

I know, I know.. but it is far from intuitive... any ideas to improve this
behaviour/docs?

This works of course...:
r.colors map=gpcp_1dd_p1d.2002_sum rules=color_tab.col
Color table for <gpcp_1dd_p1d.2001_sum> set to color_tab.col

The first command version above doesn't look harmful to me, could we
(re)enable it?

thanks
Markus

2

On Tue, Sep 23, 2008 at 7:22 AM, Markus Neteler <neteler@osgeo.org> wrote:

Hi,

the manual of 6.4 r.colors says:
"The rules color table type will cause r.colors to read color table
specifications from standard
input (stdin) and will build the color table accordingly.
"

r.colors help | grep rules
...
  color Type of color table
          options: aspect,aspectcolr,bcyr,bgyr,byg,byr,curvature,
                   differences,elevation,etopo2,evi,grey,grey1.0,grey255,
                   gyr,ndvi,population,rainbow,ramp,ryb,ryg,sepia,slope,
                   srtm,terrain,wave,random,grey.eq,grey.log,rules
...
           rules: create new color table based on user-specified rules
...
  rules Path to rules file

but:

r.colors map=gpcp_1dd_p1d.2002_sum color=rules rules=color_tab.col
ERROR: "color", "rules", and "raster" options are mutually exclusive

I know, I know.. but it is far from intuitive... any ideas to improve this
behaviour/docs?

This works of course...:
r.colors map=gpcp_1dd_p1d.2002_sum rules=color_tab.col
Color table for <gpcp_1dd_p1d.2001_sum> set to color_tab.col

The first command version above doesn't look harmful to me, could we
(re)enable it?

thanks
Markus
_______________________________________________
grass-dev mailing list
grass-dev@lists.osgeo.org
http://lists.osgeo.org/mailman/listinfo/grass-dev

This version seems most intuitive to me:
r.colors map=gpcp_1dd_p1d.2002_sum rules=color_tab.col

Cheers,

Dylan

3

On Tue, Sep 23, 2008 at 5:52 PM, Dylan Beaudette
<dylan.beaudette@gmail.com> wrote:

On Tue, Sep 23, 2008 at 7:22 AM, Markus Neteler <neteler@osgeo.org> wrote:

...

r.colors map=gpcp_1dd_p1d.2002_sum color=rules rules=color_tab.col
ERROR: "color", "rules", and "raster" options are mutually exclusive

...

This version seems most intuitive to me:
r.colors map=gpcp_1dd_p1d.2002_sum rules=color_tab.col

To me, too.
What about silently dropping color=rules instead of issuing the ERROR?

Markus

4

On Tuesday 23 September 2008, Markus Neteler wrote:

On Tue, Sep 23, 2008 at 5:52 PM, Dylan Beaudette

<dylan.beaudette@gmail.com> wrote:
> On Tue, Sep 23, 2008 at 7:22 AM, Markus Neteler <neteler@osgeo.org>
> wrote:

...

>> r.colors map=gpcp_1dd_p1d.2002_sum color=rules rules=color_tab.col
>> ERROR: "color", "rules", and "raster" options are mutually exclusive

...

> This version seems most intuitive to me:
> r.colors map=gpcp_1dd_p1d.2002_sum rules=color_tab.col

To me, too.
What about silently dropping color=rules instead of issuing the ERROR?

Markus

works for me. that shouldn't break too many scripts, and besides-- it makes
more sense. Would this be back-ported to 6.4?

Dylan

--
Dylan Beaudette
Soil Resource Laboratory
http://casoilresource.lawr.ucdavis.edu/
University of California at Davis
530.754.7341

5

Markus Neteler wrote:

the manual of 6.4 r.colors says:
"The rules color table type will cause r.colors to read color table
specifications from standard
input (stdin) and will build the color table accordingly.
"

r.colors help | grep rules
...
   color Type of color table
           options: aspect,aspectcolr,bcyr,bgyr,byg,byr,curvature,
                    differences,elevation,etopo2,evi,grey,grey1.0,grey255,
                    gyr,ndvi,population,rainbow,ramp,ryb,ryg,sepia,slope,
                    srtm,terrain,wave,random,grey.eq,grey.log,rules
...
            rules: create new color table based on user-specified rules
...
   rules Path to rules file

but:

r.colors map=gpcp_1dd_p1d.2002_sum color=rules rules=color_tab.col
ERROR: "color", "rules", and "raster" options are mutually exclusive

I know, I know.. but it is far from intuitive... any ideas to improve this
behaviour/docs?

-rules: create new color table based on user-specified rules
+rules: create new color table based on user-specified rules read from stdin

This works of course...:
r.colors map=gpcp_1dd_p1d.2002_sum rules=color_tab.col
Color table for <gpcp_1dd_p1d.2001_sum> set to color_tab.col

The first command version above doesn't look harmful to me, could we
(re)enable it?

Why? If you don't want to read rules from stdin, don't use
color=rules.

If you don't want error messages, don't provide erroneous input.

What's so special about this particular error that it should be
silently ignored?

--
Glynn Clements <glynn@gclements.plus.com>

6

On Tue, Sep 23, 2008 at 9:54 PM, Glynn Clements
<glynn@gclements.plus.com> wrote:
...

What's so special about this particular error that it should be
silently ignored?

all fine, it was answered in the forked thread.

Markus

7

> I know, I know.. but it is far from intuitive... any
> ideas to improve this behaviour/docs?

I've just added some logic in 6.x SVN to more nicely handle different
user interpretations of the commands. "accept sloppy input, create
tight output" and all that. Sure 'color=rules rules=filename' is
redundant, but the intention is obvious. some people (especially those
unfamiliar) like to tick every box. if it doesn't hurt anything, let 'em.

I also backported the effect of rules=- meaning read from stdin.

-rules: create new color table based on user-specified rules
+rules: create new color table based on user-specified rules read from stdin

I reverted that as it is somewhat misleading. It can mean either read
directly from stdin or if no stream is waiting then to enter into the
interactive environment. traditionally (not to mention currently)
color=rules in grass 5/6 triggered the interactive environment prompt
and help menu. I see no reason to strongly push users to use the -i
flag instead of color=rules when both are removed in GRASS 7. Just
let the old way fade away gracefully in its own time without disrupting
users. Where's the gain in intentionally scuttling it early?

Hamish

8

Hamish wrote:

I've just added some logic in 6.x SVN to more nicely handle different
user interpretations of the commands. "accept sloppy input, create
tight output" and all that. Sure 'color=rules rules=filename' is
redundant, but the intention is obvious. some people (especially those
unfamiliar) like to tick every box. if it doesn't hurt anything, let 'em.

Reverted.

If input is invalid, you report that it's invalid, not silently do
what you *think* that the user meant (i.e. DWIM).

If the user misunderstands something, you should educate them, not
reinforce the misconception.

I also backported the effect of rules=- meaning read from stdin.

This is a reasonable enhancement.

> -rules: create new color table based on user-specified rules
> +rules: create new color table based on user-specified rules read from stdin

I reverted that as it is somewhat misleading. It can mean either read
directly from stdin or if no stream is waiting then to enter into the
interactive environment.

Huh? It always means "read from stdin". If stdin is a tty, you get the
interactive prompts; if it's a file or pipe, you don't.

I have re-instated the "read from stdin" text.

traditionally (not to mention currently)
color=rules in grass 5/6 triggered the interactive environment prompt
and help menu. I see no reason to strongly push users to use the -i
flag instead of color=rules when both are removed in GRASS 7.

-i doesn't come into it. In fact, -i could probably be removed from
6.4. It's a fairly recent addition, and it's unlikely to be of any use
in scripts, so it's unlikely that anything is actually relying upon
it.

Just
let the old way fade away gracefully in its own time without disrupting
users. Where's the gain in intentionally scuttling it early?

This isn't about "scuttling" anything. colour=rules and rules= have
always been mutually exclusive, so long as rules= has existed.

Hopefully, we'll eventually have some way to communicate the
inter-relationships between options to the parser. In the meantime, we
should settle for communicating it to the user.

BTW, do we actually need to describe all of the color= options twice?
The description.html file includes all of the options, but the
auto-generated portion already contains that information.

--
Glynn Clements <glynn@gclements.plus.com>

9

[stating my peace then dropping this to focus on far more ghastly UI issues]

Hamish wrote:
> I've just added some logic in 6.x SVN to more nicely handle different
> user interpretations of the commands. "accept sloppy input, create
> tight output" and all that. Sure 'color=rules rules=filename' is
> redundant, but the intention is obvious. some people (especially those
> unfamiliar) like to tick every box. if it doesn't hurt anything, let
> 'em.

Glynn:

Reverted.

If input is invalid, you report that it's invalid, not silently do
what you *think* that the user meant (i.e. DWIM).

I accept the general point, but in this case can you offer an
alternative intent for 'color=rules rules=filename'?

I find "invalid" a bit strong in this case, but agree that if the user
misinterprets something then it is our task to make the instructions
clearer.

If the user misunderstands something, you should educate them, not
reinforce the misconception.

In cases where it is obvious what they meant, my view would be to focus on the goal and let a minor misappreciation for the underlying design pass.

trying to get into the head of a new user for a minute:

Gary the Grass user is presented with the r.colors GUI.
He starts filling in options from the top down. As a beginner he can
only guess what to put for each option. For "color=" he gets a drop
down menu, the top entry being blank and the bottom being rules. ummm...
The next is for "rules=" filename. That makes sense and he uses that.
But what to put for the colors= option now? Being slightly unsure of
himself with this new complex software, and wanting to make doubly sure
that the rules= option is used, and lacking the experience to follow
the subtle logic, the points the colors= option at what he thinks is
for rules=. That gives an error not to use the colors= option. But then
he thinks that he *did* give the neutral answer to color=, and what to
set it to now? (blank may be far from obvious)

> > -rules: create new color table based on user-specified rules
> > +rules: create new color table based on user-specified rules read from stdin
>
> I reverted that as it is somewhat misleading. It can mean either read
> directly from stdin or if no stream is waiting then to enter into the
> interactive environment.

Huh? It always means "read from stdin". If stdin is a tty, you get the
interactive prompts; if it's a file or pipe, you don't.

Well technically, yes, but I feel that we're splitting hairs here.
To the same newly recruited user, what is a stdin and where can I go to
buy one? -----Do those extra words contribute to the clarity of meaning?
Or, although technically correct, do they needlessly confuse the matter?
I have a small goal that module and option labels should, whenever
possible, be concise enough to fit in 80 chars or less. (partly cosmetic,
partly it's a nice round number for the task) Unnecessary words must go!

BTW, do we actually need to describe all of the color=
options twice?
The description.html file includes all of the options, but
the auto-generated portion already contains that information.

yep, they're redundant.

Hamish

10

Hamish wrote:

[stating my peace then dropping this to focus on far more ghastly UI issues]

> Hamish wrote:
> > I've just added some logic in 6.x SVN to more nicely handle different
> > user interpretations of the commands. "accept sloppy input, create
> > tight output" and all that. Sure 'color=rules rules=filename' is
> > redundant, but the intention is obvious. some people (especially those
> > unfamiliar) like to tick every box. if it doesn't hurt anything, let
> > 'em.
Glynn:
> Reverted.
>
> If input is invalid, you report that it's invalid, not silently do
> what you *think* that the user meant (i.e. DWIM).

I accept the general point, but in this case can you offer an
alternative intent for 'color=rules rules=filename'?

I find "invalid" a bit strong in this case, but agree that if the user
misinterprets something then it is our task to make the instructions
clearer.

Well, if the user specifies 'color=rules rules=filename', the error
message is:

  ERROR: "color", "rules", and "raster" options are mutually exclusive

From that, it should be clear that the user has to choose between

color= and rules=. The option descriptions:

  rules Path to rules file
  color Type of color table

should make it clear that rules= is the correct choice for reading
rules from a file.

Also, the additon of "from stdin" to the text for color=rules:

  create new color table based on user-specified rules read from stdin

should make it clear that this isn't what they want if they are
reading rules from a file.

> If the user misunderstands something, you should educate them, not
> reinforce the misconception.

In cases where it is obvious what they meant, my view would be to
focus on the goal and let a minor misappreciation for the underlying
design pass.

trying to get into the head of a new user for a minute:

Gary the Grass user is presented with the r.colors GUI.
He starts filling in options from the top down. As a beginner he can
only guess what to put for each option. For "color=" he gets a drop
down menu, the top entry being blank and the bottom being rules. ummm...
The next is for "rules=" filename. That makes sense and he uses that.
But what to put for the colors= option now? Being slightly unsure of
himself with this new complex software, and wanting to make doubly sure
that the rules= option is used, and lacking the experience to follow
the subtle logic, the points the colors= option at what he thinks is
for rules=. That gives an error not to use the colors= option. But then
he thinks that he *did* give the neutral answer to color=, and what to
set it to now? (blank may be far from obvious)

If a user thinks that they should fill in as many options as possible,
that's a fundamental misconception that should be corrected sooner
rather than later.

I've just noticed that the wxPython dialogs don't indicate whether an
option is required or optional, while the Tcl/Tk dialogs note this for
each option.

Really, if a user just selects options based upon instinct, they're
likely to run into more substantial problems sooner rather than later.

> > > -rules: create new color table based on user-specified rules
> > > +rules: create new color table based on user-specified rules read from stdin
> >
> > I reverted that as it is somewhat misleading. It can mean either read
> > directly from stdin or if no stream is waiting then to enter into the
> > interactive environment.
>
> Huh? It always means "read from stdin". If stdin is a tty, you get the
> interactive prompts; if it's a file or pipe, you don't.

Well technically, yes, but I feel that we're splitting hairs here.
To the same newly recruited user, what is a stdin and where can I go to
buy one? -----Do those extra words contribute to the clarity of meaning?

Absolutely. Otherwise, it's stating that the option uses
user-specified rules read from ... who knows where?

For someone as new as "Gary", would they even know that they need to
put the rules into a file? Or what format those rules should be in?

Or would they just see "based on user-specified rules" and expect it
to pop up a window into which they can enter rules? If they do,
they're in for shock, as the GUI waits for r.colors, which is waiting
for something to be fed to its stdin.

By the point that they are entering a valid sequence of colour rules
into a text file, they probably know that they will need to use rules=
to use it. Otherwise, why would they be creating that file in the
first place? What are they planning to do with it once it has been
created?

--
Glynn Clements <glynn@gclements.plus.com>

11

I've just noticed that the wxPython dialogs don't indicate whether an
option is required or optional, while the Tcl/Tk dialogs
note this for each option.

I believe it manifests itself in the tab name.
(for better or worse)

Or would they just see "based on user-specified rules" and expect it
to pop up a window into which they can enter rules? If they do,
they're in for shock, as the GUI waits for r.colors,
which is waiting for something to be fed to its stdin.

Hopefully the discover Michael's handywork in Raster->Manage map colors
->Color rules. (tcl/tk)

Hamish

12

On Sep 25, 2008, at 11:36 AM, Glynn Clements wrote:

Hamish wrote:

[stating my peace then dropping this to focus on far more ghastly UI issues]

Hamish wrote:

I've just added some logic in 6.x SVN to more nicely handle different
user interpretations of the commands. "accept sloppy input, create
tight output" and all that. Sure 'color=rules rules=filename' is
redundant, but the intention is obvious. some people (especially those
unfamiliar) like to tick every box. if it doesn't hurt anything, let
'em.

Glynn:

Reverted.

If input is invalid, you report that it's invalid, not silently do
what you *think* that the user meant (i.e. DWIM).

I accept the general point, but in this case can you offer an
alternative intent for 'color=rules rules=filename'?

I find "invalid" a bit strong in this case, but agree that if the user
misinterprets something then it is our task to make the instructions
clearer.

Well, if the user specifies 'color=rules rules=filename', the error
message is:

  ERROR: "color", "rules", and "raster" options are mutually exclusive

From that, it should be clear that the user has to choose between

color= and rules=. The option descriptions:

  rules Path to rules file
  color Type of color table

should make it clear that rules= is the correct choice for reading
rules from a file.

Also, the additon of "from stdin" to the text for color=rules:

  create new color table based on user-specified rules read from stdin

should make it clear that this isn't what they want if they are
reading rules from a file.

If the user misunderstands something, you should educate them, not
reinforce the misconception.

In cases where it is obvious what they meant, my view would be to
focus on the goal and let a minor misappreciation for the underlying
design pass.

trying to get into the head of a new user for a minute:

Gary the Grass user is presented with the r.colors GUI.
He starts filling in options from the top down. As a beginner he can
only guess what to put for each option. For "color=" he gets a drop
down menu, the top entry being blank and the bottom being rules. ummm...
The next is for "rules=" filename. That makes sense and he uses that.
But what to put for the colors= option now? Being slightly unsure of
himself with this new complex software, and wanting to make doubly sure
that the rules= option is used, and lacking the experience to follow
the subtle logic, the points the colors= option at what he thinks is
for rules=. That gives an error not to use the colors= option. But then
he thinks that he *did* give the neutral answer to color=, and what to
set it to now? (blank may be far from obvious)

this is almost exactly what happened in our class today - I told the students
to use predefined color rules table that was provided in a text file,
so you give an input raster map and then you are asked to provide
"Type of color table"
so logically you select "rules"
and then you provide path to the rules table and Run
and you get the error message that they are exclusive

Replacing "Type of color table" with "Select a predefined color table"
or something like that would make it clearer that this is an alternative to
the rules file not a parameter indicating that rules file will be used.

And I can confirm that when you go back to try to fix it - blank indeed
is not obvious at all - it looks like you always have to select from the list
something.

If a user thinks that they should fill in as many options as possible,
that's a fundamental misconception that should be corrected sooner
rather than later.

changing the wording may help. I am not sure that one would have to go as
far as say - "Select only one option from the three provided below"
I guess GRASS users are pretty smart and don't need that level
of guidance,

Helena

I've just noticed that the wxPython dialogs don't indicate whether an
option is required or optional, while the Tcl/Tk dialogs note this for
each option.

Really, if a user just selects options based upon instinct, they're
likely to run into more substantial problems sooner rather than later.

-rules: create new color table based on user-specified rules
+rules: create new color table based on user-specified rules read from stdin

I reverted that as it is somewhat misleading. It can mean either read
directly from stdin or if no stream is waiting then to enter into the
interactive environment.

Huh? It always means "read from stdin". If stdin is a tty, you get the
interactive prompts; if it's a file or pipe, you don't.

Well technically, yes, but I feel that we're splitting hairs here.
To the same newly recruited user, what is a stdin and where can I go to
buy one? -----Do those extra words contribute to the clarity of meaning?

Absolutely. Otherwise, it's stating that the option uses
user-specified rules read from ... who knows where?

For someone as new as "Gary", would they even know that they need to
put the rules into a file? Or what format those rules should be in?

Or would they just see "based on user-specified rules" and expect it
to pop up a window into which they can enter rules? If they do,
they're in for shock, as the GUI waits for r.colors, which is waiting
for something to be fed to its stdin.

By the point that they are entering a valid sequence of colour rules
into a text file, they probably know that they will need to use rules=
to use it. Otherwise, why would they be creating that file in the
first place? What are they planning to do with it once it has been
created?

--
Glynn Clements <glynn@gclements.plus.com>
_______________________________________________
grass-dev mailing list
grass-dev@lists.osgeo.org
http://lists.osgeo.org/mailman/listinfo/grass-dev