demos for AQLM 2025

[mattersoflight]

I am adding two demos in the examples/demos/ folder. These are based on simulations on examples/maintanence folder. During AQLM, we will finetune these demos. It would make sense to turn the examples/maintenance into non-interactive tests after we merge this PR.

• Make jupytext dependency of dev installation.
• QLIPP forward simulation and reconstruction
• test QLIPP forward simulation and reconstruction using Google Colab: https://colab.research.google.com/github/mehta-lab/waveorder/blob/demos-aqlm/docs/examples/demos/QLIPP/QLIPP_simulation.ipynb
• QPI from defocus simulation and reconstruction
• test QPI from defocus simulation and reconstruction using Google Colab:
  https://colab.research.google.com/github/mehta-lab/waveorder/blob/demos-aqlm/docs/examples/demos/QPI_defocus/QPI_defocus_simulation.ipynb
• QPI from defocus reconstruction with experimental data
• test QPI from defocus reconstruction with experimental data https://colab.research.google.com/github/mehta-lab/waveorder/blob/demos-aqlm/docs/examples/demos/QPI_defocus/QPI_defocus_experiment.ipynb

[talonchandler]

I've given these notebooks a pass, and they now run end to end locally.

The QPI simulation notebook runs on Colab, but I'm still trying to figure out iohub installation issues in Colab for the QPI experiment notebook.

[talonchandler]

Found a solution in !pip install iohub==0.2.0.

FYI @edyoshikun @ziw-liu, iohub==0.1.0 doesn't seem to be working with colab.

[ziw-liu]

Found a solution in !pip install iohub==0.2.0.

FYI @edyoshikun @ziw-liu, iohub==0.1.0 doesn't seem to be working with colab.

I think the kernel needs to be restarted for the old version. But we should really update waveorder's dependencies. (#197)

[mattersoflight]

@talonchandler, the demos via google colab worked well. I updated the phase from defocus demo to illustrate 3D OTF's magnitude and phase, which sparked good discussion.

Few observations and questions (I am getting familiar again with codebase and will continue to do so as we wrap up the paper):

• QLIPP reconstruction is done through waveorder_simulator.waveorder_microscopy_simulator, which appears to be the code path from earlier (PTI submission). Should we switch to using waveorder.models.inplane_oriented_thick_pol3d_vector?
• Is the code for inverse filter shared across above demos?

[mattersoflight]

@talonchandler why do we pin iohub to 0.1.0?

This cell shows this error - but the notebook runs fine.

import sys
import subprocess

# Install latest waveorder from main branch
subprocess.check_call(
    [
        sys.executable,
        "-m",
        "pip",
        "install",
        "git+https://github.com/mehta-lab/waveorder.git@main",
    ]
)
!pip install iohub==0.2.0

ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts.
waveorder 2.2.2.dev1378+g8315e00 requires iohub==0.1.0, but you have iohub 0.2.0 which is incompatible.
waveorder 2.2.2.dev1378+g8315e00 requires pydantic==1.10.19, but you have pydantic 2.11.4 which is incompatible.
Successfully installed iohub-0.2.0 numcodecs-0.15.1 pydantic-2.11.4 pydantic_extra_types-2.10.4 tifffile-2025.3.30 zarr-2.18.7

[mattersoflight]

Add a block on phase reconstruction as well.

[mattersoflight]

Perhaps using waveorder.models.inplane_oriented_thick_pol3d_vector

[talonchandler]

QLIPP reconstruction is done through waveorder_simulator.waveorder_microscopy_simulator, which appears to be the code path from earlier (PTI submission). Should we switch to using waveorder.models.inplane_oriented_thick_pol3d_vector?

That's correct. As much as possible we should use the code paths in /docs/examples/models/.

Is the code for inverse filter shared across above demos?

The reconstructions in /docs/examples/models/ use a shared code path for reconstructions wherever possible---e.g. waveorder.filter.apply_filter_bank applies all of our Fourier reconstructions.

why do we pin iohub to 0.1.0?

No longer needed! Thanks @ziw-liu --- see #448.

---

@mattersoflight let's catch up on our plans here after your deadlines.

• There are major code paths that can be cut soon if we want to prioritize the PTI path.
• I'd like to chat about which types of notebooks are critical to maintain, and if we can reduce duplication between the notebooks and the napari-based test scripts in /docs/examples/models. FWIW these test scripts are my day-to-day entry point into these models at the python level.

[mattersoflight]

@talonchandler @ziw-liu

My thoughts below on what makes a good collection of test scripts and demos:

• Napari-based scripts for methods we report in the paper (including PTI). Let's use a common code path, even if that breaks previous PTI notebooks - we can version them as a PDF with a note that the code is being refactored. We should switch over to methods in waveorder.models.* and waveorder.filter.apply_filter_bank for all of our work.
• Illustrative notebooks for methods that we are deploying outside of Biohub (2D QPI, 3D QPI, QLIPP). These could be identical to your napari-based scripts, except they use the ipywidget visualizations. Google Colab works very well for teaching and demos. We could also containerize the napari demos to make installations reproducible.
• Let's depend on iohub 0.2.0

[talonchandler]

Adding a couple notes following our discussion @mattersoflight:

• we think notebooks generated by jupytext from scripts are a good way to
• we've found that installing napari in a conda environment is a significant barrier to entry. We want to try sharing a docker container as a way for a new user to run our scripts with napari.

[mattersoflight]

Hi @talonchandler since we decided to not work on docker with napari for now. I think we can proceed with current jupyter notebooks for "onboarding" new users. Do you need further review to merge these?