Key elements of the shift plot is not documented

[isaacto]

There are a few things in the documentation of plot_shift that is lacking:

• The X axis of the scatter plot is hard-coded to "score (a.u.)", but what that means is a mystery.
• The scatter plot has lines connecting the X and the Y deciles, with color which I can tell only by reading the source code.
• The Y axis of the plot of the shift function also has the "(a. u.)" with unknown meaning.
• It might be a good idea to have a sentence about or doc link to the matplotlib violinplot, for those who don't know about it before.

It is also not immediately clear from the examples in the documentation what is the effect of the "show_median" option, perhaps because a percentile line is right on top of it.

[raphaelvallat]

Hi @isaacto,

Thanks for opening the issue. Yeah I agree that the documentation of this function could be improved. In fact, this is an old function of Pingouin that has not had the same levels of testing that some other functions had, and I was almost tempted to gradually deprecate it in the next versions of Pingouin. It is not clear to me what percent of Pingouin's users actually use this function (I never use it).

If we decide to keep it, then yes, we should clarify the documentation / output. Related, please note that a.u. stands for "arbitrary units"

Thanks,
Raphael

[isaacto]

Thanks for the information. I didn't know about split plots before, so pingouin actually taught me that (and in fact many other ideas... before I was using T-test for everything...). I think it would be useful, but of course I'm open to anything equally or even more useful to replace it.

On the other hand, I'm thinking about creating a few routines (or perhaps a public module) to do the plotting myself, using holoviews (using matplotlib to produce a figure in a fully bokeh-backed website looks somewhat odd). So the computed data may turn out to be more important than the plot itself for me.