Updates to pisode 2, notes on running carpentries workbench

Author: mwhamgenomics

episodes/02-applying-filters.md

@@ -1,6 +1,7 @@
 ---
+
 title: 'Applying Filters'
-teaching: 10
+teaching: 40
 exercises: 3
 ---
 
@@ -11,7 +12,6 @@ exercises: 3
 ::::::::::::::::::::::::::::::::::::: objectives
 - Apply mean and Gaussian filters to an image
 - Select one of these filtered images to use for processing in subsequent chapters
-- Todo: Discuss Difference of Gaussian and Laplacian of Gaussian algorithms
 ::::::::::::::::::::::::::::::::::::::::::::::::
 
 ## Filters
@@ -26,7 +26,7 @@ Here are two to get started:
 
 A mean filter will, for each pixel:
 
-  - Create a kernel of pixels around it, in a size/shape of the user's choosing
+  - Create a **kernel** of pixels around it, in a size/shape of the user's choosing
   - Take the mean of all pixels within this kernel
   - Assign this new value to the pixel
 
@@ -35,75 +35,96 @@ The kernel in this case can be considered analogous to a 2-dimensional sliding w
 A Gaussian filter is similar to a mean filter, except that pixels near the centre of
 the kernel will have a greater effect on the result.
 
+You can create a kernel with skimage:
+
+```python
+from skimage.morphology import square
+kernel = square(3)  # create a 3x3 square kernel
+```
+
+There are other shapes of kernel that can be used, and are documented
+[here](https://scikit-image.org/docs/stable/api/skimage.morphology.html).
+
+(Note that as of skimage 0.25.0, the `square` function has been deprecated in
+favour of a new function, [footprint_rectangle](https://scikit-image.org/docs/stable/api/skimage.morphology.html#skimage.morphology.footprint_rectangle).)
+
 ::::::::::::::::::::::::::::::::::::: challenge 
-## Exercise 7: Applying filters
+## Exercise 6: Applying filters
 
-Look at the documentation pages for the mean and Gaussian filters above. Load the last channel
-of FluorescentCells_3channel.tif containing the nuclei, and build a figure displaying it in each
-of the following forms:
+Look at the documentation pages for the mean and Gaussian filters above. Load the second channel
+of the 30th frame of the test image [skimage.data.cells3d()](https://scikit-image.org/docs/stable/api/skimage.data.html#skimage.data.cells3d):
+
+```python
+from skimage.data import cells3d
+
+image = cells3d()[30, 1, :, :]
+```
+
+Build a figure displaying this image in each of the following forms:
 
 - original image
-- 5x5 square mean filter applied
-- 15x15 square mean filter
-- Gaussian filter of sigma = 3
+- mean filter using a 3x3 square kernel
+- mean filter using a 9x9 square kernel
+- Gaussian filter of sigma = 1
 - Gaussian filter of sigma = 5
 
 How do the different methods compare?
 
 :::::::::::::::::::::::: solution
 ```python
-import skimage
-import matplotlib.pyplot as plt
-
-img = imread('data/FluorescentCells_3channel.tif')[:, :, -1]
-
-plt.figure(figsize=(10, 12))
-plt.subplot(3, 2, 1)
-plt.imshow(img)
-plt.title('Original')
-
-plt.subplot(3, 2, 2)
-mean5x5 = skimage.filters.rank.mean(img, skimage.morphology.square(5))
-plt.imshow(mean5x5)
-plt.title('5x5 mean filter')
-
-plt.subplot(3, 2, 3)
-mean15x15 = skimage.filters.rank.mean(img, skimage.morphology.square(15))
-plt.imshow(mean15x15)
-plt.title('15 x 15 mean filter')
-
-plt.subplot(3, 2, 4)
-gauss3 = skimage.filters.gaussian(img, 3)
-plt.imshow(gauss3)
-plt.title('Gaussian blur, σ=3')
-
-plt.subplot(3, 2, 5)
-gauss5 = skimage.filters.gaussian(img, 5)
-plt.imshow(gauss5)
-plt.title('Gaussian blur, σ=5')
+from skimage.data import cells3d
+from skimage.filters import gaussian
+from skimage.filters.rank import mean
+from skimage.morphology import square
+
+image = cells3d()[30, 1, :, :]
+matplotlib.pyplot.figure(figsize=(10, 12))
+
+matplotlib.pyplot.subplot(3, 2, 1)
+imshow(image)
+matplotlib.pyplot.title('Original')
+
+matplotlib.pyplot.subplot(3, 2, 2)
+imshow(mean(image, footprint=square(3)))
+matplotlib.pyplot.title('3x3 mean filter')
+
+matplotlib.pyplot.subplot(3, 2, 3)
+imshow(mean(image, footprint=square(9)))
+matplotlib.pyplot.title('9x9 mean filter')
+
+matplotlib.pyplot.subplot(3, 2, 4)
+imshow(gaussian(image, sigma=1))
+matplotlib.pyplot.title('Gaussian blur, σ=1')
+
+matplotlib.pyplot.subplot(3, 2, 5)
+imshow(gaussian(image, sigma=5))
+matplotlib.pyplot.title('Gaussian blur, σ=5')
 ```
 
 ![](fig/2_1_filters.jpg){alt='Filters'}
 
-Larger mean kernels and sigma values will result in a greater smoothing
-effect and a more blurred image.
+Larger kernels and sigma values will result in a greater smoothing
+effect and a more blurred image - as you can see, it is possible to
+over-blur the image.
 :::::::::::::::::::::::::::::::::
 :::::::::::::::::::::::::::::::::::::::::::::::
 
 ## Removing the background
 
-Sometimes when we're trying to isolate the foreground from the background, the two
-are not entirely distinct from each other. In cases like this, a rolling ball
+Eventually we're going to want to isolate the foreground from the background. In some
+images, this may be difficult especially if the two are not entirely distinct from each
+other, or if the background is not a uniform shade. In cases like this, a rolling ball
 algorithm can be applied. The rolling ball estimates the background intensity of an
 image by using the pixel values to translate the image into a height map, and then
 rolling a ball of a given radius across it. Additional information on how it works
 can be found [here](https://www.researchgate.net/figure/Schematic-diagram-of-background-subtraction-by-the-rolling-ball-method-the-histogram_fig3_319985119).
 
 ::::::::::::::::::::::::::::::::::::: challenge
-## Exercise 8: Rolling ball background intensity
+## Exercise 7: Rolling ball background intensity
 
 Look at the [scikit-image documentation](https://scikit-image.org/docs/stable/auto_examples/segmentation/plot_rolling_ball.html)
-on the rolling ball filter. Load the example image `skimage.data.coins` and display:
+on the rolling ball filter. Load the example image [skimage.data.coins](https://scikit-image.org/docs/stable/api/skimage.data.html#skimage.data.coins)
+and display:
 
 - the original image
 - image with a rolling ball of radius 100 applied
@@ -118,36 +139,36 @@ Compute time can be found using Python's datetime library:
 
 ```python
 import datetime
-import skimage
-import matplotlib.pyplot as plt
+from skimage.data import coins
+from skimage.restoration import rolling_ball
+
+image = coins()
+matplotlib.pyplot.figure(figsize=(10, 12))
 
-img = skimage.data.coins()
 t0 = datetime.datetime.now()
+matplotlib.pyplot.subplot(2, 2, 1)
+imshow(image)
+matplotlib.pyplot.title('Original')
 
-plt.subplot(2, 2, 1)
-plt.imshow(img)
 t1 = datetime.datetime.now()
-plt.title('Original')
+matplotlib.pyplot.subplot(2, 2, 2)
+rolling_ball_100 = rolling_ball(image, radius=100)
+imshow(rolling_ball_100)
+matplotlib.pyplot.title('Rolling ball, r=100')
 
-plt.subplot(2, 2, 2)
-rolling_ball_100 = skimage.restoration.rolling_ball(img, radius=100)
-plt.imshow(rolling_ball_100)
 t2 = datetime.datetime.now()
-plt.title('Rolling ball, r=100')
+matplotlib.pyplot.subplot(2, 2, 3)
+rolling_ball_50 = rolling_ball(image, radius=50)
+imshow(rolling_ball_50)
+matplotlib.pyplot.title('Rolling ball, r=50')
 
-plt.subplot(2, 2, 3)
-rolling_ball_50 = skimage.restoration.rolling_ball(img, radius=50)
-plt.imshow(rolling_ball_50)
 t3 = datetime.datetime.now()
-plt.title('Rolling ball, r=50')
-
-plt.subplot(2, 2, 4)
-plt.imshow(img - rolling_ball_50)
-plt.title('Original - rolling ball r50')
+matplotlib.pyplot.subplot(2, 2, 4)
+imshow(image - rolling_ball_50)
+matplotlib.pyplot.title('Original - rolling ball r50')
 
-plt.show()
 print('Original image:', t1 - t0)
-print('Rolling ball 100: ', t2 - t1)
+print('Rolling ball 100:', t2 - t1)
 print('Rolling ball 50:', t3 - t2)
 print('Total:', t3 - t0)
 ```
@@ -164,44 +185,62 @@ the Gaussian filter.
 
 In a [Difference of Gaussian](https://scikit-image.org/docs/stable/api/skimage.filters.html#skimage.filters.difference_of_gaussians),
 two Gaussian filters are taken of the image, each with a different sigma value.
-The larger filter is then subtracted from the first to give an image where image
+The larger filter is then subtracted from the first to give an image where
 features are effectively highlighted by an area of high contrast.
 
 In a Laplacian of Gaussian, a Gaussian-filtered image is supplied to a
 [Laplace](https://scikit-image.org/docs/stable/api/skimage.filters.html#skimage.filters.laplace)
 filter. This eliminates the need to manually select two sigma values as with Difference of Gaussian.
 
 ::::::::::::::::::::::::::::::::::::: challenge
-## Exercise 9: Dogs and logs
+## Exercise 8: Dogs and logs
 
-Load the image 'Ersi_organoid_WT2.nd2' and select the end channel of the 16th
-frame, i.e. `img[15, 2, :, :]`. Display a figure of:
+Load the second channel of the 30th frame of [skimage.data.cells3d()](https://scikit-image.org/docs/stable/api/skimage.data.html#skimage.data.cells3d)
+again:
+
+```python
+from skimage.data import cells3d
+
+image = cells3d()[30, 1, :, :]
+```
+
+Display a figure of:
 
 - The original image
 - Image with a Difference of Gaussians applied with sigma values 2 and 4
 - Image with a Laplacian of Gaussians applied. Note that the Laplace filter linked
-  above does not perform the Gaussian filter for you.
+  above does not perform the Gaussian filter for you, so you will need to pass the
+  image through `gaussian()` first.
 
 :::::::::::::::::::::::: solution 
 
 ```python
-plt.subplot(1, 3, 1)
-imshow(img[15, 2, :, :])
+from skimage.data import cells3d
+from skimage.filters import difference_of_gaussians, laplace
+
+image = cells3d()[30, 1, :, :]
+matplotlib.pyplot.figure(figsize=(10, 12))
+
+matplotlib.pyplot.subplot(2, 2, 1)
+imshow(image)
+matplotlib.pyplot.title('Original')
 
-plt.subplot(1, 3, 2)
-imshow(skimage.filters.difference_of_gaussians(img[15, 2, :, :], 2, 4))
+matplotlib.pyplot.subplot(2, 2, 2)
+imshow(difference_of_gaussians(image, 1, 2), cmap='gray')
+matplotlib.pyplot.title('Difference of Gaussians')
 
-plt.subplot(1, 3, 3)
-imshow(skimage.filters.laplace(img[15, 2, :, :]))
+matplotlib.pyplot.subplot(2, 2, 3)
+imshow(laplace(gaussian(image, sigma=2)), cmap='gray')
+matplotlib.pyplot.title('Laplacian of Gaussian')
 ```
 
 ![](fig/2_3_dogs_and_logs.jpg){alt='Dogs and logs'}
 
 :::::::::::::::::::::::::::::::::
 
-## Exercise 10: Choosing a filter
+## Exercise 9: Choosing a filter
 
-Look at the images you produced in exercises 7 and 9, and select one to use in
+Look at the images you produced in exercises 6 and 8, and select one to use in
 subsequent chapters for thresholding and segmentation!
 :::::::::::::::::::::::::::::::::::::::::::::::
 

episodes/fig/2_1_filters.jpg

@@ -2,4 +2,21 @@
 title: Instructor Notes
 ---
 
-This is a placeholder file. Please add content here.
+# Building the course
+
+Set up R:
+
+conda create -p path/to/conda -c conda-forge r-base pandoc
+
+Install sandpaper as per the [docs](https://carpentries.github.io/sandpaper-docs):
+
+```r
+install.packages(c('sandpaper', 'varnish', 'pegboard'), c("https://carpentries.r-universe.dev/", getOption("repos")))
+```
+
+To build and serve interactively:
+
+```r
+library('sandpaper')
+sandpaper::serve()
+```