DOC: explain non-linear scales and imshow (closes #7661) #7800

Merged
merged 4 commits into from Jan 16, 2017

Projects

None yet

7 participants

@phobson
Member
phobson commented Jan 11, 2017 edited

No description provided.

@afvincent

I am not very used to RST language, but from what I read here, I guess the whole literal block (meaning even the even the if 1: line) should be indented to be correctly rendered. Personally, I would simply remove if 1: line as the example is short and clean, but maybe it is a matter of personal taste :).

doc/users/whats_new/imshow_logscales.rst
+Log-scale on image plots
+------------------------
+
+:func:`imshow` not properly displays data on log-scales.
@afvincent
afvincent Jan 11, 2017 Contributor

not <- now?

@phobson
phobson Jan 11, 2017 edited Member

You're right on both accounts (the if 1: trick is there so can I be lazy when copy/pasting into jupyter -- oops)

@codecov-io
codecov-io commented Jan 11, 2017 edited

Current coverage is 62.10% (diff: 100%)

Merging #7800 into master will decrease coverage by 0.01%

@@             master      #7800   diff @@
==========================================
  Files           174        174          
  Lines         56028      56051    +23   
  Methods           0          0          
  Messages          0          0          
  Branches          0          0          
==========================================
+ Hits          34803      34810     +7   
- Misses        21225      21241    +16   
  Partials          0          0          

Powered by Codecov. Last update c676432...68230b2

@phobson
Member
phobson commented Jan 11, 2017

Cleaned up based on comments from @afvincent and squashed/force-pushed

doc/users/whats_new/imshow_logscales.rst
@@ -0,0 +1,31 @@
+Log-scale on image plots
@anntzer
anntzer Jan 11, 2017 Contributor

"nonlinear scales"? (also applies to logit, etc. I guess)

doc/users/whats_new/imshow_logscales.rst
+Log-scale on image plots
+------------------------
+
+:func:`imshow` now properly displays data on log-scales.
@anntzer
anntzer Jan 11, 2017 Contributor

"Properly" and "correct" below don't really help describing the behavior. Something like "draws values at the requested points in data space after application of the scale"?

@phobson phobson changed the title from DOC: explain logscales and imshow (closes #7661) to DOC: explain non-linear scales and imshow (closes #7661) Jan 11, 2017
@phobson phobson DOC: explain logscales and imshow (closes #7661)
82c4aab
@anntzer
Contributor
anntzer commented Jan 11, 2017

Actually, this should probably go into the same subheader as http://matplotlib.org/devdocs/users/whats_new.html#improved-image-support.

@phobson
Member
phobson commented Jan 11, 2017

@anntzer great point

@phobson phobson closed this Jan 11, 2017
@phobson phobson reopened this Jan 11, 2017
@efiring
Member
efiring commented Jan 11, 2017

I'm concerned about this because I think that using imshow for anything other than linear scales is a terrible idea, confusing in the extreme. At this stage we should strongly discourage it in the documentation, and a real improvement would be to block it in later releases after the usual warning period.

Try changing the example to:

ax1.imshow(data, origin='bottom', aspect="auto", extent=(5, 0, 1e5, 1e0), interpolation='nearest')

and see if you think people will be happy with it, and will understand what it is doing without a long bout of head-scratching.
imshow simply doesn't have the right interface for anything other than normal, simple images. Even the existing extent kwarg is a pain--it gives no clue as to which of the many possible sets and permutations of 4 numbers it needs.

@efiring
Member
efiring commented Jan 11, 2017 edited

Specific advice for the present PR: state that the behavior of imshow with other than linear axes has changed, but it remains undefined and should not be used. And I would omit the plots.

@tacaswell
Member

@efiring I disagree about not using imshow on non-linear axes. If you have evenly spaced bins it is a more efficient way than using pcolormesh to get the same effect.

Agree extent could be clearer.

@efiring
Member
efiring commented Jan 11, 2017

@tacaswell, are you volunteering to explain to puzzled users why the result of the example change that I gave above looks the way it does? And why this is an acceptable API? We can do this right, but imshow doesn't do so, by design. What do we lose by my suggestion of acknowledging that imshow was never designed for log scales, and now, by accident, happens to do what one might want, sometimes, with the right combination of obscure arguments? I think this acknowledgement would be doing users a favor.

@tacaswell
Member

The issue with flipping extent around like that seems to be more about bottom and non-increasing values in extent being confusing as it is just as puzzilng in linear scale as with log.

import numpy as np
import matplotlib.pyplot as plt

data = np.arange(30).reshape(5, 6)
x = np.linspace(0, 6, 7)
y = 10**np.linspace(0, 5, 6)
X, Y = np.meshgrid(x, y)

fig, (ax1, ax2) = plt.subplots(ncols=2, figsize=(8, 4))

ax1.imshow(data, origin='bottom', aspect="auto", extent=(6, 0, 1e5, 1e0),
           interpolation='nearest')



ax2.imshow(data, origin='bottom', aspect="auto", extent=(6, 0, 1e5, 1e0),
           interpolation='nearest')
ax2.set_yscale('log')

plt.show()

so

@efiring
Member
efiring commented Jan 11, 2017

The log scale adds another dimension to the confusion, as illustrated by the fact that this discussion started when a user had been relying on the old behavior and considered that to be correct.

doc/users/whats_new/imshow_logscales.rst
+
+ fig, (ax1, ax2) = plt.subplots(ncols=2, figsize=(8, 4))
+
+ ax1.imshow(data, aspect="auto", extent=(0, 5, 1e0, 1e5), interpolation='nearest')
@tacaswell
tacaswell Jan 11, 2017 Member

the 5 should be a 6

@tacaswell
Member

And the gap on the right is dependent on figure size...

@tacaswell
Member
tacaswell commented Jan 11, 2017 edited

In my personal use I have used imshow almost exclusively for data extracted from imaging detectors where the pixel value is a measure of how many photons hit that pixel (ie, a 2D histogram). The pixel edges moving with the scale seems very natural to me.

For example

import numpy as np
import matplotlib.pyplot as plt

data = np.arange(30).reshape(5, 6)
x = np.linspace(0, 6, 7)
y = 10**np.linspace(0, 5, 6)
X, Y = np.meshgrid(x, y)

fig, (ax1, ax2) = plt.subplots(ncols=2, figsize=(8, 4))
ax1.hist(np.random.rand(5000)*50000, bins=10, edgecolor='k')
ax2.hist(np.random.rand(5000)*50000, bins=10, edgecolor='k')
ax2.set_xscale('log')

plt.show()

so

which although it seems to expose yet another bug in log handling, seems very natural. As does

import numpy as np
import matplotlib.pyplot as plt

data = np.arange(30).reshape(5, 6)
x = np.linspace(0, 6, 7)
y = 10**np.linspace(0, 5, 6)
X, Y = np.meshgrid(x, y)

fig, (ax1, ax2) = plt.subplots(ncols=2, figsize=(8, 4))
ax1.hist(np.random.rand(5000)*100000, bins=np.logspace(0, 5, 10), edgecolor='k')
ax2.hist(np.random.rand(5000)*100000, bins=np.logspace(0, 5, 10), edgecolor='k')
ax2.set_xscale('log')

plt.show()

so

@tacaswell tacaswell DOC: tweak example + add some extra prose
68230b2
doc/users/whats_new/imshow_logscales.rst
+
+
+This can be understood by analogy to plotting a histogram with linearly spaced bins
+with a logarithmic x-axis. Equal sized bins at will be displayed as wider for small
@NelleV
NelleV Jan 16, 2017 Contributor

I don't understand this sentence "Equal sized bins at will be displayed …"

phobson added some commits Jan 16, 2017
@phobson phobson DOC: fix minor typos in img-show logscale blurb ab978b8
@phobson phobson DOC: add non-linear scales blurb to main whats-new
a9530f6
@efiring efiring merged commit 54b120f into matplotlib:master Jan 16, 2017

0 of 2 checks passed

continuous-integration/appveyor/pr Waiting for AppVeyor build to complete
Details
continuous-integration/travis-ci/pr The Travis CI build is in progress
Details
@tacaswell
Member

@efiring you mind if I do the backport of this? I have it ready to push, but don't want mess you up if you are doing it.

@tacaswell
Member

backported to v2.x as cfafd3d

@phobson phobson deleted the phobson:doc-imshow-logscale branch Jan 23, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment