forked from rstudio-conf-2020/r-for-excel
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathR-for-Excel-Users.tex
4325 lines (3263 loc) · 204 KB
/
R-for-Excel-Users.tex
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
\PassOptionsToPackage{unicode=true}{hyperref} % options for packages loaded elsewhere
\PassOptionsToPackage{hyphens}{url}
%
\documentclass[]{book}
\usepackage{lmodern}
\usepackage{amssymb,amsmath}
\usepackage{ifxetex,ifluatex}
\usepackage{fixltx2e} % provides \textsubscript
\ifnum 0\ifxetex 1\fi\ifluatex 1\fi=0 % if pdftex
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{textcomp} % provides euro and other symbols
\else % if luatex or xelatex
\usepackage{unicode-math}
\defaultfontfeatures{Ligatures=TeX,Scale=MatchLowercase}
\fi
% use upquote if available, for straight quotes in verbatim environments
\IfFileExists{upquote.sty}{\usepackage{upquote}}{}
% use microtype if available
\IfFileExists{microtype.sty}{%
\usepackage[]{microtype}
\UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
}{}
\IfFileExists{parskip.sty}{%
\usepackage{parskip}
}{% else
\setlength{\parindent}{0pt}
\setlength{\parskip}{6pt plus 2pt minus 1pt}
}
\usepackage{hyperref}
\hypersetup{
pdftitle={R for Excel Users},
pdfauthor={Julie Lowndes \& Allison Horst},
pdfborder={0 0 0},
breaklinks=true}
\urlstyle{same} % don't use monospace font for urls
\usepackage{color}
\usepackage{fancyvrb}
\newcommand{\VerbBar}{|}
\newcommand{\VERB}{\Verb[commandchars=\\\{\}]}
\DefineVerbatimEnvironment{Highlighting}{Verbatim}{commandchars=\\\{\}}
% Add ',fontsize=\small' for more characters per line
\usepackage{framed}
\definecolor{shadecolor}{RGB}{248,248,248}
\newenvironment{Shaded}{\begin{snugshade}}{\end{snugshade}}
\newcommand{\AlertTok}[1]{\textcolor[rgb]{0.94,0.16,0.16}{#1}}
\newcommand{\AnnotationTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
\newcommand{\AttributeTok}[1]{\textcolor[rgb]{0.77,0.63,0.00}{#1}}
\newcommand{\BaseNTok}[1]{\textcolor[rgb]{0.00,0.00,0.81}{#1}}
\newcommand{\BuiltInTok}[1]{#1}
\newcommand{\CharTok}[1]{\textcolor[rgb]{0.31,0.60,0.02}{#1}}
\newcommand{\CommentTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textit{#1}}}
\newcommand{\CommentVarTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
\newcommand{\ConstantTok}[1]{\textcolor[rgb]{0.00,0.00,0.00}{#1}}
\newcommand{\ControlFlowTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{\textbf{#1}}}
\newcommand{\DataTypeTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{#1}}
\newcommand{\DecValTok}[1]{\textcolor[rgb]{0.00,0.00,0.81}{#1}}
\newcommand{\DocumentationTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
\newcommand{\ErrorTok}[1]{\textcolor[rgb]{0.64,0.00,0.00}{\textbf{#1}}}
\newcommand{\ExtensionTok}[1]{#1}
\newcommand{\FloatTok}[1]{\textcolor[rgb]{0.00,0.00,0.81}{#1}}
\newcommand{\FunctionTok}[1]{\textcolor[rgb]{0.00,0.00,0.00}{#1}}
\newcommand{\ImportTok}[1]{#1}
\newcommand{\InformationTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
\newcommand{\KeywordTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{\textbf{#1}}}
\newcommand{\NormalTok}[1]{#1}
\newcommand{\OperatorTok}[1]{\textcolor[rgb]{0.81,0.36,0.00}{\textbf{#1}}}
\newcommand{\OtherTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{#1}}
\newcommand{\PreprocessorTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textit{#1}}}
\newcommand{\RegionMarkerTok}[1]{#1}
\newcommand{\SpecialCharTok}[1]{\textcolor[rgb]{0.00,0.00,0.00}{#1}}
\newcommand{\SpecialStringTok}[1]{\textcolor[rgb]{0.31,0.60,0.02}{#1}}
\newcommand{\StringTok}[1]{\textcolor[rgb]{0.31,0.60,0.02}{#1}}
\newcommand{\VariableTok}[1]{\textcolor[rgb]{0.00,0.00,0.00}{#1}}
\newcommand{\VerbatimStringTok}[1]{\textcolor[rgb]{0.31,0.60,0.02}{#1}}
\newcommand{\WarningTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
\usepackage{longtable,booktabs}
% Fix footnotes in tables (requires footnote package)
\IfFileExists{footnote.sty}{\usepackage{footnote}\makesavenoteenv{longtable}}{}
\usepackage{graphicx,grffile}
\makeatletter
\def\maxwidth{\ifdim\Gin@nat@width>\linewidth\linewidth\else\Gin@nat@width\fi}
\def\maxheight{\ifdim\Gin@nat@height>\textheight\textheight\else\Gin@nat@height\fi}
\makeatother
% Scale images if necessary, so that they will not overflow the page
% margins by default, and it is still possible to overwrite the defaults
% using explicit options in \includegraphics[width, height, ...]{}
\setkeys{Gin}{width=\maxwidth,height=\maxheight,keepaspectratio}
\setlength{\emergencystretch}{3em} % prevent overfull lines
\providecommand{\tightlist}{%
\setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
\setcounter{secnumdepth}{5}
% Redefines (sub)paragraphs to behave more like sections
\ifx\paragraph\undefined\else
\let\oldparagraph\paragraph
\renewcommand{\paragraph}[1]{\oldparagraph{#1}\mbox{}}
\fi
\ifx\subparagraph\undefined\else
\let\oldsubparagraph\subparagraph
\renewcommand{\subparagraph}[1]{\oldsubparagraph{#1}\mbox{}}
\fi
% set default figure placement to htbp
\makeatletter
\def\fps@figure{htbp}
\makeatother
\usepackage{etoolbox}
\makeatletter
\providecommand{\subtitle}[1]{% add subtitle to \maketitle
\apptocmd{\@title}{\par {\large #1 \par}}{}{}
}
\makeatother
\usepackage{booktabs}
% https://github.com/rstudio/rmarkdown/issues/337
\let\rmarkdownfootnote\footnote%
\def\footnote{\protect\rmarkdownfootnote}
% https://github.com/rstudio/rmarkdown/pull/252
\usepackage{titling}
\setlength{\droptitle}{-2em}
\pretitle{\vspace{\droptitle}\centering\huge}
\posttitle{\par}
\preauthor{\centering\large\emph}
\postauthor{\par}
\predate{\centering\large\emph}
\postdate{\par}
\usepackage[]{natbib}
\bibliographystyle{apalike}
\title{R for Excel Users}
\author{Julie Lowndes \& Allison Horst}
\date{2020-01-09}
\begin{document}
\maketitle
{
\setcounter{tocdepth}{1}
\tableofcontents
}
\hypertarget{welcome}{%
\chapter{Welcome}\label{welcome}}
Hello! This is a workshop taught by Julie Stewart Lowndes and Allison Horst at the RStudio Conference: January 27-28 in San Francisco, California.
We are environmental scientists who use and teach R in our daily work. We both work at the University of California Santa Barbara: Julie is based at the National Center for Ecological Analysis and Synthesis as part of the Ocean Health Index team and leads Openscapes, and Allison is based at the Bren School of Environmental Science and Management as a lecturer of data science \& statistics --- and is also an Artist in Residence at RStudio.
\hypertarget{agenda}{%
\section{Agenda}\label{agenda}}
\begin{longtable}[]{@{}lrr@{}}
\toprule
Time & Day 1 & Day 2\tabularnewline
\midrule
\endhead
9-10:30 & \protect\hyperlink{overview}{Motivation}, \protect\hyperlink{rstudio}{R \& RStudio, RMarkdown} (JL) & \protect\hyperlink{tidying}{Tidying data} (AH)\tabularnewline
break & &\tabularnewline
11-12:30 & \protect\hyperlink{github}{Intro to GitHub} (JL) & \protect\hyperlink{dplyr-vlookups}{\texttt{dplyr} \& VLOOKUPs} (AH)\tabularnewline
lunch & &\tabularnewline
13:30-15:00 & \protect\hyperlink{ggplot2}{\texttt{ggplot2} \& Charts} (AH) & \protect\hyperlink{collaboration}{Collaborating in \#rstats} (JL)\tabularnewline
break & &\tabularnewline
15:30-17:00 & \protect\hyperlink{dplyr-pivot-tables}{\texttt{dplyr} \& Pivot Tables} (JL) & \protect\hyperlink{synthesis}{Synthesis} (AH)\tabularnewline
\bottomrule
\end{longtable}
\hypertarget{prerequisites}{%
\section{Prerequisites}\label{prerequisites}}
Before the training, please make sure you have done the following:
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\tightlist
\item
Download and install \textbf{up-to-date versions} of:
\begin{itemize}
\tightlist
\item
R: \url{https://cloud.r-project.org}
\item
RStudio: \url{http://www.rstudio.com/download}
\end{itemize}
\item
Install the Tidyverse
\item
Create a an account:
\begin{itemize}
\tightlist
\item
\url{https://github.com}
\end{itemize}
\end{enumerate}
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\tightlist
\item
Get comfortable: if you're not in a physical workshop, be set up with two screens if possible. You will be following along in RStudio on your own computer while also watching a virtual training or following this tutorial on your own.
\end{enumerate}
\hypertarget{overview}{%
\chapter{Overview}\label{overview}}
TODO: add Star Wars illustrations \& Wickham R4DS illustration (as slides?)
\hypertarget{welcome-1}{%
\section{Welcome!}\label{welcome-1}}
In this workshop you will learn hands-on how to begin to interoperate between Excel and R. But this workshop is not only about learning R; we will learn R using additional software: RStudio and GitHub. These tools will help us develop good habits for working in a reproducible and collaborative way --- critical attributes of the modern analyst.
It's going to be fun and empowering!
\hypertarget{why-learn-r-if-i-know-excel}{%
\section{Why learn R if I know Excel?}\label{why-learn-r-if-i-know-excel}}
Excel is a widely used and powerful tool for working with data, and it is great for a lot of things. This is convenient and familiar; most of us have had their first experiences with data through Excel or other spreadsheet programs. As Jenny Bryan has said, \href{}{``Excel is how we learn that we love data analysis''}.
Excel is great for data entry. Can also be good for looking at data and feeling like you can touch it, and creating quick exploratory figures.
Excel can also become problematic with extending to analyses. This is because there aren't firm lines between what is data and what is analyses. For example, in this sheet:
\includegraphics[width=0.7\linewidth]{img/excel-sheet-example}
This makes the analytical steps taken are not readily apparent, nor easy to reproduce. Have you ever done forensics on an Excel sheet, trying to understand what happened between columns or sheets? Maybe it was even your own Excel file from the (recent) past.
This also makes them pretty brittle/sensitive to minor changes. Has seeing this ever given you a feeling of horror:
\includegraphics[width=0.8\linewidth]{img/want-to-save-changes-excel}
So while it is great how easily you can update different fields and add analytical steps in an Excel sheet, it can also be a bit hard to handle, particularly as projects get more complicated.
So, as automation, reproducibility, collaboration, and frequent reporting become increasingly expected in data analysis, a good option for Excel users is to extend their workflows with R.
\hypertarget{what-to-expect}{%
\subsection{What to expect}\label{what-to-expect}}
This is going to be a fun workshop.
This workshop will give you hands-on experience and confidence with R, and how to interoperate between Excel and R --- it is not about wholesale replacing everything you do in Excel into R.
We will learn technical skills that you can incrementally incorporate into your existing workflows. But a big part of interfacing between Excel and R is not only skillsets, it is mindsets. It is the mindset about how we think about data. How we shape data and organize data and analyze data. And how what we do now can make our analytical life better in the future.
\textbf{A modern R user has a workflow framed around collaboration}, and uses an ecosystem of tools and practices. We will be learning three main things all at the same time:
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\tightlist
\item
coding with best practices (R/RStudio/tidyverse)
\item
collaborative bookkeeping (Git/GitHub)
\item
reporting and publishing (RMarkdown/GitHub)
\end{enumerate}
\textbf{R users keep raw data separate from their analyses}, which means having data in one file and written computational commands saved as a separate file. We also embrace the concept of \textbf{``tidy data''}, where the data has a rectangular shape and each column is a variable and each row is an observation. Tidy data is a way of life.
\includegraphics[width=0.7\linewidth]{img/tidy_img_np}
\textbf{We are going to go through a lot in these two days} and it's less important that you remember it all. More importantly, you'll have experience with it and confidence that you can do it. The main thing to take away is that there \emph{are} good ways to work between R and Excel; we will teach you to expect that so you can find what you need and use it! A theme throughout is that tools exist and are being developed by real, and extraordinarily nice, people to meet you where you are and help you do what you need to do.
\textbf{You are all welcome here}, please be respectful of one another. Everyone in this workshop is coming from a different place with different experiences and expectations. But everyone will learn something new here, because there is so much innovation in the data science world. Instructors and helpers learn something new every time, from each other and from your questions. If you are already familiar with some of this material, focus on how we teach, and how you might teach it to others. Use these workshop materials not only as a reference in the future but also for talking points so you can communicate the importance of these tools to your communities. A big part of this training is not only for you to learn these skills, but for you to also teach others and increase the value and practice of open data science in science as a whole.
\hypertarget{guiding-principles-recurring-themes}{%
\section{Guiding principles / recurring themes}\label{guiding-principles-recurring-themes}}
\textbf{``Keep the raw data raw''} --- A hard line separating raw data and analyses. In R, we have data in one file and written computational commands saved as a separate file.
\textbf{Scripted analyses} --- We write analytical logic in code (rather than clicks) so that can be understood, rerun, and built upon.
\textbf{Learn from data that are not your own} --- We aren't using your data in this workshop, but you will see similiarities and patterns, and you'll see that these tools and practices apply to your work.
\textbf{Think ahead for Future You, Future Us.} Help make lives easier --- first and foremost your own. Create breadcrumbs for yourselves and others: document and share your work.
\hypertarget{resources}{%
\section{Resources}\label{resources}}
R is not only a language, it is an active community of developers, users, and educators (often these traits are in each person). This workshop and book based on many excellent materials created by other members in the R community, who share their work freely to help others learn. Using community materials is how WE learned R, and each chapter of the book will have Resources listed for further reading into the topics we discuss. And, when there is no better way to explain something (ahem Jenny Bryan), we will quote or reference that work directly.
\begin{itemize}
\tightlist
\item
\href{https://whattheyforgot.org/}{What They Forgot to Teach You About R} --- Jenny Bryan \& Jim Hester
\item
\href{https://stat545.com/}{Stat545} --- Jenny Bryan \& Stat545 TAs
\item
\href{http://rex-analytics.com/things-live-r-r-excel-users/}{Where do Things Live in R?} REX Analytics
\item
\href{https://blog.shotwell.ca/posts/r_for_excel_users/}{}
\item
\href{http://nssdeviations.com/episode-9-spreadsheet-drama}{Spreadsheet Drama (Episode 9)} --- Not So Standard Deviations with Roger Peng \& Hilary Parker
\item
more to come!
\end{itemize}
\hypertarget{rstudio}{%
\chapter{R \& RStudio, RMarkdown}\label{rstudio}}
\hypertarget{summary}{%
\section{Summary}\label{summary}}
We'll learn RMarkdown, which helps you tell a story with your data analysis because you can write text alongside the code. We are actually learning two languages at once: R and Markdown.
\hypertarget{objectives}{%
\subsection{Objectives}\label{objectives}}
In this lesson we will:
\begin{itemize}
\tightlist
\item
get oriented to the RStudio interface
\item
explore RMarkdown.
\item
discuss RMarkdown files vs Console (running vs knitting)
\item
learn a few base R functions (\texttt{c()})
\item
error messages and help pages
\item
discuss and install packages (\texttt{here()}) usethis
\item
intro pipe operator (\texttt{\%\textgreater{}\%})
\item
configure Git (to prepare for next session)
\end{itemize}
\hypertarget{resources-1}{%
\subsection{Resources}\label{resources-1}}
\begin{itemize}
\tightlist
\item
\href{https://blog.shotwell.ca/posts/r_for_excel_users/}{R for Excel Users} by Gordon Shotwell (blog)
\end{itemize}
\hypertarget{rstudio-orientation}{%
\section{RStudio Orientation}\label{rstudio-orientation}}
Open RStudio for the first time.
Launch RStudio/R.
\includegraphics[width=0.8\linewidth]{img/RStudio_IDE}
Notice the default panes:
\begin{itemize}
\tightlist
\item
Console (entire left)
\item
Environment/History (tabbed in upper right)
\item
Files/Plots/Packages/Help (tabbed in lower right)
\end{itemize}
We won't click through this all immediately but we will become familiar with more of the options and capabilities throughout the next few days.
Something critical to know now is that you can make everything you see BIGGER by going to the navigation pane: View \textgreater{} Zoom In. Learn these keyboard shortcuts; being able to see what you're typing will help avoid typos \& help us help you.
I think that \textbf{R is your airplane, and the RStudio IDE is your airport}. You are the pilot, and you use R to go places! With practice you'll gain skills and confidence; you can fly further distances and get through tricky situations. You will become an awesome pilot and can fly your plane anywhere. And the RStudio IDE provides support! Runways, communication, community, and other services that makes your life as a pilot much easier. It provides not only the infrastructure but a hub for the community that you can interact with.
An important first question: \textbf{where are we?}
If you've have opened RStudio for the first time, you'll be in your Home directory. This is noted by the \texttt{\textasciitilde{}/} at the top of the console. You can see too that the Files pane in the lower right shows what is in the Home directory where you are. You can navigate around within that Files pane and explore, but note that you won't change where you are: even as you click through you'll still be Home: \texttt{\textasciitilde{}/}.
\includegraphics[width=0.8\linewidth]{img/RStudio_IDE_homedir}
We are going to have our first experience with R through RMarkdown, so let's do the following.
\hypertarget{intro-to-rmarkdown}{%
\section{Intro to RMarkdown}\label{intro-to-rmarkdown}}
An RMarkdown file is a plain text file that allow us to write code and text together, and when it is ``knit'', the code will be evaluated and the text formatted so that it creates a reproducible report or document that is nice to read as a human.
This is really critical to reproducibility, and it also saves time. This document will recreate your figures for you in the same document where you are writing text. So no more doing analysis, saving a plot, pasting that plot into Word, redoing the analysis, re-saving, re-pasting, etc.
Let's experience this a bit ourselves and then we'll talk about it more.
\hypertarget{create-an-rmarkdown-file}{%
\subsection{Create an RMarkdown file}\label{create-an-rmarkdown-file}}
Let's do this together:
File -\textgreater{} New File -\textgreater{} RMarkdown\ldots{} (or alternatively you can click the green plus in the top left -\textgreater{} RMarkdown).
Let's title it ``Testing'' and write our name as author, then click OK with the recommended Default Output Format, which is HTML.
\includegraphics[width=0.8\linewidth]{img/rstudio_new-rmd-doc-html}
OK, first off: by opening a file, we are seeing the 4th pane of the RStudio console, which is essentially a text editor. This lets us organize our files within RStudio instead of having a bunch of different windows open.
Let's have a look at this file --- it's not blank; there is some initial text is already provided for you. Let's have a high-level look through of it:
\begin{itemize}
\tightlist
\item
The top part has the Title and Author we provided, as well as today's date and the output type as an HTML document like we selected above.
\item
There are white and grey sections. These are the 2 main languages that make up an RMarkdown file.
\begin{itemize}
\tightlist
\item
\textbf{Grey sections are R code}
\item
\textbf{White sections are Markdown text}
\end{itemize}
\item
There is black and blue text.
\end{itemize}
\includegraphics[width=0.8\linewidth]{img/rmarkdown}
\hypertarget{knit-your-rmarkdown-file}{%
\subsection{Knit your RMarkdown file}\label{knit-your-rmarkdown-file}}
Let's go ahead and ``Knit'' by clicking the blue yarn at the top of the RMarkdown file.
It's going to ask us to save first, I'll name mine ``testing.Rmd''. Note that this is by default going to save this file in your home directory \texttt{/\textasciitilde{}}. Since this is a testing document this is fine to save here; we will get more organized about where we save files very soon. Once you click Save, the knit process will be able to continue.
OK so how cool is this, we've just made an html file! This is a single webpage that we are viewing locally on our own computers. Knitting this RMarkdown document has rendered --- we also say formatted --- both the Markdown text (white) and the R code (grey), and the it also executed --- we also say ran --- the R code.
Let's have a look at them side-by-side:
\includegraphics[width=0.8\linewidth]{img/rmarkdown_side_by_side}
Let's take a deeper look at these two files. So much of learning to code is looking for patterns.
\hypertarget{markdown-text}{%
\subsection{Markdown text}\label{markdown-text}}
To warm us up for R, let's start by talking about another language, Markdown. This is a formatting language for plain text, and there are only about 15 rules to know.
Notice the syntax for:
\begin{itemize}
\tightlist
\item
\textbf{headers} get rendered at multiple levels: \texttt{\#}, \texttt{\#\#}
\item
\textbf{bold}: \texttt{**word**}
\end{itemize}
There are some good \href{https://github.com/adam-p/markdown-here/wiki/Markdown-Here-Cheatsheet}{cheatsheets} to get you started, and here is one built into RStudio: Go to Help \textgreater{} Markdown Quick Reference
\hypertarget{r-code}{%
\subsection{R code}\label{r-code}}
Let's look at the R code that we see executed in our knitted document.
We see that \texttt{summary(cars)} produces a table
And we see that \texttt{plot(pressure)} produces a plot.
\texttt{cars} and \texttt{pressure} are small datasets that come with R out-of-the-box.
\hypertarget{code-chunks}{%
\subsection{Code chunks}\label{code-chunks}}
Let's start of by looking at the 3 code chunks, which are grey.
Each of them are start by 3 backticks and \texttt{\{r\ label\}}, which signify that there will be R code inside, and they are each given a unique name. Anything inside the brackets (\texttt{\{\ \}}) is instructions for RMarkdown about that code to run. For example:
\begin{itemize}
\tightlist
\item
the first chunk says \texttt{include=FALSE}, and we don't see it included in the HTML document.
\item
the second chunk has no additional instructions, and in the HTML document we see the code and the evaluation of that code (a summary table)
\item
the third chunk says \texttt{echo=FALSE}, and in the HTML document we do not see the code echoed, we only see the plot when the code is executed.
\end{itemize}
There are many more options available and we will explore more as we go.
\hypertarget{naming-code-chunks-deep-thought}{%
\subsubsection{Naming code chunks (Deep thought?)}\label{naming-code-chunks-deep-thought}}
All three chunks say \texttt{r} as the language, and have a label (\texttt{setup}, \texttt{cars}, \texttt{pressure}. This is to help us navigate between them and keep them organized. They are optional, but will become powerful as you become a powerful R user. But if you label your code chunks, you must have unique labels. Otherwise you will see an error when you try to knit:
\begin{verbatim}
processing file: Untitled.Rmd
Error in parse_block(g[-1], g[1], params.src) : duplicate label 'cars'
Calls: <Anonymous> ... process_file -> split_file -> lapply -> FUN -> parse_block
Execution halted
\end{verbatim}
In this case, you read the error message. Not everything immediately looks like something I would know anything about, but pressing on still allows me to identify the problem: ``duplicate label `cars'\,''.
\hypertarget{delete-everything-and-reknit}{%
\subsubsection{Delete everything and reknit}\label{delete-everything-and-reknit}}
R knows that a file with extension .Rmd is a special file to be knit. But it does not rely on any of this stuff that is in the template file.
Do this: delete all the content from this file. You can do this by dragging your cursor to highlight all text, or use the keyboard shortcut Command-A. And then delete. You should now have a blank document.
To demo that it will still knit, let's write \texttt{\#\ Julie\textquotesingle{}s\ workshop\ notes} (with your name) and reknit.
This will be your notes.
The reason we use RMarkdown or an R script is so that we can write down our code once in our script but then can execute it as many times as we want.
\hypertarget{new-code-chunks}{%
\subsubsection{New code chunks}\label{new-code-chunks}}
We can create a new chunk in your RMarkdown first in one of these ways:
\begin{itemize}
\tightlist
\item
click ``Insert \textgreater{} R'' at the top of the editor pane
\item
type by hand
```\{r\}
```
\item
if you haven't deleted a chunk that came with the new file, edit that one
\end{itemize}
\begin{quote}
Cool tip: doesn't have to be only R, other languages supported.
\end{quote}
Now, let's write some code in R. Let's say we want to plot the cars data. I'm going to press enter to to add some extra carriage returns because sometimes I find it easier to look at my code when there is a bit more space, and R lets you use as much whitespace as you would like.
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{plot}\NormalTok{(cars)}
\end{Highlighting}
\end{Shaded}
\includegraphics{R-for-Excel-Users_files/figure-latex/unnamed-chunk-10-1.pdf}
We can knit this and see the plot of cars. This is the same data that we made the summary table with.
\begin{quote}
Troubleshooting: If you could not successfully knit your document without error, Look at your code again. Do you have both open \texttt{(} and close \texttt{)} parentheses? Are your code chunk fences correct?
\end{quote}
\hypertarget{running-r-code}{%
\subsection{Running R code}\label{running-r-code}}
Knitting the document is great, and you can see all your updates rendered nicely. But you can imagine that this would be tedious that if every time you made an update you needed to knit this document. We can run R code in the Console.
TODO: build out more about Console
To run, we need to get what we typed in the the R chunk (the grey R code) down into the console. How do we do it? There are several ways (let's do each of them):
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\tightlist
\item
copy-paste this line into the console.
\item
select the line (or simply put the cursor there), and click `Run'. This is available from
\begin{enumerate}
\def\labelenumii{\alph{enumii}.}
\tightlist
\item
the bar above the file (green arrow)
\item
the menu bar: Code \textgreater{} Run Selected Line(s)
\item
keyboard shortcut: command-return
\end{enumerate}
\item
click the green arrow at the right of the code chunk
\end{enumerate}
\begin{quote}
Troubleshooting: The following error is because you also highlighted and asked to run ```\texttt{\{r\}}, and this is the code fencing, not R code itself.
\end{quote}
\begin{verbatim}
Error: attempt to use zero-length variable name
\end{verbatim}
What is \texttt{plot} anyways? It is a function. Let's talk about that next.
\hypertarget{r-functions}{%
\section{R Functions}\label{r-functions}}
TODO --- add c()?
Like Excel, some of the biggest power in R is that there are built-in functions that you can use in your analyses (and, as we'll see, R users can easily create and share functions, and it is this open source developer and contributor community that makes R so awesome).
R has a mind-blowing collection of built-in functions that are used with the same syntax: function name with parentheses around what the function needs to do what it is supposed to do.
TODO: swap out for simpler
\includegraphics[width=0.6\linewidth]{img/horst-naming-terms}
\texttt{function\_name(argument1\ =\ value1,\ argument2\ =\ value2,\ ...)}. When you see this syntax, we say we are ``calling the function''.
So with \texttt{plot()}, the arguments it requires are \texttt{x} and \texttt{y}, and when we pass \texttt{cars} to plot(), R is able to understand that it should use the two columns in that dataset as x and y.
\hypertarget{help-pages}{%
\section{Help pages}\label{help-pages}}
\emph{TODO - complete}
A good way to learn about functions is to look at the help pages. Let's navigate over to the Help tab and type \texttt{plot}. All help pages will have the same format, here is how I look at it:
The help page tells the name of the package in the top left, and broken down into sections:
\begin{itemize}
\tightlist
\item
Description: An extended description of what the function does.
\item
Usage: The arguments of the function and their default values.
\item
Arguments: An explanation of the data each argument is expecting.
\item
Details: Any important details to be aware of.
\item
Value: The data the function returns.
\item
See Also: Any related functions you might find useful.
\item
Examples: Some examples for how to use the function.
\end{itemize}
When I look at a help page, I start with the description, which might be too in-the-weeds for the level of understanding I need at the offset. For the \texttt{sum} page, it is pretty straight-forward and lets me know that yup, this is the function I want.
I next look at the usage and arguments, which give me a more concrete view into what the function does. This syntax looks a bit cryptic but what it means is that you use it by writing sum, and then passing whatever you want to it in terms of data: that is what the ``\ldots{}'' means. And the ``na.rm=FALSE'' means that by default, it will not remove NAs (I read this as: ``remove NAs? FALSE!'')
Then, I usually scroll down to the bottom to the examples. This is where I can actually see how the function is used, and I can also paste those examples into the Console to see their output. Let's try it:
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{plot}\NormalTok{(sin, }\OperatorTok{-}\NormalTok{pi, }\DecValTok{2}\OperatorTok{*}\NormalTok{pi)}
\end{Highlighting}
\end{Shaded}
\includegraphics{R-for-Excel-Users_files/figure-latex/plot-help-example-1.pdf}
Let's try another function. In Excel, there is a ``SUM'' function to calculate a total. Let's expect that there is the same in R. I will type this into the Console:
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{sum}\NormalTok{(}\DecValTok{1}\NormalTok{, }\DecValTok{2}\NormalTok{, }\DecValTok{3}\NormalTok{)}
\end{Highlighting}
\end{Shaded}
R is case-sensitive. So ``sum'' is a completely different thing to ``Sum'' or ``SUM''. And this is true for the names of functions, data sets, variable names, and data itself (``blue'' vs ``Blue'').
Awesome. Let's try this on our \texttt{cars} data
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{sum}\NormalTok{(cars)}
\end{Highlighting}
\end{Shaded}
Alright. What is this number? It is the sum of ALL of the data in the \texttt{cars} dataset. Maybe in some analysis this would be a useful operation, but I would worry about the way your data is set up and your analyses if this is ever something you'd want to do. More likely, you'd want to take the sum of a specific column. In R, you can do that with the \texttt{\$} operator.
Let's say we want to calculate the total distance:
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{sum}\NormalTok{(cars}\OperatorTok{$}\NormalTok{dist)}
\end{Highlighting}
\end{Shaded}
Let's do one more: try using \texttt{c()} which combines values together.
So let's create a new R code chunk. And we'll write:
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{c}\NormalTok{(}\DecValTok{1}\NormalTok{, }\DecValTok{7}\OperatorTok{:}\DecValTok{9}\NormalTok{)}
\end{Highlighting}
\end{Shaded}
\begin{verbatim}
## [1] 1 7 8 9
\end{verbatim}
So you can see that this combines these values all into the same place, which is called a vector here. But let's learn more about what this does.
Let's do one more. Not all functions have (or require) arguments:
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{date}\NormalTok{()}
\end{Highlighting}
\end{Shaded}
\begin{verbatim}
## [1] "Thu Jan 9 09:21:09 2020"
\end{verbatim}
Let's try combining some of these things together.
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{c}\NormalTok{(}\StringTok{"R is awesome"}\NormalTok{, }\KeywordTok{date}\NormalTok{())}
\end{Highlighting}
\end{Shaded}
\begin{verbatim}
## [1] "R is awesome" "Thu Jan 9 09:21:09 2020"
\end{verbatim}
We can also save this as an object.
\hypertarget{assigning-objects-with--}{%
\section{\texorpdfstring{Assigning objects with \texttt{\textless{}-}}{Assigning objects with \textless{}-}}\label{assigning-objects-with--}}
TODO refine
\includegraphics[width=0.6\linewidth]{img/horst-naming-terms}
This might be a really important thing that we want to be able to work with later. We can save this as its own object.
\begin{Shaded}
\begin{Highlighting}[]
\NormalTok{my_object <-}\StringTok{ }\KeywordTok{c}\NormalTok{(}\StringTok{"R is awesome"}\NormalTok{, }\KeywordTok{date}\NormalTok{())}
\end{Highlighting}
\end{Shaded}
This is a big difference with Excel, where you usually identify data by its location on the grid, like \texttt{\$A1:D\$20}. (You can do this with Excel by naming ranges of cells, but many people don't do this.)
Data can be a variety of formats, like numeric and text.
We do this by writing the name along with the assignment operator \texttt{\textless{}-}
\begin{Shaded}
\begin{Highlighting}[]
\NormalTok{sum_dist <-}\StringTok{ }\KeywordTok{sum}\NormalTok{(cars}\OperatorTok{$}\NormalTok{dist)}
\end{Highlighting}
\end{Shaded}
And we can execute it. In my head I hear ``sum\_dist gets 2149''.
Object names can be whatever you want, although they cannot start with a digit and cannot contain certain other characters such as a comma or a space. Different folks have different conventions; you will be wise to adopt a \href{http://en.wikipedia.org/wiki/Snake_case}{convention for demarcating words} in names.
\begin{Shaded}
\begin{Highlighting}[]
\CommentTok{# i_use_snake_case}
\CommentTok{# other.people.use.periods}
\CommentTok{# evenOthersUseCamelCase}
\end{Highlighting}
\end{Shaded}
\hypertarget{console-vs.rmarkdownr-script}{%
\section{Console vs.~RMarkdown/R script}\label{console-vs.rmarkdownr-script}}
\hypertarget{r-code-in-the-console}{%
\section{R code in the Console}\label{r-code-in-the-console}}
There is another way to get to the help pages besides clicking on the Help tab --- we can write this in R with \texttt{?}.
Let's try this with\ldots{}c()?
Every time we run R code, it is sent to the Console.
\hypertarget{r-packages}{%
\section{R Packages}\label{r-packages}}
TODO: update, with here()
So far we've been using a couple functions from base R, such as \texttt{sum()} and \texttt{plot()}. But, one of the amazing things about R is that a vast user community is always creating new functions and packages that expand R's capabilities. In R, the fundamental unit of shareable code is the package. A package bundles together code, data, documentation, and tests, and is easy to share with others. They increase the power of R by improving existing base R functionalities, or by adding new ones.
The traditional place to download packages is from CRAN, the \href{https://cran.r-project.org/}{Comprehensive R Archive Network}, which is where you downloaded R. CRAN is like a grocery store for vetted R packages.
You can also install packages from GitHub, which we'll do tomorrow.
You don't need to go to CRAN's website to install packages, this can be accomplished within R using the command \texttt{install.packages("package-name-in-quotes")}. Let's install our first package \texttt{here}. You need to use quotes around the package name.
Do this in the Console instead of in your RMarkdown file because we don't want this to load every time:
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{install.packages}\NormalTok{(}\StringTok{"here"}\NormalTok{)}
\end{Highlighting}
\end{Shaded}
Now we've installed the package, but we need to tell R that we are going to use the functions within the \texttt{praise} package. We do this by using the function \texttt{library()}.
In my mind, this is analogous to needing to wire your house for electricity: this is something you do once; this is \texttt{install.packages}. But then you need to turn on the lights each time you need them (R Session).
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{library}\NormalTok{(here)}
\end{Highlighting}
\end{Shaded}
Now that we've loaded the \texttt{praise} package, we can use the single function in the package, \texttt{praise()}, which returns a randomized praise to make you feel better.
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{here}\NormalTok{()}
\end{Highlighting}
\end{Shaded}
\begin{verbatim}
## [1] "/Users/lowndes/github/rstudio-conf-2020/r-for-excel"
\end{verbatim}
\hypertarget{recap}{%
\section{Recap}\label{recap}}
R console executes
running code
knitting
Learn more: \url{http://rmarkdown.rstudio.com/}
\hypertarget{activity}{%
\subsubsection{Activity}\label{activity}}
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\tightlist
\item
In Markdown write some italic text, make a numbered list, and add a few subheaders.
Use the Markdown Quick Reference (in the menu bar: Help \textgreater{} Markdown Quick Reference).
\item
Reknit your html file.
\end{enumerate}
\hypertarget{restart-r}{%
\subsubsection{Restart R}\label{restart-r}}
To end our work from this session, save, knit, and then restart R (Go to the top menus: Session \textgreater{} Restart R.)
Notice that now with a clean workspace, if I knit my document instead of sending code to the Console, my objects (like \texttt{mean\_dist}) don't show up in my Environment. This is because R isn't actually running this in this R session, it is actually spinning up a clean session to knit my document. This is important for reproducible analyses because I don't want the success of this analysis to be dependent on some weird setting I have on my computer that will make Future Me or Future Us not able to run or understand these important analyses. Having RMarkdown be self-contained in this way helps you develop good habits for reproducibility.
\hypertarget{what-is-rmarkdown-1-minute-video}{%
\subsection{What is RMarkdown? (1-minute video)}\label{what-is-rmarkdown-1-minute-video}}
Let's watch this to demonstrate all the amazing things you can now do:
\href{https://vimeo.com/178485416}{What is RMarkdown?}
\hypertarget{r-console}{%
\section{R Console}\label{r-console}}
OK let's go into the Console, where we interact with the live R process.
We can do math:
\begin{Shaded}
\begin{Highlighting}[]
\DecValTok{52}\OperatorTok{*}\DecValTok{40}
\DecValTok{365}\OperatorTok{/}\DecValTok{12}
\end{Highlighting}
\end{Shaded}
But like Excel, the power comes not from doing small operations by hand (like 8*22.3), it's by being able to operate on whole suites of numbers and datasets. In Excel, data are stored in the spreadsheet. In R, they are stored in objects, which are often vectors or dataframes. They are rectangular.
\hypertarget{viewing-data-in-r}{%
\subsection{Viewing data in R}\label{viewing-data-in-r}}
Let's have a look at some data in R. Unlike Excel, R comes out-of-the-box with several built-in data sets that we can look at and work with.
One of these datasets is called \texttt{cars}. If I write this in the Console, it will print the data in the console.
\begin{Shaded}
\begin{Highlighting}[]
\NormalTok{cars}
\end{Highlighting}
\end{Shaded}
This returns data. To me this is not super interesting data, but I can appreciate that there are different variables listed as column headers and then numeric values for each type of row observation. (Unfortunately I don't know if these are different cars or trials or conditions but we won't focus on that for now).
I can also use RStudio's Viewer to see this in a more familiar-looking format. Let's type this --- and make sure it's a capital V and open and closed parentheses:
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{View}\NormalTok{(cars)}
\end{Highlighting}
\end{Shaded}
This opens the fourth pane of the RStudio IDE; when you work in R you will have all four panes open so this will become a very comforting setup for you.
\begin{quote}
\textbf{\emph{Aside}} The basic R data structure is a vector. You can think of a vector like a column in an Excel spreadsheet with the limitation that all the data in that vector must be of the same type. If it is a character vector, every element must be a character; if it is a logical vector, every element must be TRUE or FALSE; if it's numeric you can trust that every element is a number. There's no such constraint in Excel: you might have a column which has a bunch of numbers, but then some explanatory test intermingled with the numbers. This isn't allowed in R. - \href{https://blog.shotwell.ca/posts/r_for_excel_users/}{Gordon Shotwell}
\end{quote}
In the Viewer I can do things like filter or sort. This does not do anything to the actual data, it just changes how you are viewing the data. So even as I explore it, I am not editing or manipulating the data.
Notice that as I start typing \texttt{sum\_dist} in the Console, there will be options to auto-fill. This is RStudio helping you out, which is great because we all are prone to typos. I actually have to ignore the help to try to force a typo:
\begin{Shaded}
\begin{Highlighting}[]
\NormalTok{sumdist}
\CommentTok{# Error: object 'sumdist' not found}
\end{Highlighting}
\end{Shaded}
OK this is an error, but I didn't break R --- error messages are your friends.
The first thing to do with an error message is read it. Yes it's in angry red text and it's unexpected --- but most error messages are doing their best to help you solve the problem. And you'll get more familiar with they way they tell you. By saying ``object `sumdist' not found'' alerts me immediately to the fact that this thing I think exists R doesn't think exists --- so maybe it's a typo or not loaded?
\hypertarget{error-messages-are-your-friends}{%
\subsection{Error messages are your friends}\label{error-messages-are-your-friends}}
As \href{https://stat545.com/r-basics.html}{Jenny Bryan says}:
\begin{quote}
Implicit contract with the computer / scripting language: Computer will do tedious computation for you. In return, you will be completely precise in your instructions. Typos matter. Case matters. Pay attention to how you type.
\end{quote}
Remember that this is a language, not unsimilar to English! There are times you aren't understood -- it's going to happen. There are different ways this can happen. Sometimes you'll get an error. This is like someone saying `What?' or `Pardon'? Error messages can also be more useful, like when they say `I didn't understand what you said, I was expecting you to say blah'. That is a great type of error message. Error messages are your friend. Google them (copy-and-paste!) to figure out what they mean.
And also know that there are errors that can creep in more subtly, when you are giving information that is understood, but not in the way you meant. Like if I am telling a story about suspenders that my British friend hears but silently interprets in a very different way (true story). This can leave me thinking I've gotten something across that the listener (or R) might silently interpreted very differently. And as I continue telling my story you get more and more confused\ldots{} Clear communication is critical when you code: write clean, well documented code and check your work as you go to minimize these circumstances!
\begin{quote}
Shortcuts
You will make lots of assignments and the operator \texttt{\textless{}-} is a pain to type. Don't be lazy and use \texttt{=}, although it would work, because it will just sow confusion later. Instead, utilize \textbf{RStudio's keyboard shortcut: Alt + - (the minus sign)}.
Notice that RStudio automagically surrounds \texttt{\textless{}-} with spaces, which demonstrates a useful code formatting practice. Code is miserable to read on a good day. Give your eyes a break and use spaces.
RStudio offers many handy \href{https://support.rstudio.com/hc/en-us/articles/200711853-Keyboard-Shortcuts}{keyboard shortcuts}. Also, Alt+Shift+K brings up a keyboard shortcut reference card.
\end{quote}
\begin{quote}
My most common shortcuts include command-Z (undo), and combinations of arrow keys in combination with shift/option/command (moving quickly up, down, sideways, with or without highlighting.
\end{quote}
\hypertarget{clearing-the-environment}{%
\section{Clearing the environment}\label{clearing-the-environment}}
Now look at the objects in your environment (workspace) -- in the upper right pane. The workspace is where user-defined objects accumulate.
For reproducibility, it is critical that you delete your objects and restart your R session frequently. You don't want your whole analysis to only work in whatever way you've been working right now --- you need it to work next week, after you upgrade your operating system, etc. Restarting your R session will help you identify and account for anything you need for your analysis.
We will keep coming back to this theme but let's restart our R session together: Go to the top menus: Session \textgreater{} Restart R.
Don't save the workspace!
So this is great, but if we were going to do any kind of real analysis, we need to be able to write it in a document rather than this command line prompt in the Console. Let's do something much more interesting and really start feeling its power.
\hypertarget{setup-git-github}{%
\section{Setup Git \& GitHub}\label{setup-git-github}}
Before we break, we are going to set up Git and GitHub for our next lesson (and if you have trouble please stay a few extra minutes).
We're going to switch gears from R for a moment and set up Git and GitHub, which we will be using along with R and RStudio for the rest of the workshop. This set up is a one-time thing! You will only have to do this once per computer. We'll walk through this together.
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\tightlist
\item
We will use the \texttt{usethis} package to configure \textbf{git} with global commands, which means it will apply `globally' to all files on your computer, rather than to a specific folder.
\end{enumerate}
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{install.packages}\NormalTok{(}\StringTok{"usethis"}\NormalTok{)}
\KeywordTok{library}\NormalTok{(usethis)}
\KeywordTok{use_git_config}\NormalTok{(}\DataTypeTok{user.name =} \StringTok{"jules32"}\NormalTok{, }\DataTypeTok{user.email =} \StringTok{"[email protected]"}\NormalTok{)}
\end{Highlighting}
\end{Shaded}
\emph{BACKUP PLAN} If \texttt{usethis} fails, the following is the classic approach to configuring \textbf{git}. Open the Git Bash program (Windows) or the Terminal (Mac) and type the following:
\begin{verbatim}
# display your version of git
git --version
# replace USER with your Github user account
git config --global user.name USER
# replace [email protected] with the email you used to register with Github
git config --global user.email [email protected]
# list your config to confirm user.* variables set
git config --list
\end{verbatim}
Not only have you just set up git as a one-time-only thing, you have just used the command line. We don't have time to learn much of the command line today, but you just successfully used it following explicit instructions, which is huge! There are great resources for learning the command line, check out \href{http://remi-daigle.github.io/2016-04-15-UCSB/shell/}{this tutorial from SWC at UCSB}.
\hypertarget{troubleshooting}{%
\subsection{Troubleshooting}\label{troubleshooting}}
If you have problems setting up git, please see the \href{http://happygitwithr.com/troubleshooting.html}{Troubleshooting section} in Jenny Bryan's amazing \href{http://happygitwithr.com}{HappyGitWithR}.
\hypertarget{newish-error-on-a-mac}{%
\subsubsection{New(ish) Error on a Mac}\label{newish-error-on-a-mac}}
We've also seen the following errors from RStudio:
\begin{verbatim}
error key does not contain a section --global terminal
\end{verbatim}
and