scRNA-seq is a computational science

• A single 10x Genomics run produces millions of reads and a count matrix with tens of thousands of rows (genes) × thousands of columns (cells).
• The wet lab generates the data; the computer generates the biology.
• Every analytical decision — filtering, normalization, clustering, differential expression — is a line of code.
• Reproducibility requires that every step is recorded, versioned, and re-runnable.

The computational stack for this workshop

• Hardware — your laptop today; the UO HPC cluster Talapas on Friday.
• Operating system — macOS, Linux, or Windows (with WSL) — all speaking the same Unix shell.
• Command line — navigate, move data, run scripts, chain tools together.
• R & Bioconductor / Seurat — the analysis layer: QC, normalization, clustering, DE, annotation.
• RStudio - a coding editor / IDE to run R code locally (covered in P2)
• VS Code — the editor that ties it all together locally and on Talapas.
• Quarto — literate programming: prose + code + figures in one reproducible document.

The three things that matter most

• CPU — does the processing (it’s even in the name)
  • Made of cores (independent workers) running at some clock speed (GHz).
  • More cores = more tasks at once. Parallelism needs explicit setup.
• RAM — fast, volatile working memory. Your data must fit here while you analyze it. Lost when power is off.
• Disk — slow, persistent storage. SSDs (~0.1 ms latency) are fast; spinning HDDs (~10 ms) are cheap and large. Network storage on a cluster adds another layer of latency.

CPU vs GPU (one slide)

Storage hierarchy — where your data lives

What an operating system does

• The OS is the manager sitting between you and the hardware.
• Process management — schedules many running programs across cores; gives each program a time-slice.
• Memory management — hands out RAM, protects programs from clobbering each other.
• File system — organizes files into directories with permissions and ownership.
• Security — users, groups, and the least-privilege principle.

The file system tree

• Files live in a tree of directories rooted at / on Unix/macOS (or C:\ on Windows).
• Every file has an absolute path from the root: /home/wcresko/scRNAseq_tutorial/data/counts.rds
• A relative path is interpreted from wherever you currently are: ../data/counts.rds
• Shortcuts: . = here, .. = one level up, ~ = your home directory.

Files live in a tree of directories rooted at /. Your home (~) is your branch; paths are addresses within the tree.

Processes and permissions

• A process is a running program — the OS gives each a slice of CPU time and a private chunk of RAM.
• Processes have an owner (user) and inherit the owner’s file permissions.
• Permissions: read (r), write (w), execute (x) — for owner, group, and others.
• On a shared machine, many users’ processes coexist — good citizenship matters, especially on a cluster.

ls -l data/
# -rw-r--r-- 1 wcresko workshop 42M Jun  9 09:00 counts.rds
#  ^^ owner can read+write; group and others can only read

What is the shell — and why use it?

• The shell (bash, zsh) is a text interface to the OS — you type a command, the OS runs it, you see the result.
• Why bother when there’s a GUI? Because the shell is:
  • Scriptable — record every step; re-run with one command.
  • Composable — chain small tools into powerful pipelines.
  • Universal — the same commands work on your laptop and on Talapas.
• Open a terminal: Terminal on macOS/Linux, WSL/Ubuntu on Windows, or the VS Code integrated terminal (Ctrl/Cmd + `).

Anatomy of a shell command

Every shell command has the same shape: the command, its options/flags (e.g. -l), and its arguments (what it acts on).

Where am I? What’s here?

pwd                 # print working directory — the absolute path you're in
ls                  # list files & folders in the current directory
ls -F               # mark directories with /, executables with *
ls -l               # long format: permissions, owner, size, date
ls -la              # long format + hidden dotfiles (.bashrc, .config …)

Navigating with cd

cd ~                   # go home (~ is always your home directory)
cd /home/wcresko       # absolute path — works from anywhere
cd scRNAseq_tutorial   # relative path — one step down from here
cd ..                  # up one level
cd -                   # back to the directory you were in last (toggle)
pwd                    # confirm where you landed

• Absolute paths start with / — unambiguous from anywhere.
• Relative paths start with a directory name, ., or .. — shorter, and survive moving the whole project.

Paths — practice example

You’re in /home/wcresko/scRNAseq_tutorial/data. Get to scripts/ two ways:

# absolute — starts at /
cd /home/wcresko/scRNAseq_tutorial/scripts

# relative — go up one (../) then into scripts
cd ../scripts

Make, move, copy, remove

mkdir p1_practice          # make a new directory
cd p1_practice
touch notes.txt            # create an empty file
cp notes.txt notes_bak.txt # copy a file
mv notes.txt readme.txt    # rename (move within the same dir)
mkdir archive
mv notes_bak.txt archive/  # move a file into a subdirectory
ls -F                      # see the result

rm archive/notes_bak.txt   # remove a file — NO UNDO
rmdir archive              # remove an *empty* directory
# rm -r somedir            # remove a directory AND all its contents

Viewing file contents

cat readme.txt          # dump a whole (small) file to the screen
head big.txt            # first 10 lines (default)
head -n 3 big.txt       # first 3 lines
tail big.txt            # last 10 lines
wc -l big.txt           # count lines
less big.txt            # page through: SPACE=down  b=up  /pattern=search  q=quit

Wildcards

Wildcards let one command act on many files at once.

cd ~/p1_practice
touch sample_01.fastq sample_02.fastq sample_03.fastq control.fastq notes.md

ls *.fastq              # everything ending in .fastq
ls sample_*.fastq       # the three sample_ files
ls sample_0?.fastq      # ? matches exactly one character
ls sample_0[12].fastq   # only sample_01 and sample_02
ls *.{fastq,md}         # brace expansion: .fastq OR .md

Pipes and redirection

Two ideas power most command-line work:

# Redirection — save output to (or read input from) a file
ls -l > listing.txt              # write (overwrites)
echo "generated $(date)" >> listing.txt  # append
wc -l < big.txt                  # feed a file as input

# Pipes — stream output of one command into the next
cat big.txt | wc -l              # count lines via pipe
head -n 50 big.txt | tail -n 5   # lines 46–50
ls *.fastq | wc -l               # how many .fastq files?

# A longer pipeline: most common words in a file
cat readme.txt | tr ' ' '\n' | sort | uniq -c | sort -rn | head

stdin, stdout, stderr

Every Unix program has three standard streams:

# Capture errors separately from results
seurat_pipeline.R > results.txt 2> errors.log

# Discard noisy status messages
wget https://example.com/big.fasta 2>/dev/null

Downloading data with wget / curl

Genomic references and datasets usually come from a URL — fetch them directly, no browser needed.

cd ~/p1_practice

# wget — straightforward download
wget https://raw.githubusercontent.com/githubtraining/hellogitworld/master/README.txt

# curl — -o names the output file
curl -o readme_copy.txt \
  https://raw.githubusercontent.com/githubtraining/hellogitworld/master/README.txt

ls -lh README.txt    # -h = human-readable size
head README.txt

# Compressed files — stream without unpacking
zcat data.fastq.gz | head
zless data.fastq.gz

A command-line reference card

What is an IDE?

• An Integrated Development Environment bundles editor + terminal + debugger + version control in one window.
• Plain text editors (nano, vim) are powerful but bare; IDEs add guardrails.
• For R/Bioconductor work the two leading choices are RStudio and VS Code.

What is VS Code?

• Visual Studio Code — free, open-source editor from Microsoft, runs on macOS, Windows, and Linux.
• Syntax highlighting, autocomplete, Git integration, and a built-in terminal.
• Lightweight enough for quick edits; powerful enough to replace a full IDE.
• Download from code.visualstudio.com — free, no account required.

Key extensions for this workshop

• Quarto — renders .qmd documents, live preview in the editor.
• R (Posit) — R language support, inline output, variable explorer.
• R Debugger — step-through debugging for R scripts.
• vscode-pdf — view PDFs inside VS Code.
• Excel Viewer — renders .csv files as a formatted table.
• GitLens / Git Graph — visualize the repository history alongside your code.

Install from the Extensions panel (Ctrl/Cmd + Shift + X) or from the command line:

code --install-extension quarto.quarto
code --install-extension REditorSupport.r

The VS Code layout

• Activity Bar (left edge) — switches between Explorer, Search, Source Control, Extensions, Remote Explorer.
• Explorer panel — the file tree for your open folder.
• Editor — open multiple files in tabs; split panes with Ctrl/Cmd + \.
• Integrated terminal — a full shell at the bottom; open with Ctrl/Cmd + `.
• Command Palette (Ctrl/Cmd + Shift + P) — access almost every VS Code command by typing.

Opening a project folder

• VS Code is folder-centric: File → Open Folder… opens the root of a project.
• The Explorer panel shows the full folder tree — click any file to open it.
• The integrated terminal opens in that folder automatically.
• VS Code may ask if you trust the authors — click Yes, I trust the authors to enable full functionality.

# From the integrated terminal — you're already in the right place
pwd                          # confirms the folder you are in
ls                           # see all the files in that path
R --version                  # confirm R is on your PATH

The integrated terminal

• Open with Ctrl/Cmd + ` — a full shell inside the editor window.
• Run R scripts, shell commands, Git — without switching applications.
• The terminal inherits the open folder as its working directory.
• Multiple terminals in the same window: shell + R REPL side by side.

Editing and running code

• .qmd files: edit prose and code chunks side by side; click Preview or Ctrl/Cmd + Shift + K to render.
• .R files: send lines to an R terminal with Ctrl/Cmd + Enter — exactly like RStudio.
• Run a single .qmd chunk with the ▶ button above the chunk (ignores eval: false — runs interactively regardless).
• Source control panel shows changed files; stage and commit without leaving VS Code.

Useful VS Code habits

Prototyping locally before scaling up

• Start every new analysis on your laptop: explore, plot, confirm the code runs.
• Laptop RAM is the limiting factor for single-cell work — once your dataset outgrows it, it’s time for the cluster.
• The code you write locally runs unchanged on the cluster — only the execution environment changes.

How the workshop modules are organized

All Modules 00–08 use the same folder layout. Set it up once; use it everywhere.

scRNAseq_tutorial/
├── scripts/          # .R and .qmd analysis scripts
├── data/
│   ├── raw/          # immutable inputs — never modify these
│   └── processed/    # outputs from Module 01 onward
└── output/
    ├── figures/      # plots saved by your scripts (.png, .svg)
    └── tables/       # result tables (.csv, .tsv)

• data/raw/ is read-only — always read from here, never write to it.
• output/ is expendable — everything in it can be regenerated from scripts/ + data/raw/.
• Use relative paths in your scripts (../data/raw/counts.rds) so the project is portable.

Try Making A Local Workshop Directory

# Create the workshop structure in one command
mkdir -p scRNAseq_tutorial/{scripts,data/{raw,processed},output/{figures,tables}}

Naming conventions that save headaches

• Avoid spaces in file names — use _ or - instead (module_01_qc.qmd, not module 01 qc.qmd).
• Date-prefix output files when you iterate: 2026-06-09_umap_clusters.png.
• Never overwrite raw data — write results to output/ or data/processed/.
• Number scripts to make the order obvious: 01_qc.R, 02_normalize.R, 03_cluster.R.

What is a Quarto .qmd notebook?

• A .qmd file is plain text that mixes prose (Markdown), code chunks (R, Python, bash), and output (plots, tables).
• Quarto renders it into HTML, PDF, or slides — running the code and weaving the output in.
• Every workshop laptop tutorial is a .qmd — you edit, run, and read the same file.
• Importantly, you can run code chunks and render the entire .qmd file

---
title: "Module 01 — QC & Preprocessing"
---

## Load the data

```{r}
library(Seurat)
seu <- readRDS("data/raw/pbmc_raw.rds")
dim(seu)
```

Why literate programming for science?

• Reproducibility — the document is the analysis; re-render to re-run everything.
• Transparency — every figure comes with the code that made it.
• Narrative — wrap your results in the reasoning that produced them, not a separate write-up.
• This is how we write all the workshop tutorials and these very slides
• You can think of a Quarto document as an electronic laboratory notebook for coding

When your laptop isn’t enough

• Large datasets, long-running jobs, and parallel pipelines call for an HPC cluster.
• UO’s cluster is Talapas — thousands of CPU cores, GPUs, and petabytes of storage.
• Friday morning (Modules 09–10): you’ll
  • log in with VS Code Remote-SSH,
  • explore the file system,
  • run some interactive SLURM jobs on Talapas
  • and submit the full analysis pipeline as SLURM batch jobs.
• The shell skills you practiced today transfer unchanged to Talapas.

Recap

• CPU / RAM / disk — RAM is usually the limiting resource for single-cell work.
• The OS manages processes, memory, files, and permissions.
• The shell: pwd/ls/cd; mkdir/cp/mv/rm; head/tail/less; wildcards; pipes | and redirection >/>>; wget/curl.
• VS Code on your laptop: cross-platform editor, Quarto + R extensions, integrated terminal — your daily coding environment.
• Project layout: scripts/ + data/raw/ + output/ — consistent across Modules 00–08.
• Quarto .qmd — prose + code + output in one reproducible document.