Add documentation clarifying appropriate use of weights in slice_sample()

[apeterson91]

Users may be led astray by the current language describing weighted sampling via slice_sample(). As discussed in https://stats.stackexchange.com/q/639211/ and elaborated on in issue #6848, there's more nuance to how weights might be used for sampling. The current base R algorithm which slice_sample() relies on does not use the sampling weights in a way that conform to how a user might suspect the weights ought to work, as in Horvitz Thompson estimation for example.

I've added appropriate details here in the documentation including the above link for further details.

[etiennebacher]

Hi, I'm not a member of the tidyverse team, but I just want to point out that you need to redocument the package to include this change in the .Rd file. You can use devtools::document(), or comment "/document" (without the quotes) in this PR to trigger a github action workflow (I'm not sure the latter will work).

[apeterson91]

Thanks @etiennebacher! Been a bit since I've built an R package locally – appreciate the reminder.

[skolenik]

The description of the problem is insufficient. I can poke at a more accurate answer with better references to both methodology and the existing R libraries.

(I would also point out that it is a somewhat better practice to name your branches informatively rather than main -- I would have called this slice_sample_7052 to indicate the function affected and the issue number.)

[apeterson91]

I don't completely follow the first part of your comment, but your edits LGTM.

I would also point out that it is a somewhat better practice to name your branches informatively

Acknowledged. I'll follow this convention in the future.

[DavisVaughan]

Thanks @apeterson91!