taup: added a time plot -- analogue to the existing ray path plot #1877

kaspervanwijk · 2017-09-06T23:48:44Z

What does this PR do?

create a method on the arrivals object for a travel time plot, analogue to the ray path plot method. It replaces the old (and removed travelTimePlot function, see https://docs.obspy.org/archive/1.0.3/tutorial/code_snippets/travel_time.html#travel-time-plot)

Why was it initiated? Any relevant Issues?

Fixes #1501, fixes #1330

PR Checklist

This PR is not directly related to an existing issue (which has no PR yet).
All tests still pass.
Any new features or fixed regressions are be covered via new tests.
Any new or changed features have are fully documented.
Significant changes have been added to CHANGELOG.txt .
First time contributors have added your name to CONTRIBUTORS.txt .

Todos

add convenience wrapper function
add example usage to convenience wrapper function docstring (with example plot)
add image test
add example plot to gallery

import numpy as np
import matplotlib.pyplot as plt
from obspy.taup import TauPyModel

# set the velocity model you want to use:
model = TauPyModel(model='iasp91')

# set epicentral distances, the phases you want, and a source depth:
DISTANCES=range(0,100,1)
PHASES = ['S','P']
sourcedepth=5

plt.figure(figsize=(10, 10))
ax = plt.subplot(111)

# plot arrival times for all arrivals in arrivals object:
for distance in DISTANCES:
    arrivals = model.get_ray_paths(sourcedepth, distance, phase_list=PHASES)
    if not len(arrivals):
        print('No arrival time for:', PHASES, distance)
        continue
    arrivals.timeplot(PHASES,show=False,ax=ax)
ax.set_xlim(DISTANCES[0],DISTANCES[-1])
plt.show()

…up calculations

megies · 2017-09-07T08:43:37Z

@kaspervanwijk Can you post an example image?

megies · 2017-09-07T08:46:20Z

obspy/taup/tau.py

+
+        :returns: The (possibly created) axes instance.
+        :rtype: :class:`matplotlib.axes.Axes`
+
        """


Please reformat docstring to (to be in line with rest of codebase):

""" Method to plot the travel times of arrivals class, if any have been calculated. :param ax: Axes to plot to. If not given, a new figure with an axes will be created. Must be a polar axes for the spherical plot and a regular one for the Cartesian plot. :type ax: :class:`matplotlib.axes.Axes` :param show: Show the plot. :type show: bool :returns: The (possibly created) axes instance. :rtype: :class:`matplotlib.axes.Axes` """

Oh and phases is missing in docstring..

kaspervanwijk · 2017-09-07T09:03:48Z

The output of the example test code with this is:

megies · 2017-09-07T09:18:40Z

Ah OK, so this is basically a replacement for the old plot that is not working in master anymore?

https://docs.obspy.org/tutorial/code_snippets/travel_time.html#travel-time-plot

kaspervanwijk · 2017-09-07T09:22:22Z

That's right. A replacement (hopefully; this is my first attempt at a PR), but the same way the ray paths are currently plotted: as a method on "arrivals."

megies · 2017-09-07T09:28:33Z

This will be a really nice PR! Thanks already!

Having this as a method on arrivals is very nice API-wise, but I think also a convenience wrapper function for the whole process would also be a real handy addition. Something like this..

def traveltime_plot(source_depth, phases=['P', 'S'], model='iasp91',
                    distance_range=(0, 180)):
    ...

I'll add some todos in the OP.

Let us know if you need help setting up the image test or adding the plot to the gallery.

…ch the convention in obspy.

megies · 2017-09-07T09:45:57Z

For distances over 180 degrees, this could optionally be done in the plot doing a wraparound like here: in "Jeffreys/Bullen style" but it might be a bit tricky to get the duplicated x-axis labels right..

kaspervanwijk · 2017-09-07T10:00:15Z

Could make the wrapper function you mention, but that would be very similar to the old way (except it would not call deprecated code, but properly use TauPyModel.get_travel_times(). Would you want both the method and the wrapper function?

As is, the plot handles >180 correctly, I believe.

(Yes, I will need some tips on how to do an image test and gallery add)

megies · 2017-09-07T10:13:20Z

Would you want both the method and the wrapper function?

Yes, I would implement both. For the user it's much more convenient to just have a single function call rather than use the above code snippet. But having the logic as a method with Arrivals is also very nice API-logic-wise.

megies · 2017-09-08T07:43:20Z

Requesting a docs build for this PR, so that we can check the example plot: +DOCS

megies · 2017-09-08T07:48:42Z

obspy/taup/tau.py

+
+
+def traveltime_plot(min_degree=0, max_degree=360, npoints=1000,
+                    phases=['P', 'S'], source_depth=10, model='iasp91',


I would vote for making source_depth an argument, not a kwarg with default value, such that people have to explicitly set their source depth of choice. Otherwise people might overlook it's importance for the output and I feel like there's no generally useful default value for it.

megies · 2017-09-08T07:50:51Z

obspy/taup/tau.py

+
+        :param min_degree: minimum distance from the source (in degrees) to 
+            plot travel times Defaults to ``0``.
+        :type min_degree: float, optional


I think we nowadays usually leave away the , optional part (I know we still have it in older parts of the docs).

It's just plain redundant to add it for just every kwarg out there and only clutters the docs, IMHO.

megies · 2017-09-08T07:51:54Z

obspy/taup/tau.py

+        :param source_depth: Source pepth in kilometers. Defaults to ``10``.
+        :type source_depth: float, optional
+        :param model: string containing the model to use.
+        :type model: str. Defaults to 'iasp91'


The default value should be mentioned in the :param ..: section below, I think, rather than the :type : section

megies · 2017-09-08T07:53:32Z

obspy/taup/tau.py

+
+        .. rubric:: Example
+
+        >>> from obspy.taup.tau import traveltime_plot


This plot will be very useful, I'd vote to add it's import to obspy/taup/__init__.py so that it can be imported as from obspy.taup import traveltime_plot. Accordingly then all examples should also use that shorter import notation.

megies · 2017-09-08T08:10:16Z

This is looking real nice already. :-)

To add it to the gallery, just replace the old example that's still in there (broken of course). I.e. adapt obspy/misc/docs/source/tutorial/code_snippets/travel_time_plot.py and obspy/misc/docs/source/tutorial/code_snippets/travel_time_plot.rst and also adapt it in obspy/misc/docs/source/gallery.rst (line 141).

For the image test, just copy/paste/adapt one of the test routines in obspy/obspy/taup/tests/test_plotting.py. You can then run $ obspy-runtests taup --keep-images (or alternatively $ OBSPY_KEEP_IMAGES= python taup/tests/test_plotting.py if you want to omit the other taup tests) and move the newly created image in obspy/obspy/taup/tests/images/testrun up one directory to drop it in as the base line image. If I'm not mistaken, base line images are still based on matplotlib 1.3.1.. (@krischer, @QuLogic, that right?), so that's the version you should use when creating the base line image.

megies · 2017-09-08T08:18:39Z

Btw.. If you want to see what flake8 thinks of your commits right when doing them, you could set up a local git hook, see first paragraph on this page: https://docs.obspy.org/master/coding_style.html#obspy-coding-style-guide

It's really useful.

megies · 2017-09-08T08:51:23Z

Docs build for the PR is up (will be automatically updated on new commits): http://docs.obspy.org/pull-requests/1877/packages/obspy.taup.html#module-obspy.taup

Example plot's not working..: http://docs.obspy.org/pull-requests/1877/packages/autogen/obspy.taup.tau.traveltime_plot.html#obspy.taup.tau.traveltime_plot

See http://docs.obspy.org/pull-requests/1877/log.txt, searching for traveltime_plot:

/private-backup/home/obspy/update-docs-pr/src/obspy/obspy/taup/tau.py:docstring of obspy.taup.tau.traveltime_plot:36: WARNING: Exception occurred in plotting obspy-taup-tau-traveltime_plot-1
 from /private-backup/home/obspy/update-docs-pr/src/obspy/misc/docs/source/packages/autogen/obspy.taup.tau.traveltime_plot.rst:
Traceback (most recent call last):
  File "/home/obspy/anaconda3/envs/tmp_build_docs-pr/lib/python3.4/site-packages/matplotlib/sphinxext/plot_directive.py", line 517, in run_code
    six.exec_(code, ns)
  File "<string>", line 2, in <module>
NameError: name 'travetime_plot' is not defined

Can you also add a short paragraph with plot to the taup landing page (i.e. taup/__init__.py docstring)?

testing

indentation

megies · 2017-10-06T13:16:56Z

@kaspervanwijk I just pushed some changes, would be good if you breifly check them. I'll start rebasing intermediate images out of this now and will then force-push over this branch. For reference, current tip is at 0a0b8ac.

kaspervanwijk · 2017-10-06T20:56:22Z

thank you, @megies, your edits are all improvements. I agree with making the default number of travel times to calculate a smaller number to speed up the code, but hope we can keep a nice dense graph in the gallery.

megies · 2017-10-07T06:48:54Z

hope we can keep a nice dense graph in the gallery.

fair enough, i'll crank it up

plot type (Spherical/cartesian)

this can be used in tests that should fail and then might attempt to upload images which takes several seconds and is totally unwanted in this case

…mits also sanitize ax/fig kwarg handling in one routine

megies

I think this can be merged. Travis is failing virtually every image test right now, and since this PR is coming from a fork the imgur uploads from Travis don't work unfortunately, because the imgur token in the secure env variable is not available for PRs from forks.

Anyway, good to merge, IMHO.

megies · 2017-10-09T08:18:07Z

Thanks a bunch @kaspervanwijk, great work on this PR!

megies · 2017-10-09T09:51:46Z

see 9bd3a80

kaspervanwijk added 5 commits September 7, 2017 11:38

added a time plot -- analogue to the existing ray path plot -- for ta…

6af9a64

…up calculations

fixed some style problems; mostly spaces.

6506ac2

fixed more style problems.

4faa0b8

one more style problem fixed.

46e5e58

Hopefully last style thing fixed!

faa6f7b

megies reviewed Sep 7, 2017

View reviewed changes

megies changed the title ~~added a time plot -- analogue to the existing ray path plot -- for ta…~~ taup: added a time plot -- analogue to the existing ray path plot Sep 7, 2017

megies added this to the 1.1.0 milestone Sep 7, 2017

megies added .imaging Issues with our plotting functionalities .taup enhancement feature request labels Sep 7, 2017

Added "phases" to the doc string, and formatted the doc string to mat…

02f5c27

…ch the convention in obspy.

kaspervanwijk added 2 commits September 8, 2017 14:04

Added a wrapper function traveltime_plot()

c1bc501

Fixed format stuff.

de26df2

megies reviewed Sep 8, 2017

View reviewed changes

megies added 5 commits October 6, 2017 15:15

taup plots: sanitize ax/fig if/else clauses

f872abb

replace some assert statements in unit tests with proper unittest

58f317a

testing

raise proper exception type, better exception message

5db7f1f

taup plots: add verbose=False and add/fix legend kwarg, also fix

ef5e58d

indentation

update taup plot tests

3efc10c

update all taup test base line images

27f14eb

megies force-pushed the timeplot branch from 0a0b8ac to 27f14eb Compare October 6, 2017 14:05

megies added 2 commits October 6, 2017 16:06

flake8

b849c90

taup: add some changes again that got lost during rebasing somehow

b9e5b96

megies force-pushed the timeplot branch from f1dffac to b9e5b96 Compare October 6, 2017 14:37

make taup travel time plot in tutorial denser (more points)

cc1d4d7

megies added 6 commits October 7, 2017 09:18

taup ray path plotting: warn if provided axes doesn't match the selected

a2fd7bd

plot type (Spherical/cartesian)

taup plots: add test for invalid plot type

d99183a

taup travel time plot: add image test for option plot_all=False

fb42ed8

taup travel time plot: add option plot_all to convenience function

ab62644

add new test base line image

f37f531

taup: better testing of option 'plot_all' in travel time plot

b9e2a94

megies force-pushed the timeplot branch from 09e7fed to c942ad4 Compare October 7, 2017 10:40

ImageComparison decorator: add option to deactivate imgur upload

0d82278

this can be used in tests that should fail and then might attempt to upload images which takes several seconds and is totally unwanted in this case

megies force-pushed the timeplot branch from c942ad4 to 0d82278 Compare October 7, 2017 10:48

taup plots: fix ax/fig setup that i garbled in one of the earlier com…

a477f7d

…mits also sanitize ax/fig kwarg handling in one routine

megies force-pushed the timeplot branch from 7dd5d21 to a477f7d Compare October 7, 2017 16:50

megies approved these changes Oct 8, 2017

View reviewed changes

megies merged commit aa91c19 into obspy:master Oct 9, 2017

paul-freeman mentioned this pull request Oct 12, 2017

Some docs building warnings/errors #1881

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

taup: added a time plot -- analogue to the existing ray path plot #1877

taup: added a time plot -- analogue to the existing ray path plot #1877

kaspervanwijk commented Sep 6, 2017 •

edited by megies

megies commented Sep 7, 2017

megies Sep 7, 2017 •

edited

kaspervanwijk commented Sep 7, 2017

megies commented Sep 7, 2017

kaspervanwijk commented Sep 7, 2017 •

edited

megies commented Sep 7, 2017 •

edited

megies commented Sep 7, 2017

kaspervanwijk commented Sep 7, 2017

megies commented Sep 7, 2017 •

edited

megies commented Sep 8, 2017 •

edited

megies Sep 8, 2017

megies Sep 8, 2017

megies Sep 8, 2017

megies Sep 8, 2017

megies commented Sep 8, 2017

megies commented Sep 8, 2017 •

edited

megies commented Sep 8, 2017

megies commented Oct 6, 2017

kaspervanwijk commented Oct 6, 2017

megies commented Oct 7, 2017

megies left a comment

megies commented Oct 9, 2017

megies commented Oct 9, 2017



		def traveltime_plot(min_degree=0, max_degree=360, npoints=1000,
		phases=['P', 'S'], source_depth=10, model='iasp91',


		.. rubric:: Example

		>>> from obspy.taup.tau import traveltime_plot

taup: added a time plot -- analogue to the existing ray path plot #1877

taup: added a time plot -- analogue to the existing ray path plot #1877

Conversation

kaspervanwijk commented Sep 6, 2017 • edited by megies

What does this PR do?

Why was it initiated? Any relevant Issues?

PR Checklist

Todos

megies commented Sep 7, 2017

megies Sep 7, 2017 • edited

Choose a reason for hiding this comment

kaspervanwijk commented Sep 7, 2017

megies commented Sep 7, 2017

kaspervanwijk commented Sep 7, 2017 • edited

megies commented Sep 7, 2017 • edited

megies commented Sep 7, 2017

kaspervanwijk commented Sep 7, 2017

megies commented Sep 7, 2017 • edited

megies commented Sep 8, 2017 • edited

megies Sep 8, 2017

Choose a reason for hiding this comment

megies Sep 8, 2017

Choose a reason for hiding this comment

megies Sep 8, 2017

Choose a reason for hiding this comment

megies Sep 8, 2017

Choose a reason for hiding this comment

megies commented Sep 8, 2017

megies commented Sep 8, 2017 • edited

megies commented Sep 8, 2017

megies commented Oct 6, 2017

kaspervanwijk commented Oct 6, 2017

megies commented Oct 7, 2017

megies left a comment

Choose a reason for hiding this comment

megies commented Oct 9, 2017

megies commented Oct 9, 2017

kaspervanwijk commented Sep 6, 2017 •

edited by megies

megies Sep 7, 2017 •

edited

kaspervanwijk commented Sep 7, 2017 •

edited

megies commented Sep 7, 2017 •

edited

megies commented Sep 7, 2017 •

edited

megies commented Sep 8, 2017 •

edited

megies commented Sep 8, 2017 •

edited