In our area of work, we will frequently run into code error messages as well as work with concepts that span multiple research fields including neuroscience, genomics, and bioinformatics. Thus, it is completely natural that we’ll need to ask others for help. We do this so frequently, that we end up developing skills for searching for the information that we need. Most of the times, we can spend a bit of time ourselves searching for a solution as described in more detail in “you must try, and then must ask”. Though at some point, we will ask others for their direct input.
Many of the communication tools we use for asking for help are text-based. It can be hard to convey jokes, so sometimes it’s best to refrain from making jokes in order to prioritize a clear exchange of ideas. You should also be respectful of everyone’s time and with the words you choose. For example, see what Jim Hester has to say about issue titles:
Take time⌚️to think about your issue titles!!!— Jim Hester (@jimhester_) January 11, 2021
xyz is broken
xyz fails with malformed input
The former puts the maintainers in a foul mood 😡
Issues should be requests 💐 rather than demands 🔨
Actually, Jim Hester keeps providing excellent advice, so you might want to check this table he made and shared on Twitter.
Ultimately, some coding issues are complex. Here are some tips on some strategies for resolving complex coding problems.
In general, please follow these Bioconductor composing guidelines when asking for help.
While a screenshot might convey a lot of information, it is challenging to extract the relevant code in order to reproduce the error being described. Thus text is strongly encouraged over screenshots.
The function call and the associated error message are frequently not informative enough for others to determine the root of the problem. You should aim to include the
traceback() information in R or equivalent in other languages which provides more detail on what happened. However, even the
traceback() information might not be enough, which is why you should definitely include the code for re-creating any objects you used in the function call. One simple way to do so is to include a permalink to a script you have version controlled on GitHub.
Use the reprex package for making small reproducible examples. Check our LIBD rstats club session on
reprex to learn more about it.
Either on Slack or GitHub, you can use some Markdown syntax features. In particular, you can use in line code formatting (1 back tick) and multi-line code formatting (3 backt icks). On GitHub, you can also use the html code tags
</details> to hide long output, which is useful for showing the R session information. That is, the output from sessioninfo. As an example, check this
Use the sessioninfo package to provide the full details of your R session. Some errors might have already been addressed in newer versions of R packages or R versions. Providing that information makes it easier for others to help you.
We have occasionally used a team activity called “learning from our search history” described in this blog post. One of the goals of this activity was to learn some search skills each of us has that are typically not taught. Another goal was to show that we all search for more information all the time because no one, not matter how experienced, knows all the answers.
We use Bioconductor R packages for most of our work because they contain a lot of useful functions for the type of work we do. Bioconductor packages can be under active development and changing frequently. Plus, some are challenging to understand how to use. For these and other reasons, Bioconductor has a BioC Support Website.
You will need to make an account before you can ask (or answer) a question. Once you do, you will need to use tags for labeling your question: typically with the tag that matches the Bioconductor package you are using. When you start to ask a new question, you will see a link to the new posts guide and the tutorial for asking questions.
You should try your best to follow those guidelines in order to make it easier for others to help you. Remember that you should follow the Bioconductor code of conduct.
Since we use R so much, we also use R packages developed by RStudio developers. One great and friendly website for asking for help with all things that are related to R (but maybe not so much related to Bioconductor) is the RStudio Community website. This website is particularly useful if you have questions about RStudio itself or the
tidyverse R packages.
If you want to get a summary of new posts that might be relevant to you, you can sign up for weekly email updates. On this website, there’s a strong preference for using the reprex package for making small reproducible examples. Check our LIBD rstats club session on
reprex to learn more about it.
At LIBD we have a GitHub organization account github.com/LieberInstitute. Think of it as our code library. As described in more detail in this video, you can search our code base, which might be useful to see actual examples on how we’ve used functions from specific R packages or other tools. If you work at LIBD, email Bill Urich so he can add you to the organization account, thank you!
Most open source projects on GitHub have an issues page where you can interact directly with the developers of the software you are using. Note that most open source software developers are not payed to provide support, and their time might be very limited. As such, you should try very hard to provide all the information the developers need in order to help you. This is a time consuming process, but it can help you learn more too, and sometimes even resolve the problem yourself.
Some GitHub repositories have issue templates such as
lcolladotor/biocthis that will tell you a bit more of what information you should provide to make it easier for others to help you out. Others like
rstudio/blogdown will ask you to fill a few checkmarks before submitting your question.
Again, Jim Hester has some useful advice.
Writing issues with too much description is nearly as bad as too little. 𐄷— Jim Hester (@jimhester_) January 15, 2021
Often the real problem is something completely different then what the reporter spent so long describing. 🤔
One reproducible example is worth 1,000 words. 🖼
Eventually, you might need to ask for help through specific e-mail mailing lists. This is more common the closer you get to source code. Some of the mailing lists we use frequently are listed below.
If you need help with R and JHPCE, you might find this video and companion notes useful.
This is the main mailing list for asking for help with all things related to JHPCE. The JHPCE admins plus some JHPCE users such as myself and Kasper Daniel Hansen receive these emails and might reply back. You can sign up to receive these emails too if you want. Or if you want to check the previous emails, check the bithelp website. Before you ask for help, check the JHPCE website since there are several guides there already that might answer the question you have in mind.
This is the main mailing list for all things related to JHPCE admin requests. For example, if you need help with getting your password reset or changing your default JHPCE user group.
This is the mailing list where all Bioconductor package authors are subscribed to. It’s sole purpose is to help current and new Bioconductor package authors. If you have questions about how to use a Bioconductor R package, use the Bioconductor Support website only. However, if you do have questions about R package development, then check out bioc-devel and its archives.
You might also like this video on some specific feedback about R/Bioconductor package development. Here are some companion notes.
Some mailing lists are very specific to what they serve. There are several of these mailing lists related to the R source itself, for sample R-SIG-Mac which is useful if you are compiling R in macOS, and only for questions related to that. This is a rare situation for us, but for some situations, this is where you can find the latest information and reach the experts on this topic.
Within our team and collaborators, we use Slack extensively. If you are new to Slack, you might want to read this blog post that I co-authored with Stephanie C Hicks. In that blog post, we talk about some important Slack settings that will make it easier to keep your work-life balance in check.
Slack is organized in Workspaces. Each of them is either free or payed, depending on the group. We mostly use the JHU Genomics Collective Slack workspace, which is a payed workspace. Meaning that we have access to all Slack-related goodies, like integrations with GitHub, Google Calendar, Google Docs, email, etc. Below you can find more information about the differnet Slack workspaces we use.
This is our main Slack workspace. Just like
git commit messages, channels are cheap. The idea is to make one channel per project. Currently, we are adding all team members to each channel even if they are not working on the specific project. Team members not involved in the project should feel free to mute the channel. However, by being a part of the channel, they can then see images and code that we are working on, which in some situations can be useful. For example, maybe we figured out how to make a new
plotly interactive graph in one channel, then others who are curious can get access to that knowledge and incorporate it into their projects.
If you need help use:
- libd_helpdesk: for asking general questions to all team members and LIBD collaborators
For team logistics, our channel is:
- libd_team_lcolladotor: meeting reminders, papers we’ll discuss and other team logistics
The remaining main Slack channels are:
- libd_alumni: for all LIBD past and current members
- libd_dsgs: for the DSgs-guides
- libd_general: for all current LIBD members that are on the JHU Genomics Slack workspace
- libd_genomics_martinowich: a shared channel with the Martinowich lab Slack workspace
- libd_lunchtrain: for random topics as well as organizing lunch outings 5 using the
/lunchtrainSlack command 6
- libd_pkgs: for software (mostly R packages) we are making that is not specific to a particular project
- libd_rstats_club: for the LIBD rstats club
There are also a set of public channels that we use frequently:
- genomics_journal_club: a student-run journal club
- genomics_seminar: Genomics at JHU seminars
- jhpce: JHPCE users, though also check the
- jhu_papers: where we announce papers with JHU authors
- joint_group_meeting: a JHU bi-weekly meeting led by Steven Salzberg and JHU colleagues. This is a great meeting to learn about methods work being done across Hopkins for genomics data analysis.
- langmead_rss: a channel where Ben Langmead shares papers he’s interested in
- rstats: major R announcements and other goodies
This is the LIBD Slack workspace used by Keri Martinowich’s team. Several of us work closely with her, Kristen Maynard, Stephanie Page and other Martinowich team projects.
Some Slack channels of interest here are:
One very useful public Slack workspace is the Bioconductor one. You can join for free through bioc-community.herokuapp.com/. If you join this Slack workspace, please introduce yourself on the introductions channel. You mgith also be interested in channels such as:
- biocYYYY where
YYYYis the given year, which is the main channel for that year’s Bioconductor conference. For example,
- containers to learn more about the Bioconductor Docker images
- developers_forum for learning about the Bioconductor Developer’s forum (typically held once per month)
- jobs for job announcements
- spatial for spatial transcriptomics and related technologies
Another public Slack workspace is the one run by R-Ladies Baltimore, a local chapter from R-Ladies Global. This Slack workspace is mostly active during the meetup sessions. Check out their Meetup page for more information.
I’m a part of a few more Slack workspaces, though not all of them are public.
- JHU Biostatistics: for members and alumni of the JHBSPH Biostatistics department.
- rOpenSci: for members of rOpenSci
- CSCCE: from the Center for Scientific Collaboration and Community Engagement which is useful if you want to learn more about community engagement
- CDSB: the Community of Bioinformatics Software Developers (in Spanish) which I co-founded in 2018 and through which we organize R workshops to help grow the community of R/Bioconductor developers in Latin America
- LatinR: a public Slack workspace related to the LatinR conference and community, whose goals are overlaping with those from CDSB