r-lib / generics Goto Github PK

Prepare for release:

• devtools::build_readme()
• Check current CRAN check results
• devtools::check(remote = TRUE, manual = TRUE)
• devtools::check_win_devel()
• revdepcheck::revdep_check(num_workers = 4)
• Update cran-comments.md
• Polish NEWS

Submit to CRAN:

• usethis::use_version('minor')
• devtools::submit_cran()
• Approve email

Wait for CRAN...

• Accepted 🎉
• usethis::use_github_release()
• usethis::use_dev_version()

Is the visible column of the info attribute in utils::methods() doing what we expect? Currently, this is used to determine if a method shows up in the dynamic documentation or not.

However, I was confused by the fact that even when you add the \Sexpr line to, say, the tidy() generic to generate the dynamic docs, and then load the dev version of broom, no methods show up.

attr(utils::methods("tidy"), "info") should show that all of the methods from broom are not visible.

Digging into the base code, utils::methods() calls .S3methods(), and this eventually calls the helper, rbindSome(), when it appends all of the S3 method information onto the info attribute. rbindSome() sets visible = FALSE for ALL of the registered S3 methods.

This seems to be what is preventing the methods from showing up. Since methods like tidy.zoo have useful information, I would think we would want them to show up even though they are shown as visible = FALSE. Maybe we should not rely on that?

PS) Setting visible = FALSE in the call to methods_find() in methods_rd() fixes this by not omitting methods if they aren't visible and things work as expected.

This will allow dbplyr to import generics instead of dplyr.

CC @topepo.

hypothesize() was added from #10, it would also be nice to export it as hypothesise() also.

2023

• Update email addresses *@rstudio.com -> *@posit.co
• Update copyright holder in DESCRIPTION: person("Posit Software, PBC", role = c("cph", "fnd"))
• Run devtools::document() to re-generate package-level help topic with DESCRIPTION changes
• Update logo (https://github.com/rstudio/hex-stickers); run use_tidy_logo()
• usethis::use_tidy_coc()
• Use pak::pak("org/pkg") in README
• Consider running use_tidy_dependencies() and/or replace compat files with use_standalone()
• Use cli errors or file an issue if you don't have time to do it now
• use_standalone("r-lib/rlang", "types-check") instead of home grown argument checkers;
  or file an issue if you don't have time to do it now
• Change files ending in .r to .R in R/ and/or tests/testthat/
• Add alt-text to pictures, plots, etc; see https://posit.co/blog/knitr-fig-alt/ for examples

Eternal

• use_mit_license()
• use_package("R", "Depends", "3.6")
• usethis::use_tidy_description()
• usethis::use_tidy_github_actions()
• devtools::build_readme()
• Re-publish released site if needed

^{Created on 2023-10-30 with usethis::use_tidy_upkeep_issue(), using usethis v2.2.2.9000}

for example：
augment <- function(x, ...) {
UseMethod("augment")
}
it use the S3 method，but where is the full source code?
Is this some kind of new technology?

• Functions should have {}
• Documentation should use sentence case in titles
• Use markdown bulleted list

Presumably at https://generics.r-lib.org

e.g.

library(purrr)

m <- methods("summary")
m_vis <- m[attr(m, "info")$visible]

topics <- map(m_vis, help)
map_chr(topics, attr_getter("topic"))

Currently only 1 generic for each of those files has dynamic docs. Should be able to keep them all in the same help file. (I'll handle this)

I have put together a package of generics for modeling that I consider to be missing from the generics package.

https://github.com/poissonconsulting/universals

Can you let me know which, if any, of the generics you are willing to house in the generics packages and I'll put together a pull request?

This is a followup to #32, but an attempt to start answering "what should augment() look like"?

I'm of the belief that augment() should be split into three different generics:

• add_predictions(x, new_data, ...)
  • Primarily for adding predictions to the original data for supervised models
  • Thin wrapper around bind_cols(new_data, safepredict::safe_predict(x, new_data, ...))
  • Other possible names: bind_predictions(), add_predicted()
  • Has most of the same arguments as safepredict::safe_predict()
• add_training_info(x, data, ...)
  • Adds information specific to the training data to data (influences measures, residuals, etc)
  • Should inherent a cleaned up version of the arguments to influence.measures(), residuals(), rstandard() and rstudent().
• One version of augment() that doesn't have a data or new_data argument, for transformations that aren't maps (i.e. t-SNE, time series decompositions). Not sure what to call it.

A big question is how maintain backwards compatibility with previous versions of broom. cc @dgrtwo @topepo

> install()
Installing generics
'/Library/Frameworks/R.framework/Resources/bin/R' --no-site-file --no-environ  \
  --no-save --no-restore --quiet CMD INSTALL  \
  '/Users/max/github/modelgenerics'  \
  --library='/Library/Frameworks/R.framework/Versions/3.5/Resources/library'  \
  --install-tests 

* installing *source* package ‘generics’ ...
** R
** byte-compile and prepare package for lazy loading
** help
Warning: /Users/max/github/modelgenerics/man/setops.Rd:47: unexpected macro '\link', expecting '{' or '['
*** installing help indices
** building package indices
** testing if installed package can be loaded
* DONE (generics)
Reloading installed generics

Attaching package: ‘generics’

The following objects are masked from ‘package:base’:

    intersect, is.element, setdiff, setequal, union

@topepo can you please do ?setops, and give me the traceback if it throws an error?

I think all the generics should start with the same argument; I'd recommend x

The generic for bake() currently lives in recipes but as outlined in rstudio/vetiver-r#179, this presents difficulties for providing bake() methods for other kinds of objects, like a bundled recipe vetiver model.

Can we move the generic for bake() here to generics?

cc @topepo

The master branch of this repository will soon be renamed to main, as part of a coordinated change across several GitHub organizations (including, but not limited to: tidyverse, r-lib, tidymodels, and sol-eng). We anticipate this will happen by the end of September 2021.

That will be preceded by a release of the usethis package, which will gain some functionality around detecting and adapting to a renamed default branch. There will also be a blog post at the time of this master --> main change.

The purpose of this issue is to:

• Help us firm up the list of targetted repositories
• Make sure all maintainers are aware of what's coming
• Give us an issue to close when the job is done
• Give us a place to put advice for collaborators re: how to adapt

message id: euphoric_snowdog

We do it here (and in a number of other functions):
https://github.com/r-lib/generics/blob/master/R/tidy.R#L5

This probably was not noticed b/c if you have tibble installed locally a check won't pick it up, and this NOTE doesn't cause travis to fail, but it does show up.
https://travis-ci.org/DavisVaughan/generics/jobs/439136280#L1631

Suggest tibble?
Revert to saying data frame instead?

I have reviewed all non-RStudio contributors. I think the following contribution[s] are significant enough to merit a potential copyright claim:​

• those made by @mitchelloharawild
• those made by @alexpghayes

@mitchelloharawild, @alexpghayes, would you give your permission to relicense generics as MIT? If so, please comment "I agree" below.

intersect(), setdiff(), union() etc

These generics are used within fable models for producing a single model (estimate()) or a collection of models (model()) from model definitions.

To avoid "namespace grabbing", these generics should probably be moved to generics before the first CRAN release of the fable packages.

I'm also happy to open a dialogue for how these generics should be used, with regards to their default arguments.

Relevant discussion detailing the usage of model(), and to a lesser extent estimate(): tidyverts/fable#91

I have a package where I use tidy() to get a clean output of both simple and mixed models. Since some models require broom and mixed models need broom.mixed, I thought I can use the generics package instead.

However, when I add generics to the dependencies and remove broom and broom.mixed, the latter two packages are not installed along with my package. What if users did not have these two packages already installed? What is the best practice to reduce dependencies and use generics, without letting the user run into errors or create confusion?

Pre-history

• usethis::use_readme_rmd()
• usethis::use_roxygen_md()
• usethis::use_github_links()
• usethis::use_pkgdown_github_pages()
• usethis::use_tidy_github_labels()
• usethis::use_tidy_style()
• usethis::use_tidy_description()
• urlchecker::url_check()

2020

• usethis::use_package_doc()
  Consider letting usethis manage your @importFrom directives here.
  usethis::use_import_from() is handy for this.
• usethis::use_testthat(3) and upgrade to 3e, testthat 3e vignette
• Align the names of R/ files and test/ files for workflow happiness.
  The docs for usethis::use_r() include a helpful script.
  usethis::rename_files() may be be useful.

2021

• usethis::use_tidy_dependencies()
• usethis::use_tidy_github_actions() and update artisanal actions to use setup-r-dependencies
• Remove check environments section from cran-comments.md
• Bump required R version in DESCRIPTION to 3.5
• Use lifecycle instead of artisanal deprecation messages, as described in Communicate lifecycle changes in your functions
• Make sure RStudio appears in Authors@R of DESCRIPTION like so, if appropriate:
  person("RStudio", role = c("cph", "fnd"))

2022

• usethis::use_tidy_coc()
• Handle and close any still-open master --> main issues
• Update README badges, instructions in r-lib/usethis#1594
• Update errors to rlang 1.0.0. Helpful guides:
  https://rlang.r-lib.org/reference/topic-error-call.html
  https://rlang.r-lib.org/reference/topic-error-chaining.html
  https://rlang.r-lib.org/reference/topic-condition-formatting.html
• Update pkgdown site using instructions at https://tidytemplate.tidyverse.org
• Ensure pkgdown development is mode: auto in pkgdown config
• Re-publish released site; see How to update a released site

This is incredibly nitpicky, but if we're going to use tidyverse style and snake_case, it may be a bad idea to export varImp. If we build off of camelCase from the very beginning it may get entrenched, or others may copy the camelCase style.

On CRAN, the license is listed as GPL-2. On GitHub, the license is listed as MIT. I think this is just an issue with docs/index.html (there are also a few files in tests/testthat which also mention GPL-2). Perhaps the documentation needs to be updated. btw, i'm super glad to see this package is not GPL-2.

Currently, the recommendations for using generics functions is to import and reexport them in your package. With roxygen2, this automatically creates a re-exports doc page. When the user then uses ?tidy, they are presented with 2 help pages, one for generics and one for the re-export. I think ideally that re-export page would not get created, and only the generics page would show up and the user would be taken straight there. Is there a way to not create the re-export page (and still pass cran check if this is an issue?)

So that (e.g.) ?fit provides something useful

Currently the documentation is aimed at the developer, but most of the time the person reading them will be a user looking for documentation about that function. I think that means that the modelling functions need to be broken down into smaller pieces (documenting tightly related functions), and the current documentation moved to (e.g.) @section For package authors:.

I've come up with a few ideas for testing generics. They all revolve around testing the output of generics:::methods_rd(). I think I'm in favor of number 3, but am open to improvements / suggestions.

1. Suggest other packages such as lubridate or broom and library them when testing to have methods registered for methods_rd() to find.

Pros:

• Can test the output of multiple packages to ensure the rd is correct
• Easy to do

Cons:

• Adding heavy dependencies to Suggests
• Slightly reliant on the names of the Rd files of these packages when testing against "known" output of methods_rd(). If the Rd file names change, the tests could break.

2. Create a genericstests package that extends generics and adds some methods with documentation. Then Suggest it in generics and library it when testing so methods_rd() can find the methods.

Pros:

• Lightweight

Cons:

• One more package to manage

3. Maintain un-exported methods in generics that can be used for testing, and dynamically register them when it is time to test. These un-exported methods have their own documentation pages. I'm testing that out in a branch. Here is the R file with the methods and their docs. Here is the test file that dynamically registers the methods and has some explanation of this.

Pros:

• Lightweight
• Contained in 1 package

Cons:

• Somewhat complicated
• Can't test interactively with devtools::test() (but can test manually by installing and then running that test file, or by running R CMD Check)

Passing travis

Prepare for release:

• Check current CRAN check results
• Polish NEWS
• devtools::build_readme()
• urlchecker::url_check()
• devtools::check(remote = TRUE, manual = TRUE)
• devtools::check_win_devel()
• revdepcheck::cloud_check()
• Update cran-comments.md

Submit to CRAN:

• usethis::use_version('patch')
• devtools::submit_cran()
• Approve email

Wait for CRAN...

• Accepted 🎉
• usethis::use_github_release()
• usethis::use_dev_version()

In my package, I am extracting a list of available S3 tidy methods using generics template:

https://github.com/IndrajeetPatil/broomExtra/blob/56292a0fca15cd18df605c32b1f8e6d041813f25/R/generics.R#L17-L18

But, as can be seen from the webpage, this is not properly formatted:
https://indrajeetpatil.github.io/broomExtra/reference/tidy.html#methods

Any ideas on how to fix this?

What are your thoughts on adding sum() generic which is currently primitive.

Raised originally in tidyverse/lubridate#937

Prepare for release:

• git pull
• Check current CRAN check results
• Polish NEWS
• devtools::build_readme()
• urlchecker::url_check()
• devtools::check(remote = TRUE, manual = TRUE)
• devtools::check_win_devel()
• rhub::check_for_cran() offline
• revdepcheck::cloud_check() "42e12a3d-ddc5-44d9-abdf-9a997987e8be"
• Update cran-comments.md
• git push

Submit to CRAN:

• usethis::use_version('patch')
• devtools::submit_cran()
• Approve email

Wait for CRAN...

• Accepted 🎉
• git push
• usethis::use_github_release()
• usethis::use_dev_version()
• git push

i.e. do you expect users of this package to re-export it or depend on it?

It has been suggested that the forecast() and accuracy() generic functions would be better placed in the generics package, rather than having them duplicated across several packages, or importing the forecast package just to use these functions. Would you be willing to consider this? If yes, do you want a PR? @mitchelloharawild @config-i1

Fix documentation so that Roxygen comments were not visible. From RStudio 'Help' window:

If you really need aliases, you should pick one to make generic, and just call that generic from the other two.

It is currently used by at least two packages (quanteda (albeit deprecated) and wavethresh), and some of my packages have planned uses for them as well.

I would be happy to submit a PR.

varying_args() has been superseded by tune_args()

generate, calculate, hypothesize, specify, and visualize are all pretty generic.

I think that these are all simple functions that take tibbles so it might require overloading the classes to get a specific method what infer wants to do.

@andrewpbray and @ismayc... any thoughts on this? This would enable others to use those verbs for their specific needs.

Hi,

I am working on resolving the namespace issues between arules and dplyr. I am done with the set operations.

dplyr and rules, both create a generic for "recode". Can we move the generic definition to generics?

Thanks,
-Michael

The IRKernel currently relies on the repr package to provide generics for displaying Jupyter cell outputs. Adding repr generics would enable package writers to ensure that S3 objects print in the Jupyter console/notebook as they would in the R REPL.

Would it be useful to move the dynamic doc code pieces over to roxygen2? What if you could just use @dynamic in the roxygen comments of any generic function, and then the S3 methods would all be pulled in dynamically? @clauswilke and I talked about this briefly, and think it could be useful in places outside of just the generics package.