48 Getting help
This page covers how to get help by posting a Github issue or by posting a reproducible example (“reprex”) to an online forum.
48.1 Github issues
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.
48.2 Reproducible example
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.
library()
orp_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
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)
::p_load(tidyverse) pacman
- Begin an R script that creates your problem, step-by-step, starting from loading packages and data.
# load packages
::p_load(
pacman# data mgmt and vizualization
tidyverse, # example outbreak datasets
outbreaks)
# flu epidemic case linelist
<- outbreaks::fluH7N9_china_2013 # retrieve dataset from outbreaks package
outbreak_raw
# Clean dataset
<- outbreak_raw %>%
outbreak 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:
::reprex() reprex
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 = TRUE
the output ofsessioninfo::session_info()
with your R and R package versions will be included
- You can provide a working directory to
wd =
- You can read more about the arguments and possible variations at the documentation or by entering
?reprex
In the example above, the ggplot()
command did not run because the arguemnt date_format =
is not correct - it should be date_labels =
.
Minimal data
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.
48.3 Posting to a forum
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.
Read these posts about how to ask a good question the Stack overflow code of conduct.
48.4 Resources
Tidyverse page on how to get help!
Tips on producing a minimal dataset
Documentation for the dput function