Confusing documentation vs default value for week_start in wday()

[FlorenceMounier]

Hello,

My problem is somehow related to #1025 but for a different reason and with different propositions to solve the problem.

I find the choice of default value for week_start really confusing in wday(), especially for beginners (see "Details" section at the end of this issue if necessary).

However, I understand that this is an historical choice and that changing it would have many consequences for users. Having a more explicit documentation (1), or adding an example(2), would probably be the best options.

1. Rewording

week_start: day on which week starts following ISO conventions - 1 means Monday, 7 means Sunday (default). When label = FALSE, the number returned for this day of the week will be 1. When label = TRUE, this day of the week will be the first level of the returned factor. You can set lubridate.week.start option to control this parameter globally.`

2. New example

library(lubridate)

x <- ymd("2022-12-25")
wday(x)  # 1
wday(x, label = TRUE) 
#> [1] Sun
#> Levels: Sun < Mon < Tue < Wed < Thu < Fri < Sat

---

Details

The documentation of wday() for the week_start argument mentions that "following ISO convention [...] 7 means Sunday (default)". As a consequence, we could expect the result of wday() to be equal to 7 for a Sunday, by default.

However, wday() returns 1 for a Sunday as the default value for week_start is 7, thus Sunday is the first day of the week.

The documentation, and the use of wday(), would be clearer if the default value for week_start was consistent with the ISO conventions used and mentionned (i.e. 1 means Monday, thus week_start would be 1 by default). Indeed, it would be much easier to explain to beginners.

[GegznaV]

I agree that consistency is essential especially when you have to teach. Every inconsistency consumes time to explain and it becomes more difficult to remember. I would vote for consistency, clear documentation and for following ISO standards. But I know (as a user and as a package maintainer) that it is inconvenient to change the default behaviour of functions. But this sentence in the documentation:

`week_start` | day on which week starts following ISO conventions - 1 means Monday, 7 means Sunday (default). -- | --

implies that 1 is Monday and 7 is Sunday by default. Especially if you are from a country where the word "Monday" means not "the moon's day" but "the first day". So it is really counterintuitive to understand when you get a numeric answer which does not match your expectation ("the first day" = 2). So my suggestion would be at least to write in the documentation, that by default Sunday (translated as "the seventh day" in some countries) is 1 when week_start = 7 (that is the default).

So my suggestions:

1) if possible, change the defaults to meet ISO standards. 2) make the description in the documentation cristal clear for people from all cultures. I.e., default output should be explicitly stated. (E.g., add the sentence "When week_start = 7 (default), then 1 is returned for Sunday, 2 for Monday, etc.")

[GegznaV]

And, please, add an example with week_start = 1 and week_start = 7, e.g.,

x <- as.Date("2009-09-02")
wday(x) # 4

wday(x, week_start = 1) # 3
wday(x, week_start = 7) # 4

[GegznaV]

@FlorenceMounier, I created 2 pull requests for this issue. Do they meet your expectations? Or would be better to use the date, which means "Sunday"?

[FlorenceMounier]

Thanks a lot for your work @GegznaV, @vspinu.