h parameter documented as "height" rather than "density smoothing"

[pierre-haessig]

I'm just reporting that as a fresh user of vioplot, I initially got confused by the way the h parameter of vioplot() is documented.

I was looking for the density bandwith tuning argument, but the doc says h is the "the height for the density estimator, if omit as explained in sm.density, h will be set to an optimum". I interpreted this as a tuning for the height of the density plot (which is in fact the width when the violin is drawn vertically), but this happens to be tuned by wec (however, to add to the confusion, the code of vioplot then computes in internal variable "hscale" based on wec...).

My proposition is to use a documentation of the h parameter based on the doc of sm.density ("a vector of length one, two or three, defining the smoothing parameter. A normal kernel function is used and h is its standard deviation. If this parameter is omitted, a normal optimal smoothing parameter is used."). The important keywords to appear for me are "density smoothing parameter".

References

Places where "height" is used:
https://github.com/TomKellyGenetics/vioplot/blob/master/R/vioplot.R#L15
https://github.com/TomKellyGenetics/vioplot/blob/master/man/vioplot.Rd#L181

Doc of vioplot (0.3.7):
https://www.rdocumentation.org/packages/vioplot/versions/0.3.7/topics/vioplot

Doc of sm.density:
https://www.rdocumentation.org/packages/sm/versions/2.2-5.4/topics/sm.density

[TomKellyGenetics]

This parameter is passed directly to the sm dependency so please defer to this version for accurate information. I'll considering updating vioplot documentation to reflect this.

[pierre-haessig]

Thanks for the update.

If I understand the changes correctly, there is now a concatenation of the initial parameter documentation (h is "the height for the density estimator") and the doc from sm.density (which mention smoothing). This certainly clarifies things, although my idea would have been to remove the word "height" entirely because I find it confusing.