IGC-Advanced-Imaging-Resource · lauracmurphy · Jul 2, 2025 · Jul 2, 2025 · Jul 2, 2025 · Jul 2, 2025
diff --git a/config.yaml b/config.yaml
@@ -8,8 +8,14 @@
 # lc: Library Carpentry
 # cp: Carpentries (to use for instructor training for instance)
 # incubator: The Carpentries Incubator
+# Note that you can also use a custom carpentry type. For more info,
+# see the documentation: https://carpentries.github.io/sandpaper-docs/editing.html
 carpentry: 'incubator'
 
+# Custom carpentry description
+# This will be used as the alt text for the logo
+# carpentry_description: "Custom Carpentry"
+
 # Overall title for pages.
 title: 'Microscopy Image Analysis with Python and Napari'
 
@@ -59,12 +65,14 @@ contact:
 
 # Order of episodes in your lesson
 episodes: 
+- introduction.md
 - 01-opening-and-checking-an-image.md
 - 02-applying-filters.md
 - 03-thresholding-and-segmentation.md
 - 04-measurements.md
 - 05-napari.md
 
+
 # Information for Learners
 learners: 
 

diff --git a/data/FluorescentCells_3channel.tif b/data/FluorescentCells_3channel.tif
diff --git a/data/confocal-series_zstack.tif b/data/confocal-series_zstack.tif
diff --git a/data/hela-cells_rgb.tif b/data/hela-cells_rgb.tif
diff --git a/data/hela.tif b/data/hela.tif
diff --git a/data/summary.md b/data/summary.md
diff --git a/data/Ersi_organoid_WT2.nd2 → episodes/data/Ersi_organoid_WT2.nd2 b/data/Ersi_organoid_WT2.nd2 → episodes/data/Ersi_organoid_WT2.nd2
diff --git a/data/Thumbs.db → episodes/data/Thumbs.db b/data/Thumbs.db → episodes/data/Thumbs.db
diff --git a/episodes/data/cells3d.tif b/episodes/data/cells3d.tif
diff --git a/episodes/data/nuclei.tif b/episodes/data/nuclei.tif
diff --git a/episodes/data/summary.md b/episodes/data/summary.md
@@ -0,0 +1,9 @@
+# Details of data
+
+| Dataset       | Source        | Copyright details |
+| ------------- |-------------|-------------|
+| Ersi_organoid_WT2.nd2|[Institute of Genetics and Cancer](https://institute-genetics-cancer.ed.ac.uk/)|CC0 1.0|
+| nuclei.tif |[scitkit-image - adaped from cells3d dataset](https://gitlab.com/scikit-image/data)|CC0|
+| cells3d.tif |[scitkit-image](https://gitlab.com/scikit-image/data)|CC0|
+| zebrafish_nuclei_and_membranes.tif|[Bioimage Archive entry S-BIAD559 by Hartmann et al.,](https://www.ebi.ac.uk/biostudies/BioImages/studies/S-BIAD599)|CC BY 4.0|
+| zebrafish_nuclei_and_membranes_crop_stack.tif|[Bioimage Archive entry S-BIAD559 by Hartmann et al.,](https://www.ebi.ac.uk/biostudies/BioImages/studies/S-BIAD599)|CC BY 4.0|
diff --git a/episodes/data/zebrafish_nuclei_and_membranes.tif b/episodes/data/zebrafish_nuclei_and_membranes.tif
diff --git a/episodes/data/zebrafish_nuclei_and_membranes_crop_stack.tif b/episodes/data/zebrafish_nuclei_and_membranes_crop_stack.tif
diff --git a/episodes/fig/snapshot_example_cells_3d.png b/episodes/fig/snapshot_example_cells_3d.png
diff --git a/episodes/introduction.md b/episodes/introduction.md
@@ -0,0 +1,130 @@
+---
+title: 'Introduction'
+teaching: 10
+exercises: 2
+---
+
+:::::::::::::::::::::::::::::::::::::: questions 
+- What will I learn in this course, and how is it structured?
+- Why use Python for microscopy image analysis?
+- What are digital microscopy images, and how do they differ from everyday images?
+- What kinds of things can I measure from images using Python?
+- How is the course organised and what software and data will I need to follow along?
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::: objectives
+- Describe the aims and structure of the course
+- Identify the main Python tools used in microscopy image analysis
+- Recognise different types of microscopy image data and formats
+- Verify that the required software and packages are installed
+- Navigate the lesson materials and setup environment
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+## Welcome
+
+This course introduces essential tools and techniques for working with digital microscopy images using Python. It is aimed at researchers and students with some experience in microscopy and a basic familiarity with scripting. You do not need to be an expert programmer to benefit.
+
+We’ll use real image data and widely-used open-source Python libraries.
+
+## What will we do in this course?
+
+By the end of the course, you will be able to:
+
+- Open and inspect images in Python
+- Explore and process multi-dimensional datasets (e.g. time series, z-stacks, multi-channel images)
+- Apply filters and perform background correction
+- Segment and measure biological objects (e.g. nuclei, cells)
+- Use Napari for visualising and interacting with image data
+
+## Bioimage Analysis
+
+Bioimage analysis allows you to extract measurable information from biological samples. Examples include:
+
+- Object size, shape, and area
+- Intensity or signal distribution per region
+- Cell counts, distances, and object relationships
+- Colocalisation of signals across channels
+
+A typical image analysis workflow looks like:
+
+1. **Preprocessing** (e.g. background subtraction, filtering)
+2. **Segmentation** (defining objects of interest, such as nuclei)
+3. **Feature extraction** (e.g. area, intensity, shape, location)
+4. **Analysis and interpretation** (e.g. plotting, classification, statistics)
+
+## Key software tools
+
+In this course, we’ll use:
+
+- **Jupyter notebooks**: for writing and running Python interactively
+- **NumPy**: for handling numerical arrays (which is what images are!)
+- **scikit-image**: for general image processing operations
+- **matplotlib**: for plotting and displaying images
+- **Napari**: for interactive viewing and annotation of multi-dimensional images
+
+All episodes use open-source tools that you can install locally or access via your institution’s JupyterHub (e.g. Noteable for University of Edinburgh users).
+
+::::::::::::::::::::::::::::::::::::: callout
+### 💡 Reflection
+
+Have you used any of the following before?
+
+- Jupyter notebooks
+- Napari
+- Python image libraries (e.g. scikit-image, OpenCV)
+
+Take a minute to note down which tools you're already familiar with and what you'd like to learn.
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+## What kind of data?
+
+We’ll work with real microscopy images, including:
+
+- Multi-channel fluorescence `.tif` files
+- 3D z-stacks and time series
+- Proprietary formats (e.g. `.nd2`, `.czi`)
+
+We'll also cover how to read metadata, understand bit depth, and interpret image dimensions.
+
+::::::::::::::::::::::::::::::::::::: callout
+### Note: RGB vs Multichannel Images
+
+Images like `.jpg` or `.png` use RGB colour, where each pixel contains red, green, and blue values. This format is common in photography, but also used in scientific imaging — for example, brightfield pathology slides stained with H&E or H-DAB are typically stored as RGB images.
+
+In fluorescence microscopy, however, images are usually stored as **separate grayscale channels**, one per fluorophore (e.g. DAPI, GFP, RFP). These can be combined into a colour composite for display, but are fundamentally different from RGB images where colour is already baked in. These are the only types of images we'll look at today but it's important to know that RGB images exist and you may need to analyse and it might look a bit different from what we do today.
+
+:::::::::::::::::::::::::::::::::::::::::::::::::
+:::::::::::::::::::::::::::::::::::::::::::::::::
+
+## Course structure
+
+This course is made up of the following episodes:
+
+1. **Introduction** (this episode)
+2. **Opening and checking an image**
+3. **Applying Filters**
+4. **Thresholding and Segmentation**
+5. **Measurements**
+6. **Introduction to Napari**
+
+Each episode includes code-along demonstrations, exercises, and challenges. 
+
+## Meet the dataset
+
+Here is one of the images we’ll be working with:
+
+![Sample fluorescent image](fig/FluorescentCells_3channel_thumb.jpg){alt="Thumbnail of test image"}
+
+This is a multi-channel fluorescent image showing nuclei, membranes, and cytoplasm in different colours.
+
+You’ll also work with z-stacks, RGB images, and proprietary formats like `.nd2`.
+
+➡️ See the [Reference page](../reference) for a quick recap of Python syntax and digital image basics used in this course.
+
+---
+
+::::::::::::::::::::::::::::::::::::: keypoints
+- This course is for researchers with some Python and microscopy experience
+- We will use open-source tools for exploring, processing, and analysing images
+- You will learn how to work with multi-dimensional bioimages and extract useful measurements
+::::::::::::::::::::::::::::::::::::::::::::::::
diff --git a/index.md b/index.md
@@ -2,16 +2,15 @@
 site: sandpaper::sandpaper_site
 ---
 
-This image analysis course provides an introduction to basic image analysis techniques in two environments:
-[Python](https://www.python.org) and [Napari](https://napari.org).
+This image analysis course provides an introduction to basic image analysis techniques in two Python environments:
+[Jupyter](https://www.python.org) and [Napari](https://napari.org).
 
 These two environments have different interfaces for user interaction, but both offer powerful tools for image
 processing and analysis. Both are discussed here in order to highlight the relative strengths of each one, and
 to present the analysis techniques in this course as generic and independent of one particular platform.
 
-The first section on Python consists of working in a [Jupyter](https://jupyter.org/) notebook setting, but can equally be done in the
-terminal. This way of working also lends itself quite well to adapting your analysis process into a workflow that
-can be applied to a batch of many images.
+The first section on Python consists of working in a [Jupyter Notebook](https://jupyter-notebook.readthedocs.io/en/stable/) setting, but can equally be done in the
+terminal. Juypter notebooks are often used for academic purpose as they facilitate documenting what the code does, the output and the ability to add additional explanations and links to resources. The lends itself quite well to adapting your analysis process into a workflow that can be applied to a batch of many images.
 
 Napari is a point-and-click graphical user interface, which is well-suited to exploring and previewing images,
 and is particularly useful for viewing multi-dimensional data such as 3D Z-stacks and time series. Incidentally,

diff --git a/jupyter notebook/blank b/jupyter notebook/blank
diff --git a/jupyter notebook/spindle angle.ipynb b/jupyter notebook/spindle angle.ipynb
diff --git a/learners/reference.md b/learners/reference.md
@@ -1,7 +1,61 @@
 ---
 title: Reference
 ---
-
+## Basics of Digital Images Primer
+### Pixels and Intensity  
+Microscopy images are made up of pixels arranged in a grid. Each pixel stores a numerical value representing how bright that part of the image is, often referred to as the intensity. In most images, higher values mean brighter areas. These values are the foundation for all image-based measurements.
+
+### Bit Depth  
+Bit depth determines the range of intensity values that can be stored per pixel. An 8-bit image stores values from 0 to 255, while a 16-bit image allows values from 0 to 65,535. Higher bit depth enables better representation of subtle brightness differences, which is important when imaging faint or low-contrast structures.
+
+### Image Dimensions  
+Microscopy data often has more than two dimensions. In addition to spatial (x, y), you may also have:
+- **z-stacks** (depth),
+- **Time series** (t),
+- **Multiple channels** (c).
+
+This results in 3D, 4D, or even 5D images. Tools like Napari are built to work with n-dimensional image data.
+
+### Channels  
+Each channel represents a different signal or fluorophore, captured using specific excitation and emission settings (e.g. DAPI for nuclei or GFP-tagged proteins). These are usually stored as separate greyscale images and can be visualised together as composite images. Different channels are often analysed separately, depending on what they label.
+
+### Brightness and Contrast  
+Brightness and contrast settings determine how intensity values are mapped to your screen. You usually set a display minimum and maximum; for a linear greyscale lookup table, intensities below the minimum will appear black, those above the maximum will appear white, and values in between are scaled accordingly. These adjustments affect only the display, making structures appear brighter or increasing contrast. The underlying data is not affected.
+
+### File Formats  
+Microscopy images come in a range of formats:
+- **Open formats** such as `.tif` (TIFF) are commonly used and broadly supported by analysis tools.
+- **Proprietary formats** such as `.nd2`, `.czi`, and `.lif` are produced by specific microscope systems and often contain embedded metadata.
+When exporting images for analysis, use formats that preserve full bit depth and metadata.
+
+### Metadata  
+Metadata is "data about data": it describes how to interpret the intensity grid. This includes pixel size (e.g. microns per pixel), z-step size, channel names, and microscope settings such as exposure time or objective lens. Metadata is essential for accurate measurements and reproducibility.
+
+### Noise and Convolution  
+All microscopy images contain **noise**: random fluctuations in pixel values that do not reflect the actual structure of the sample. Common sources include:
+- **Shot noise** from the light detection process
+- **Electronic noise** from the detector
+- **Background autofluorescence** from the sample or mounting medium
+
+**Convolution** in microscopy refers to how light from a single point in the sample spreads into a shape called the **point spread function (PSF)**, due to diffraction and optical limitations. This blurs the image and limits resolution. Many image processing steps aim to reverse or compensate for the effects of both convolution and noise.
+
+### Filters  
+Filters are used to reduce noise, enhance contrast, or correct illumination. Common examples include:
+- **Gaussian blur**: smooths the image by averaging nearby pixels
+- **Median filter**: removes speckle noise while preserving edges
+- **Background subtraction**: removes uneven illumination using techniques such as rolling ball or difference of Gaussians
+
+These filters can improve the performance of downstream analysis such as segmentation.
+
+### Segmentation  
+Segmentation is the process of identifying and outlining objects of interest (e.g. nuclei, cells, vesicles). It is a key step in quantitative image analysis. Approaches include:
+- **Thresholding**: the process of deciding which pixels belong to the object or background based on their intensity  
+- **Binarisation**: the result of thresholding; this converts the image into two values (typically 0 and 1), where one represents the object and the other the background  
+- **Watershed**: splits touching objects based on shape or topography  
+- **Semantic segmentation**: labels each pixel according to class (e.g. cell vs background)  
+- **Instance segmentation**: detects and labels each object individually  
+- **Deep learning-based tools**: [Cellpose](https://www.cellpose.org/), [StarDist](https://github.com/stardist/stardist), and [Instanseg](https://github.com/instanseg/instanseg) use pre-trained neural networks to perform instance segmentation. These tools can often give good results on complex or low-contrast images that are difficult to segment using traditional image processing methods.
+
 ## Python syntax primer
 
 As this is a course on image analysis, some prior knowledge of Python syntax is assumed.
@@ -214,4 +268,67 @@ for val in values:
 
     else:
         print(str(val) + ' is less than 0')
-```
+```
+
+
+Glossary
+
+array
+: A structured grid of values. In Python, images are often stored as NumPy arrays.
+
+bit depth
+: The number of bits used to store each pixel's intensity. Higher bit depths allow more precise intensity values.
+
+channel
+: A single grayscale component of a multichannel image, often representing a specific stain or marker.
+
+colormap, also called a lookup table or LUT
+: A colour mapping used to display grayscale images. Doesn't affect pixel values—only how they're shown.
+
+dimension
+: One axis of a multidimensional image (e.g. X, Y, Z, time, channel).
+
+feature extraction
+: Measuring properties of segmented objects (e.g. area, intensity, shape).
+
+histogram
+: A plot showing the distribution of pixel intensities. Use to look at the distribution of intensity values in an image.
+
+Jupyter notebook
+: An interactive coding environment that mixes Python code, outputs, and text explanations in one file.
+
+label
+: A unique integer assigned to each segmented object, used to distinguish and measure them.
+
+metadata
+: Information that describes the image, such as pixel size, acquisition settings, or channel names.
+
+Napari
+: A Python-based interactive viewer for multidimensional image data.
+
+NumPy
+: A Python library for numerical computing. Its arrays are used to represent images in most analysis workflows.
+
+pixel
+: The smallest unit of an image, representing a single intensity value.
+
+pixel spacing
+: The real-world size each pixel represents (e.g. 0.2 µm per pixel). Needed to convert measurements to physical units.
+
+preprocessing
+: Steps to clean or improve an image before analysis, like noise reduction or background subtraction.
+
+Python
+: A high-level programming language widely used for scientific computing and image analysis.
+
+RGB image
+: A colour image with three channels: red, green, and blue..
+
+scikit-image
+: A Python library offering tools for filtering, segmentation, and measuring images.
+
+segmentation
+: Dividing an image into regions of interest, such as cells or nuclei.
+
+thresholding
+: Converting a grayscale image to binary by setting a pixel intensity cutoff.
diff --git a/profiles/learner-profiles.md b/profiles/learner-profiles.md
@@ -1,5 +1,14 @@
 ---
-title: FIXME
+title: Learner Profiles
 ---
 
-This is a placeholder file. Please add content here.
+This course is designed for microscopists in the life sciences who want to get started with microscopy image analysis using Python and Napari. It assumes learners already have:
+
+- Basic familiarity with programming (e.g., using variables, loops, functions). If you need help, see our Python primer [here](https://igc-advanced-imaging-resource.github.io/image-analysis-python-napari/reference.html#python-syntax-primer).
+- Some experience working with digital microscopy images, even if only through acquisition or basic visual inspection in software like FIJI. We have also prepared a primer of the basics of digital images [here](https://igc-advanced-imaging-resource.github.io/image-analysis-python-napari/reference.html#digital-images-primer) but if you want to put your best foot forward at the workshop then a great resource to prime yourself with is Pete Bankhead's online textbook ["Introduction to Bioimage Analysis"](https://bioimagebook.github.io/index.html), particularly the section on ["Images & Pixels"](https://bioimagebook.github.io/chapters/1-concepts/1-images_and_pixels/images_and_pixels.html)
+
+No prior experience with Napari or advanced image processing techniques is required. 
+
+
+
+