-
Notifications
You must be signed in to change notification settings - Fork 0
/
01_getting-started.Rmd
1039 lines (785 loc) · 39.9 KB
/
01_getting-started.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
Getting Started
===============
R is a program for statistical computing. It provides a rich set of built-in
tools for cleaning, exploring, modeling, and visualizing data.
The main way you'll interact with R is by writing code or _expressions_ in the
R programming language. Most people use "R" as a blanket term to refer to both
the program and the programming language. Usually, the distinction doesn't
matter, but in cases where it does, we'll point it out and be specific.
By writing code, you create an unambiguous record of every step taken in an
analysis. This it one of the major advantages of R (and other programming
languages) over point-and-click software like Tableau and Microsoft Excel.
Code you write in R is *reproducible*: you can share it with someone else, and
if they run it with the same inputs, they'll get the same results.
Another advantage of writing code is that it's often *reusable*. This can mean
automating a repetitive task within a single analysis, recycling code from one
analysis into another, or _packaging_ useful code for distribution to the
general public. At the time of writing, there were over 17,000 user-contributed
packages available for R, spanning a broad range of disciplines.
R is one of many programming languages used in data science. Compared to other
programming languages, R's particular strengths are its interactivity, built-in
support for handling missing data, the ease with which you can produce
high-quality data visualizations, and its broad base of user-contributed
packages (due to both its age and growing popularity).
#### Learning Objectives {-}
* Run code in the R console
* Call functions and create variables
* Check (in)equality of values
* Describe a file system, directory, and working directory
* Write paths to files or directories
* Get or set the R working directory
* Identify RDS, CSV, TSV files and functions for reading these
* Inspect the structure of a data frame
Prerequisites
-------------
<img src="img/rlogo.png" width="10%">
You can download R for free [here](https://cloud.r-project.org/), and can find
an install guide [here]().
In addition to R, you'll need RStudio. RStudio is an *integrated development
environment* (IDE), which means it's a comprehensive program for writing,
editing, searching, and running code. You can do all of these things without
RStudio, but RStudio makes the process easier. You can download RStudio Desktop
Open-Source Edition for free
[here](https://www.rstudio.com/products/rstudio/download/), and can find an
install guide [here]().
The R Interface
---------------
The first time you open RStudio, you'll see a window divided into several
panes, like this:
<img src="img/rstudio_start.png">
Don't worry if the text in the panes isn't exactly the same on your computer;
it depends on your operating system and versions of R and RStudio. The console
pane, on the left, is the main interface to R. If you type R code into the
console and press the `Enter` key on your keyboard, R will run your code and
return the result.
On the right are the environment pane and the plots pane. The environment pane
shows data in your R workspace. The plots pane shows any plots you make, and
also has tabs to browse your file system and to view R's built-in help files.
We'll learn more about these gradually, but to get started we'll focus on the
console pane.
Let's start by using R to do some arithmetic. In the console, you'll see that
the cursor is on a line that begins with `>`, called the *prompt*. You can make
R compute the sum $2 + 2$ by typing the code `2 + 2` after the prompt and then
pressing the `Enter` key. Your code and the result from R should look like
this:
<img src="img/arithmetic.png">
R always puts the result on a separate line (or lines) from your code. In this
case, the result begins with the tag `[1]`, which is a hint from R that the
result is a *vector* and that this line starts with the *element* at position 1.
We'll learn more about vectors in Section \@ref(vectors), and eventually learn
about other data types that are displayed differently. The result of the sum,
`4`, is displayed after the tag. In this reader, results from R will usually be
typeset in monospace and further prefixed with `##` to indicate that they
aren't code.
If you enter an incomplete expression, R will change the prompt to `+`, then
wait for you to type the rest of the expression and press the `Enter` key.
Here's what it looks like if you only enter `2 +`:
<img src="img/incomplete.png">
You can finish entering the expression, or you can cancel it by pressing the
`Esc` key (or `Ctrl-c` if you're using R without RStudio). R can only tell an
expression is incomplete if it's missing something, like the second operand in
`2 +`. So if you mean to enter `2 + 2` but accidentally enter `2`, which is a
complete expression by itself, don't expect R to read your mind and wait for
more input!
Try out some other arithmetic in the R console. Besides `+` for addition, the
other arithmetic operators are:
* `-` for subtraction
* `*` for multiplication
* `/` for division
* `%%` for remainder division (modulo)
* `^` or `**` for exponentiation
You can combine these and use parentheses to make more complicated expressions,
just as you would when writing a mathematical expression. When R computes a
result, it follows the standard order of operations: parentheses,
exponentiation, multiplication, division, addition, and finally subtraction.
For example, to estimate the area of a circle with radius 3, you can write:
```{r}
3.14 * 3^2
```
You can write R expressions with any number of spaces (including none) around
the operators and R will still compute the result. Nevertheless, putting spaces
in your code makes it easier for you and others to read, so it's good to make
it a habit. Put spaces around most operators, after commas, and after keywords.
### Variables
Since R is designed for mathematics and statistics, you might expect that it
provides a better appoximation for $\pi$ than `3.14`. R and most other
programming languages allow you to create named values, or _variables_. R
provides a built-in variable called `pi` for the value of $\pi$. You can
display a variable's value by entering its name in the console:
```{r}
pi
```
You can also use variables in expressions. For instance, here's a more precise
expression for the area of a circle with radius 3:
```{r}
pi * 3^2
```
You can define your own variables with the assignment operator `=` or `<-`. In
most circumstances these two operators are interchangeable. For clarity, it's
best to choose one you like and use it consistently in all of your R code. In
this reader, we use `=` for assignment because this is the assignment operator
in most programming languages.
The main reason to use variables is to save results so that you can use them
on other expressions later. For example, to save the area of the circle in a
variable called `area`, we can write:
```{r}
area = pi * 3^2
```
In R, variable names can contain any combination of letters, numbers, dots `.`,
and underscores `_`, but must always start with a letter or a dot. Spaces and
other symbols are not allowed in variable names.
Now we can use the `area` variable anywhere we want the computed area. Notice
that when you assign a result to a variable, R doesn't automatically display
that result. If you want to see the result as well, you have to enter the
variable's name as a separate expression:
```{r}
area
```
Another reason to use variables is to make an expression more general. For
instance, you might want to compute the area of several circles with different
radii. Then the expression `pi * 3^2` is too specific. You can rewrite it as
`pi * r^2`, and then assign a value to the variable `r` just before you compute
the area. Here's the code to compute and display the area of a circle with
radius 1 this way:
```{r}
r = 1
area = pi * r^2
area
```
Now if you want to compute the area for a different radius, all you have to do
is change `r` and run the code again (R will not change `area` until you do
this). Writing code that's general enough to reuse across multiple problems can
be a big time-saver in the long run. Later on, we'll see ways to make this code
even easier to reuse.
### Strings
R treats anything inside single or double quotes as literal text rather than as
an expression to evaluate. In programming jargon, a piece of literal text is
called a _string_. You can use whichever kind of quotes you prefer, but the
quote at the beginning of the string must match the quote at the end.
```{r}
'Hi'
"Hello!"
```
Numbers and strings are not the same thing, so for example R considers `1`
different from `"1"`. As a result, you can't use strings with most of R's
arithmetic operators. For instance, this code causes an error:
```{r, error = TRUE}
"1" + 3
```
The error message notes that `+` is not defined for non-numeric values.
### Comparisons
Besides arithmetic, you can also use R to compare values. The comparison
operators are:
* `<` for "less than"
* `>` for "greater than"
* `<=` for "less than or equal to"
* `>=` for "greater than or equal to"
* `==` for "equal to"
* `!=` for "not equal to"
The "equal to" operator uses two equal signs so that R can distinguish it from
`=`, the assignment operator.
Let's look at a few examples:
```{r}
1.5 < 3
"a" > "b"
pi == 3.14
"hi" == 'hi'
```
When you make a comparison, R returns a _logical_ value, `TRUE` or `FALSE`, to
indicate the result. Logical values are not the same as strings, so they are
not quoted.
Logical values are values, so you can use them in other computations. For
example:
```{r}
TRUE
TRUE == FALSE
```
Section \@ref(logic) describes more ways to use and combine logical values.
Beware that the equality operators don't always return `FALSE` when you compare
two different types of data:
```{r}
"1" == 1
"TRUE" <= TRUE
"FALSE" <= TRUE
```
Section \@ref(implicit-coercion) explains why this happens, and Appendix
\@ref(more-about-comparisons) explains several other ways to compare
values.
### Calling Functions
Most of R's features are provided through _functions_, pieces of reusable code.
You can think of a function as a machine that takes some inputs and uses them
to produce some output. In programming jargon, the inputs to a function are
called _arguments_, the output is called the _return value_, and when we use a
function, we say we're _calling_ the function.
To call a function, write its name followed by parentheses. Put any arguments
to the function inside the parentheses. For example, in R, the sine function is
named `sin` (there are also `cos` and `tan`). So we can compute the sine of
$\pi / 4$ with this code:
```{r}
sin(pi / 4)
```
There are many functions that accept more than one argument. For instance, the
`sum` function accepts any number of arguments and adds them all together. When
you call a function with multiple arguments, separate the arguments with
commas. So another way to compute $2 + 2$ in R is:
```{r}
sum(2, 2)
```
When you call a function, R assigns each argument to a _parameter_. Parameters
are special variables that represent the inputs to a function and only exist
while that function runs. For example, the `log` function, which computes a
logarithm, has parameters `x` and `base` for the operand and base of the
logaritm, respectively. The next section, Section \@ref(getting-help), explains
how to look up the parameters for a function.
By default, R assigns arguments to parameters based on their order. The first
argument is assigned to the function's first parameter, the second to the
second, and so on. So we can compute the logarithm of 64, base 2, with this
code:
```{r}
log(64, 2)
```
The argument 64 is assigned to the parameter `x`, and the argument 2 is
assigned to the parameter `base`. You can also assign arguments to parameters
by name with `=` (not `<-`), overriding their positions. So some other ways we
could write the call above are:
```{r}
log(64, base = 2)
log(x = 64, base = 2)
log(base = 2, x = 64)
log(base = 2, 64)
```
All of these are equivalent. When you write code, choose whatever seems the
clearest to you. Leaving parameter names out of calls saves typing, but
including some or all of them can make the code easier to understand.
Parameters are not regular variables, and only exist while their associated
function runs. You can't set them before a call, nor can you access them after
a call. So this code causes an error:
```{r, error = TRUE}
x = 64
log(base = 2)
```
In the error message, R says that we forgot to assign an argument to the
parameter `x`. We can keep the variable `x` and correct the call by making `x`
an argument (for the parameter `x`):
```{r}
log(x, base = 2)
```
Or, written more explicitly:
```{r}
log(x = x, base = 2)
```
In summary, variables and parameters are distinct, even if they happen to have
the same name. The variable `x` is not the same thing as the parameter `x`.
Getting Help
------------
Learning and using a language is hard, so it's important to know how to get
help. The first place to look for help is R's built-in documentation. In the
console, you can access a specific help page by name with `?` followed by the
name of the page.
There are help pages for all of R's built-in functions, usually with the same
name as the function itself. So the code to open the help page for the `log`
function is:
```{r, eval = FALSE}
?log
```
For functions, help pages usually include a brief description, a list of
parameters, a description of the return value, and some examples.
There are also help pages for other topics, such as built-in mathematical
constants (such as `?pi`), data sets (such as `?iris`), and operators. To look
up the help page for an operator, put the operator's name in single or double
quotes. For example, this code opens the help page for the arithmetic
operators:
```{r, eval = FALSE}
?"+"
```
It's always okay to put quotes around the name of the page when you use `?`,
but they're only required if it contains non-alphabetic characters. So `?sqrt`,
`?'sqrt'`, and `?"sqrt"` all open the documentation for `sqrt`, the square root
function.
Sometimes you might not know the name of the help page you want to look up. You
can do a general search of R's help pages with `??` followed by a string of
search terms. For example, to get a list of all help pages related to linear
models:
```{r, eval = FALSE}
??"linear model"
```
This search function doesn't always work well, and it's often more efficient to
use an online search engine. When you search for help with R online, include
"R" as a search term. Alternatively, you can use [RSeek][rseek], which
restricts the search to a selection of R-related websites.
[rseek]: https://rseek.org/
### When Something Goes Wrong
As a programmer, sooner or later you'll run some code and get an error message
or result you didn't expect. Don't panic! Even experienced programmers make
mistakes regularly, so learning how to diagnose and fix problems is vital.
Try going through these steps:
1. If R returned a warning or error message, read it! If you're not sure what
the message means, try searching for it online.
2. Check your code for typographical errors, including incorrect capitalization
and missing or extra commas, quotes, and parentheses.
3. Test your code one line at a time, starting from the beginning. After each
line that assigns a variable, check that the value of the variable is what
you expect. Try to determine the exact line where the problem originates
(which may differ from the line that emits an error!).
If none of these steps help, try asking online. [Stack Overflow][stacko] is a
popular question and answer website for programmers. Before posting, make sure
to read about [how to ask a good question][goodq].
[stacko]: https://stackoverflow.com/
[goodq]: https://stackoverflow.com/help/how-to-ask
File Systems
------------
Most of the time, you won't just write code directly into the R console.
Reproducibility and reusability are important benefits of R over
point-and-click software, and in order to realize these, you have to save your
code to your computer's hard drive. Let's start by reviewing how files on a
computer work. You'll need to understand that before you can save your code,
and it will also be important later on for loading data sets.
Your computer's _file system_ is a collection of _files_ (chunks of data) and
_directories_ (or "folders") that organize those files. For instance, the file
system on a computer shared by [Ada][ada] and [Charles][chuck], two pioneers of
computing, might look like this:
[ada]: https://en.wikipedia.org/wiki/Ada_Lovelace
[chuck]: https://en.wikipedia.org/wiki/Charles_Babbage
<img src="img/filesystem.png" width="50%">
Don't worry if your file system looks a bit different from the picture.
File systems have a tree-like structure, with a top-level directory called the
_root directory_. On Ada and Charles' computer, the root is called `/`, which
is also what it's called on all macOS and Linux computers. On Windows, the root
is usually called `C:/`, but sometimes other letters, like `D:/`, are also used
depending on the computer's hardware.
A _path_ is a list of directories that leads to a specific file or directory on
a file system (imagine giving directons to someone as they walk through the
file system). We use forward slashes `/` to separate the directories in a path,
rather than commas or spaces. The root directory includes a forward slash as
part of its name, and doesn't need an extra one.
For example, suppose Ada wants to write a path to the file `cats.csv`. She can
write the path like this:
```
/Users/ada/cats.csv
```
You can read this path from left-to-right as, "Starting from the root
directory, go to the `Users` directory, then from there go to the `ada`
directory, and from there go to the file `cats.csv`." Alternatively, you can
read the path from right-to-left as, "The file `cats.csv` inside of the `ada`
directory, which is inside of the `Users` directory, which is in the root
directory."
As another example, suppose Charles wants a path to the `Programs` directory.
He can write:
```
/Programs/
```
The `/` at the end of this path is reminder that `Programs` is a directory, not
a file. Charles could also write the path like this:
```
/Programs
```
This is still correct, but it's not as obvious that `Programs` is a directory.
In other words, when a path leads to a directory, including a _trailing slash_
is optional, but makes the meaning of the path clearer. Paths that lead to
files never have a trailing slash.
On Windows computers, paths are usually written with backslashes ```\``` to
separate directories instead of forward slashes. Fortunately, R uses forward
slashes `/` for all paths, regardless of the operating system. So when you're
working in R, use forward slashes and don't worry about the operating system.
This is especially convenient when you want to share code with someone that
uses a different operating system than you.
### Absolute & Relative Paths
A path that starts from the root directory, like all of the ones we've seen so
far, is called an _absolute path_. The path is "absolute" because it
unambiguously describes where a file or directory is located. The downside is
that absolute paths usually don't work well if you share your code.
For example, suppose Ada uses the path `/Programs/ada/cats.csv` to load the
`cats.csv` file in her code. If she shares her code with another pioneer of
computing, say [Gladys][gladys], who also has a copy of `cats.csv`, it might
not work. Even though Gladys has the file, she might not have it in a directory
called `ada`, and might not even have a directory called `ada` on her computer.
Because Ada used an absolute path, her code works on her own computer, but
isn't portable to others.
[gladys]: https://en.wikipedia.org/wiki/Gladys_West
On the other hand, a _relative path_ is one that doesn't start from the root
directory. The path is "relative" to an unspecified starting point, which
usually depends on the context.
For instance, suppose Ada's code is saved in the file `analysis.R` (more about
`.R` files in Section \@ref(r-scripts)), which is in the same directory as
`cats.csv` on her computer. Then instead of an absolute path, she can use a
relative path in her code:
```
cats.csv
```
The context is the location of `analysis.R`, the file that contains the code.
In other words, the starting point on Ada's computer is the `ada` directory. On
other computers, the starting point will be different, depending on where the
code is stored.
Now suppose Ada sends her corrected code in `analysis.R` to Gladys, and tells
Gladys to put it in the same directory as `cats.csv`. Since the path `cats.csv`
is relative, the code will still work on Gladys' computer, as long as the two
files are in the same directory. The name of that directory and its location in
the file system don't matter, and don't have to be the same as on Ada's
computer. Gladys can put the files in a directory `/Users/gladys/from_ada/` and
the path (and code) will still work.
Relative paths can include directories. For example, suppose that Charles wants
to write a relative path from the `Users` directory to a cool selfie he took.
Then he can write:
```
charles/cool_hair_selfie.jpg
```
You can read this path as, "Starting from wherever you are, go to the `charles`
directory, and from there go to the `cool_hair_selfie.jpg` file." In other
words, the relative path depends on the context of the code or program that
uses it.
When use you paths in R code, they should almost always be relative paths. This
ensures that the code is portable to other computers, which is an important
aspect of reproducibility. Another benefit is that relative paths tend to be
shorter, making your code easier to read (and write).
When you write paths, there are three shortcuts you can use. These are most
useful in relative paths, but also work in absolute paths:
* `.` means the current directory.
* `..` means the directory above the current directory.
* `~` means the _home directory_. Each user has their own home directory, whose
location depends on the operating system and their username. Home directories
are typically found inside `C:/Users/` on Windows, `/Users/` on macOS, and
`/home/` on Linux.
As an example, suppose Ada wants to write a (relative) path from the `ada`
directory to Charles' cool selfie. Using these shorcuts, she can write:
```
../charles/cool_hair_selfie.jpg
```
Read this as, "Starting from wherever you are, go up one directory, then go to
the `charles` directory, and then go to the `cool_hair_selfie.jpg` file." Since
`/Users/ada` is Ada's home directory, she could also write the path as:
```
~/../charles/cool_hair_selfie.jpg
```
This path has the same effect, but the meaning is slightly different. You can
read it as "Starting from your home directory, go up one directory, then go to
the `charles` directory, and then go to the `cool_hair_selfie.jpg` file."
The `..` and `~` shortcut are frequently used and worth remembering. The `.`
shortcut is included here in case you see it in someone else's code. Since it
means the current directory, a path like `./cats.csv` is identical to
`cats.csv`, and the latter is preferable for being simpler. There are a few
specific situations where `.` is necessary, but they fall outside the scope of
this text.
### R Scripts
Now that you know how file systems and paths work, you're ready to learn how to
save your R code to a file. R code is usually saved into an _R script_
(extension `.R`) or an _R Markdown file_ (extension `.Rmd`). R scripts are
slightly simpler, so let's focus on those.
In RStudio, you can create a new R script with this menu option:
```
File -> New File -> R Script
```
This will open a new pane in RStudio, like this:
<img src="img/rstudio_script.png">
The new pane is the scripts pane, which displays all of the R scripts you're
editing. Each script appears in a separate tab. In the screenshot, only one
script, the new script, is open.
Editing a script is similar to editing any other text document. You can write,
delete, copy, cut, and paste text. You can also save the file to your
computer's file system. When you do, pay attention to where you save the file,
as you might need it later.
The contents of an R script should be R code. Anything else you want to write
in the script (notes, documentation, etc.) should be in a _comment_. In R,
comments begin with `#` and extend to the end of the line:
```{r}
# This is a comment.
```
R will ignore comments when you run your code.
When you start a new project, it's a good idea to create a specific directory
for all of the project's files. If you're using R, you should also create one
or more R scripts in that directory. As you work, write your code directly into
a script. Arrange your code in the order of the steps to solve the problem,
even if you write some parts before others. Comment out or delete any lines of
code that you try but ultimately decide you don't need. Make sure to save the
file periodically so that you don't lose your work. Following these guidelines
will help you stay organized and make it easier to share your code with others
later.
While editing, you can run the current line in the R console by pressing
`Ctrl`+`Enter` on Windows and Linux, or `Cmd`+`Enter` on macOS. This way you
can test and correct your code as you write it.
If you want, you can instead run (or _source_) the entire R script, by calling
the `source` function with the path to the script as an argument. This is also
what the "Source on Save" check box refers to in RStudio. The code runs in
order, only stopping if an error occurs.
For instance, if you save the script as `my_cool_script.R`, then you can run
`source("my_cool_script.R")` in the console to run the entire script (pay
attention to the path---it may be different on your computer).
R Markdown files are an alternative format for storing R code. They provide a
richer set of formatting options, and are usually a better choice than R
scripts if you're writing a report that contains code. You can learn more
about R Markdown files [here][rmd].
[rmd]: https://rmarkdown.rstudio.com/
### The Working Directory
Section \@ref(absolute-relative-paths) explained that relative paths have a
starting point that depends on the context where the path is used. We can make
that idea more concrete for R. The _working directory_ is the starting point R
uses for relative paths. Think of the working directory as the directory R is
currently "at" or watching.
The function `getwd` returns the absolute path for the current working
directory, as a string. It doesn't require any arguments:
```{r}
getwd()
```
On your computer, the output from `getwd` will likely be different. This is a
very useful function for getting your bearings when you write relative paths.
If you write a relative path and it doesn't work as expected, the first thing
to do is check the working directory.
The related `setwd` function changes the working directory. It takes one
argument: a path to the new working directory. Here's an example:
```{r eval=FALSE}
setwd("..")
# Now check the working directory.
getwd()
```
Generally, you should avoid using calls to `setwd` in your R scripts and R
Markdown files. Calling `setwd` makes your code more difficult to understand,
and can always be avoided by using appropriate relative paths. If you call
`setwd` with an absolute path, it also makes your code less portable to other
computers. It's fine to use `setwd` interactively (in the R console), but avoid
making your saved code dependent on it.
Another function that's useful for dealing with the working directory and file
system is `list.files`. The `list.files` function returns the names of all of
the files and directories inside of a directory. It accepts a path to a
directory as an argument, or assumes the working directory if you don't pass a
path. For instance:
```{r}
# List files and directories in /home/.
list.files("/home/")
# List files and directories in the working directory.
list.files()
```
As usual, since you have a different computer, you're likely to see different
output if you run this code. If you call `list.files` with an invalid path or
an empty directory, the output is `character(0)`:
```{r}
list.files("/this/path/is/fake/")
```
Later on, we'll learn about what `character(0)` means more generally.
Reading Files
-------------
Analyzing data sets is one of the most common things to do in R. The first step
is to get R to read your data. Data sets come in a variety of file formats, and
you need to identify the format in order to tell R how to read the data.
Most of the time, you can guess the format of a file by looking at its
_extension_, the characters (usually three) after the last dot `.` in the
filename. For example, the extension `.jpg` or `.jpeg` indicates a [JPEG image
file][jpg]. Some operating systems hide extensions by default, but you can find
instructions to change this setting online by searching for "show file
extensions" and your operating system's name. The extension is just part of the
file's name, so it should be taken as a hint about the file's format rather
than a guarantee.
[jpg]: https://en.wikipedia.org/wiki/JPEG
R has built-in functions for reading a variety of formats. The R community also
provides _packages_, shareable and reusable pieces of code, to read even more
formats. You'll learn more about packages later, in Section \@ref(packages).
For now, let's focus on data sets that can be read with R's built-in functions.
Here are several formats that are frequently used to distribute data, along
with the name of a built-in function or contributed package that can read the
format:
| Name | Extension | Function or Package | Tabular? | Text?
| :-------------------------- | :-------- | :------------------- | :-------- | :----
| Comma-separated Values | `.csv` | `read.csv` | Yes | Yes
| Tab-separated Values | `.tsv` | `read.delim` | Yes | Yes
| Fixed-width File | `.fwf` | `read.fwf` | Yes | Yes
| Microsoft Excel | `.xlsx` | **readr** package | Yes | No
| Microsoft Excel 1993-2007 | `.xls` | **readr** package | Yes | No
| [Apache Arrow][arrow] | `.feather` | **arrow** package | Yes | No
| R Data | `.rds` | `readRDS` | Sometimes | No
| R Data | `.rda` | `load` | Sometimes | No
| Plaintext | `.txt` | `readLines` | Sometimes | Yes
| Extensible Markup Language | `.xml` | **xml2** package | No | Yes
| JavaScript Object Notation | `.json` | **jsonlite** package | No | Yes
[arrow]: https://arrow.apache.org/
A _tabular_ data set is one that's structured as a table, with rows and columns.
We'll focus on tabular data sets for most of this reader, since they're easier
to get started with. Here's an example of a tabular data set:
| Fruit | Quantity | Price
| :---- | -------: | ----:
| apple | 32 | 1.49
| banana | 541 | 0.79
| pear | 10 | 1.99
A _text_ file is one that contains human-readable lines of text. You can check
this by opening the file with a text editor such as Microsoft Notepad or macOS
TextEdit. Many file formats use text in order to make the format easier to work
with.
For instance, a _comma-separated values_ (CSV) file records a tabular data
using one line per row, with commas separating columns. If you store the table
above in a CSV file and open the file in a text editor, here's what you'll see:
```
Fruit,Quantity,Price
apple,32,1.49
banana,541,0.79
pear,10,1.99
```
A _binary_ file is one that's not human-readable. You can't just read off the
data if you open a binary file in a text editor, but they have a number of
other advantages. Compared to text files, binary files are often faster to read
and take up less storage space (bytes).
As an example, R's built-in binary format is called _RDS_ (which may stand for
"R data serialized"). RDS files are extremely useful for backing up work, since
they can store any kind of R object, even ones that are not tabular. You can
learn more about how to create an RDS file on the `?saveRDS` help page, and how
to read one on the `?readRDS` help page.
### Hello, Data!
Let's read our first data set! Over the next few sections, we're going to
explore data from the U.S. Bureau of Labor Statistics about median employee
earnings. The data set was prepared as part of the Tidy Tuesday R community
project. You can find more details about the data set [here][earn], and you can
download the data set [here][earn-dl] (you may need to choose `File -> Save
As...` in your browser's menu).
[earn]: https://github.com/rfordatascience/tidytuesday/tree/master/data/2021/2021-02-23
[earn-dl]: https://raw.githubusercontent.com/rfordatascience/tidytuesday/master/data/2021/2021-02-23/earn.csv
The data set is a file called `earn.csv`, which suggests it's a CSV file. In
this case, the extension is correct, so we can read the file into R with the
built-in `read.csv` function. The first argument is the path to where you saved
the file, which may be different on your computer. The `read.csv` function
returns the data set, but R won't keep the data in memory unless we assign the
returned result to a variable:
```{r}
earn = read.csv("data/earn.csv")
```
The variable name `earn` here is arbitrary; you can choose something different
if you want. However, in general, it's a good habit to choose variable names
that describe the contents of the variable somehow.
If you tried running the line of code above and got an error message, pay
attention to what the error message says, and remember the strategies to get
help in Section \@ref(getting-help). The most common mistake when reading a
file is incorrectly specifying the path, so first check that you got the path
right.
If you ran the line of code and there was no error message, congratulations,
you've read your first data set into R!
Data Frames
-----------
Now that we've loaded the data, let's take a look at it. When you're working
with a new data set, it's usually not a good idea to print it out directly (by
typing `earn`, in this case) until you know how big it is. Big data sets can
take a long time to print, and the output can be difficult to read.
Instead, you can use the `head` function to print only the beginning, or
_head_, of a data set. Let's take a peek:
```{r}
head(earn)
```
This data set is tabular---as you might have already guessed, since it came
from a CSV file. In R, it's represented by a _data frame_, a table with rows
and columns. R uses data frames to represent most (but not all) kinds of
tabular data. The `read.csv` function, which we used to read this data, always
returns a data frame.
For a data frame, the `head` function only prints the first six rows. If there
are lots of columns or the columns are wide, as is the case here, R wraps the
output across lines.
When you first read an object into R, you might not know whether it's a data
frame. One way to check is visually, by printing it, as we just did. A better
way to check is with the `class` function, which returns information about what
an object is. For a data frame, the result will always contain `data.frame`:
```{r}
class(earn)
```
We'll learn more about classes in Section \@ref(data-types-classes), but for
now you can use this function to identify data frames.
By counting the columns in the output from `head(earn)`, we can see that this
data set has eight columns. A more convenient way to check the number of
columns in a data set is with the `ncol` function:
```{r}
ncol(earn)
```
The similarly-named `nrow` function returns the number of rows:
```{r}
nrow(earn)
```
Alternatively, you can get both numbers at the same time with the `dim` (short
for "dimensions") function.
Since the columns have names, we might also want to get just these. You can do
that with the `names` or `colnames` functions. Both return the same result:
```{r}
names(earn)
colnames(earn)
```
If the rows have names, you can get those with the `rownames` function. For
this particular data set, the rows don't have names.
### Summarizing Data
An efficient way to get a sense of what's actually in a data set is to have R
compute summary information. This works especially well for data frames, but
also applies to other data. R provides two different functions to get
summaries: `str` and `summary`.
The `str` function returns a _structural summary_ of an object. This kind of
summary tells us about the structure of the data---the number of rows, the
number and names of columns, what kind of data is in each column, and some
sample values. Here's the structural summary for the earnings data:
```{r}
str(earn)
```
This summary lists information about each column, and includes most of what we
found earlier by using several different functions separately. The summary uses
`chr` to indicate columns of text ("characters") and `int` to indicate columns
of integers.
In contrast to `str`, the `summary` function returns a _statistical summary_ of
an object. This summary includes summary statistics for each column, choosing
appropriate statistics based on the kind of data in the column. For numbers,
this is generally the mean, median, and quantiles. For categories, this is the
frequencies. Other kinds of statistics are shown for other kinds of data.
Here's the statistical summary for the earnings data:
```{r}
summary(earn)
```
### Selecting Columns
You can select an individual column from a data frame by name with `$`, the
dollar sign operator. The syntax is:
```{r, eval = FALSE}
VARIABLE$COLUMN_NAME
```
For instance, for the earnings data, `earn$age` selects
the `age` column, and `earn$n_persons` selects the `n_persons` column. So one
way to compute the mean of the `n_persons` column is:
```{r}
mean(earn$n_persons)
```
Similarly, to compute the range of the `year` column:
```{r}
range(earn$year)
```
You can also use the dollar sign operator to assign values to columns. For
instance, to assign `0` to the entire `quarter` column:
```{r}
earn$quarter = 0
```
Be careful when you do this, as there is no undo. Fortunately, we haven't
applied any transformations to the earnings data yet, so we can reset the
`earn` variable back to what it was by reloading the data set:
```{r}
earn = read.csv("data/earn.csv")
```
In Section \@ref(indexing), we'll learn how to select rows and individual
elements from a data frame, as well as other ways to select columns.
Exercises
---------
### Exercise
In a string, an _escape sequence_ or _escape code_ consists of a backslash
followed by one or more characters. Escape sequences make it possible to: