Introduction

Goals

We’re going to start the introduction by writing down some basic goals that underlie the construction and content of this book. We’re writing this for you, the reader, but also to hold ourselves accountable as we write. So, feel free to read if you are interested or skip ahead if you aren’t.

The goals of this book are:

To teach you how to use R and RStudio as tools for applied epidemiology. Our goal is not to teach you to be a computer scientist or an advanced R programmer. Therefore, some readers who are experienced programmers may catch some technical inaccuracies regarding what we consider to be the fine points of what R is doing “under the hood.”
To make this writing as accessible and practically useful as possible without stripping out all of the complexity that makes doing epidemiology in real life a challenge. In other words, We’re going to try to give you all the tools you need to do epidemiology in “real world” conditions (as opposed to ideal conditions) without providing a whole bunch of extraneous (often theoretical) stuff that detracts from doing. Having said that, we will strive to add links to the other (often theoretical) stuff for readers who are interested.
To teach you to accomplish common tasks, rather than teach you to use functions or families of functions. In many R courses and texts, there is a focus on learning all the things a function, or set of related functions, can do. It’s then up to you, the reader, to sift through all of these capabilities and decided which, if any, of the things that can be done will accomplish the tasks that you are actually trying to accomplish. Instead, we will strive to start with the end in mind. What is the task we are actually trying to accomplish? What are some functions/methods we could use to accomplish that task? What are the strengths and limitations of each?
To start each concept by showing you the end result and then deconstruct how we arrived at that result, where possible. We find that it is easier for many people to understand new concepts when learning them as a component of a final product.
To learn concepts with data instead of (or alongside) mathematical formulas and text descriptions, where possible. We find that it is easier for many people to understand new concepts by seeing them in action.

Text conventions used in this book

Bold text is used to highlight important terms, file names, and file extensions.
Highlighted inline code is used to emphasize small sections of R code and program elements such as variable or function names.

Contributing to R4Epi

Over the years, we have learned so much from our students and colleagues, and we anticipate that there is much more we can learn from you – our readers. Therefore, we welcome and appreciate all constructive contributions to R4Epi!

Typos

The easiest way for you to contribute is to help us clean up the little typos and grammatical errors that inevitably sneak into the text.

If you spot a typo, you can offer a correction directly in GitHub. You will first need to create a free GitHub account: sign-up at github.com. Later in the book, we will cover using GitHub in greater depth. Here, we’re just going to walk you through how to fix a typo without much explanation of how GitHub works.

Let’s say you spot a typo while reading along.

Next, click the edit button in the toolbar as shown in the screenshot below.

Close up, it looks like this:

The first time you click the icon, you will be taken to the R4Epi repository on GitHub and asked to Fork it. For our purposes, you can think of a GitHub repository as being similar to a shared folder on Dropbox or Google Drive.

“Forking the repository” basically just means “make a copy of the repository” on your GitHub account. In other words, copy all of the files that make up the R4Epi textbook to your GitHub account. Then, you can fix the typos you found in your copy of the files that make up the book instead of directly editing the actual files that make up the book. This is a safeguard to prevent people from accidentally making changes that shouldn’t be made.

🗒Side Note: Forking the R4Epi repository does not cost any money or add any files to your computer.

After you fork the repository, you will see a text editor on your screen.

The text editor will display the contents of the file (called an R markdown file), which is used to make the chapter you were looking at when you clicked the edit button. In our example, it was the “Contributing to R4Epi” section of the file named index.Rmd. We will learn more about R markdown files in the chapter on [R markdown], but for now just know that R Markdown files contain a mix of R code and plain text like the text you are reading right now. You may not understand the code yet, but you will probably be able to skim through the document and find the typo you want to fix.

Next, Scroll down through the text until you find the typo, and fix it.

Now, the only thing left to do is propose your typo fix to the authors. To do so, simply scroll to the bottom of the same screen where you made the edits to the file. There, you will see a “Propose changes” form box you can fill out. In the first line, type a brief (i.e., 72 characters or less) summary of the change you made. There is also a box to add a more detailed description of what you did, but you shouldn’t need to use it for a simple typo fix.

Next, click the “Propose changes” button. That will take you to another screen where you will be able to create a pull request. This screen is kind of busy, but try not to let it overwhelm you.

For now, we will focus on the three different sections of the screen that are highlighted with a red outline. We will start at the bottom and work our way up. The red box that is closest to the bottom of the screenshot shows us that the change we made was on line 93. We removed the word “typoo” (highlighted in red) and added the word “typo” (highlighted in green). The red box in the middle of the screenshot shows us the brief description we wrote for our proposed change – “Fixed a typo in index.Rmd”. Finally, the red box closest to the top of the screenshot is surrounding the “Create pull request” button. Let’s go ahead and click it now.

After doing so, we will get one final chance to amend our description of our proposed changes. We don’t want to change our description, so let’s go ahead and click “Create pull request” one more time. Our job is done! It is now up to the authors to review the changes we’ve proposed and “pull” them into the file in their repository.

In case you are curious, here is what the process looks like on the authors’ end. First, when we open the R4Epi repository page on GitHub, we will see that there is a new pull request.

When we open the pull request, we can see the proposed changes to the file.

Then, all we have to do is click the “Merge pull request button” and the fixed file is “pulled in” to replace the file with the typo.

Issues

There may be times when you see a problem that you don’t know how to fix, but you still want to make the authors aware of. In that case, you can create an issue in the R4Epi repository. To do so, navigate to the issue tracker using this link: https://github.com/brad-cannell/r4epi/issues.

Once there, you can check to see if someone has already raised the issue you are concerned about. If not, you can click the “New issue” button to raise it yourself.

Please note that R4Epi uses a Contributor Code of Conduct. By contributing to this book, you agree to abide by its terms.

License Information

This book was created by Brad Cannell and is licensed under a Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License.

R for Epidemiology