Update README with the purpose of the project, how to get involved, where to get started, and how to ask for help, such as the slack channel. Keep in mind that we'll have separate documentation for the conversion process #5.

Let's try to check if Levi's conversion template (https://github.com/lwaldron/sweave2rmd_conversiontemplate) is working by creating a new branch after cloning the original repository?

Start a troubleshooting document where we can add questions and answers for common issues that we run into.

Please document handling duplicate code chunk names in https://github.com/Bioconductor/sweave2rmd/blob/main/vignettes/troubleshooting-faq.Rmd. You can follow the question and answer format.

You can add some additional details such as they prevent knitting and also make BiocCheck fail.

Related Bioconductor/GenomicRanges#72.

Let's evaluate if we can use https://github.com/LiNk-NY/Rnw2Rmd for conversions. We could do this a few ways, perhaps taking performing a conversion on an Rnw we've done before and comparing that to the method suggested by Martin to see which is closer to the final .Rmd. It might also be valuable to look at the conversion of a complex vignette.

I think it's possible to write a script to read our list of .Rnw files determine if a package is in Bioconductor 3.17 and how to categorize it on our Sweave2Rmd project board using BiocPkgTools.

You can get the name of the package from that list. You can use the BiocPkgTools::biocPkgList function to check if the package is in 3.17. If a package is in 3.17, you can check if it's maintained by Bioconductor Core with BiocPkgTools::biocMaintained. These are the packages that we'll set to Todo on the project board since we don't need to initiate any communication.

(Note: if a package isn't in 3.17, we still want to note somewhere, likely in the Trello, that no more action is needed.)

If a package is in 3.17 but not maintained by Bioconductor Core, we'll want to determine if it's high priority or low priority. We'll probably want a variable for threshold that we can adjust as needed. If BiocPkgTools::pkgDownloadRank is lower than the threshold, it's high priority; otherwise it's lower.

It might be good to write this to a spreadsheet and attach it to the Trello where the row is a package, with a column for 3.17 package (TRUE/FALSE) Bioc Maintained (TRUE/FALSE), and Priority (high/low).

@LiNk-NY gave us a suggestion to extract LaTeX tags from vignettes to assess if their difficulty.

First try this on a few vignettes to see if it might be a good option.

If this seems like a viable option, let's add it to the categorize_vignettes.R script.

Let's incorporate Rnw2Rmd in the contribution document. Replace the pandoc line that we run with the code to do the conversion with Rnw2Rmd. Could you also put Rnw2Rmd in the "Good to Have" section and also move pandoc from "Good to Have" to "Required"?

We are trying to add two more columns for package maintainers name and email-id in the output file of the script so that it would be easier for us to contact them and also to keep a record for us.

Welcome Outreachy applicants!

Note: Multiple Outreachy applicants can work on this issue.

Please choose this as your first contribution task to Bioconductor as it will familiarize you with R, R Markdown, RStudio, git, documentation, and GitHub processes we use on this project.

If you're not familiar with R and R Markdown, please learn a little about them. The following links should be sufficient to get you started:

• R Primer - Programming basics
• R Markdown

Prep Work

• Install R.
• Install RStudio
• In RStudio or through the terminal, install devtools and BiocManager:

  install.packages(c("devtools", "BiocManager"))
  # Use Bioconductor devel with BiocManager; we always Bioconductor devel with this project
  BiocManager::install(version = "devel")
  

Contribution Task

Create a simple package that includes a function and a vignette, the long-form documentation that explains how to use the package.

1. Clone the packageTemplate repository at https://github.com/jwokaty/packageTemplate but rename it.
2. Write a simple function that imports data from BugSigDB using
   bugsigdbr, takes some inputs, to filter the data in some way and return a filtered data frame. Note: This is intentionally pretty vague to give you room to explore the bioinformatics aspect of this project.
3. Create a vignette in R Markdown that explains how to use your package and includes examples using your function. Verify that you can knit your vignette with 'knitr' into HTML.
4. Update your DESCRIPTION file such that it reflects that you made it, the correct package name, its description, and add bugsigdbr as a dependency.
5. Update the README.
6. Push your changes to GitHub.
7. Make a comment in this issue with a link to your repository.

If you have any general questions about this contribution task, you're welcome to ask here so that we can learn from each other.

Remember to record your contributions in Outreachy at https://www.outreachy.org/outreachy-december-2022-internship-round/communities/bioconductor/convert-sweave-vignettes-to-r-markdown/contributions/.

Add VignetteBuilder: knitr to DESCRIPTION file so that new vignettes will appear on the landing page. Also BiocStyle and knitr should be under Suggests in the DESCRIPTION file. This information should be noted in the contributor and maintainer documentation.

We have a few vignettes that are labeled Contacted but without further information, such as the date contacted or how they were contacted. We should update these the dates when they were last contacted and how (it's an issue, it should be linked on the board), so that we know to either follow up, wait, or mark it as 'unresponsive'.

Write a style guide for .Rmds. Could possibly be separate from contribute.Rmd.

Document the review process, working from the pull request.

• Update vignettes/contributed.Rmd with the update to pandoc in #38

This issue likely needs more thought. For ideas, let's look at https://github.com/markdownlint/markdownlint

RStudio's knit functionality will knit regardless if the DESCRIPTION file is correct. Document the manual way to verify that the build system can generate the .html from R CMD build in contribute.Rmd. See Bioconductor/GenomicAlignments#22 for more details.

Group similar items on the checklist

Add the following to the checklist:

• Only files necessary for the conversion are included in the pull request. See the Bioconductor Packages: Development, Maintenance, and Peer Review for more information.
• Long lines have been broken up and reformatted.
• Code blocks are surrounded by a blank line and there are no blank lines before the start or after the end of the code within the code block.

The code block checklist item should probably have examples.

There should probably be more thought about what are the characteristics of a successful conversion and how we can identify that within the PR.

Adding a sidenote is not entirely clear in the BiocStyle style sheet.

.

To add a sidenote, use the following syntax:

Your text ^[Your sidenote]

Document the conversion process/workflow from selecting an Rnw file from https://github.com/orgs/Bioconductor/projects/2/views/1 to the Pull Request. Try to keep the idea of 'best practices' in mind and that users following these documents might be taking first steps on their own as complete beginners. You're welcome to work on this with a partner or suggest we break this into smaller issues.

Add a note after the following section that states if a contributor has performed multiple conversion then the comment can be shorted to

"Converted vignettes from Sweave to RMarkdown / HTML."),

Make reference of code of conduct in readme and future contributions.md.

Let's make a new document to describe the process of using Levi's https://github.com/lwaldron/sweave2rmd_conversiontemplate. We will need to figure out the process of how to use it then when/where does a user go back to follow the contribute.Rmd.

I think we just need to be careful because it could be confusing for someone who isn't familiar with Github and we still need to keep the manual instructions for vignettes in the case that the conversion template doesn't work.

Investigate possible use of styler. Install and try on a conversion to see if it will reduce of some the manual formatting tasks to achieve sweave2rmd style, such as textwidth = 80, blank line between start / end of code blocks and surrounding content, etc.

• How do you use it?
• What features are helpful/interest?
• What features are missing?

Welcome Outreachy applicants!

Note: Multiple Outreachy applicants can work on this issue.

Please choose this as your first contribution task to the Bioconductor Sweave2Rmd project as it will familiarize you with the R, R Markdown, GitHub processes, documentation, and the Sweave2Rmd conversion process (learn more about Bioconductor here).

Sweave2Rmd Project

Sweave2Rmd is a community project to convert Sweave vignettes to Rmd. Currently, there are approximately 900 vignettes .Rnw in software packages. These vignettes do not operate as effectively as .Rmd as they are older, combine latex with R, and compile to PDF whereas .Rmd vignettes compile to HTML, are BiocStyle compatible, and easier to read and maintain. Therefore, the aim of the Sweave2Rmd project is to convert these Sweave vignettes to .Rmd.

Prep Work

If you're not familiar with R and R Markdown, please learn a little about them. The following links should be sufficient to get you started: R Primer - Programming basics or R Markdown. Then you may complete the following steps:

• Install R
• Install RStudio
• In RStudio or through the terminal, install devtools and BiocManager:
  install.packages(c("devtools", "BiocManager"))
• Read through the Sweave2Rmd Contribute article, which explains step-by-step the process of converting a Sweave document to Rmd. The article will be important for completing this contribution task.

Contribution Task

After reading the Sweave2Rmd Contribute article, you may complete the 2023 Outreachy Sweave2Rmd Contribution Familiarity Quiz. The quiz contains questions about the process of converting a Sweave vignette to Rmd. It is an opportunity to both test your familiarity with the Contribute article and learn how to convert a vignette if you choose to complete the second (optional) contribution task. We expect the quiz to take up to 3 hours to complete. Only your first submission will count. If you have any questions about the quiz, feel free to post on the Sweave2Rmd Outreachy Slack channel. To join the Slack channel, view https://slack.bioconductor.org/ then search for the channel #outreachy.

Remember to record your contributions in Outreachy at https://www.outreachy.org/outreachy-may-2023-internship-cohort/communities/bioconductor/convert-sweave-vignettes-to-r-markdown/contributions/

'yes' should be 'true' in

@sonali8434 We've really appreciated your help in moving Sweave2Rmd further along through conversions, outreach, and improved documentation to mention a few of your contributions. Thanks for cleaning up the board during last week as an Outreachy intern with Bioconductor. Let's focus on the following

• Add GitHub repository URLs to unassigned vignettes
• If a maintainer is interested, set the status to 'Todo'
• Set difficulty for vignettes
• Add URL to issue for vignettes with a status of Contacted who were contacted by a GitHub issue*

I'll also note here as we discussed that if you have marked a vignette as 'Contacted' that the maintainer has been contacted once and the last date of contact is the date last modified.

*For vignettes with a status of Contacted, could you include the URL to the issue if you used an issue for communication? This way we will know how to continue dialogue with the maintainer. For those that do not have a URL, we will assume they were contacted by email.

pandoc -f latex -t markdown file.Rnw -o file.Rmd

A problem with this translation is that unknown LaTex macros are dropped. So for instance in https://github.com/Bioconductor/BiocParallel/blob/master/vignettes/Introduction_To_BiocParallel.Rnw the first few lines of the Introduction

Numerous approaches are available for parallel computing in \R{}. The
CRAN Task View for high performance and parallel computing provides
useful high-level summaries and package categorization.
\url{http://cran.r-project.org/web/views/HighPerformanceComputing.html}
Most Task View packages cite or identify one or more of \CRANpkg{snow},
\CRANpkg{Rmpi}, \CRANpkg{multicore} or \CRANpkg{foreach} as relevant
parallelization infrastructure. Direct support in \R{} for parallel

are translated to

Numerous approaches are available for parallel computing in . The CRAN
Task View for high performance and parallel computing provides useful
high-level summaries and package categorization.
http://cran.r-project.org/web/views/HighPerformanceComputing.html Most
Task View packages cite or identify one or more of , , or as relevant
parallelization infrastructure. Direct support in for parallel computing
started with release 2.14.0 with inclusion of the package which contains
modified versions of and .

where the LaTeX macros \R{} and \CRANpkg{} (from the BiocStyle package?) are silently dropped, making it very difficult to get the translation complete.

Using instead the command

pandoc -f latex+raw_tex -t markdown file.Rnw -o file.Rmd

produces

Numerous approaches are available for parallel computing in
\R{}{=latex}. The CRAN Task View for high performance and parallel
computing provides useful high-level summaries and package
categorization.
http://cran.r-project.org/web/views/HighPerformanceComputing.html Most
Task View packages cite or identify one or more of
\CRANpkg{snow}{=latex}, \CRANpkg{Rmpi}{=latex},
\CRANpkg{multicore}{=latex} or \CRANpkg{foreach}{=latex} as relevant
parallelization infrastructure. Direct support in \R{}{=latex} for
parallel computing started with release 2.14.0 with inclusion of the
\CRANpkg{parallel}{=latex} package which contains modified versions of
\CRANpkg{multicore}{=latex} and \CRANpkg{snow}{=latex}.

so it is easy to spot (and fix, e.g., using find / replace) the things that could not be automatically converted.

I am not very knowledgeable in pandoc, so there might be better solutions.

Change the hard coded date in the contribute document with "r format(Sys.time(), '%B %d, %Y')"

The Github action fails during deployment: https://github.com/Bioconductor/sweave2rmd/actions/runs/3876716635/jobs/6615690404. This might be due to an error in the deployment action or it may need a Github PAT.

Hello Outreachy applicants!

Note: This task can be completed by multiple Outreachy applicants. Please choose this as your second (optional) contribution task to the Bioconductor Sweave2Rmd project as it builds upon the familiarity quiz in the Sweave2Rmd first contribution.

Prep Work

• Sweave2Rmd Knowledge Check
• Please read our contribution document, which gives a good overview of the project plus the general workflow. In particular, you will be performing the tasks from Create the R Markdown (.Rmd) vignette and Remove the Sweave vignette (.Rnw).
• Install pandoc

Contribution Task

Make a pull request replacing a Sweave vignette with an R Markdown vignette.

1. Select a vignette from our project board that is labeled 'Easy' or 'Medium', set to 'Todo' and are unassigned. (As a FYI, although there is no maximum # of vignettes you're allowed to convert, project leads must review everyone's first PR before we are able to assess any additional vignettes from anyone contributing to the project).
2. Write a comment with the path of the vignette you'd like to do--e.g., BiocParallel/vignettes/Introduction_To_BiocParallel.Rnw. We will write your GitHub username as 'Assigned' and set 'Last Modified' to today.
3. Perform the steps in Create the R Markdown (.Rmd) vignette and Remove the Sweave vignette (.Rnw). Note: You do not need to contact the maintainers to work on this set of vignettes as they have either been previously contacted OR they are maintained by the Bioconductor Core Team.
4. Make sure that you request a review by writing @Bioconductor/sweave2rmd in a comment so that we can review your pull request. For example, @Bioconductor/sweave2rmd please review my contribution for Outreachy.
5. Make a comment in this issue with a link to your PR.
6. If you receive any feedback requesting changes, please address them.

Tip: You can find the PDF you'll be replacing by visiting the landing page for the package under Documents. You can look up the package at Bioconductor Software Packages.
Tip: You can read how we review PRs in the contribution document. Use the checklist to assess if your PR will pass review.

If your pull request is good, it will be merged into Bioconductor!

Remember to record your contributions in Outreachy at https://www.outreachy.org/outreachy-may-2023-internship-cohort/communities/bioconductor/convert-sweave-vignettes-to-r-markdown/contributions/.

Announcement: https://www.r-consortium.org/announcement/2023/03/16/kaizen-project-for-r-package-documentation
CFP: https://www.r-consortium.org/all-projects/call-for-proposals

Apply for 2nd grant cycle:
September 1, 2023 – Grant Application period opens
October 1, 2023 – Grant Application period close, 11:59pm US ET
November 1, 2023 – All accepted grantees are contacted by the ISC
December 1, 2023 – Deadline for acceptance of grant and contract. Public notification of grantees occurs shortly thereafter.

Template: https://github.com/RConsortium/isc-proposal

After executing this code in R console

pkgsList <- list()
for (i in 1:length(packageNames)) {
  if (packageNames[[i]] %in% pckgs) {
    rank <- pkgDownloadRank(packageNames[[i]], "software", version)
    pkgsList[[i]] <- list(package = packageNames[[i]],
                          rank = rank[[1]],
                          priority = ifelse(rank[[1]] < threshold, "High", "Low"),
                          status = ifelse(packageNames[[i]] %in% coreMaintained, "To do", "Contact maintainer"))
  } else {
    pkgsList[[i]] <- list(package = packageNames[[i]],
                          rank = " ",
                          priority = " ",
                          status = "Deprecated")
  }
}

we got multiple request of bfcdownload() function asking for overwrite existing files.

bfcdownload() will overwrite exisiting files, continue? (yes/no): yes
                                                                                                  |==================================================================================================================================================| 100%

bfcdownload() will overwrite exisiting files, continue? (yes/no): 

@jwokaty has suggested that there might be a issue with pkgDownloadRank function which is why we are having multiple requests of overwriting existing files.

The bitmap vignette in AnnotationDbi package has been labelled deprecated meaning it should be phased out or removed.
https://bioconductor.org/packages/release/bioc/vignettes/AnnotationDbi/inst/doc/AnnotationDbi.pdf

Users are no longer supposed to use the 'bimaps' interface but we don't know whether other Bioconductor packages are still using it or not. We will keep the vignette around until we know for sure that all packages have migrated to the 'select' interface which is the replacement for the 'bitmap' interface.

To give credit (and responsibility!) for work done, the vignette translator should be acknowledged in the package DESCRIPTION file. This information (real first and last name, no email address) needs to be provided by the converter, since real name is not necessarily available through GitHub account.

Packages using the Authors@R field in the DESCRIPTION allow for specification of 'role'. One possible value of 'role' is ctb (contributor); another might be com (compiler; this is rarely used). This format also allows for a comment = field, which might read converted <vignette name>.Rnw to <vignette name>.Rmd. These fields are documented under ?person.

See Bioconductor/BiocParallel#225 (comment) .

This issue collects some notes about how we can possibly automate some of the review process for a vignette conversion from Sweave to R Markdown.

Some of the checklist items for reviewing a pull request could be automated.

Martin gives another idea by using R CMD Stangle to extract the R code in the vignettes for comparison in Bioconductor/GSEABase#6 (comment).

Additional ideas from 3/8 lab meeting:

• a separate repo with github action template that is only used by contributor to convert and test (avoids adding github action to package directly, automates conversion and testing)
• same as above, but also checkouts out and makes pr

Hello Outreachy applicants!

Note: This task can be complete by multiple Outreachy applicants.

This second contribution task builds on what you've learned by working on a Bioconductor package vignette.

Prep Work

• Please read our contribution document, which gives a good overview of the project plus the general workflow. In particular, you will be performing the tasks from Create the R Markdown (.Rmd) vignette and Remove the Sweave vignette (.Rnw).
• Install pandoc

Contribution Task

Make a pull request replacing a Sweave vignette with an R Markdown vignette.

1. Select a vignette from our project board that is labeled 'Easy' or 'Medium', set to 'Todo' and are unassigned.
2. Write a comment with the path of the vignette you'd like to do--e.g., BiocParallel/vignettes/Introduction_To_BiocParallel.Rnw to @Bioconductor/sweave2rmd. We will write your GitHub username as 'Assigned' and set 'Last Modified' to today.x
3. Perform the steps in Create the R Markdown (.Rmd) vignette and Remove the Sweave vignette (.Rnw). Note: You do not need to contact the maintainers to work on this set of vignettes as they have either been previously contact OR they are maintained by the Bioconductor Core Team.
4. Make sure that you request a review by writing @Bioconductor/sweave2rmd in a comment so that we can review your pull request. For example, @Bioconductor/sweave2rmd please review my contribution for Outreachy.
5. If you receive any feedback requesting changes, please address them.

Tip: You can find the PDF you'll be replacing by visiting the landing page for the package under Documents. You can look up the package at Bioconductor Software Packages.

If your pull request is good, it will be merged into Bioconductor!

Remember to record your contributions in Outreachy at https://www.outreachy.org/outreachy-december-2022-internship-round/communities/bioconductor/convert-sweave-vignettes-to-r-markdown/contributions/.

Add a section about end of document error while using pandoc and Rnw2Rmd code in Troubleshooting FAQ section- https://bioconductor.github.io/sweave2rmd/articles/troubleshooting-faq.html.

Adding a carriage return in YAML header:

If you need to add a carriage return to the YAML header as shown in attached screenshot, add a "|+" in the section where the carriage return is needed (here under date), followed by a return. After the first line, add 2 returns.

title: "2. Using filterVcf to Select Variants from VCF Files"
author: "Paul Shannon"
date: |+
    Created: 20 February, 2013
    
    Last Modified: `r format(Sys.Date(), "%B %d, %Y")`
vignette: >
  %\VignetteIndexEntry{2. Using filterVcf to Select Variants from VCF Files}
  %\VignetteDepends{VariantAnnotation}
  %\VignettePackage{VariantAnntation}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteIndexEntry{Quick-start Guide}
  %\VignetteEncoding{UTF-8}
output:
  BiocStyle::html_document:
    number_sections: yes
    toc: yes
    toc_depth: 4

I've put the file using 20230530.txt at https://docs.google.com/spreadsheets/d/1_9XCDFrMrXn7X__Vty22qXn8NZYY-bZjjf62spw3RlY/edit#gid=1718851904. We can use this to keep track vignette conversions moving to the GitHub Project Board.

I highlighted the first group that should be part of our first round of communications. For now, I've also added Maintainer and Notes columns as I briefly looked at some of the packages.

@sonali8434 Could I ask you to do the following tasks:

• Verify we have all vignettes on the board for those marked "Has Prs -- Are all vignettes on the board?". Sometimes the names of the vignettes on the board change or aren't clear. Try searching on the board first and if you don't see it there, check the package's repository's issues to check if they are available there. If a vignette is missing, add it to the board and update the information in the sheet.
• For those marked for week of 20230605, check the package's landing page for repository and the maintainer information (names and emails). Add those to the sheet.

Following on #34, This StackOverflow post shows how to write a Lua filter; a set of these might be developed for the BiocStyle macros as a kind of 'meta' resource for this project.

This

return {
  {
    RawInline = function (raw)
      local macro = raw.text:match '\\R{}'
      if raw.format == 'latex' and macro then
        return pandoc.RawInline('markdown', '_R_')
      end
    end
  }
}

would replace the Rnw macro \R{} with the markdown _R_ and if in a file BiocStyle-Rnw-to-Rmd.lua would be used as

pandoc -f latex+raw_tex -t markdown file.Rnw --lua-filter BiocStyle-Rnw-to-Rmd.lua -o file.Rmd

The next macros to tackle are likely \CRANpkg{<package name>} and \Biocpkg{<package name>} which translate to markdown links [<package name>](https://cran.r-project.org/package=<package name>) and [<package name>](https://bioconductor.org/packages/<package name> followed by \Rcode{<inline code>} translated to `<inline code>`. I think Sweave code chunks <<...>>= ... @ could also be translated automatically

RStudio addin https://github.com/mwip/beautifyR formats R Markdown tables and also can handle fixing the width of multiple lines. Installation and how to use it should be added as a suggestion for ease of styling.

CONTRIBUTING.md file with contribution guidelines to your repository

The current contribution document gives the impression that all that is needed is to run pandoc without errors to generate a successful .Rmd, but this is misleading. In particular, there should be a section to expand on what needs manual correction in steps current 13 and 16. This can include examples of code.

Additionally, there should be another step that considers further how to make code easier to maintain, for example, by using Reflow Comment to break up long lines.

Add rationale for converting vignettes into R Markdown. Some of this is listed at https://docs.google.com/presentation/d/11PX1CWperCET_oDMM43KSTIhwsuTtuqAO1kgY7Pq96w/edit#slide=id.g168379e359d_0_5.