Improve the documentation of tidytranscriptomics adapters, `tidySE`, `tidySCE`, `tidySPE`, `tidyseurat`

[stemangiola]

These issues Spence several packages. This includes:

All of these packages share 90% of the functions of the work done on one will be applicable to all the others.

• improving examples for methods
• solving documentation working (when packages are loading or installing)
• Improving methods' argument description

[HelenaLC]

Here's another subtask that I'd be happy to cover. Open for discussion / alterations / additions! I.e., these are just suggestions (based on how I personally like Bioc vignettes to be written).

• revision of tidySingleCellExperiment vignette, including
  • fixing vignette HTML rendering on Bioc (see here)
  • hyperlinking external packages using BiocStyle::CRAN/Biocpkg() and friends
  • consistent style to improve readability and distinguish between, e.g.,
    ecosystems (tidyverse), classes/variables (tibble), functions (unnest())
  • loading full set dependencies in the preamble (?) (currently missing some, e.g., GGally, but also others)
  • abbreviating class names that are lengthy and used repetitively, for example, SingleCellExperiment -> SCE, tidySingleCellExperiment -> tidySCE (?)
  • prettify table summarizing tidySingleCellExperiment's functionality, e.g., removing tidySingleCellExperiment:: (?)

[HelenaLC]

regarding revision of method documentation, I think the most
comprehensive and easiest to maintain approach would be:

• separate documentation for groups of methods analogous to, e.g., dplyr
• link to corresponding man pages via @aliases and @rdname
• fully inherit documentation, but expand on application-focused @examples. E.g., documenting slice and friends would come down to:

  
  #' @name slice
  #' @rdname slice
  #' @aliases slice slice_head slice_tail slice_sample slice_min slice_max
  #' 
  #' @inherit dplyr::slice
  #' @family single table verbs
  #' 
  #' @examples
  #' ...
  NULL

' @rdname slice

' @importFrom dplyr slice

' @importFrom SummarizedExperiment colData

' @export

slice.SingleCellExperiment <- function(...) { }

with the option to overwrite default inheritance of parameters, e.g., by adding

@param .data A tidySummarizedExperiment object or any data frame.

[stemangiola]

Here's another subtask that I'd be happy to cover. Open for discussion / alterations / additions! I.e., these are just suggestions (based on how I personally like Bioc vignettes to be written).

• revision of tidySingleCellExperiment vignette, including

  • fixing vignette HTML rendering on Bioc (see here)
  • hyperlinking external packages using BiocStyle::CRAN/Biocpkg() and friends
  • consistent style to improve readability and distinguish between, e.g., ecosystems (tidyverse), classes/variables (tibble), functions (unnest())
  • loading full set dependencies in the preamble (?) (currently missing some, e.g., GGally, but also others)
  • abbreviating class names that are lengthy and used repetitively, for example, SingleCellExperiment -> SCE, tidySingleCellExperiment -> tidySCE (?)
  • prettify table summarizing tidySingleCellExperiment's functionality, e.g., removing tidySingleCellExperiment:: (?)

Amazing, agree on everything

except

"abbreviating class names", I'm allergic to acronyms :)

[stemangiola]

regarding revision of method documentation, I think the most comprehensive and easiest to maintain approach would be

All great, you are the best!

[stemangiola]

@HelenaLC on the same note, I have modified the documentation https://github.com/stemangiola/tidySingleCellExperiment/pull/69 to avoid any conflict with tidyverse and be completely "transparent".

This pull request will probably undo a lot of your changes, so it would be easier for you to have a look at the few things I'm changing in that pull request.

[stemangiola]

@cbrueffer, in case you were thinking of tackling the documentation for tidySummarizedExperiment please coordinate with @HelenaLC

If you want to contribute, a good idea could be to tackle some efficiency challenge or new functionality (e.g. dplyr > 1.0.0 new grammar).

Let's chat!

[cbrueffer]

Thanks @stemangiola; happy to chip in wherever I can! Haven't decided yet where to start; I'm on Slack as well, so happy to discuss.

[stemangiola]

tidySingleCellExperiment documentation part on this challenge is done! Thanks @HelenaLC!

[stemangiola]

@william-hutchison do you want to add yourself to this challenge to port the updated annotation style of tidySingleCellExperiment?

from https://github.com/stemangiola/tidySingleCellExperiment/commit/dc27e23a7a4d3e13f6cd4e24c16dd2d6ba5a6700 for reference.

[GrootJ]

Happy to chip in as well! Also thinking about where to start. I have a done bunch of NGS/omics analyses in R (incl using tidyverse grammar/structures). More of a user than a developer, and I am new to the summarized experiment containers/structures. Happy to discuss where I could help (with documentation, testing, etc?) - I am also on the slack channel..

[stemangiola]

Happy to chip in as well! Also thinking about where to start. I have a done bunch of NGS/omics analyses in R (incl using tidyverse grammar/structures). More of a user than a developer, and I am new to the summarized experiment containers/structures. Happy to discuss where I could help (with documentation, testing, etc?) - I am also on the slack channel..

Great. How about tackling tidybulk documentation? That is quite creative work and needs contributions at multiple levels

https://github.com/stemangiola/tidybulk/issues/282

But of course, if you want definitely to contribute to this one, we could discuss, and coordinate with @HelenaLC which is leading the tidySingleCellExperiment effort.

[stemangiola]

Thanks @stemangiola; happy to chip in wherever I can! Haven't decided yet where to start; I'm on Slack as well, so happy to discuss.

Let us know if you are keen to start. Again tidybulk is a good option

https://github.com/stemangiola/tidybulk/issues/282

[GrootJ]

Happy to chip in as well! Also thinking about where to start. I have a done bunch of NGS/omics analyses in R (incl using tidyverse grammar/structures). More of a user than a developer, and I am new to the summarized experiment containers/structures. Happy to discuss where I could help (with documentation, testing, etc?) - I am also on the slack channel..

Great. How about tackling tidybulk documentation? That is quite creative work and needs contributions at multiple levels

stemangiola/tidybulk#282

But of course, if you want definitely to contribute to this one, we could discuss, and coordinate with @HelenaLC which is leading the tidySingleCellExperiment effort.

I can contribute to tidybulk docs - i have experience w bulk - can provide feedback there (no examples i can make public tho). you will also migrate the tidybulk issues to tidyomics repo right? the current documentation is the github readme? Let me try to get that workflow going on my local machine.. probably good to touch base on goals (zoom or other) some time

[stemangiola]

Happy to chip in as well! Also thinking about where to start. I have a done bunch of NGS/omics analyses in R (incl using tidyverse grammar/structures). More of a user than a developer, and I am new to the summarized experiment containers/structures. Happy to discuss where I could help (with documentation, testing, etc?) - I am also on the slack channel..

Great. How about tackling tidybulk documentation? That is quite creative work and needs contributions at multiple levels stemangiola/tidybulk#282 But of course, if you want definitely to contribute to this one, we could discuss, and coordinate with @HelenaLC which is leading the tidySingleCellExperiment effort.

I can contribute to tidybulk docs - i have experience w bulk - can provide feedback there (no examples i can make public tho). you will also migrate the tidybulk issues to tidyomics repo right? the current documentation is the github readme? Let me try to get that workflow going on my local machine.. probably good to touch base on goals (zoom or other) some time

I have tagged you into the actual tidybulk issue.

[william-hutchison]

I will work on overhauling the tidySpatialExperiment documentation. Because tidySpatialExperiment is an extension of tidySingleCellExperiment, this will mainly involve copying across Helena's excellent changes.

[noriakis]

Hello, I would like to contribute to tidyseurat documentation. I would first try to do this with reference to @HelenaLC 's pull request for tidySingleCellExperiment https://github.com/stemangiola/tidySingleCellExperiment/pull/74.

[stemangiola]

Hello, I would like to contribute to tidyseurat documentation. I would first try to do this with reference to @HelenaLC 's pull request for tidySingleCellExperiment stemangiola/tidySingleCellExperiment#74.

Amazing! @HelenaLC did quite a few PRs about this topic; I would suggest looking at the latest master branch of tidySingleCellExperiment directly. She simplified the documentation incredibly and made use of zzz.R.

[stemangiola]

Congrats to everyone involved! We refactored all packages mentioned in this issue!