Function examples do not illustrate functionality due to external file

[joshwlambert]

In many of the exported functions, it is unclear to me what the function is doing, and the example is not illustrative of the functionality as the function is applied on test_linelist.rds which is loaded from the package.

It might be more illustrative to construct a data.frame in the examples to showcase what messy aspect of the data.frame is being addressed by each function.

[Karim-Mane]

Thank @joshwlambert for raising this point.

The examples in every exported function are designed illustrate what the function takes as arguments, and what it returns after the specific cleaning task. The function description in both the function documentation, vignette and the design vignette, title describe well about what the function is doing.

We have a set of predefined messy dataset saved as RDS that we are using all along the package to demonstrate the function usage. Could you please give an example where the function's example do not reflect what the function is doing?

On the other hand, we do not emphasis on the process of creating the messy dataset in {cleanepi} as this, I believe, is out of the scope of the package. There are packages like [{messy}(https://github.com/nrennie/messy) and potentially the messy feature that you are developing in {simulist} where this is more appropriate.

[joshwlambert]

I appreciate the other aspects of the function documentation is good and descriptive, my issue is specifically related to the function examples (@examples). I often, as I think many other users do, go straight to the examples to see the code in action to see what it is doing.

Below I've posted the original example for convert_numeric_to_date() with an alternative that I believe will give people reading the documentation a more clear illustration of what the function is doing.

library(cleanepi)

# current example in convert_numeric_to_date
data <- readRDS(system.file("extdata", "test_df1.RDS", package = "cleanepi"))
data <- convert_numeric_to_date(
  data = data,
  target_columns = "recruted_on_day",
  ref_date = as.Date("2022-10-13"),
  forward = TRUE
)

# new example showing the input and output data
messy_data <- data.frame(
  recruited_on_day = sample(10:70, 10, replace = TRUE),
  sex_at_birth = sample(c("Male", "Female"), 10, replace = TRUE),
  removed_on_day = sample(10:70, 10, replace = TRUE)
)
messy_data
#>    recruited_on_day sex_at_birth removed_on_day
#> 1                51       Female             11
#> 2                27       Female             59
#> 3                24         Male             28
#> 4                36         Male             66
#> 5                60         Male             11
#> 6                15       Female             25
#> 7                21         Male             33
#> 8                61         Male             31
#> 9                50         Male             36
#> 10               12         Male             43
clean_data <- convert_numeric_to_date(
  data = messy_data,
  target_columns = "recruited_on_day",
  ref_date = as.Date("2022-10-13"),
  forward = TRUE
)
clean_data
#>    recruited_on_day sex_at_birth removed_on_day
#> 1        2022-12-03       Female             11
#> 2        2022-11-09       Female             59
#> 3        2022-11-06         Male             28
#> 4        2022-11-18         Male             66
#> 5        2022-12-12         Male             11
#> 6        2022-10-28       Female             25
#> 7        2022-11-03         Male             33
#> 8        2022-12-13         Male             31
#> 9        2022-12-02         Male             36
#> 10       2022-10-25         Male             43

^{Created on 2025-02-06 with reprex v2.1.1}

The changes I've made:

• Create and print the messy data to show users the data structure, in this case a data.frame.
• Give variable more specific names to separate clean from messy data
• Print the output after calling {cleanepi} function to show the difference between data before and after

[jamesmbaazam]

The original example could be improved by printing the intermediate objects created. I think that is a balance between the original and proposed improvement in this issue. I agree with Karim that there's no need to recreate the messy data unless the process of reading in the data is slower or the stored data makes the package heavier.