Merge branch 'main' into set-opertions

concepts/basics/.meta/config.json

@@ -1,5 +1,5 @@
 {
   "authors": ["jonmcalder"],
-  "contributors": [],
+  "contributors": ["colinleach"],
   "blurb": "Learn about R basics like variable assignment and function declaration."
 }

concepts/basics/about.md

@@ -0,0 +1,78 @@
+# About
+
+## Variables and assignment
+
+R is a dynamically typed language, so in general it is not necessary to specify the type of a variable. The default `mode` is `numeric`, usually implemented as a double-precision float. To force use of 32-bit integers use a `L` suffix:
+
+```R
+> class(50)
+[1] "numeric"
+> class(50L)
+[1] "integer"
+```
+
+The preferred assignment operator is `<-` 
+
+```R
+x <- 42
+avogadro <- 6.02e23
+mystr <- "Hello, World!"
+```
+
+Using `=` instead will often but not always work. This is discouraged as poor style.
+
+Operators work conventionally:
+```R
+2 + 3   # 5
+2 - 3   # -1
+2 * 3   # 6
+2 / 3   # 0.6666667
+8 %/% 3 # 2 (integer division)
+8 %% 3  # 2 (remainder)
+2 ^ 3   # 8 (exponential)
+```
+
+Also, note that `#` starts a single-line comment. There is no separate syntax for multiline comments.
+
+## Functions
+
+To define a function:
+
+```R
+squareit <- function(x) {
+    x * x
+}
+```
+
+Functions can have zero or more arguments, separated by commas.
+Parentheses are needed with `function()` even if there are no parameters.
+
+Default values can be specified for arguments, though these must come after any arguments without defaults.
+As a rather pointless example:
+
+```R
+squareit <- function(x = 42) {
+    x * x
+}
+
+> squareit()
+[1] 1764
+```
+
+The braces `{ }` are not strictly required for single-line function bodies, but including them is considered good style.
+
+R will automatically return the final value of a function, as in the examples above.
+
+`return()` can be used anywhere within the function body to make a return value explicit, but will return the specified value immediately and terminate the function without executing any of the remaining expressions in the function body. 
+
+So an explicit call to `return()` is usually only really required if one wants to exit the function early and return a specific value for some reason. 
+An example might be within an [`if-else` clause](/tracks/R/concepts/conditionals).
+
+Some developers do prefer explicit returns as a matter of code style though.
+
+Calling a function is conventional:
+
+```R
+> squareit(3)
+[1] 9
+```

concepts/basics/introduction.md

@@ -0,0 +1,42 @@
+# Introduction
+
+## Variables and assignment
+
+R is a dynamically typed language, so in general it is not necessary to specify the type of a variable. The preferred assignment operator is `<-` 
+
+```R
+x <- 42
+avogadro <- 6.02e23
+mystr <- "Hello, World!"
+```
+
+Operators work conventionally:
+```R
+2 + 3   # 5
+2 - 3   # -1
+2 * 3   # 6
+2 / 3   # 0.6666667
+8 %/% 3 # 2 (integer division)
+8 %% 3  # 2 (remainder)
+2 ^ 3   # 8 (exponential)
+```
+
+Also, note that `#` starts a single-line comment.
+
+## Functions
+
+To define a function:
+
+```R
+squareit <- function(x) {
+    x * x
+}
+```
+
+R will automatically return the final value of a function. More generally, `return(x * x)` will work from anywhere in the function body.
+
+Calling a function is conventional:
+
+```R
+y <- squareit(3) # y is now 9
+```

concepts/basics/links.json

@@ -1 +1,15 @@
-[]
+[
+    {
+      "url": "https://cran.r-project.org/doc/manuals/r-release/R-intro.html",
+      "description": "An Introduction to R"
+    },
+    {
+      "url": "https://intro2r.com/",
+      "description": "An Introduction to R (an open book)"
+    },
+    {
+      "url": "https://www.youtube.com/playlist?list=PL69A9CCD816A5F3A5",
+      "description": "R Tutorial on YouTube"
+    }
+  ]
+

concepts/booleans/.meta/config.json

@@ -0,0 +1,5 @@
+{
+  "authors": ["colinleach"],
+  "contributors": [],
+  "blurb": "R has boolean values TRUE and FALSE, operators ! (not), & or && (and), | or || (or)."
+}

concepts/booleans/about.md

@@ -0,0 +1,22 @@
+# About
+
+The boolean values in R are `TRUE` and `FALSE`.
+
+Boolean operators:
+
+```R
+!TRUE # FALSE (not)
+TRUE && FALSE # FALSE (scalar and)
+TRUE || FALSE # TRUE (scalar or)
+
+TRUE & FALSE # FALSE (vector and)
+TRUE | FALSE # TRUE (vector or)
+```
+
+Note that there are two sets of and/or operators. 
+The double-character versions operate on single values. 
+The single-character variants operate element-wise on vectors, returning a vector of booleans.
+
+Using `&&` or `||` on vectors means that only fhe first element is used in the comparison, yielding a single `TRUE`/`FALSE` and probably a warning message.
+
+This distinction will become important, and probably clearer, in the `vector-filtering` concept.

concepts/booleans/introduction.md

@@ -0,0 +1,11 @@
+# Introduction
+
+The boolean values in R are `TRUE` and `FALSE`.
+
+Boolean operators:
+
+```R
+TRUE && FALSE # FALSE (and)
+TRUE || FALSE # TRUE (or)
+!TRUE # FALSE (not)
+```

concepts/booleans/links.json

@@ -0,0 +1,6 @@
+[
+    {
+      "url": "https://intro2r.com/combining-logical-operators.html",
+      "description": "Combining logical operators"
+    }
+]

concepts/conditionals/.meta/config.json

@@ -0,0 +1,5 @@
+{
+  "authors": ["colinleach"],
+  "contributors": ["jonmcalder"],
+  "blurb": "R has fairly conventional set of comparison operators and if-then-else constructs."
+}

concepts/conditionals/about.md

@@ -0,0 +1,69 @@
+# About
+
+## Comparison operators
+
+R has a set of operators that is the same as many other languages:
+
+```R
+1 == 2 # FALSE
+1 != 2 # TRUE
+1 < 2 # TRUE
+1 > 2 # FALSE
+1 <= 2 # TRUE
+1 >= 2 # FALSE
+```
+
+There is no infix operator for exclusive or (i.e. A OR B, but not both). The `xor()` function can be used in this case.
+
+## Branching
+
+The basic form of an if-then-else is 
+
+```R
+if (x > 10) {
+    y <- "big"
+} else if (x > 2) {
+    y <- "medium"
+} else {
+    y <- "tiny"
+}
+```
+
+In this case, both parentheses `()` around the boolean and braces `{}` around the statement are required. 
+A simple `if` statement can be shortened:
+
+```R
+if (x == 0) return("success")
+```
+
+## Using vectors in conditionals
+
+Looking ahead to the `vector-filtering` concept: the conditional clause in parentheses `()` must evaluate to a single `TRUE`/`FALSE`. 
+Including vectors in the comparison usually gives a vector of booleans, so these will need to be wrapped in an aggregating function such as `all()` or `any()`.
+
+```R
+> numbers <- c(4,5,7,9,10,11)
+> numbers %% 3 == 0 # gives vector of booleans
+[1] FALSE FALSE FALSE  TRUE FALSE FALSE
+
+# use any() to get a single TRUE/FALSE
+> if (any(numbers %% 3 == 0)) print("1 or more numbers are divisible by 3")
+[1] "1 or more numbers are divisible by 3"
+```
+
+## The `ifelse` function
+
+An alternative if-else form may be useful, provided there is only a true/false outcome.
+
+```R
+y = ifelse(x > 8, "big", "small")
+
+# Don't do this:
+z = ifelse(x > 100, 100, "small") # can lead to problems
+```
+
+`ifelse()` takes exactly three parameters: boolean clause, value if `TRUE`, value if `FALSE`.
+
+Vector inputs are acceptable, and then a vector output is produced. 
+In this case, ensure both branches result in the same type (`mode`) of data: numeric, character, boolean, etc.
+This will be covered in the `vector-functions` concept. 

concepts/conditionals/introduction.md

@@ -0,0 +1,43 @@
+# Introduction
+
+## Comparison operators
+
+R has a set of operators that is the same as many other languages:
+
+```R
+1 == 2 # FALSE
+1 != 2 # TRUE
+1 < 2 # TRUE
+1 > 2 # FALSE
+1 <= 2 # TRUE
+1 >= 2 # FALSE
+```
+
+## Branching
+
+The basic form of an if-else is 
+
+```R
+if (x > 10) {
+    y <- "big"
+} else if (x > 2) {
+    y <- "medium"
+} else {
+    y <- "tiny"
+}
+```
+
+In this case, parentheses `()` around the boolean and braces `{}` around the statement are both required. 
+A simple `if` statement can be shortened:
+
+```R
+if (x == 0) return("success")
+```
+
+An alternative if-else form may be useful:
+
+```R
+y <- ifelse(x > 8, "big", "small")
+```
+
+`ifelse()` takes exactly three parameters: boolean clause, value if `TRUE`, value if `FALSE`.

concepts/conditionals/links.json

@@ -0,0 +1,6 @@
+[
+  {
+    "url": "https://intro2r.com/conditional-statements.html",
+    "description": "Conditional statements"
+  }
+]