[R] Surprise when mapping matrix to image

[Richard A. O'Keefe]

Deepayan Sarkar <deepayan at cs.wisc.edu> wrote:
	You seem to be thinking that Prof Ripley's solution had
	something to do with image().

"Glynn, Earl" <EFG at Stowers-Institute.org>
could certainly be excused for thinking so, because
what Prof Ripley wrote included this:

	> > Did you try reading the help for image?  You don't seem to 
	> > understand it if you actually did.

That certainly sounds to me as though the answer should have been
obvious from ?image

Now, the image() function is trying to be extremely helpful and offers
you lots of ways of providing the data, and that is explained in ?image.

In fact a key piece of information *IS* in ?image, so it really DOES
have something to do with image():

    Details:

     The length of 'x' should be equal to the 'nrow(z)+1' or 'nrow(z)'.
     In the first case 'x' specifies the boundaries between the cells:
     in the second case 'x' specifies the midpoints of the cells. 

This tells us that the "x" direction of the image goes along the *rows*
of the matrix and by implication that the "y" direction goes along the
*columns* of the matrix, and is precisely what you need to figure out
that image(t(x)) is the thing to use.

One does have to be a little subtle at reading between the lines to see
the relevance of details about a parameter one is not passing, but the
information _is_ there and it _is_ 'something to do with image()', not
something to do with matrices.

The 'volcano' example from ?image also points the same way.

The basic problem here is that the standard visual layout of
matrices sets up such a strong expectation that it's difficult for
any text to override it.

I don't see anything that explicitly discusses the direction of the
axes, I don't see anything explicit, but I took it that ?image would
follow the usual "horizontal axis increases from left to right,
vertical axis increases from bottom to top" convention, which means
"horizontal gives ROW number increasing left to right,
 vertical gives COLUMN number increasing bottom to top"
so when I do image(t(x)) I see my columns as vertical strips but
they are "upside down", so the last step, to
    image(t(x)[ncol(x):1,])
does make sense, provided you read ?image as *implying* without actually
stating "follows the usual graphical conventions for axes".  But again,
this really is a fact about image(), not about matrices.

As for the claim that
	It doesn't, it has to do with manipulating a matrix. image()
	visualizes a matrix in a particular and well-defined way.

Well yes, it is a particular way, and I suppose you could say that the
code is defined well, but it really isn't, when you get right down to
it, and *EXPLICITLY* documented way.  You really have to work at it.

This is NOT a criticism of R documentation.  Of all the open-source
programs I use, I reckon R is by far the best documented, and its
on-line documentation can more than withstand comparison against most
of the commercial programs I've seen.  The real problem is that R is
just so big and there are only so many people writing documentation for
it.

Given the wide range of ways that the x, y, z arguments can be passed
to image(), it would actually make sense to have some kind of flip and/or
mirror operations specified via an argument to image().
The source code of image is available (image.default) so it wouldn't be
a lot of work for someone who wants it to produce such a thing.