Remove the data_*() prefix from statistical transformation function names

[etiennebacher]

I also feel that we should remove the data_*() prefix from statistical transformation function names.

Originally posted by @IndrajeetPatil in #183 (comment)

Moved here, since it is not related to the vignette about equivalence with tidyverse

[IndrajeetPatil]

Specifically, here is what the function names look like right now:

Preparation

• data_filter()
• data_select()
• data_to_long()
• data_to_wide()
• data_rotate()
• data_rename()
• data_relocate()
• data_join()

Transformation:

• standardize()
• normalize()
• center()
• degroup()
• winsorize()
• data_cut()
• data_recode()
• data_shift()

And I am wondering if the following should lose their data_ prefix:

• data_cut()
• data_recode()
• data_shift()

[bwiernik]

The problem is cut() is in base and recode() is in dplyr. shift() is in data.table--that's probably less of a collision issue, but I imagine we probably have a fair number of data.table users

[bwiernik]

1. We could rename data_cut() to bin() (or cut() and ignore the masking considering it's a wrapper?)
2. Maybe rename data_recode() to remap() or change_code()? This one is tough to find a good alternative name--probably why recode() has stuck around as "questioning" in dplyr forever without the promised future replacement function.
3. We could rename data_shift() to translate() or baseline() (or shift() and ignore the masking with data.table--that one is probably fine?)

There are also:

• data_reverse() : change to just reverse() or reverse_scale()
• data_rescale() : change to just rescale()
• the various data_to_*() functions : change to just to_*()

All of these functions have methods for both vectors and data frames. Is it more confusing to be able to use a function without data_ with a data frame? Should we have separate versions of each function for vectors and data frames?

[etiennebacher]

How about:

1. data_cut -> categorize
2. ?
3. data_shift -> move

reverse_scale is already an alias for data_rescale.

I don't know which is better, removing data_ for these functions or not. I just want to say that I like having the prefix for the data prep functions, it's easy to see which functions are available with autocomplete. So if you want to remove data_ maybe it would be a good idea to replace it with another prefix for all data transformation functions. For example, having a prefix do_ would give the following:

• do_standardize()
• do_normalize()
• do_center()
• do_degroup()
• do_winsorize()
• do_recode()
• etc.

use_, make_ or apply_ could be other prefixes.

[mattansb]

cut > discretize?
recode > revalue?
shift > I like translate, or slide (like a slide ruler), or "add" 😅?

I think it's a good idea to have dedicated data_* functions for data frames. I've found that students don't often fully comprehend that difference classes have different methods for the same function. So having separate functions for dfs sounds good (or having aliases for the methods e.g. data_standardize <- standardize.data.frame).

[bwiernik]

I would prefer not to have prefixes for vector functions

[mattansb]

Same, that's what I mean - the data_ prefix would only be aliases for data frame methods:

#' @export
standardize <- function(x, ...) {
  UseMethod("standardize")
}

#' @export
#' @rdname standardize
standardize.numeric <- function(...) {
  ...
}

#' @export
#' @rdname standardize
standardize.data.frame <- function(...) {
  ...
}

#' @export
#' @rdname standardize
data_standardize <- standardize.data.frame

Or perhaps all the data_* functions can have their own doc together? ...

[bwiernik]

reverse_scale() is not exactly an alias. It has fewer arguments and is designed to provide a more intuitive function for using rescale() to reverse

[bwiernik]

I think I like the idea of documenting the data frame methods all together.

[bwiernik]

My votes:

1. cut -> categorize
2. recode -> relabel
3. shift -> slide
4. reverse -> reverse
5. rescale -> rescale
6. data_to_type -> to_type

(For 2, forcats::fct_relabel() is a different function that is rarely used AFAICT)

data_ prefixes only for data frame methods

[mattansb]

I second all of what @bwiernik says, except for relabel - from the docs recode is (also?) for chancing numeric values to other number values.

[DominiqueMakowski]

Whatever we decide for Wmwe should avoid having conflicts with base R at all cost

Why not having another alias for all these transfo functions like:

values_recode(), values_reverse() etc

so that data_ is meant primarily for dfs and values_ for vectors. It's a bit longer to type but autocompletion much

[mattansb]

yardstick has a convention where data frame function's gets the measure name, and vectors get a *_vec suffix.
I think we should have just one, and I think the data_* for dfs makes more sense.

[bwiernik]

of the available synonyms for "recode", "relabel" seemed the least objectionable. A conflict with dplyr is nearly as bad as a conflict with base IMO. I don't think that "relabel" precludes numeric values--the function changes the numeric labels used for different categories. And in contrast to rescale(), it does it through 1:1 mapping of values/labels, rather than a linear or other mathematical transformation

[strengejacke]

1. cut -> categorize

agree-

2. recode -> relabel

I prefer recode here (or put differently: I don't like "relabel"), because relabel sounds like changing value labels (I always have the association with labelled data)

3. shift -> slide

agree.

4. reverse -> reverse

agree.

5. rescale -> rescale

agree.

6. data_to_type -> to_type

agree.

[bwiernik]

We can't do recode() because of dplyr::recode(). What other options do we have?

[etiennebacher]

recode -> revalue? (cf @mattansb proposition)

[bwiernik]

That word means "reassess the worth of something"

[mattansb]

convert?

[bwiernik]

I think that suggests type conversion (numeric -> factor or character, etc.)

[bwiernik]

Perhaps change_code() is the best option?

[IndrajeetPatil]

The problem with change_code() is that it breaks the single work pattern for other transformation functions:

• data_cut() -> categorize()
• data_recode() -> ???
• data_shift() -> slide()
• data_reverse() -> reverse()
• data_rescale() -> rescale()

But I also agree that recode() (because of dplyr), relabel(), revalue() also don't sound good.

So I guess change_code() is the least bad option? Everyone else agrees about this choice?

[IndrajeetPatil]

data_to_type -> to_type

@bwiernik Which function is this? Definitely not in datawizard.

[bwiernik]

data_to_factor, data_to_numeric, etc. that family of functions

[IndrajeetPatil]

Ah, I see! Got it.

In that case, the following comment is irrelevant:

The problem with change_code() is that it breaks the single work pattern for other transformation functions:

[IndrajeetPatil]

If we're renaming data_to_numeric() to to_numeric(), what should the existing to_numeric() should be renamed to?

How about coerce_to_numeric()

datawizard/R/data_to_numeric.R

Lines 262 to 268 in 3a3529b

	#' @export
	to_numeric <- function(x) {
	tryCatch(as.numeric(as.character(x)),
	error = function(e) x,
	warning = function(w) x
	)
	}

[strengejacke]

We could integrate it, having an argument that either preserves factors or coerces to numeric.

Have you checked other packages for usage of to_numeric()?

[IndrajeetPatil]

We could integrate it, having an argument that either preserves factors or coerces to numeric.

Yeah, that sounds better.

Have you checked other packages for usage of to_numeric()?

Few do, but I'd worry only about tidyverse namespace collisions.

[strengejacke]

Few do, but I'd worry only about tidyverse namespace collisions.

Sorry, I was referring to internal uses of to_numeric() in across easystats, so we don't break code. :-)

[IndrajeetPatil]

AFAICT, it is used only in one place: https://github.com/easystats/modelbased/blob/671ba596eeb350536d08290ee97248145d7fdba0/R/visualisation_recipe.estimate_grouplevel.R#L41

So we can definitely make this breaking change.

[IndrajeetPatil]

The easystats ecosystem after the renaming.

I think I have put out all the fires now, so should be fine.