Merge pull request #123 from coding-for-reproducible-research/download-rmd-files

Download rmarkdown files buttons added to all R courses

Author: liamjberrisford

individual_modules/introduction_to_r/basic_commands.ipynb

@@ -13,6 +13,12 @@
    "source": [
     "# Running Commands With R\n",
     "\n",
+    "## Download Rmd Version\n",
+    "\n",
+    "If you wish to engage with this course content via Rmd, then please click the link below to download the Rmd file.\n",
+    "\n",
+    "[Download basic_commands.Rmd](rmarkdown/basic_commands.Rmd)\n",
+    "\n",
     "## Learning Objectives\n",
     "- Understand how to use the R console and RStudio interface for running commands and displaying results\n",
     "- Learn the importance of the working directory in R and how to set and verify it using R commands\n",

individual_modules/introduction_to_r/control_flow.ipynb

@@ -16,6 +16,14 @@
     "R is just another programming language and here we are going to introduce some common programming paradigms that\n",
     "empower you to write code efficiently and control the flow of information. \n",
     "\n",
+    "## Download Rmd Version\n",
+    "\n",
+    "If you wish to engage with this course content via Rmd, then please click the link below to download the Rmd file.\n",
+    "\n",
+    "[Download control_flow.Rmd](rmarkdown/control_flow.Rmd)\n",
+    "\n",
+    "\n",
+    "\n",
     "## Learning Objectives\n",
     "- Learn the fundamental concepts of control flow in R programming, including loops and conditional statements\n",
     "- Understand how to use for loops to automate repetitive tasks in R\n",

individual_modules/introduction_to_r/data_types.ipynb

@@ -13,6 +13,12 @@
    "source": [
     "# Data Types and Structures\n",
     "\n",
+    "## Download Rmd Version\n",
+    "\n",
+    "If you wish to engage with this course content via Rmd, then please click the link below to download the Rmd file.\n",
+    "\n",
+    "[Download data_types.Rmd](rmarkdown/data_types.Rmd)\n",
+    "\n",
     "## Learning Objectives\n",
     "- Understand and identify the five core data types used in R (Numeric, Integer, Complex, Character, Logical)\n",
     "- Learn how to use functions like `typeof()`, `class()`, `mode()`, `length()`, and `attributes()` to examine the features of variables or objects in R\n",

individual_modules/introduction_to_r/load_data.ipynb

@@ -13,6 +13,12 @@
    "source": [
     "# Loading Data\n",
     "\n",
+    "## Download Rmd Version\n",
+    "\n",
+    "If you wish to engage with this course content via Rmd, then please click the link below to download the Rmd file.\n",
+    "\n",
+    "[Download load_data.Rmd](rmarkdown/load_data.Rmd)\n",
+    "\n",
     "## Learning Objectives\n",
     "- Learn how to load data from CSV files into R using the `read.csv` function.\n",
     "- Recognize and understand the arguments for the `read.csv` functions, particularly `file` and `header`\n",

individual_modules/introduction_to_r/manipulating_data.ipynb

@@ -0,0 +1,288 @@
+---
+layout: page
+title: Running commands with R
+order: 3
+session: 1
+length: 20
+toc: true
+adapted: true
+attrib_name: Programming with R
+attrib_link: https://github.com/swcarpentry/r-novice-inflammation
+attrib_copywrite: Software Carpentry
+attrib_license: CC-BY 4.0
+attrib_license_link: https://creativecommons.org/licenses/by/4.0/
+---
+
+
+
+```{r setup, include=FALSE}
+knitr::opts_chunk$set(echo = TRUE)
+```
+
+
+# Executing commands in R
+
+The console pane (in RStudio, the bottom left panel) is the place where R is
+waiting for you to tell it what to do, and where it will show the results of a
+command that has been executed. This console is the fundamental component of R and is available
+outside of RStudio. It is recognisable due to the blurb of text at the top (which provides details
+on which R version you are using) and the arrowhead cursor (>).
+
+ ![Alt Text](../images/r_console.png)
+
+
+You can type commands directly into the console
+and press `Enter` to execute those commands. For example we can use R as a calculator:
+
+```{r echo=TRUE}
+2+2 
+```
+
+
+# Interacting with R
+
+
+There are two main ways of interacting with R: using the console or by using
+a script. A script is a text file that contains your code. R scripts are often saved with the file extension .r or .R.
+
+We want our code and workflow to be reproducible. In other words, we want to write code in a way that
+anyone (including our future selves) can easily replicate, such they will obtain the same results from our code
+on their computer. If we type our commands directly into the Console, they will be forgotten when you close the session. 
+It is preferable to type the commands you want to run directly into the script editor, so that you can save the script. This way, 
+you have a complete record of what you did, 
+you can easily show others how you did it and you can do it again later on if needed. 
+
+RStudio allows you to execute commands directly from the script editor by using
+the <kbd>`Ctrl`</kbd> + <kbd>`Enter`</kbd> shortcut. If no text is highlighted, the command on the current
+line in the script (i.e. where the line containing the cursor) will be
+sent to the console and executed. Alternatively you can select multiple lines to 
+send to the console for execution when you press <kbd>`Ctrl`</kbd> +
+<kbd>`Enter`</kbd>.
+
+
+There may be times when you want to type directly in the console, for example a quick calcuation. 
+RStudio provides the <kbd>`Ctrl`</kbd> + <kbd>`1`</kbd> and <kbd>`Ctrl`</kbd> +
+<kbd>`2`</kbd> shortcuts allow you to jump between the script and the console
+windows.
+
+If R is ready to accept commands, the R console shows a `>` prompt. If it
+receives a command (by typing, copy-pasting or sent from the script editor using
+<kbd>`Ctrl`</kbd> + <kbd>`Enter`</kbd>), R will try to execute it, and when
+ready, show the results and come back with a new `>`prompt to indicate it is ready for
+the next command.
+
+If R is still waiting for you to enter more text to complete the current command 
+the console will show a `+` prompt. It means that you haven't finished entering
+a complete command. This is because it is expecting a specific character, that 
+finishes a command you have already started. For example, if you open a parenthesis or
+quotation,  it needs to be closed before the command can be processed. Another way of thinking about this 
+is R expects for every left-parentheses you include, a right-parentheses to accompany it. Similarly, it expects an even 
+number of quotation marks. This can be quite frustrating, as it might not be obvious what R is waiting for, but if
+you're in RStudio and this happens, click inside the console window and press
+`Esc`; this will cancel the incomplete command and return you to the `>` prompt.
+
+
+# Set the Working Directory
+
+When using R, often we want to analyse data stored in files on our computer and potentially save some output. 
+
+It is important to note that we are always working in a folder or directory on our computer. There are times when this may not be 
+important (for example running a simulation from given parameters). 
+But if we want a specific file, we need to tell R where to find it. We do using by specifying the filepath. One common issue, when 
+starting out with programming is understanding where a program (in this case R/Rstudio) is looking for the file(s).
+
+Theoretically, we can find any file from any location given the correct filepath. However, to make our code simpler, it can be helpful 
+to change location, and move to a folder where the files we want to work on are located. The folder we are currently in is called the working directory. 
+
+Let's create a folder on our computer, to store all the files we will work on for this series of workshops. On your computer, open up a 
+file explorer window (outside of Rstudio) and create a folder called **R-workshop** somewhere memorable. For example on the Desktop.
+
+In Rstudio, we can change the working directory through the drop down menus by selecting options
+
+`Session` -> `Set Working Directory` -> `Choose Directory...` 
+ 
+We then search for and select the folder we want.
+
+![Alt Text](../images/rstudio_workdirectory.png)
+
+You will note that in the R console a line of code has appeared.
+
+![Alt Text](../images/rstudio_setwd.png)
+
+This is the R command that is required to change the current working directory using the function `setwd()`. 
+The text string inside the "()" is the filepath to the folder we want to change to. If you save this to your script, 
+next time you won't need to click through the menus, you can execute this line of code instead.
+
+You should also see that in the File Pane (bottom-right), this has also changed to this new directory. We need to 
+know where we are such that we can navigate R to find files and locations appropriately.  If we ever get lost we can use `getwd()` to get the path 
+of our current location.
+
+``` {r}
+getwd()
+```
+
+<br>
+<details>
+	<summary> Absolute vs Relative Filepaths </summary>
+	<pre>
+    <p>
+		
+We can specify filepaths in two ways: 
+
+1. Absolute - this is where we direct R how to get there from the root folder, which is the uppermost folder in the system and is denoted "/". 
+Any file path that starts with "/" is an absolute filepath.
+2. Relative - this is where we direct R how to get to the new folder from where we currently are. For example to get to a sub-folder of the current 
+folder we can just provide the name of the current folder. We can use shortcuts to go up a folder (".."). Relative file paths do not start with "/"
+</p>
+</pre>
+</details>
+<br>
+
+# Defining Variables
+
+A key concept in any programming language is that of a variable. A variable is just a name, such as `x`, `current_temperature`, or `subject_id` which 
+represents some value. We use the word value here loosely as it could be a singular number, a matrix, or a more complex numerical structure. It also 
+does not have to even be a number it could be a string of text. The idea though is it's value might change and we want to simplify how we process the value.
+
+In R, we can create a new variable simply by assigning a value to it using `<-`
+
+```{r}
+weight_kg <- 55
+```
+
+
+Once a variable has a value, we can print it by typing the name of the variable and hitting `Enter` (or `return`).
+In general, R will print to the console any object returned by a function or operation *unless* we assign it to a variable.
+
+```{r}
+weight_kg
+```
+
+We can do arithmetic with the variable:
+
+```{r}
+# weight in pounds:
+2.2 * weight_kg
+```
+
+We can also change an object's value by assigning it a new value:
+
+```{r}
+weight_kg <- 57.5
+# weight in kilograms is now
+weight_kg
+```
+
+If we imagine the variable as a sticky note with a name written on it,
+assignment is like putting the sticky note on a particular value:
+
+
+<img src="../images/python-sticky-note-variables-01.svg" alt="Variables as Sticky Notes" />
+
+
+This means that assigning a value to one object does not change the values of other variables.
+For example, let's store the subject's weight in pounds in a variable:
+
+```{r}
+weight_lb <- 2.2 * weight_kg
+# weight in kg...
+weight_kg
+# ...and in pounds
+weight_lb
+```
+
+<img src="../images/python-sticky-note-variables-02.svg" alt="Creating Another Variable" />
+
+and then change `weight_kg`:
+
+```{r}
+weight_kg <- 100.0
+# weight in kg now...
+weight_kg
+# ...and weight in pounds still
+weight_lb
+```
+
+<img src="../images/python-sticky-note-variables-03.svg" alt="Updating a Variable" />
+
+Since `weight_lb` doesn't "remember" where its value came from, it isn't automatically updated when `weight_kg` changes.
+This is different from the way spreadsheets work.
+
+
+<details>
+	<summary> Assignment operator </summary>
+	<pre>
+		
+	`<-` is the assignment operator. It assigns values on the right to objects on
+    the left. So, after executing `x <- 3`, the value of `x` is `3`. The arrow can
+    be read as 3 **goes into** `x`.  For historical reasons, you can also use `=` for assignments,
+    but not in every context. Because of the (slight)[http://blog.revolutionanalytics.com/2008/12/use-equals-or-arrow-for-assignment.html] 
+    (differences)[https://web.archive.org/web/20130610005305/https://stat.ethz.ch/pipermail/r-help/2009-March/191462.html] in syntax,
+    it is good practice to use always `<-` for assignments, except when specifying the values of
+    arguments in functions, when only `=` should be used, see below.
+
+    In RStudio, typing <kbd>Alt</kbd> + <kbd>-</kbd> (push <kbd>Alt</kbd> at the
+    same time as the <kbd>-</kbd> key) will write ` <- ` in a single keystroke.
+    </pre>
+</details>
+
+
+## Activity: Assigning Values to Variables
+
+Draw diagrams showing what variables refer to what values after each statement in the following program:
+
+~~~
+mass <- 47.5
+age <- 122
+mass <- mass * 2.0
+age <- age - 20
+~~~
+
+<details>
+	<summary> Printing with Parentheses </summary>
+	<pre>
+		
+    An alternative way to print the value of a variable is to use () around the 
+    assignment statement.
+
+    As an example: 
+    
+    `(total_weight <- weight_kg + weight_lb)` 
+    
+    adds the values of `weight_kg` and `weight_lb`,
+    assigns the result to the `total_weight`,
+    and finally prints the assigned value of the variable `total_weight`.
+    </pre>
+</details>
+
+
+
+
+## Naming objects in R
+
+You can use any combination of alphanumeric characters, along with dots and underscores, to name an R object. But there are a few ___exceptions___:
+
+* Names cannot start with a number;
+* Names cannot have spaces;
+* Names cannot be a standalone number such as ```12``` or ```0.34```;
+* Names cannot be a reserved word such as ```if```, ```else```, ```function```, ```TRUE```, ```FALSE``` and ```NULL``` just to name a few 
+(to see the full list of reserved words, type ```?Reserved```).
+
+Examples of __*valid names*__ include ```a```, ```dat2```, ```cpi_index```, ```.tmp```, and even a standalone dot ```.``` (though a dot can 
+make reading code difficult under certain circumstances).
+
+Examples of __*invalid names*__ include ```1dat```,``` dat 2``` (note the space between ```dat``` and ```2```), ```df-ver2``` (the dash is 
+treated as a mathematical operator), and ```Inf``` (the latter is a reserved word listed in the ```?Reserved``` help document).
+
+You can mix cases, but use upper cases with caution since some letters look very much the same in both lower and upper cases (e.g. s and S).
+
+# Functions
+
+Functions are a core concept in programming, they are commands which tells R to perform a particular task. The utility of a function is that it 
+will perform its given action again and again. R identifies functions by the presence of "()" following their name. You can customise how the function behaves
+by the use of arguments, this is additional information provide to the function to allow it to run). 
+
+We have already used two functions in this workshop. First we used `setwd()`. We used this function with an argument, which was the path to the folder we 
+wanted to change to. We can reuse this function to change to an unlimited number of different folders on our computer. Then we used `getwd()`, this is an example 
+of a function that doesn't require any arguments. 
+