Merge pull request #413 from UBC-DSCI/patch-versions-setup

Patch versions setup

Author: ttimbers

setup.Rmd

@@ -2,7 +2,7 @@
 
 ## Overview
 
-In this chapter, you'll learn how to install all of that software 
+In this chapter, you'll learn how to install all of the software 
 needed to do the data science covered in this book on your own computer.
 
 ## Chapter learning objectives
@@ -16,14 +16,14 @@ By the end of the chapter, readers will be able to do the following:
 ## Installing software on your own computer
 
 This section will provide instructions for installing the software required by 
-this book on our own computers. 
+this book on your own computer. 
 Given that installation instructions can vary widely based on the computer setup,
 we have created instructions for multiple operating systems.
 In particular, the installation instructions below have been verified to work
 on a computer that:
 
 - runs one of the following operating systems: Ubuntu 20.04, macOS Big Sur (version 11.4.x or 11.5.x), Windows 10 Professional, Enterprise or Education (version 2004, 20H2, or 21H1),
-- can connect to networks via a wireless connection,
+- has a connection to the internet,
 - uses a 64-bit CPU,
 - uses English as the default language.
 
@@ -58,9 +58,10 @@ sudo apt install git
 
 ### Miniconda
 
-To run Jupyter notebooks on our computers, 
-we will need to install the web-based platform JupyterLab. 
-But JupyterLab relies on Python; we can install this via
+To run Jupyter notebooks on your computer, 
+you will need to install the web-based platform JupyterLab. 
+But JupyterLab relies on Python, so we need to install Python first.
+We can install Python via
 the \index{miniconda} [miniconda Python package distribution](https://docs.conda.io/en/latest/miniconda.html).
 
 **Windows:** To install miniconda on Windows, download 
@@ -73,35 +74,57 @@ by opening the Start Menu and searching for the program called
 When this opens, you will see a prompt similar to 
 `(base) C:\Users\your_name`. 
 
-**MacOS:** To install miniconda on MacOS, download 
+**MacOS:** To install miniconda on MacOS, you will need to use a different 
+installation method depending on the type of processor chip your computer has.
+
+If your Mac computer has an Intel x86 processor chip you can download 
 the [latest Python 64-bit version from here](https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.pkg). 
 After the download has finished, run the installer and accept the default 
 configuration for all pages.
 
-**Ubuntu:** To install miniconda on Ubuntu, we first download
+If your Mac computer has an Apple M1 processor chip you can download 
+the [latest Python 64-bit version from here](https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh).
+After the download has finished, you need to run the downloaded script in the terminal using a command
+like:
+
+```
+bash path/to/Miniconda3-latest-MacOSX-arm64.sh
+```
+
+Make sure to replace `path/to/` with the path of the folder
+containing the downloaded script. Most computers will save downloaded files to the `Downloads` folder. 
+If this is the case for your computer, you can run the script in the terminal by typing:
+
+```
+bash Downloads/Miniconda3-latest-MacOSX-arm64.sh
+```
+
+The instructions for the installation will then appear. 
+Follow the prompts and agree to accepting the license,
+the default installation location,
+and to running `conda init`, which makes `conda` available from the terminal.
+
+**Ubuntu:** To install miniconda on Ubuntu, first download
 the [latest Python 64-bit version from here](https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh). 
 After the download has finished, open the terminal and execute the following 
-commands:
+command:
 
 ```
 bash path/to/Miniconda3-latest-Linux-x86_64.sh
 ```
 
-> **Note:** Most often, this file is downloaded to the Downloads directory, 
-and thus the command will look like this:
-> ```
-> bash Downloads/Miniconda3-latest-Linux-x86_64.sh
-> ```
-
+Make sure to replace `path/to/` with the path of the folder containing the downloaded
+script. Most often this file will be downloaded to the `Downloads` folder.
+If this is the case for your computer, you can run the script in the terminal by typing:
 
-The instructions for the installation will then appear:
-
-(1) Press Enter.
-(2) Once the license agreement shows, you can press space scroll down or press `q` to skip reading it.
-(3) Type `yes` and press enter to accept the license agreement.
-(4) Press Enter to accept the default installation location.
-(5) Type `yes` and press enter to instruct the installer to run `conda init`, which makes `conda` available from the terminal/shell.
+```
+bash Downloads/Miniconda3-latest-Linux-x86_64.sh
+```
 
+The instructions for the installation will then appear. 
+Follow the prompts and agree to accepting the license,
+the default installation location,
+and to running `conda init`, which makes `conda` available from the terminal.
 
 ### JupyterLab
 
@@ -121,52 +144,64 @@ tab in your default browser with the JupyterLab interface. To exit out of
 JupyterLab you can click `File -> Shutdown`, or go to the terminal from which 
 you launched JupyterLab, hold `Ctrl`, and press `C` twice.
 
-### R and the IRkernel
-
-To have R \index{R!installation} available to you in JupyterLab, 
-you will need to install the R programming language and the \index{kernel!installation} IRkernel R package. 
-To install these, type the following into 
-the Anaconda Prompt (Windows) or terminal (MacOS and Ubuntu):
-
-```
-conda install -c conda-forge -y r-base">=4.1.1"
-conda install -c conda-forge -y r-irkernel
-```
-
-To improve the experience of using R in JupyterLab, we will add an extension 
-that allows us to set up keyboard shortcuts for inserting text.
+To improve the experience of using R in JupyterLab, you should also add an extension 
+that allows you to set up keyboard shortcuts for inserting text.
 By default, 
 this extension creates shortcuts for inserting two of the most common R 
 operators: `<-` and `|>`. Type the following in the Anaconda Prompt (Windows)
-or terminal (MacOS and Ubuntu) and press  enter:
+or terminal (MacOS and Ubuntu) and press enter:
 
 ```
 jupyter labextension install @techrah/text-shortcuts
 ```
 
-### R packages
+### R, R packages, and the IRkernel 
 
-To install the packages \index{package} used in this book, 
-type the following in the Anaconda Prompt (Windows) 
-or terminal (MacOS and Ubuntu) and press enter:
+To have the software \index{R!installation} used in this book available to you in JupyterLab, 
+you will need to install the R programming language,
+several R packages,
+and the \index{kernel!installation} IRkernel.
+To install versions of these that are compatible with the accompanying worksheets, 
+type the command shown below into the Anaconda Prompt (Windows) 
+or terminal (MacOS and Ubuntu). 
 
 ```
-conda install -c conda-forge -y \
-  r-cowplot \
-  r-ggally \
-  r-gridextra \
-  r-kknn \
-  r-rodbc \
-  r-rpostgres \
-  r-rsqlite \
-  r-scales \
-  r-testthat \
-  r-tidymodels \
-  r-tidyverse \
-  r-tinytex \
-  unixodbc
+conda env update --file https://raw.githubusercontent.com/UBC-DSCI/data-science-a-first-intro-worksheets/main/environment.yml
 ```
 
+This command installs the specific R and package versions specified in
+the `environment.yml` file found in 
+[the worksheets repository](https://ubc-dsci.github.io/data-science-a-first-intro-worksheets).
+We will always keep the versions in the `environment.yml` file updated
+so that they are compatible with the exercise worksheets that accompany the book.
+
+> You can also install the *latest* version of R 
+> and the R packages used in this book by typing the commands shown below 
+> in the Anaconda Prompt (Windows) 
+> or terminal (MacOS and Ubuntu) and pressing enter.
+> **Be careful though:** this may install package versions that are
+> incompatible with the worksheets that accompany the book; the automated
+> exercise feedback might tell you your answers are not correct even though
+> they are!
+> 
+> ```
+> conda install -c conda-forge -y \
+>   r-base \
+>   r-cowplot \
+>   r-ggally \
+>   r-gridextra \
+>   r-irkernel \
+>   r-kknn \
+>   r-rpostgres \
+>   r-rsqlite \
+>   r-scales \
+>   r-testthat \
+>   r-tidymodels \
+>   r-tidyverse \
+>   r-tinytex \
+>   unixodbc
+> ```
+
 ### LaTeX
 
 To be able to render `.ipynb` files to `.pdf` you need to install a LaTeX 
@@ -232,8 +267,10 @@ to save and close the file.
 
 It is good practice to restart all the programs you used when installing this
 software stack before you proceed to doing your data analysis.
+This includes restarting JupyterLab as well as the terminal (MacOS and Ubuntu) 
+or the Anaconda Prompt (Windows).
 This will ensure all the software and settings you put in place are 
-correctly sourced. This includes JupyterLab, terminal or Anaconda Prompt.
+correctly sourced. 
 
 ## Downloading the worksheets for this book