This page covers how to get help by posting a Github issue or by posting a reproducible example (“reprex”) to an online forum.
Many R packages and projects have their code hosted on the website Github.com. You can communicate directly with authors via this website by posting an “Issue”.
Read more about how to store your work on Github in the page [Collaboration and Github].
On Github, each project is contained within a repository. Each repository contains code, data, outputs, help documentation, etc. There is also a vehicle to communicate with the authors called “Issues”.
See below the Github page for the incidence2 package (used to make epidemic curves). You can see the “Issues” tab highlighted in yellow. You can see that there are 5 open issues.
Once in the Issues tab, you can see the open issues. Review them to ensure your problem is not already being addressed. You can open a new issue by clicking the green button on the right. You will need a Github account to do this.
In your issue, follow the instructions below to provide a minimal, reproducible example. And please be courteous! Most people developing R packages and projects are doing so in their spare time (like this handbook!).
To read more advanced materials about handling issues in your own Github repository, check out the Github documentation on Issues.
Providing a reproducible example (“reprex”) is key to getting help when posting in a forum or in a Github issue. People want to help you, but you have to give them an example that they can work with on their own computer. The example should:
- Demonstrate the problem you encountered
- Be minimal, in that it includes only the data and code required to reproduce your problem
- Be reproducible, such that all objects (e.g. data), package calls (e.g.
p_load()) are included
Also, be sure you do not post any sensitive data with the reprex! You can create example data frames, or use one of the data frames built into R (enter
data() to open a list of these datasets).
The reprex package can assist you with making a reproducible example:
- reprex is installed with tidyverse, so load either package
# install/load tidyverse (which includes reprex) pacman::p_load(tidyverse)
- Begin an R script that creates your problem, step-by-step, starting from loading packages and data.
# load packages pacman::p_load( tidyverse, # data mgmt and vizualization outbreaks) # example outbreak datasets # flu epidemic case linelist outbreak_raw <- outbreaks::fluH7N9_china_2013 # retrieve dataset from outbreaks package # Clean dataset outbreak <- outbreak_raw %>% mutate(across(contains("date"), as.Date)) # Plot epidemic ggplot(data = outbreak)+ geom_histogram( mapping = aes(x = date_of_onset), binwidth = 7 )+ scale_x_date( date_format = "%d %m" )
Copy all the code to your clipboard, and run the following command:
You will see an HTML output appear in the RStudio Viewer pane. It will contain all your code and any warnings, errors, or plot outputs. This output is also copied to your clipboard, so you can post it directly into a Github issue or a forum post.
- If you set
session_info = TRUEthe output of
sessioninfo::session_info()with your R and R package versions will be included
- You can provide a working directory to
- You can read more about the arguments and possible variations at the documentation or by entering
In the example above, the
ggplot() command did not run because the arguemnt
date_format = is not correct - it should be
The helpers need to be able to use your data - ideally they need to be able to create it with code.
To create a minumal dataset, consider anonymising and using only a subset of the observations.
UNDER CONSTRUCTION - you can also use the function
dput() to create minimal dataset.
Read lots of forum posts. Get an understanding for which posts are well-written, and which ones are not.
First, decide whether to ask the question at all. Have you thoroughly reviewed the forum website, trying various search terms, to see if your question has already been asked?
Give your question an informative title (not “Help! this isn’t working”).
Write your question:
- Introduce your situation and problem
- Link to posts of similar issues and explain how they do not answer your question
- Include any relevant information to help someone who does not know the context of your work
- Give a minimal reproducible example with your R session information
- Use proper spelling, grammar, punctuation, and break your question into paragraphs so that it is easier to read
Monitor your question once posted to respond to any requests for clarification. Be courteous and gracious - often the people answering are volunteering their time to help you. If you have a follow-up question consider whether it should be a separate posted question.
Mark the question as answered, if you get an answer that meets the original request. This helps others later quickly recognize the solution.