Went through 1a and 1b again after Juna's changes. started to work on 1c

Author: julien-roux

day1/day1-1a_SpatialExperiment.qmd

@@ -53,10 +53,9 @@ library(HDF5Array)
 
 ## Data for the course
 
-We will work on a human colorectal cancer study by [Oliveira _et al_](https://www.nature.com/articles/s41588-025-02193-3). The dataset contains normal adjacent tissue (NAT) and colorectal carcinoma (CRC) from 5 patients.
+We will work on a human colorectal cancer study by [Oliveira _et al_](https://www.nature.com/articles/s41588-025-02193-3). The dataset contains normal adjacent tissue (NAT) and colorectal carcinoma (CRC) from 5 patients. We will focus on data from a patient called "P2", available from the [10X website](https://www.10xgenomics.com/datasets/visium-hd-cytassist-gene-expression-libraries-of-human-crc). 
 
-We will focus on data from a patient called "P2", available from the [10X website](https://www.10xgenomics.com/datasets/visium-hd-cytassist-gene-expression-libraries-of-human-crc). 
-For this sample, the study provides Visium HD data at 2, 8, and 16 um binned resolutions and output from cell segmentation, as well as a matching Xenium dataset. The data were generated from serial sections of the same samples, so they are spatially matched and can be used for cross-platform comparisons.
+For this sample, the study provides Visium HD data at 2, 8, and 16 um resolution and the per-cell output after cell segmentation. Matching Xenium data generated from serial sections of the same sample is also available and can be used for cross-platform comparisons.
 
 In this exercise we will work with **Visium HD** data and focus on the "binned output" available as an output of the Space Ranger pipeline (version 3.0). The full output is very large, so for practical reasons we use a region of interest, selected to include an interesting part of the tissue, because it contains gland-like epithelial structures together with stromal or lower-density areas:
 
@@ -83,7 +82,7 @@ osta_roi_visium <- c(
 osta_roi_visium
 ```
 
-*Note 2*: The same study also generated a matching Xenium dataset from serial sections of the same samples, which we will use in `Exercise 1 B` (we subsetted to regions of interest of the P2CRC slide, approximately matching the one selected here).
+*Note 2*: In `Exercise 1B` we focus on the matching Xenium dataset from a serial section of the same P2CRC sample, subsetted to an approximately matching region of interest.
 
 
 ```{r day1-1a-SpatialExperiment-5}
@@ -108,7 +107,7 @@ if (!dir.exists("data/Human_Colon_Cancer_P2/")) {
 }
 ```
 
-We will import the 16 um binned Visium HD output into a `SpatialExperiment` object and then subset it to the course region. The coordinates are in the native Visium HD image coordinate system returned by `spatialCoords()`.
+We will import the 16 um binned Visium HD output into a `SpatialExperiment` object and then subset it to the region of internet. The coordinates are in the native Visium HD image coordinate system returned by `spatialCoords()`.
 
 ```{r day1-1a-SpatialExperiment-6}
 spe <- TENxVisiumHD(
@@ -160,7 +159,7 @@ In this exercise, we will inspect the `SpatialExperiment` class used to store th
 
 ![Overview of the `SpatialExperiment` class structure](../assets/images/spe.png)
 
-*Note*: The practical `Exercise 1 B` uses a Xenium dataset stored into a `SpatialFeatureExperiment` class, which is an extension of the `SpatialExperiment` incorporating geometries, allowing to store cell segmentation polygons for example.
+*Note*: The practical `Exercise 1B` uses a Xenium dataset stored into a `SpatialFeatureExperiment` class, which is an extension of the `SpatialExperiment` incorporating geometries, allowing to store cell segmentation polygons for example.
 
 
 ::: callout-important
@@ -220,7 +219,7 @@ assay(spe)
 class(assay(spe))
 ```
 
-The `DelayedArray` class allows to store out-of-memory representations of count matrices, which are saved as .h5 files on the disk. This is very useful for efficient processing of large datasets (100,000s of cells or spots)
+The `DelayedArray` class allows to store out-of-memory representations of count matrices, which are saved as `.h5` files on the disk. This is very useful for efficient processing of large datasets (100,000s of cells or spots)
 
 The `reducedDims` slot is empty at this stage:
 
@@ -270,7 +269,7 @@ Why do we see only a specific region of the slide?
 ::: {.callout-tip collapse="true"}
 ## Answer
 
-The full Visium HD output is much larger than needed for this introductory exercise. At the start of this exercise, we subsetted the object to one representative tissue region so that it remains fast to plot and process. This same region is also used as the anchor for selecting a comparable Xenium region in `Exercise 1 B`.
+The full Visium HD output is much larger than needed for this introductory exercise. At the start of this exercise, we subsetted the object to one representative tissue region so that it remains fast to plot and process. This same region is also used as the anchor for selecting a comparable Xenium region in `Exercise 1B`.
 :::
 
 It is possible to colour bins according to a gene or a column in `colData`, for example `PIGR`. We renamed the rows to gene symbols after import, which is why we can refer to this marker as `"PIGR"` rather than by its Ensembl ID. At this stage we plot the number of UMIs since log-normalized counts will be introduced later in the course.

day1/day1-1b_SpatialFeatureExperiment.qmd

@@ -16,7 +16,7 @@ By the end of this exercise, you will be able to:
 -   Explain when `SpatialFeatureExperiment` is useful compared with `SpatialExperiment`.
 -   Access cell-level metadata and spatial coordinates from Xenium data.
 -   Inspect geometry information such as cell or nucleus boundaries.
--   Compare the Xenium representation with the Visium HD representation from Exercise 1 A.
+-   Compare the Xenium representation with the Visium HD representation from Exercise 1A.
 
 ## Libraries
 
@@ -40,7 +40,7 @@ Next, will work with the **Xenium** dataset from the P2 sample (human colorectal
 
 This slide is a serial section of the sample used in `Exercise 1A`, so the two datasets are biologically related but not the exact same physical tissue section. 
 
-The full Xenium output is very large and includes cell boundaries, nucleus boundaries, transcript locations, morphology images, and expression matrices. For this exercise, for practical reasons we use a region of interest, selected to **approximately match the region of interest used in `Exercise 1 A`**, and only include some of the layers in the imported compact course folder. This makes the two exercises comparable while avoiding a full image-registration workflow during the practical.
+The full Xenium output is very large and includes cell boundaries, nucleus boundaries, transcript locations, morphology images, and expression matrices. For this exercise, for practical reasons we use a region of interest, selected to **approximately match the region of interest used in `Exercise 1A`**, and only include some of the layers in the imported compact course folder. This makes the two exercises comparable while avoiding a full image-registration workflow during the practical.
 
 
 ```{r day1-1b-SFE-2}
@@ -77,7 +77,7 @@ sfe <- sfe_full[, spatialCoords(sfe_full)[, 1] >= roi_xenium[["xmin"]] &
   spatialCoords(sfe_full)[, 1] <= roi_xenium[["xmax"]] &
   spatialCoords(sfe_full)[, 2] >= roi_xenium[["ymin"]] &
   spatialCoords(sfe_full)[, 2] <= roi_xenium[["ymax"]]]
-
+rm(sfe_full)
 sfe
 ```
 
@@ -117,7 +117,7 @@ Questions:
 
 -   What do the columns represent?
 -   What do the rows represent?
--   What differs compared to the Visium HD `spe` object in `Exercise 1 A`?
+-   What differs compared to the Visium HD `spe` object in `Exercise 1A`?
 -   What is stored in the main assay?
 :::
 
@@ -185,7 +185,7 @@ ggplot(xy, aes(x = x, y = y)) +
 ::: callout-important
 ## Exercise 4
 
-Compare this point-based visualization with the Visium HD plot from `Exercise 1 A`.
+Compare this point-based visualization with the Visium HD plot from `Exercise 1A`.
 
 What does one point represent in each dataset?
 :::
@@ -207,17 +207,33 @@ plotSpatialFeature(sfe, "PIGR", exprs_values = "counts")
 
 Choose another marker gene and visualize its spatial pattern.
 
-How does the interpretation differ from plotting a gene on Visium HD bins?
-
-:::
-<!-- JUNA: If we want them to compare to Visium HD we should not delete environment in previous exercise, or load the spe object here as part of the solution -->
-
-
+How does the interpretation differ from plotting a gene on Visium HD bins? How does the expression of the same gene compares across platforms?
 
 ::: {.callout-tip collapse="true"}
 ## Answer
 
 The Xenium signal is measured over segmented cells, while the Visium HD binned signal aggregates molecules within fixed spatial bins. Xenium can therefore represent cell-level heterogeneity more directly, but it measures a targeted panel rather than the whole transcriptome.
+
+Here is some code to plot the expression of the same gene across platforms in a similar way:
+```{r day1-1b-SFE-12}
+xy <- data.frame(spatialCoords(sfe), colData(sfe), PIGR=counts(sfe)["PIGR",] + 1)
+names(xy)[1:2] <- c("x", "y")
+ggplot(xy, aes(x = x, y = y, color=PIGR)) +
+  geom_point(size = 0.2) +
+  coord_fixed() +
+  scale_color_gradient(trans = "log", low = "white", high = "red") +
+  theme_bw() 
+
+## load the object from Exercise 1A
+spe <- loadHDF5SummarizedExperiment(dir="results/day1/", prefix="01.1_spe_")
+xy <- data.frame(spatialCoords(spe), colData(spe), PIGR=counts(spe)["PIGR",] + 1)
+names(xy)[1:2] <- c("x", "y")
+ggplot(xy, aes(x = x, y = y, color=PIGR)) +
+  geom_point(size = 1, shape=15) +
+  coord_fixed() +
+  scale_color_gradient(trans = "log", low = "white", high = "red") +
+  theme_bw() 
+```
 :::
 
 ## Exercise 6
@@ -227,7 +243,7 @@ Use the `plotSpatialFeature()` function to visualize the cell segmentation mask,
 ::: {.callout-tip collapse="true"}
 ## Answer
 
-```{r day1-1b-SFE-12}
+```{r day1-1b-SFE-13}
 plotSpatialFeature(sfe, 
                    colGeometryName="cellSeg", 
                    features="cell_area") 
@@ -237,22 +253,22 @@ plotSpatialFeature(sfe,
                    features="nucleus_area") 
 ```
 :::
-1
+
 ## Save the object
 
-```{r day1-1b-SFE-13}
+```{r day1-1b-SFE-14}
 dir.create("results/day1", showWarnings = FALSE, recursive = TRUE)
 
 saveHDF5SummarizedExperiment(sfe,
-  dir = "results/day1", prefix = "01.1b_sfe_xenium", replace = TRUE,
+  dir = "results/day1", prefix = "01.1b_sfe_xenium_", replace = TRUE,
   chunkdim = NULL, level = NULL, as.sparse = NA,
   verbose = NA
 )
 ```
 
 Clear your environment:
 
-```{r day1-1b-SFE-14}
+```{r day1-1b-SFE-15}
 #| eval: false
 rm(list = ls())
 gc()
@@ -263,6 +279,6 @@ gc()
 **Key Takeaways:**
 
 -   `SpatialFeatureExperiment` is useful for geometry-rich spatial data.
--   Xenium observations are cell-resolved, while the Visium HD object in Exercise 1 A is bin-resolved.
+-   Xenium observations are cell-resolved, while the Visium HD object in Exercise 1A is bin-resolved.
 -   The P2 CRC subsets are designed to be comparable in course scope and approximate tissue region, not identical at cell level.
 :::

day1/day1-1c_visium_HD_segmented.qmd

@@ -13,7 +13,7 @@ execute:
 By the end of this exercise, you will be able to:
 
 -  TO DEFINE
-<!-- Adapt depending on the final data structure -->
+<!-- TO DO: Adapt depending on the final data structure -->
 
 
 ## Libraries
@@ -36,8 +36,7 @@ library(VisiumIO)
 
 Finally, we will work with the **Visium HD segmented output**. This data corresponds to the same sample and region of interest as the binned data from `Exercise 1A`, but instead of being binned, it contains the output of cell segmentation. Since Space Ranger version 4.0, the output of cell segmentation is available as an optional output of the pipeline, and it contains the coordinates of the segmented cells and their boundaries.
 
-<!-- Download the segmented output from the 10X website if it does not exist in the `data` folder. -->
-
+<!-- TO DO: we need to make a smaller version of teh dataset for the course! -->
 
 ```{r day1-1c-visium_HD_segmented-3}
 options(timeout = 600)
@@ -63,20 +62,20 @@ if (!dir.exists("data/Visium_HD_Human_Colon_Cancer_segmented_outputs/")) {
 
 ::: callout-important
 ## Exercise 1
-Why will we use SpatialFeatureExperiment to work with the segmented data instead of SpatialExperiment as we did for the binned data in Exercise 1A
-?
+Which class do you think should be used to store the Visium HD segmented data? `SpatialExperiment` as we used in Exercise 1A
+or `SpatialFeatureExperiment` as we used in Exercise 1B?
 ::: 
 
 ::: {.callout-tip collapse="true"}
 ## Answer
-Since segmeneted data contains cell boundaries, the coordinates of the segmented cells are not limited to the spot coordinates as in the binned data. Therefore, we will use `SpatialFeatureExperiment` to work with the segmented data, as it allows us to store and visualize spatial features such as cell boundaries, as we did for the Xenium data in Exercise 1B. 
+Since segmented data contains cell boundaries, the coordinates of the segmented cells are not limited to the spot coordinates as in the binned data. Therefore, we will use `SpatialFeatureExperiment` to work with the segmented data, as it allows us to store and visualize spatial features such as cell boundaries, as we did for the Xenium data in Exercise 1B. 
 In contrast, `SpatialExperiment` is more suitable for binned data where the coordinates correspond to the spot centroids and there are no additional spatial features to store.
 ::: 
 
 
-We will create the `SpatialFeatureExperiment` object in two steps.
-
-We start reading the object into a `SpatialExperiment` object and subset it to the course region, as we have done for visium HD binned data in the previous exercises.
+Here we will proceed in two steps:
+- We start reading the object into a `SpatialExperiment` object and subset it to the region of interest, as we have done for Visium HD binned data in the previous exercises. This allows a quick comparison of the two types of processing for the same slide
+- We then convert the object to create a `SpatialFeatureExperiment` object and add the cell segmentation information to it/
 
 
 ```{r day1-1c-visium_HD_segmented-4}

day2/day2-1b_normalization_xenium.qmd

@@ -45,7 +45,7 @@ library(HDF5Array)
 We start with the Xenium object saved at the end of Exercise 1B.
 
 ```{r}
-sfe <- loadHDF5SummarizedExperiment(dir = "results/day1", prefix = "01.1b_sfe_xenium")
+sfe <- loadHDF5SummarizedExperiment(dir = "results/day1", prefix = "01.1b_sfe_xenium_")
 sfe
 ```