wording

episodes/intro-sce.Rmd

@@ -20,21 +20,13 @@ exercises: 10 # Minutes of exercises in the lesson
 
 ::::::::::::::::::::::::::::::::::::::::::::::::
 
-## Setup
 
 ```{r chunk-opts, include=FALSE}
 knitr::opts_chunk$set(echo = TRUE, message = FALSE, warning = FALSE)
 library(BiocStyle)
 options(digits = 3)
 ```
 
-```{r setup}
-library(SingleCellExperiment)
-library(MouseGastrulationData)
-```
-
-It's normal to see lot of startup messages when loading these packages. 
-
 ## Bioconductor
 
 ### Overview 
@@ -101,6 +93,19 @@ Be careful: if you have a lot of packages to update, this can take a long time.
 
 ## The `SingleCellExperiment` class
 
+### Setup
+
+First start by loading some libraries we'll be using:
+
+```{r setup}
+library(SingleCellExperiment)
+library(MouseGastrulationData)
+```
+
+It's normal to see lot of startup messages when loading these packages. 
+
+### Motivation and overview
+
 One of the main strengths of the Bioconductor project lies in the use of a common data infrastructure that powers interoperability across packages. 
 
 Users should be able to analyze their data using functions from different Bioconductor packages without the need to convert between formats. To this end, the `SingleCellExperiment` class (from the _SingleCellExperiment_ package) serves as the common currency for data exchange across 70+ single-cell-related Bioconductor packages.
@@ -111,7 +116,7 @@ This class implements a data structure that stores all aspects of our single-cel
 knitr::include_graphics("http://bioconductor.org/books/release/OSCA.intro/images/SingleCellExperiment.png")
 ```
 
-Let's start with an example dataset.
+Let's look at an example dataset. `WTChimeraData` comes from a study on mouse development. We can assign one sample to a `SingleCellExperiment` object named `sce` like so:
 
 ```{r, message = FALSE, warning=FALSE}
 sce <- WTChimeraData(samples=5)
@@ -125,13 +130,13 @@ Depending on the object, slots can contain different types of data (e.g., numeri
 
 :::: challenge
 
-Before SingleCellExperiments, coders working with single cell data would sometimes keep all of these components in separate objects e.g. a matrix of counts, a data.frame of sample metadata, a data.frame of gene annotations and so on. What are the main disadvantage of this sort of "from scratch" approach?
+Before `SingleCellExperiment`, coders working with single cell data would sometimes keep all of these components in separate objects e.g. a matrix of counts, a data.frame of sample metadata, a data.frame of gene annotations and so on. What are the main disadvantages of this sort of "from scratch" approach?
 
 ::: solution
 
 1. You have to do tons of book-keeping! If you perform a QC step that removes dead cells, now you also have to remember to remove that same set of cells from the cell-wise metadata. Dropped un-expressed genes? Don't forget to filter the gene metadata table too. 
 
-2. All the downstream steps have to be "from scratch" as well! If your tables have some slight format difference from those of your lab-mate, suddenly the plotting code you're trying to re-use doesn't work! Agh!
+2. All the downstream steps have to be "from scratch" as well! All the data munging, analysis, and visualization code has to be customized to the idiosyncrasies of your input. Agh!
 
 :::