How to read/interpret plotnine documentation

Question

As the saying goes, "Give a person a fish, and they won't be hungry for a day. Teach them how to fish, and they won't be hungry for a lifetime."

I cannot, for the life of me, interpret the plotnine documentation. This is not at all a criticism of the fine people who have developed the package - I really love the package which is why I am trying to get better, and I am truly indebted to them.

But I cannot understand how to implement the documentation into my work. I have to spend ages googling someone who has a working example using the feature I want to implement, which can be extremely time consuming.

Take, for example, the task of inserting an arrow into the below plot.

The documentation is here:

https://plotnine.readthedocs.io/en/stable/generated/plotnine.geoms.arrow.html

plotnine.geoms.arrow(angle=30, length=0.2, ends='last', type='open')

I tried the following combinations:

p + geoms_arrow(angle=30, length=0.2, ends='last', type='open')
p + geom_arrow(angle=30, length=0.2, ends='last', type='open')
p + geoms.arrow(angle=30, length=0.2, ends='last', type='open')
p + geom.arrow(angle=30, length=0.2, ends='last', type='open')
p + geoms('arrow',angle=30, length=0.2, ends='last', type='open')
p + geom('arrow',angle=30, length=0.2, ends='last', type='open')
p + arrow(angle=30, length=0.2, ends='last', type='open')

Related to this, I also couldn't understand how to change the number of rows and columns in a legend. The documentation:

https://plotnine.readthedocs.io/en/stable/generated/plotnine.guides.guide_legend.html

plotnine.guides.guide_legend(**kwargs)

I tried various combinations of:

p + guides(guide_legend(nrow=1))

But couldn't get anything to work. The only example I could find that implemented guide_legend was this:

http://www.danielrothenberg.com/blog/2017/Jul/declarative-visualization-in-python-update/

Based on this I also tried:

+ guides(color=guide_legend(nrow=1))

I am now just trying random stuff, without any success.

How do you decipher the plotnine documentation to do the above 2 things (ie change the legend to 1 row and 6 columns in the below code, and insert an arrow head).

Note: I am really looking for an understand of how to read the documentation rather than just these two issues solved. This will help me with lots of other queries as well...

Some sample code:

import pandas as pd
from plotnine import *

df = pd.DataFrame({})
df['cat1'] = ('1A', '1A', '1A', '1A', '1A', '1A', '1B', '1B', '1B', '1B', '1B', '1B', '1C', '1C', '1C', '1C', '1C', '1C')
df['cat2'] = ('2A', '2B', '2C', '2D', '2E', '2F', '2A', '2B', '2C', '2D', '2E', '2F', '2A', '2B', '2C', '2D', '2E', '2F')
df['value'] = (0.8965, 0.0579, 0.0250, 0.0119, 0.0060, 0.0027, 0.7645, 0.0989, 0.0456, 0.0319, 0.0268, 0.0322, 0.5889, 0.0947, 0.0819, 0.0772, 0.0707, 0.0866)

p = (ggplot(df, aes(x='cat1', y='value', fill='cat2'))
  + theme_light(8)
  + geom_bar(stat='identity',width=0.8, position='dodge', alpha=0.80)
  + theme(
        legend_direction='horizontal',
        legend_position='bottom',
  )
  + guides(guide_legend(nrow=1))
)
p

Answer 1

You missed an important part in the help page:

This is used to define arrow heads for geom_path.

Not very sure how you will use this in your plot because x is a factor, so I show an example below how the arrow works. You can also check the help page for geom_path:

da = pd.DataFrame({'x':[1,2,3],'y':[4,5,6]})
p = (ggplot(da, aes(x='x', y='y'))
  + geom_path(arrow = arrow(angle=30, length=0.2, ends='last', type='open'))
)
p

For legend, you need to specify which legend you want to modify, and in your case it is:

p = (ggplot(df, aes(x='cat1', y='value', fill='cat2'))
  + theme_light(8)
  + geom_bar(stat='identity',width=0.8, position='dodge', alpha=0.80)
  + theme(
        legend_direction='horizontal',
        legend_position='bottom',
  )
  + guides(fill=guide_legend(nrow=1))
)