r-lib/scales

`trans_new()`'s `breaks` docs are confusing and inconsistent

Closed this issue · 0 comments

I have a few issues with the trans_new() docs:


The breaks parameter is documented as "applied to the raw data"

https://github.com/r-lib/scales/blob/b3df2fb6efd5b440377b0699d3830f1082fa3140/R/trans.r#L15C7-L16

but the description paragraph seems to imply that the function will be called on the transformed data

scales/R/trans.r

Lines 4 to 5 in b3df2fb

#' as the information needed to create pleasing breaks and labels. The breaks
#' function is applied on the transformed range of the range, and it's

In practice this seems to be called on the original data, before any transformation has been made, and is expected to return data in the original units as well.


The description paragraph references a "labels function" but that isn't an argument to trans_new().

scales/R/trans.r

Lines 5 to 8 in b3df2fb

#' function is applied on the transformed range of the range, and it's
#' expected that the labels function will perform some kind of inverse
#' transformation on these breaks to give them labels that are meaningful on
#' the original scale.

I assume this is actually a reference to format? That is also confusing because format actually gets the breaks in the original data units, not the transformed units, as is being implied by the docs here


In general, I find that saying "raw data" on this help page is rather confusing. It seems like "raw data" means the original data units, but in my head I think that the transformed units are more "raw" because they are often a bare integer or double vector (and the original units are a richer type like a date vector). Can we say "original" or "pre-transformed" or something else?