--- session: "Session 1" title: "R Setup, Quarto, and Basic Data Workflow" subtitle: "From individual code cells to a reproducible analysis" format: html: toc: true code-copy: true code-overflow: wrap execute: echo: true warning: false message: false --- ::: {.callout-important} ## Work together Work through this exercise with the person next to you. Compare what you see in RStudio and help each other when something behaves differently. If you get stuck and cannot see how to move forward, **indicate that you need help** so that a TA or instructor can assist you. ::: ## Learning goals After this exercise, you should be able to: - orient yourself in **RStudio** and distinguish the editor, R console, Environment, Files, and Viewer; - run R code interactively and execute individual code cells in a Quarto (`.qmd`) document; - edit a Quarto document in **Visual mode** and add text, links, lists, and R code cells; - create, inspect, and remove R objects in memory; - install and load R packages; - create and inspect data frames and tibbles; - save tabular data to disk and load data from a local file or a URL; - distinguish objects in the current R session from files stored on disk; - restart R and reproduce the complete analysis by rendering the document from top to bottom. ::: {.callout-note} ## How to work through this exercise For now, **do not render the complete document** and do not enable **Render on Save**. Work through the document from top to bottom. Whenever you encounter an R code cell, **run that cell yourself** and inspect what happens in RStudio. This lets you see how code changes the current R session step by step. At the end of the exercise, you will restart R and **render the complete document**. That final render checks whether your analysis is reproducible from a clean session. ::: ## Get oriented in RStudio This exercise focuses on **RStudio**. If you are already more familiar with **Positron** or **Visual Studio Code**, you may use one of those instead; the same basic ideas apply, although buttons and pane names differ. Open the folder containing this `.qmd` file as an **RStudio Project**. You will mainly work with these parts of RStudio: ![](https://raw.githubusercontent.com/fs-ise/machine-learning-for-big-data/main/images/rstudio-overview.png) At the top of the Source editor, switch the document from **Source** to **Visual** mode. Use Visual mode for the editing tasks in this exercise. ## Test the R setup Start with a simple R command: ```{r} R.version.string ``` **Run this code cell now:** click the **green play button** at the top-right of the code cell. This runs the code in your current R session without rendering the complete document. Now use R as a calculator. Run this cell yourself: ```{r} 3 * 5 7 + 2 100 / 5 99 - 1 ``` Try a few functions: ```{r} sqrt(144) log(10) mean(c(4, 6, 8, 10)) ``` ::: {.callout-tip} ### Exercise: console versus document 1. Run `2^10` directly in the **Console**. 2. Add a line below that computes `17 * 23`. 3. Run the code cell from the document using its play button. 4. Save the `.qmd` file. Do **not** render the document yet. ```{r} # YOUR CODE HERE: calculate 17 * 23 ``` What is the difference between code typed only in the Console and code stored in this document? **Your answer:** *Write your answer here.* ::: ## Edit a Quarto document A Quarto document combines formatted text, links, lists, code, and computational results. Before working with data, practice adding these elements in **Visual mode**. Replace the placeholder below with your own content. ::: {.callout-tip} ### Exercise: add content in Visual mode Using the Visual editor toolbar and menus, add all of the following below the placeholder: - a **heading** called `My first Quarto section`; - a sentence containing a **link** to ; - a **bullet list** with at least three items; - an **R code cell** that calculates `10 + 20`, with evaluation enabled; - a second **R code cell** that contains `print("This should not run")` and has evaluation disabled. Insert the R code cells using the **Insert** dropdown in the Visual editor. For the second cell, use the code-cell options dropdown to set **`eval: false`**. Run the first cell and confirm that it produces a result. The second cell should remain visible as code but should not execute when the document is later rendered. ::: **--- ADD YOUR QUARTO CONTENT HERE ---** ## Create variables and inspect memory R stores values in named **objects** in the current R session. The assignment operator is `<-`. Run this cell: ```{r} a <- 3 * 5 b <- 7 + 2 c <- a * b c ``` Create objects of different types: ```{r} course <- "Machine Learning for Big Data" session_number <- 1 setup_complete <- TRUE ``` List the objects currently in memory: ```{r} ls() ``` Inspect individual objects: ```{r} class(course) class(session_number) class(setup_complete) ``` You should also see these objects in RStudio's **Environment** pane. ::: {.callout-tip} ### Exercise: create and remove an object 1. Create an object called `answer` containing the result of `6 * 7`. 2. Confirm that it appears in `ls()` and in the Environment pane. 3. Remove only `answer` with `rm()`. 4. Confirm that it has disappeared. ```{r} # YOUR CODE HERE: create answer # YOUR CODE HERE: inspect the workspace # YOUR CODE HERE: remove answer # YOUR CODE HERE: inspect the workspace again ``` ::: ## Install and load packages R packages add functions and datasets to R. **Installing** and **loading** are different operations: - `install.packages()` installs a package on your computer, usually only once; - `library()` loads an installed package into the **current R session**. Install the tidyverse from the **Console** if it is not already installed: ```{r} #| eval: false install.packages("tidyverse") ``` Package installation should not be part of code that runs every time an analysis is rendered. Once installed, load the package in the document: ```{r} library(tidyverse) ``` Check the installed version: ```{r} packageVersion("tidyverse") ``` ::: {.callout-tip} ### Exercise: package help Open the help page for `read_csv()` interactively: ```{r} #| eval: false ?read_csv ``` Find the argument used to specify how missing values are represented in an input file. ::: ## Work with a data frame A **data frame** represents rectangular tabular data: rows are observations and columns are variables. Create a small data frame: ```{r} students <- data.frame( name = c("Alex", "Bao", "Casey", "Dina", "Emil"), study_hours = c(2.5, 4.0, 3.5, 5.5, 1.5), score = c(68, 82, 76, 91, 61), passed = c(TRUE, TRUE, TRUE, TRUE, FALSE) ) students ``` Inspect its structure: ```{r} class(students) str(students) dim(students) names(students) head(students) ``` The tidyverse can work directly with ordinary R data frames. It also commonly uses **tibbles**, which are modern data-frame subclasses. ```{r} students_tbl <- as_tibble(students) class(students_tbl) is.data.frame(students_tbl) glimpse(students_tbl) ``` ::: {.callout-tip} ### Exercise: inspect the data Use R functions to answer the following questions: - How many rows does `students` have? **Your answer:** *Write your answer here.* - How many columns does it have? **Your answer:** *Write your answer here.* - What is the mean of `score`? **Your answer:** *Write your answer here.* - What are the values in the `name` column? **Your answer:** *Write your answer here.* ```{r} # YOUR CODE HERE: number of rows # YOUR CODE HERE: number of columns # YOUR CODE HERE: mean score # YOUR CODE HERE: names of students ``` ::: ## Display a data frame in RStudio So far, you have inspected data by printing it in the Console or in this document. RStudio also provides a graphical data viewer, which is useful for browsing larger tables. Run this interactively: ```{r} #| eval: false View(students) ``` You can also click the `students` object in the **Environment** pane. Compare this with: ```{r} head(students, 3) summary(students) glimpse(students) ``` ::: {.callout-tip} ### Exercise: compare different views Compare: - printing `students`; - `glimpse(students)`; - RStudio's graphical data viewer. Which is most useful for quickly checking **values**, **column types**, and **larger tables**? **Your answer:** *Write your answer here.* ::: ## Move between objects and files You have so far worked mainly with **objects**. Objects such as `students` live in the current R session and are visible in the Environment pane. **Files** are different: they are stored on disk and remain there after the R session ends. Your `.qmd` document is a file; a CSV file is another example. For this course, open the exercise folder as an RStudio Project and use **relative paths** rather than changing the working directory with `setwd()`. Check the current working directory: ```{r} getwd() ``` Save the `students` object as a CSV file in the project folder: ```{r} write_csv(students, "students.csv") ``` Confirm that the file exists: ```{r} file.exists("students.csv") ``` Find `students.csv` in RStudio's **Files** pane and inspect it. ::: {.callout-tip} ### Exercise: file versus memory At this point, the same data exists in two different forms: - `students` is an **object in memory**; - `students.csv` is a **file on disk**. Remove the in-memory object: ```{r} rm(students) ls() ``` Now check whether the file still exists: ```{r} file.exists("students.csv") ``` Explain why the result is `TRUE` even though `students` no longer appears in `ls()`. ::: ## Load data from a file or URL Read the local CSV file back into memory: ```{r} students <- read_csv("students.csv") ``` Inspect the result: ```{r} students glimpse(students) class(students) is.data.frame(students) ``` Notice that `read_csv()` returns a **tibble**, and `is.data.frame(students)` is still `TRUE`. `read_csv()` can also load a CSV file directly from a **URL**. For example: ```{r} penguins <- read_csv( "https://raw.githubusercontent.com/allisonhorst/palmerpenguins/main/inst/extdata/penguins.csv" ) glimpse(penguins) ``` The basic workflow is the same: `read_csv()` reads data from a source and creates an object in the current R session. ::: {.callout-tip} ### Exercise: modify and save data Create a new object called `students_updated` in which every student receives 2 additional points. Then save it as `students_updated.csv`. Hints: use `mutate()` and `write_csv()`. ```{r} # YOUR CODE HERE: create students_updated # YOUR CODE HERE: save it as students_updated.csv # YOUR CODE HERE: confirm that the file exists ``` ::: ## Clean the workspace Remove one object: ```{r} rm(students_tbl) ``` To remove **all user-created objects** from the current R session, you can run: ```{r} #| eval: false rm(list = ls()) ``` This affects objects in memory; it does **not** delete your `.qmd` or CSV files. ::: {.callout-warning} ### Do not rely on a saved workspace The durable record of your analysis should be your **code and data files**, not whatever happens to be present in memory. Restarting R helps reveal missing steps and hidden dependencies. ::: ## Final reproducibility check: render the complete document So far, you have developed the analysis by executing individual code cells. Now test whether the document works as a complete, reproducible analysis. 1. Save the `.qmd` file. 2. Restart R using **Session → Restart R**. 3. Run `ls()` in the Console and confirm that your old objects are gone. 4. Click **Render** to execute the complete document from top to bottom. 5. Confirm that the document renders successfully without depending on objects from your previous session. 6. Confirm that `students.csv` and `students_updated.csv` exist in the project folder. 7. Inspect the rendered HTML in the Viewer. ```{r} #| eval: false # Run interactively immediately after restarting R, before rendering: ls() ``` ::: {.callout-note} ### Interactive execution versus rendering Use **individual code-cell execution** while developing and exploring an analysis. Use **Render** to verify that the complete document can be reproduced from a clean R session. Once you are comfortable with this distinction, features such as **Render on Save** can be convenient in later analyses. ::: ::: {.callout-tip} ### Optional challenge Without looking back at the earlier code, write the shortest sequence of commands that: 1. loads the tidyverse; 2. reads `students.csv`; 3. displays the first three rows; 4. lists the objects in memory; 5. removes the loaded data frame again. ```{r} # YOUR CODE HERE ``` ::: ## Further learning and inspiration - [RStudio User Guide: Get Started](https://docs.posit.co/ide/user/ide/get-started/) — IDE panes, packages, environment, projects, and a first analysis. - [R for Data Science (2e): Workflow — scripts and projects](https://r4ds.hadley.nz/workflow-scripts) — reproducible projects, relative paths, clean sessions, and scripts as the source of truth. - [Quarto: Computations with R](https://quarto.org/docs/get-started/computations/rstudio.html) — executable R code in `.qmd` documents and rendering workflows. - [Positron: First data analysis with R in a Quarto document](https://positron.posit.co/tutorial-get-started-quarto.html) — an alternative IDE workflow for R and Quarto. - [Visual Studio Code: R in Visual Studio Code](https://code.visualstudio.com/docs/languages/r) — R support in VS Code for students already familiar with that environment.