{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "# Setting Up Your Data Science Tool Stack\n",
        "\n",
        "Read and complete this guide as part of your first homework. We will\n",
        "also be reviewing this in class.\n",
        "\n",
        "**Your stack:**\n",
        "\n",
        "If you already have these installed, you can skip the setup\n",
        "\n",
        "-   R and RStudio: the R language and its dedicated editor\n",
        "-   Python and Conda: the Python language and its package/environment\n",
        "    manager\n",
        "-   VS Code: a general editor for Python, notebooks, and Quarto\n",
        "-   Quarto: a publishing system for reports, slides, and websites\n",
        "-   Jupyter: interactive notebooks that mix code and text\n",
        "\n",
        "**Where to go:**\n",
        "\n",
        "-   macOS users: the section “macOS Setup”\n",
        "-   Windows users: choose “Native Windows”, “WSL”, or both\n",
        "\n",
        "# Overview and Core Concepts\n",
        "\n",
        "## What is an interpreter?\n",
        "\n",
        "-   An interpreter is a program that reads your source code and runs it\n",
        "    directly, line by line, at run time.\n",
        "-   There is no separate “build” step: you hand it a script and it\n",
        "    executes right away.\n",
        "-   Contrast: compiled languages (C, C++) are first translated into a\n",
        "    standalone executable, then run.\n",
        "-   R and Python are interpreted languages: your code runs through the\n",
        "    `R` or `python` interpreter program.\n",
        "-   Takeaway: you must install the interpreter; that is the thing that\n",
        "    actually runs your code.\n",
        "\n",
        "## Common file types: Markdown, .qmd, and .ipynb\n",
        "\n",
        "-   **Markdown (.md):** plain text with lightweight formatting; `#` for\n",
        "    headers, `**bold**`, `-` for lists; renders to HTML or PDF.\n",
        "-   **Jupyter notebook (.ipynb):** a file of cells that mixes Markdown\n",
        "    (text) and code; outputs are saved inline; stored as JSON.\n",
        "-   **Quarto document (.qmd):** plain-text Markdown plus executable code\n",
        "    chunks; rendered by Quarto to HTML, PDF, Word, or slides.\n",
        "-   **Shared idea:** all three combine human instructions with code, so\n",
        "    narrative, analysis, and results live in one document.\n",
        "-   **Key difference:** .ipynb is cell-based JSON; .qmd is clean\n",
        "    Markdown text and works with R, Python, and Julia.\n",
        "-   **Scripts**:\n",
        "    -   **.py:** a Python script file (`.py`), which runs python code\n",
        "        line by line.\n",
        "    -   **.R:** an R script file (`.R`), which runs R code line by line.\n",
        "\n",
        "## Environments and Conda\n",
        "\n",
        "-   Conda is both a package manager and an environment manager, used\n",
        "    mainly for Python.\n",
        "-   We install it through Miniforge, a minimal Conda that uses the free\n",
        "    conda-forge package channel by default.\n",
        "-   An environment is an isolated set of packages and versions, so one\n",
        "    project does not break another.\n",
        "-   We will create one course environment, named `dsan`, and use it\n",
        "    everywhere.\n",
        "\n",
        "## The plan (all platforms)\n",
        "\n",
        "1.  Install the language interpreters: R, and Python by way of Conda\n",
        "    (Miniforge).\n",
        "2.  Install the editors: RStudio and VS Code.\n",
        "3.  Install Quarto and the VS Code extensions.\n",
        "4.  Create one Conda environment, then verify everything runs.\n",
        "\n",
        "# macOS Setup\n",
        "\n",
        "## Before you start (macOS)\n",
        "\n",
        "-   Most current Macs use Apple Silicon (M1 through M4). Check with the\n",
        "    Apple menu, then “About This Mac”.\n",
        "-   Apple Silicon: download the “Apple silicon” or “arm64” installers.\n",
        "-   Older Intel Macs: download the “Intel” or “x86_64” installers.\n",
        "-   Your terminal shell is zsh by default; the installers configure it\n",
        "    for you.\n",
        "\n",
        "## Step 1: Install R, then RStudio\n",
        "\n",
        "> **Check first if you already have R and RStudio installed:** in\n",
        "> Terminal run `R --version` (for R) and\n",
        "> `ls /Applications | grep -i RStudio` (for RStudio). Install whichever\n",
        "> is missing.\n",
        "\n",
        "-   Install R before RStudio so RStudio can find it.\n",
        "-   **R:** go to [cran.r-project.org](https://cran.r-project.org/), open\n",
        "    [Download R for macOS](https://cran.r-project.org/bin/macosx/),\n",
        "    choose the `.pkg` that matches your chip, then run it.\n",
        "-   **RStudio:** download [RStudio\n",
        "    Desktop](https://posit.co/download/rstudio-desktop/), open the\n",
        "    `.dmg`, drag RStudio into Applications.\n",
        "-   Open RStudio; it should detect R automatically.\n",
        "\n",
        "## Step 2: Install Miniforge (Python)\n",
        "\n",
        "> **Check first if you already have Conda installed:** in Terminal run\n",
        "> `conda --version`. If you see a version, skip this step.\n",
        "\n",
        "-   Download the macOS installer from\n",
        "    [conda-forge.org/download](https://conda-forge.org/download/),\n",
        "    choosing the `.pkg` (graphical) for your chip. Command-line\n",
        "    alternative:\n",
        "\n",
        "<!-- -->\n",
        "\n",
        "    curl -L -O https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-arm64.sh\n",
        "    bash Miniforge3-MacOSX-arm64.sh\n",
        "\n",
        "-   On Intel Macs, use the `x86_64` file instead. Reopen Terminal, then\n",
        "    run `conda --version`.\n",
        "-   conda-forge is already the default channel, so no further channel\n",
        "    setup is needed.\n",
        "\n",
        "## Step 3: Install VS Code and extensions\n",
        "\n",
        "> **Check first if you already have VS Code installed:** run\n",
        "> `code --version`, or look for Visual Studio Code in your Applications\n",
        "> folder. If present, skip the download and go straight to the\n",
        "> extensions.\n",
        "\n",
        "-   Download VS Code from\n",
        "    [code.visualstudio.com/download](https://code.visualstudio.com/download),\n",
        "    open the `.zip`, move “Visual Studio Code” into Applications.\n",
        "-   Open VS Code, go to the Extensions panel, and install: **Python**,\n",
        "    **Jupyter**, **Quarto**. Optional: **R**.\n",
        "-   Optional convenience: Command Palette (Cmd+Shift+P), run “Shell\n",
        "    Command: Install ‘code’ command in PATH”.\n",
        "\n",
        "## Step 4: Install Quarto\n",
        "\n",
        "> **Check first if you already have Quarto installed:** run\n",
        "> `quarto --version`. If you see a version, skip this step.\n",
        "\n",
        "-   RStudio already bundles Quarto; for VS Code, install the standalone\n",
        "    Quarto CLI as well.\n",
        "-   Download the macOS `.pkg` from\n",
        "    [quarto.org/docs/download](https://quarto.org/docs/download/) and\n",
        "    run it.\n",
        "-   Verify in Terminal:\n",
        "\n",
        "<!-- -->\n",
        "\n",
        "    quarto check\n",
        "\n",
        "## Step 5: Create the course environment\n",
        "\n",
        "> **Check first if you already have the `dsan` environment:** run\n",
        "> `conda env list`. If `dsan` is listed, skip creating it and just run\n",
        "> `conda activate dsan`.\n",
        "\n",
        "-   In Terminal:\n",
        "\n",
        "<!-- -->\n",
        "\n",
        "    conda create -n dsan python=3.12 jupyterlab pandas numpy matplotlib\n",
        "    conda activate dsan\n",
        "\n",
        "-   In VS Code, open a notebook or Python file, then select the\n",
        "    environment: Command Palette, “Python: Select Interpreter”, choose\n",
        "    `dsan`.\n",
        "\n",
        "## Verify (macOS)\n",
        "\n",
        "Run each command; you should see version numbers with no errors:\n",
        "\n",
        "    R --version\n",
        "    python --version\n",
        "    conda --version\n",
        "    quarto --version\n",
        "\n",
        "Then open RStudio, open VS Code, create a test `.ipynb`, and run a cell.\n",
        "\n",
        "# Windows Setup (Part 1): Native Windows\n",
        "\n",
        "## Two paths on Windows\n",
        "\n",
        "-   **Native Windows:** install everything directly on Windows; this is\n",
        "    the simplest way to start.\n",
        "-   **WSL (Ubuntu Linux inside Windows):** a Linux environment that\n",
        "    matches real servers; covered in Part 2.\n",
        "-   You do not need both. Start with native Windows unless your\n",
        "    instructor asks for WSL.\n",
        "\n",
        "## Step 1: Install R, then RStudio\n",
        "\n",
        "> **Check first if you already have R and RStudio installed:** in\n",
        "> PowerShell run `dir \"C:\\Program Files\\R\"` (for R) and\n",
        "> `dir \"C:\\Program Files\\RStudio\"` (for RStudio). A listed folder means\n",
        "> it is installed. Install whichever is missing.\n",
        "\n",
        "-   Install R before RStudio so RStudio can find it.\n",
        "-   **R:** go to [cran.r-project.org](https://cran.r-project.org/), open\n",
        "    [Download R for Windows,\n",
        "    base](https://cran.r-project.org/bin/windows/base/), then run the\n",
        "    `.exe` and accept the defaults.\n",
        "-   **RStudio:** download [RStudio\n",
        "    Desktop](https://posit.co/download/rstudio-desktop/), run the `.exe`\n",
        "    installer.\n",
        "-   Open RStudio; it should detect R automatically.\n",
        "\n",
        "## Step 2: Install Miniforge (Python)\n",
        "\n",
        "> **Check first if you already have Conda installed:** open the Start\n",
        "> Menu and look for “Miniforge Prompt” (or an existing “Anaconda\n",
        "> Prompt”). If one exists, Conda is already installed; skip this step.\n",
        "\n",
        "-   Download the Windows `.exe` from\n",
        "    [conda-forge.org/download](https://conda-forge.org/download/).\n",
        "    Direct file:\n",
        "    [Miniforge3-Windows-x86_64.exe](https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Windows-x86_64.exe).\n",
        "-   Run it, “Just Me”; leave “Add to PATH” **unchecked**.\n",
        "-   Use “Miniforge Prompt” from the Start Menu whenever you run conda\n",
        "    commands, then run `conda --version`.\n",
        "-   conda-forge is already the default channel, so no further channel\n",
        "    setup is needed.\n",
        "\n",
        "## Step 3: Install VS Code and extensions\n",
        "\n",
        "> **Check first if you already have VS Code installed:** in PowerShell\n",
        "> run `code --version`. If you see a version, skip the download and go\n",
        "> straight to the extensions.\n",
        "\n",
        "-   Download the Windows “User Installer” from\n",
        "    [code.visualstudio.com/download](https://code.visualstudio.com/download),\n",
        "    then run it (no admin needed).\n",
        "-   In the VS Code Extensions panel, install: **Python**, **Jupyter**,\n",
        "    **Quarto**. Optional: **R**.\n",
        "\n",
        "## Step 4: Install Quarto\n",
        "\n",
        "> **Check first if you already have Quarto installed:** in the Miniforge\n",
        "> Prompt run `quarto --version`. If you see a version, skip this step.\n",
        "\n",
        "-   RStudio already bundles Quarto; for VS Code, install the standalone\n",
        "    Quarto CLI as well.\n",
        "-   Download the Windows `.msi` from\n",
        "    [quarto.org/docs/download](https://quarto.org/docs/download/) and\n",
        "    run it.\n",
        "-   Verify:\n",
        "\n",
        "<!-- -->\n",
        "\n",
        "    quarto check\n",
        "\n",
        "## Step 5: Create the course environment\n",
        "\n",
        "> **Check first if you already have the `dsan` environment:** in the\n",
        "> Miniforge Prompt run `conda env list`. If `dsan` is listed, skip\n",
        "> creating it and just run `conda activate dsan`.\n",
        "\n",
        "-   In the Miniforge Prompt:\n",
        "\n",
        "<!-- -->\n",
        "\n",
        "    conda create -n dsan python=3.12 jupyterlab pandas numpy matplotlib\n",
        "    conda activate dsan\n",
        "\n",
        "-   In VS Code: Command Palette (Ctrl+Shift+P), “Python: Select\n",
        "    Interpreter”, choose `dsan`.\n",
        "\n",
        "## Verify (native Windows)\n",
        "\n",
        "Run in the Miniforge Prompt:\n",
        "\n",
        "    R --version\n",
        "    python --version\n",
        "    conda --version\n",
        "    quarto --version\n",
        "\n",
        "Common fix: if `conda` is “not recognized” in a plain PowerShell window,\n",
        "use the Miniforge Prompt instead, or run `conda init powershell` once\n",
        "and reopen the window.\n",
        "\n",
        "# Windows Setup (Part 2): WSL (Ubuntu)\n",
        "\n",
        "## What WSL is\n",
        "\n",
        "-   WSL runs a real Ubuntu Linux inside Windows; you get a Linux command\n",
        "    line and Linux tools.\n",
        "-   It is a good match for servers and cloud environments, and is widely\n",
        "    used in data science.\n",
        "-   You will edit code with VS Code on Windows, connected into Ubuntu.\n",
        "-   Reference: [Microsoft’s WSL install\n",
        "    guide](https://learn.microsoft.com/en-us/windows/wsl/install).\n",
        "\n",
        "## Step 1: Install WSL\n",
        "\n",
        "> **Check first if you already have WSL installed:** in PowerShell run\n",
        "> `wsl -l -v`. If Ubuntu is listed, skip to Step 2.\n",
        "\n",
        "-   Open PowerShell as Administrator (right-click, “Run as\n",
        "    administrator”).\n",
        "-   Install WSL together with Ubuntu:\n",
        "\n",
        "<!-- -->\n",
        "\n",
        "    wsl --install\n",
        "\n",
        "-   Restart your computer when prompted.\n",
        "-   On the first launch of Ubuntu, create a UNIX username and password\n",
        "    (separate from your Windows login).\n",
        "-   If WSL fails to start, enable virtualization in your BIOS or UEFI\n",
        "    settings, then retry.\n",
        "\n",
        "## Step 2: Update Ubuntu\n",
        "\n",
        "-   In the Ubuntu terminal, refresh the system packages:\n",
        "\n",
        "<!-- -->\n",
        "\n",
        "    sudo apt update && sudo apt upgrade -y\n",
        "\n",
        "## Step 3: Connect VS Code to WSL\n",
        "\n",
        "> **Check first if you already have VS Code installed:** in Windows\n",
        "> PowerShell run `code --version`. If missing, install [VS\n",
        "> Code](https://code.visualstudio.com/download) on Windows (Part 1, Step\n",
        "> 3).\n",
        "\n",
        "-   In VS Code, install the **WSL** extension.\n",
        "-   From Ubuntu, make a project folder and open it in VS Code:\n",
        "\n",
        "<!-- -->\n",
        "\n",
        "    mkdir -p ~/dsan && cd ~/dsan\n",
        "    code .\n",
        "\n",
        "-   VS Code reopens “connected to WSL”; when prompted, install the\n",
        "    **Python**, **Jupyter**, and **Quarto** extensions inside WSL too.\n",
        "\n",
        "## Step 4: Install Miniforge in Ubuntu\n",
        "\n",
        "> **Check first if you already have Conda installed:** in Ubuntu run\n",
        "> `conda --version`. If you see a version, skip this step.\n",
        "\n",
        "-   Download and run the Linux installer (use the `aarch64` file on\n",
        "    Arm-based Windows):\n",
        "\n",
        "<!-- -->\n",
        "\n",
        "    cd ~\n",
        "    wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh\n",
        "    bash Miniforge3-Linux-x86_64.sh\n",
        "\n",
        "-   Accept the license and default location, answer “yes” to initialize,\n",
        "    then close and reopen the terminal.\n",
        "-   conda-forge is already the default channel, so no further channel\n",
        "    setup is needed.\n",
        "\n",
        "## Step 5: Create the course environment (with Quarto and Jupyter)\n",
        "\n",
        "> **Check first if you already have the `dsan` environment:** in Ubuntu\n",
        "> run `conda env list`. If `dsan` is listed, skip creating it and just\n",
        "> run `conda activate dsan`.\n",
        "\n",
        "-   Create everything in one environment:\n",
        "\n",
        "<!-- -->\n",
        "\n",
        "    conda create -n dsan python=3.12 jupyterlab quarto pandas numpy matplotlib\n",
        "    conda activate dsan\n",
        "    quarto check\n",
        "\n",
        "-   In VS Code (connected to WSL), select the `dsan` interpreter and the\n",
        "    `dsan` notebook kernel.\n",
        "-   Alternative Quarto install: the official Linux `.deb` at\n",
        "    [quarto.org/docs/download](https://quarto.org/docs/download/).\n",
        "\n",
        "## Step 6: R in Ubuntu (optional)\n",
        "\n",
        "> **Check first if you already have R installed:** in Ubuntu run\n",
        "> `R --version`. If you see a version, R is installed.\n",
        "\n",
        "-   For Python-first work you can skip R here and use native RStudio\n",
        "    (Part 1) for R.\n",
        "-   To install R inside WSL:\n",
        "\n",
        "<!-- -->\n",
        "\n",
        "    sudo apt install -y r-base\n",
        "\n",
        "-   Use R through the VS Code **R** extension, or the `radian` console.\n",
        "-   The RStudio graphical app does not run cleanly inside WSL; for the\n",
        "    RStudio experience, use native RStudio from Part 1.\n",
        "\n",
        "## Verify (WSL)\n",
        "\n",
        "-   In the Ubuntu terminal:\n",
        "\n",
        "<!-- -->\n",
        "\n",
        "    python --version\n",
        "    conda --version\n",
        "    quarto --version\n",
        "\n",
        "-   In VS Code (connected to WSL), open a `.ipynb`, select the `dsan`\n",
        "    kernel, and run a cell.\n",
        "\n",
        "# Optional: Command Line and File Paths\n",
        "\n",
        "## Why this matters\n",
        "\n",
        "-   Tools like Conda and Quarto often run from a terminal, so a little\n",
        "    navigation goes a long way.\n",
        "-   In VS Code, use the built-in terminal (Terminal menu, “New\n",
        "    Terminal”) so your editor and command line share the same folder.\n",
        "\n",
        "## Core commands\n",
        "\n",
        "-   `pwd` (macOS, Linux) or `cd` with no argument (Windows): show the\n",
        "    current folder.\n",
        "-   `ls` (macOS, Linux) or `dir` (Windows): list the folder’s contents.\n",
        "-   `cd foldername`: enter a folder; `cd ..`: go up one level.\n",
        "-   `mkdir name`: make a new folder.\n",
        "\n",
        "## Paths\n",
        "\n",
        "-   **Absolute path:** the full location from the root, for example\n",
        "    `/Users/you/dsan` or `C:\\Users\\you\\dsan`.\n",
        "-   **Relative path:** measured from where you are now, for example\n",
        "    `data/file.csv`.\n",
        "-   **Home shortcut:** `~` on macOS and Linux.\n",
        "-   **PATH (the environment variable):** the list of folders the system\n",
        "    searches for programs; this is why “add to PATH” during install\n",
        "    matters.\n",
        "\n",
        "# You Are Ready\n",
        "\n",
        "Before lecture, confirm all of the following:\n",
        "\n",
        "-   R and RStudio open and run.\n",
        "-   Conda works, and `conda activate dsan` succeeds.\n",
        "-   VS Code runs a notebook cell using the `dsan` kernel.\n",
        "-   `quarto check` passes.\n",
        "\n",
        "Bring your laptop with these done. If a step failed, copy the exact\n",
        "error message and ask before class."
      ],
      "id": "161aba4d-671c-4466-bb5c-65817c066ab7"
    }
  ],
  "nbformat": 4,
  "nbformat_minor": 5,
  "metadata": {
    "kernelspec": {
      "name": "python3",
      "display_name": "Python 3",
      "language": "python"
    },
    "language_info": {
      "name": "python"
    }
  }
}