Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,8 @@ waveorder/_version.py
*.npz
*.tif[f]
*.pdf
# the screening tutorial ships its vector figures and whitepaper PDF
!docs/guide/labelfree-screening/**/*.pdf

# example data
/examples/data_temp/*
Expand Down
3 changes: 2 additions & 1 deletion docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,8 @@

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = []
# Developer notes that live next to a page but are not part of the site.
exclude_patterns = ["guide/labelfree-screening/README.md"]

# The reST default role (used for this markup `text`) to use for all documents.
# default_role = None
Expand Down
1 change: 1 addition & 0 deletions docs/guide.rst
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ User Guides

guide/QLIPP
guide/data-schema
guide/labelfree-screening/labelfree-screening
guide/buyers-guide
guide/microscope-installation-guide
guide/software-installation-guide
Expand Down
58 changes: 58 additions & 0 deletions docs/guide/labelfree-screening/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# Label-free screening tutorial: source files

This folder is self-contained: the tutorial page, the 2-page whitepaper PDF
source, the figures, the configs the tutorial teaches, and the scripts that
regenerate everything.

| Path | Contents |
| --- | --- |
| `labelfree-screening.md` | The tutorial page (rendered on the docs site). |
| `whitepaper.tex` | 2-page print layout of the same content (boxed failure modes, Biohub footer). |
| `whitepaper.pdf` | The built whitepaper. |
| `make_pdf.sh` | Builds `whitepaper.pdf` with pdflatex. |
| `figures/` | Tutorial figures: PDF (whitepaper) and PNG (docs site). |
| `figures/make_figures.py` | Draws the data figures from the crops in `figures/data/`. |
| `figures/data/` | 8-bit image crops behind the data figures, each scaled to the contrast its panel shows. |
| `figures/koehler/` | Draws the Koehler alignment figure from a parametric cartoon microscope (`scope_model.py`, `make_figure.py`). |
| `figures/requirements.txt` | Pinned packages for both figure scripts, compiled from `requirements.in`. |
| `configs/phase.yml` | Baseline 2D phase reconstruction config. |
| `configs/phase_autofocus.yml` | Baseline plus `z_focus_offset: auto`. |
| `configs/phase_autofocus_tilt.yml` | Autofocus plus warm-started illumination tilt fitting. |
| `brand/` | CZ Biohub logo for the whitepaper footer. |

## Rebuilding

You need [uv](https://docs.astral.sh/uv/), and for the PDF a full TeX Live or
MacTeX install (`make_pdf.sh` lists the LaTeX packages). Nothing outside this
folder is read.

```sh
cd figures
uv run --no-project --python 3.12 --with-requirements requirements.txt python make_figures.py
uv run --no-project --python 3.12 --with-requirements requirements.txt python koehler/make_figure.py
cd .. && ./make_pdf.sh
```

- The first run downloads cadquery and vtk (several hundred MB). The Koehler
figure takes one to two minutes, because it renders a 3D model; on a
headless Linux machine vtk needs an OpenGL context (e.g. `xvfb-run`).
- With the pinned packages the figures come out byte-for-byte identical to
the committed ones on the machine they were made on (macOS, Apple
silicon). Other platforms may differ in rendering details.
- `whitepaper.pdf` is built without timestamps, so rebuilding with the same
TeX install reproduces it exactly. The date in its footer is set by hand in
`whitepaper.tex`.

## Where the crops come from

The crops in `figures/data/` are cut from one raw position of the OPS atlas
store (`A/1/029029`, well center) and from `waveorder reconstruct` outputs
for that position and for `A/1/002029` (north edge), using the configs in
`configs/` and variants of them with the one setting each panel names
changed. `python figures/make_figures.py --from-hpc` rebuilds the crops from
those stores; it needs Biohub HPC access and iohub, and its docstring lists
the reconstructions it expects.

The committed crops were recovered from the figure PDFs of an earlier
revision of this tutorial, at 161 to 248 pixels across. Rebuilding them with
`--from-hpc` gives 256-pixel crops cut from the full-resolution data.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
13 changes: 13 additions & 0 deletions docs/guide/labelfree-screening/configs/phase.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
input_channel_names: [BF]
reconstruction_dimension: 2
phase:
transfer_function:
yx_pixel_size: 0.325
z_pixel_size: 2.0
wavelength_illumination: 0.450
index_of_refraction_media: 1.0
numerical_aperture_detection: 0.55
numerical_aperture_illumination: 0.4
invert_phase_contrast: false
apply_inverse:
regularization_strength: 0.001
14 changes: 14 additions & 0 deletions docs/guide/labelfree-screening/configs/phase_autofocus.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
input_channel_names: [BF]
reconstruction_dimension: 2
phase:
transfer_function:
yx_pixel_size: 0.325
z_pixel_size: 2.0
wavelength_illumination: 0.450
index_of_refraction_media: 1.0
numerical_aperture_detection: 0.55
numerical_aperture_illumination: 0.4
invert_phase_contrast: false
z_focus_offset: auto
apply_inverse:
regularization_strength: 0.001
19 changes: 19 additions & 0 deletions docs/guide/labelfree-screening/configs/phase_autofocus_tilt.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
input_channel_names: [BF]
reconstruction_dimension: 2
phase:
transfer_function:
yx_pixel_size: 0.325
z_pixel_size: 2.0
wavelength_illumination: 0.450
index_of_refraction_media: 1.0
numerical_aperture_detection: 0.55
numerical_aperture_illumination: 0.4
invert_phase_contrast: false
z_focus_offset: auto
tilt_angle_zenith: {init: 0.13, lr: 0.05}
tilt_angle_azimuth: {init: 0.0, lr: 0.05}
apply_inverse:
regularization_strength: 0.001
optimization:
max_iterations: 50
method: adam
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading