Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Add an arrow tutorial #11223

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 4 commits into from
May 30, 2018
Merged

Add an arrow tutorial #11223

merged 4 commits into from
May 30, 2018

Conversation

dstansby
Copy link
Member

Fixes #11219

This is quite short, but I think illustrates how to plot arrows with various display/data space options. All suggestions and comments welcome!

@jklymak jklymak self-requested a review May 10, 2018 16:30
@ImportanceOfBeingErnest
Copy link
Member

I think this rather qualifies as example than as tutorial?

There is also already the annotation_demo example and the annotations tutorial. So I wonder in how far they are overlapping or not. Independent of that, there should be links in between them.

@ImportanceOfBeingErnest
Copy link
Member

Or, if this is to be the "definitive arrow guide" as a tutorial, the following things should be considered:

  • what is the relation between ax.arrow, ax.annotate, ax.quiver, mpatches.FancyArrowPatch?
  • Any user looking at the patches doc would directly ask: "What is the difference between Arrow, FancyArrow, FancyArrowPatch and YAArrow?" A tutorial might want to answer this.
  • The problem when drawing arrows is mostly to understand all the different parameters. Common questions could be
    • How to make the head larger?
    • What are the units of head_length, head_width, tail_width, mutation_scale, etc.?
    • Why is my arrow shorter than the distance between the two points I specified?
    • Why can't I use an FancyArrowPatch in a collection? What's the alternative? (should be checked when deprecating other arrows)
    • How do I draw an arrow with a dotted tail?
    • When should I use a ConnectionPatch instead of a FancyArrowPatch?

jklymak
jklymak reviewed May 14, 2018
View reviewed changes
tutorials/intermediate/arrow_guide.py Outdated
Here we show three use cases for plotting arrows, depending on whether the
head or anchor points need to be fixed in data or display space:

1. Head fixed in display space, anchor points fixed in data space
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Head shape" would be better than just "head" because the head anchor does move around so I found this confusing.

tutorials/intermediate/arrow_guide.py Outdated

1. Head fixed in display space, anchor points fixed in data space
2. Head and anchor points fixed in display space
3. Head and anchor points fixed in data space
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd say arrow patch defined in purely in data space. This is really radically different than the others...

tutorials/intermediate/arrow_guide.py Outdated
Arrow guide
===========

Adding arrows to plots Matplotlib.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, this is really adding Arrow patches to matplotlib.

tutorials/intermediate/arrow_guide.py Outdated

Arrows consist of a head (and possibly a tail) and a stem drawn between a
start point and and end point, called 'anchor points' from now on.
Here we show three use cases for plotting arrows, depending on whether the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest adding: Usually we want the head shape to be drawn in physical space and not scale as the figure or axes limits change analgous to how text annotations don't change size. Conversely, we often want the anchor points to move either with the data limits of the axes, or be at a position relative to the axes or figure bounds.

... or something more eloquent but explaining why arrows are a hard shape to just draw...

tutorials/intermediate/arrow_guide.py Outdated


###############################################################################
# Head fixed in display space and anchor points fixed in data space
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Head shape

tutorials/intermediate/arrow_guide.py Outdated
axs[1].set_ylim(0, 2)

###############################################################################
# Head and anchor points fixed in display space
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Head Shape

tutorials/intermediate/arrow_guide.py Outdated


###############################################################################
# Head and anchor points fixed in data space
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Head shape and anchor points drawn in data space...

tutorials/intermediate/arrow_guide.py Outdated
#
# In this case we use `.patches.Arrow`
#
# Note that when the axis limits are changed, the arrow shape and location
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Umm, I'd have something in here about why we would ever want to do this....

@jklymak
Copy link
Member

jklymak commented May 14, 2018

I agree there is lots more that could go in here, but for now its an improvement. I do think a link to the Annotations demo and tutorial would be nice. But adding an arrow and an annotation are different, and I for one appreciate adding just the arrow documention.

@dstansby
Copy link
Member Author

Thanks for the feedback! I agree that as this stands it's more like an example, so I've put it in examples. I don't have time to expand this at the moment, but I think is an improvement as is that is worth going in.

All of your suggestions for expanding this are great @ImportanceOfBeingErnest ; maybe it would be best to put them in a new issue that someone could work on in the future?

@jklymak
Copy link
Member

jklymak commented May 30, 2018

Pushed an underline change to your PR.... I'll merge this once it passes. Indeed it doesn't cover everything, but is a good start/placeholder for further efforts.

@jklymak jklymak merged commit 50b0e16 into matplotlib:master May 30, 2018
@jklymak
Copy link
Member

jklymak commented May 30, 2018

Thanks @dstansby

Other folks - more than welcome to open new PRs with additional tutorial material!

@QuLogic QuLogic added this to the v3.0 milestone May 31, 2018
@dstansby dstansby deleted the arrow-tutorial branch May 31, 2018 09:04
@ImportanceOfBeingErnest ImportanceOfBeingErnest mentioned this pull request May 31, 2018
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@jklymak jklymak jklymak left review comments

Assignees
No one assigned
Labels
Documentation
Projects
None yet
Milestone
v3.0.0
Development

Successfully merging this pull request may close these issues.
4 participants
@dstansby @ImportanceOfBeingErnest @jklymak @QuLogic