waveorder 1.0.0rc2__tar.gz → 2.0.0__tar.gz

{waveorder-1.0.0rc2 → waveorder-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: waveorder
-Version: 1.0.0rc2
+Version: 2.0.0
 Summary: Wave optical simulations and deconvolution of optical properties
 Home-page: https://github.com/mehta-lab/waveorder
 Author: Computational Microscopy Platform, CZ Biohub
@@ -10,7 +10,6 @@ Project-URL: Bug Tracker, https://github.com/mehta-lab/waveorder/issues
 Project-URL: Documentation, https://github.com/mehta-lab/waveorder
 Project-URL: Source Code, https://github.com/mehta-lab/waveorder
 Project-URL: User Support, https://github.com/mehta-lab/waveorder/issues
-Platform: UNKNOWN
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: BSD License
@@ -29,8 +28,17 @@ Classifier: Operating System :: Unix
 Classifier: Operating System :: MacOS
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
-Provides-Extra: dev
 License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: matplotlib>=3.1.1
+Requires-Dist: scipy>=1.3.0
+Requires-Dist: pywavelets>=1.1.1
+Requires-Dist: ipywidgets>=7.5.1
+Requires-Dist: torch>=2.0.0
+Provides-Extra: dev
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: pytest>=5.0.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
 
 # waveorder
 
@@ -61,9 +69,10 @@ In addition to PTI, `waveorder` enables simulations and reconstructions of subse
 
 PTI provides volumetric reconstructions of mean permittivity ($\propto$ material density), differential permittivity ($\propto$ material anisotropy), 3D orientation, and optic sign. The following figure summarizes PTI acquisition and reconstruction with a small optical section of the mouse brain tissue:
 
-![Data_flow](https://github.com/mehta-lab/waveorder/blob/main/Fig_Readme.png?raw=true)
+![Data_flow](https://github.com/mehta-lab/waveorder/blob/main/readme.png?raw=true)
+
 
-The [example notebooks](examples/) illustrate simulations and reconstruction for 2D QLIPP, 3D PODT, and 2D/3D PTI methods.
+The [examples](https://github.com/mehta-lab/waveorder/tree/main/examples) illustrate simulations and reconstruction for 2D QLIPP, 3D PODT, and 2D/3D PTI methods.
 
 If you are interested in deploying QLIPP or PODT for label-free imaging at scale, checkout our [napari plugin](https://www.napari-hub.org/plugins/recOrder-napari),  [`recOrder-napari`](https://github.com/mehta-lab/recOrder).
 
@@ -73,7 +82,7 @@ In addition to label-free reconstruction algorithms, `waveorder` also implements
 
 1. Correlative measurements of biomolecular density and orientation from polarization-diverse widefield imaging ([multimodal Instant PolScope](https://opg.optica.org/boe/fulltext.cfm?uri=boe-13-5-3102&id=472350))
 
-We provide an [example notebook](examples/experimental_reconstructions/fluorescence_deconvolution/) for widefield fluorescence deconvolution.
+We provide an [example notebook](https://github.com/mehta-lab/waveorder/blob/main/examples/documentation/fluorescence_deconvolution/fluorescence_deconv.ipynb) for widefield fluorescence deconvolution.
 
 ## Citation
 
@@ -109,13 +118,7 @@ pip install jupyter
 jupyter notebook ./waveorder/examples/
 ```
 
-(Optional) Use NVIDIA GPUs by installing `cupy` with [these instructions](https://docs.cupy.dev/en/stable/install.html). Check that `cupy` is properly installed with
-
-```sh
-python
->>> import cupy
-```
-
-To use GPUs in `waveorder` set ```use_gpu=True``` when initializing the simulator and reconstructor classes.
-
-
+(M1 users) `pytorch` has [incomplete GPU support](https://github.com/pytorch/pytorch/issues/77764),
+so please use `export PYTORCH_ENABLE_MPS_FALLBACK=1`
+to allow some operators to fallback to CPU
+if you plan to use GPU acceleration for polarization reconstruction. 

{waveorder-1.0.0rc2 → waveorder-2.0.0}/README.md

@@ -27,9 +27,10 @@ In addition to PTI, `waveorder` enables simulations and reconstructions of subse
 
 PTI provides volumetric reconstructions of mean permittivity ($\propto$ material density), differential permittivity ($\propto$ material anisotropy), 3D orientation, and optic sign. The following figure summarizes PTI acquisition and reconstruction with a small optical section of the mouse brain tissue:
 
-![Data_flow](https://github.com/mehta-lab/waveorder/blob/main/Fig_Readme.png?raw=true)
+![Data_flow](https://github.com/mehta-lab/waveorder/blob/main/readme.png?raw=true)
 
-The [example notebooks](examples/) illustrate simulations and reconstruction for 2D QLIPP, 3D PODT, and 2D/3D PTI methods.
+
+The [examples](https://github.com/mehta-lab/waveorder/tree/main/examples) illustrate simulations and reconstruction for 2D QLIPP, 3D PODT, and 2D/3D PTI methods.
 
 If you are interested in deploying QLIPP or PODT for label-free imaging at scale, checkout our [napari plugin](https://www.napari-hub.org/plugins/recOrder-napari),  [`recOrder-napari`](https://github.com/mehta-lab/recOrder).
 
@@ -39,7 +40,7 @@ In addition to label-free reconstruction algorithms, `waveorder` also implements
 
 1. Correlative measurements of biomolecular density and orientation from polarization-diverse widefield imaging ([multimodal Instant PolScope](https://opg.optica.org/boe/fulltext.cfm?uri=boe-13-5-3102&id=472350))
 
-We provide an [example notebook](examples/experimental_reconstructions/fluorescence_deconvolution/) for widefield fluorescence deconvolution.
+We provide an [example notebook](https://github.com/mehta-lab/waveorder/blob/main/examples/documentation/fluorescence_deconvolution/fluorescence_deconv.ipynb) for widefield fluorescence deconvolution.
 
 ## Citation
 
@@ -75,11 +76,7 @@ pip install jupyter
 jupyter notebook ./waveorder/examples/
 ```
 
-(Optional) Use NVIDIA GPUs by installing `cupy` with [these instructions](https://docs.cupy.dev/en/stable/install.html). Check that `cupy` is properly installed with
-
-```sh
-python
->>> import cupy
-```
-
-To use GPUs in `waveorder` set ```use_gpu=True``` when initializing the simulator and reconstructor classes.
+(M1 users) `pytorch` has [incomplete GPU support](https://github.com/pytorch/pytorch/issues/77764),
+so please use `export PYTORCH_ENABLE_MPS_FALLBACK=1`
+to allow some operators to fallback to CPU
+if you plan to use GPU acceleration for polarization reconstruction. 

waveorder-2.0.0/docs/valuable-prs/2023-02-27.110.pr.open.md

@@ -0,0 +1,308 @@
+# [\#110 PR](https://github.com/mehta-lab/waveorder/pull/110) `open`: New Stokes and Mueller module
+
+#### <img src="https://avatars.githubusercontent.com/u/9554101?u=7ab5421e9a6613c01e9c1d3261fa6f93645d48f9&v=4" width="50">[talonchandler](https://github.com/talonchandler) opened issue at [2023-02-27 22:13](https://github.com/mehta-lab/waveorder/pull/110):
+
+This PR adds a completely rewritten version of all Stokes- and Mueller-related calculations in `waveorder`.
+
+This rewrite was motived by the following questions:
+- Q: how should we handle background correction of S3 to prepare it for deconvolution? A: keep track of S3 and use Mueller matrices to correct backgrounds. 
+- how should we handle normalization (see the closed #103 for an earlier discussion)? A: no need to normalize in a separate step. 
+- can we handle larger background retardances? A: yes, by estimating Mueller matrices. 
+
+**Highlight improvements:**
+- removal of normalization steps...instead of a two step reconstruction with a normalization followed by reconstruction, this implementation goes straight from Stokes parameters to (retardance, orientation, transmittance, depolarization). 
+- a natively ND implementation...the Stokes and Mueller indices go in the first/second axes, and the remaining indices are arbitrary. A convenience `mmul` (Mueller multiply) function that uses `einsum` is the key simplifying design choice. 
+- A Mueller-matrix based reconstruction scheme that can handle larger background retardances. 
+
+**What does the new API look like?** Here's an example snippet from `/hpc/projects/compmicro/projects/infected_cell_imaging/Image_preprocessing/Exp_2023_02_07_A549MemNucl_PolPhase3D/Background_correction_trial/bg-corr-with-mask.py`
+```
+# Calculate A and A_inv
+A = stokes.A_matrix(swing=0.1, scheme="5-State")
+A_inv = np.linalg.pinv(A)
+
+# Apply A_inv to background and sample data
+S_bg = stokes.mmul(A_inv, cyx_bg_data)
+S_sm = stokes.mmul(A_inv, czyx_data)
+
+# Calculate background correction matrix from S_bg
+M_inv = stokes.inv_AR_mueller_from_CPL_projection(*S_bg)
+
+# Apply background correction to sample data
+bg_corr_S_sm = stokes.mmul(M_inv, S_sm)
+
+# Reconstruct parameters
+ret, ori, tra, dop = stokes.inverse_s0123_CPL_after_ADR(*bg_corr_S_sm)
+```
+
+**Limitations compared to the current `waveorder_reconstructor` implementation:**
+- No GPU implementation. @ziw-liu maybe you have ideas for flipping a gpu switch for this whole module? The `waveorder_reconstructor` class' parallel `np` and `cp` implementations seem clunky. 
+- Not yet optimized...instead of using differences and ratios to apply background corrections, this implementation uses Mueller matrices and their inverses. This implementation is not slower than the phase reconstructions, and I've added comments in the places where further optimization can improve performance. 
+
+I have not removed the existing implementation in the `waveorder_reconstructor` class. My current plan is to discuss the technical parts of this reimplementation and compare with the existing implementation here, then later I can complete the refactor by removing the Stokes parts of the `waveorder_reconstructor` class and updating the `recOrder` calls. 
+
+Note: this PR is to merge into `alg-dev`, so we have a bit more flexibility in the changes. Temporarily breaking changes/suggestions are okay while we iterate. 
+
+**Specific feedback requests:** 
+- @ziw-liu your comments on a gpu switch, and on documentation+testing practice is very welcome. I wasn't sure if I should use type annotations & numpy-style docstrings? I stayed with only docstrings for now. 
+- @mattersoflight I'm particularly interested in your thoughts on naming. For example, `inverse_s0123_CPL_after_ADR` doesn't roll off the tongue like the earlier `Polarization_recon`, but I think it's important to be very specific at this level. Later layers of abstraction can reintroduce more abstract names likes `Polarization_recon` if we think they're helpful.
+
+#### <img src="https://avatars.githubusercontent.com/u/2934183?u=e638cee77e71afc6e0579e50c2712dfe8a707869&v=4" width="50">[mattersoflight](https://github.com/mattersoflight) commented at [2023-02-27 23:04](https://github.com/mehta-lab/waveorder/pull/110#issuecomment-1447249286):
+
+> @ziw-liu your comments on a gpu switch, and on documentation+testing practice is very welcome. I wasn't sure if I should use type annotations & numpy-style docstrings? I stayed with only docstrings for now.
+
+Re: GPU implementation, the API between pytorch and numpy seems quite consistent i.e., `object.operation` runs on CPU if object is a numpy array and on GPU if `object` is a torch tensor on GPU, e.g. [pinv](https://pytorch.org/docs/stable/generated/torch.linalg.pinv.html). If we are going to replace the GPU library, I'd first consider pytorch. Can you do a census of numpy methods you use and see if the same methods are available for torch tensor?
+
+>@mattersoflight I'm particularly interested in your thoughts on naming. For example, inverse_s0123_CPL_after_ADR doesn't roll off the tongue like the earlier Polarization_recon, but I think it's important to be very specific at this level. Later layers of abstraction can reintroduce more abstract names likes Polarization_recon if we think they're helpful.
+
+If we find that all the assumptions in the forward model related to polarization transfer can be covered by two properties: a) instrument matrix, and b) sample model, we can use a generic name and specify the assumptions via arguments. I'll think more about this.
+
+#### <img src="https://avatars.githubusercontent.com/u/2934183?u=e638cee77e71afc6e0579e50c2712dfe8a707869&v=4" width="50">[mattersoflight](https://github.com/mattersoflight) commented at [2023-02-27 23:17](https://github.com/mehta-lab/waveorder/pull/110#issuecomment-1447267572):
+
+`fft` is not relevant for this PR, but for deconvolution operations later. This benchmark reports that pytorch fft works almost as fast as cupy: https://thomasaarholt.github.io/fftspeedtest/fftspeedtest.html. pytorch is accelerated on M1, but cupy will require a nvidia gpu.
+
+#### <img src="https://avatars.githubusercontent.com/u/67518483?v=4" width="50">[ziw-liu](https://github.com/ziw-liu) commented at [2023-02-27 23:28](https://github.com/mehta-lab/waveorder/pull/110#issuecomment-1447278771):
+
+> Can you do a census of numpy methods you use and see if the same methods are available for torch tensor?
+
+I wouldn't be too concerned about NumPy methods. However SciPy signal processing API may have a much lower coverage. Will have to check in detail.
+
+#### <img src="https://avatars.githubusercontent.com/u/67518483?v=4" width="50">[ziw-liu](https://github.com/ziw-liu) commented at [2023-02-27 23:36](https://github.com/mehta-lab/waveorder/pull/110#issuecomment-1447285464):
+
+Using torch is an interesting idea, in that it is 'accelerated' for CPUs too, so *in theory* the same code can work for CPU and GPU. However in addition to API coverage, lack of optimization/more overhead can be [potential issues](https://discuss.pytorch.org/t/torch-is-slow-compared-to-numpy/117502).
+
+#### <img src="https://avatars.githubusercontent.com/u/67518483?v=4" width="50">[ziw-liu](https://github.com/ziw-liu) commented at [2023-02-27 23:56](https://github.com/mehta-lab/waveorder/pull/110#issuecomment-1447300776):
+
+> I wasn't sure if I should use type annotations & numpy-style docstrings? I stayed with only docstrings for now.
+
+We don't currently have type checking infra set up, so type hints serves mainly 2 purpose:
+
+1. Help devs as well as users call the API in code elsewhere, because autocompletion and other in-editor static analysis works better.
+2. Help generate the docstring. I personally use tools that populate the type info in the docstring automatically from docstrings.
+
+I like to write type hints because it helps me code faster (e.g. I get syntax-highlighted and linted types that's copied over so less typos in the docstring type field). But as long as the code is consistent in style and well-documented I think it's all fine.
+
+#### <img src="https://avatars.githubusercontent.com/u/101817974?v=4" width="50">[Soorya19Pradeep](https://github.com/Soorya19Pradeep) commented at [2023-02-28 01:31](https://github.com/mehta-lab/waveorder/pull/110#issuecomment-1447428605):
+
+@talonchandler, the cell membrane signal from the new orientation image computed with the additional background correction definitely has more contrast and is more continuous signal compared to the earlier version with just measured background correction. Thank you!
+
+#### <img src="https://avatars.githubusercontent.com/u/2934183?u=e638cee77e71afc6e0579e50c2712dfe8a707869&v=4" width="50">[mattersoflight](https://github.com/mattersoflight) commented at [2023-02-28 15:41](https://github.com/mehta-lab/waveorder/pull/110#issuecomment-1448405744):
+
+@talonchandler 
+
+>@Soorya19Pradeep asked about the consistency of this convention with the existing waveorder implementation.
+
+Could you clarify which convention we are discussing here:  convention for what is called right vs left circularly polarized light, or convention for axes of orientation, or may be both?
+
+#### <img src="https://avatars.githubusercontent.com/u/2934183?u=e638cee77e71afc6e0579e50c2712dfe8a707869&v=4" width="50">[mattersoflight](https://github.com/mattersoflight) commented at [2023-02-28 15:47](https://github.com/mehta-lab/waveorder/pull/110#issuecomment-1448414978):
+
+@ziw-liu , @talonchandler 
+>Using torch is an interesting idea, in that it is 'accelerated' for CPUs too, so in theory the same code can work for CPU and GPU. 
+My thought was to keep using numpy for CPU, and use torch instead of cupy for GPU. There can be code branches depending on whether you use CPU or GPU, but only when matrices (tensors) are instantiated.
+
+Let's focus on the model (which is making a lot of sense as I read it), naming convention, and numpy implementation in this PR, and start a separate issue to work on GPU acceleration. We should refactor whole codebase (including deconvolution code) if we change the GPU backend.
+
+#### <img src="https://avatars.githubusercontent.com/u/101817974?v=4" width="50">[Soorya19Pradeep](https://github.com/Soorya19Pradeep) commented at [2023-02-28 16:29](https://github.com/mehta-lab/waveorder/pull/110#issuecomment-1448483920):
+
+> @talonchandler
+> 
+> > @Soorya19Pradeep asked about the consistency of this convention with the existing waveorder implementation.
+> 
+> Could you clarify which convention we are discussing here: convention for what is called right vs left circularly polarized light, or convention for axes of orientation, or may be both?
+
+@mattersoflight, I am trying to understand how to read the orientation measurement of cell membrane, if it makes physical sense. The value of orientation changes with new implementation and further background correction, so I was curious. 
+This is from orientation information from a cell from earlier version with measured background correction, colorbar range of values (-0.87,+0.87)
+<img width="444" alt="image" src="https://user-images.githubusercontent.com/101817974/221914487-29cf0229-ff9b-46a7-b26a-92bfb40dcfc7.png">
+This is from the new version with just measured background correction, range (+0.87,+2.5). I realized the information here is same, just inverted and offset by 90 degrees.
+<img width="444" alt="image" src="https://user-images.githubusercontent.com/101817974/221913601-0e56f4ac-e94c-40c6-a7ac-52fcffaa02d8.png">
+After the extra background correction the range changes and more information is visible, range (0,+3.14).
+<img width="444" alt="image" src="https://user-images.githubusercontent.com/101817974/221913869-0201bc9a-b4e4-46a5-8202-666240768d92.png">
+
+#### <img src="https://avatars.githubusercontent.com/u/9554101?u=7ab5421e9a6613c01e9c1d3261fa6f93645d48f9&v=4" width="50">[talonchandler](https://github.com/talonchandler) commented at [2023-02-28 16:50](https://github.com/mehta-lab/waveorder/pull/110#issuecomment-1448514682):
+
+@mattersoflight 
+> Could you clarify which convention we are discussing here: convention for what is called right vs left circularly polarized light, or convention for axes of orientation, or may be both?
+
+Good question...I think we should discuss both. 
+
+I can think of two paths to take here:
+
+- **Decouple the reconstruction from the orientation convention.** We can give ourselves some flexibility in RCP vs. LCP, relative orientations of the camera wrt the polarizers, axis convention etc., then give the `recOrder` user (and the scripts) enough "knobs" to fix any deviation from convention. For example, we currently have one knob in recOrder that rotates by 90 degrees. To set the knobs, image a known sample (ideally a Kazansky target, but we can point our users to a more available alternative), twiddle the knobs until your colors match your expectations, then keep those knobs as default reconstruction parameters. **This is effectively what we're doing now, and I think it's workable.** 
+
+- **Couple the reconstruction and orientation convention.** We can choose to be strict with our conventions: make the user specify RCP vs. LCP, the camera orientation, axis convention etc., then use those parameters as inputs to the reconstruction code. This will lead to the same results as above, but requires more diligence from `recOrder` user. In practice, I expect that this approach will result in the same approach as above---fiddle with these (physically motivated) knobs until you match your expectations of a known sample.
+
+#### <img src="https://avatars.githubusercontent.com/u/9554101?u=7ab5421e9a6613c01e9c1d3261fa6f93645d48f9&v=4" width="50">[talonchandler](https://github.com/talonchandler) commented at [2023-02-28 16:53](https://github.com/mehta-lab/waveorder/pull/110#issuecomment-1448519731):
+
+Thanks for the comparison @Soorya19Pradeep. Very helpful. 
+
+> I realized the information here is same, just inverted and offset by 90 degrees.
+
+These are the types of knobs that we might provide in the "decoupling" approach: one checkbox/function for "invert orientation" and one for "rotate by 90 degrees".
+
+#### <img src="https://avatars.githubusercontent.com/u/2934183?u=e638cee77e71afc6e0579e50c2712dfe8a707869&v=4" width="50">[mattersoflight](https://github.com/mattersoflight) commented at [2023-02-28 16:55](https://github.com/mehta-lab/waveorder/pull/110#issuecomment-1448521331):
+
+> Decouple the reconstruction from the orientation convention. We can give ourselves some flexibility in RCP vs. LCP, relative orientations of the camera wrt the polarizers, axis convention etc., then give the recOrder user (and the scripts) enough "knobs" to fix any deviation from convention. For example, we currently have one knob in recOrder that rotates by 90 degrees. To set the knobs, image a known sample (ideally a Kazansky target, but we can point our users to a more available alternative), twiddle the knobs until your colors match your expectations, then keep those knobs as default reconstruction parameters. This is effectively what we're doing now, and I think it's workable.
+
+This is the most general approach for any light path. I think two knobs suffice to register the angular coordinate system in data with the angular coordinate system on stage: one flip and one rotation.
+
+#### <img src="https://avatars.githubusercontent.com/u/2934183?u=e638cee77e71afc6e0579e50c2712dfe8a707869&v=4" width="50">[mattersoflight](https://github.com/mattersoflight) commented at [2023-02-28 18:34](https://github.com/mehta-lab/waveorder/pull/110#issuecomment-1448671628):
+
+> After the extra background correction the range changes and more information is visible, range (0,+3.14).
+
+Thanks, @Soorya19Pradeep for the examples. It is great that you are taking a close look at FOVs.
+
+Seeing the full dynamic range of orientation after correcting background bias is promising! To be sure of the accuracy of the measurement,  I suggest finding some patches where you see strong cortical actin bundles. If the background correction in this (arguably challenging) case is accurate, you'd see that orientation is parallel to the actin bundle. Once you have reconstructed retardance and orientation, you can call [`waveorder.visual.plotVectorField` ](https://github.com/mehta-lab/waveorder/blob/4b3b13364f313f752e23dde8bf9cf2080367acb4/waveorder/visual.py#LL995C18-L995C18) to visualize the orientation.
+
+#### <img src="https://avatars.githubusercontent.com/u/9554101?u=7ab5421e9a6613c01e9c1d3261fa6f93645d48f9&v=4" width="50">[talonchandler](https://github.com/talonchandler) commented at [2023-03-07 02:23](https://github.com/mehta-lab/waveorder/pull/110#issuecomment-1457401823):
+
+I've just completed the renaming/refactoring. @mattersoflight this is ready for your re-review. 
+
+The latest API (at this level) looks like:
+```
+# Calculate I2S
+I2S = stokes.I2S_matrix(swing, scheme="5-State")
+
+# Calculate Stokes vectors
+S_sm = stokes.mmul(I2S, czyx_data)  # Apply I2S to sample data
+S_bg_meas = stokes.mmul(I2S, cyx_bg_data)  # Apply I2S to measured background
+
+# Calculate background correction matrix from S_bg
+M_bg_inv = stokes.mueller_from_stokes(*S_bg_meas)
+
+# Apply measured background correction to sample data
+bg_corr_S_sm = stokes.mmul(M_bg_inv, S_sm)
+
+# Recover ADR parameters
+ret, ori, tra, dop = stokes.estimate_ADR_from_stokes(*bg_corr_S_sm)
+```
+
+I've also spent some time characterizing the old (green profiles) vs. new algorithms (white profiles).
+
+**Soorya's cells - retardance on y axis - measured bkg correction only**
+![Screenshot 2023-03-06 at 5 53 03 PM](https://user-images.githubusercontent.com/9554101/223301263-a580ca6c-e835-4aaf-85cc-e4712134d70f.png)
+At most 2% difference in retardance.
+
+**Kazansky target - retardance on y axis - measured bkg correction only**
+![Screenshot 2023-03-06 at 5 31 36 PM](https://user-images.githubusercontent.com/9554101/223301450-7e6e5638-03f3-4560-9273-76eeb8a59790.png)
+At most 1% difference in retardance.
+
+**Kazansky target - orientation on y axis - measured bkg correction only**
+![Screenshot 2023-03-06 at 5 35 18 PM](https://user-images.githubusercontent.com/9554101/223301559-46b1ebab-9350-4c7e-90a1-3a1ed560b6ed.png)
+At most 2% difference in non-background regions when the different orientation convention is accounted for. This main difference here is from a difference in orientation conventions which we'll be handling with two user-facing switches as discussed above. 
+
+**Timing**
+Current performance bottleneck is the pre-calculation of `mueller_from_stokes` from the background stokes vectors, which can be further optimized (I expect factors of 2-4x). For now, here are a couple benchmarks: 
+
+1 x 2048 x 2048: 
+old algorithm: 1.0 s 
+new algorithm: 15.4 s 
+
+8 x 2048 x 2048: 
+old algorithm: 17.8 s 
+new algorithm: 19.6 s 
+
+**Example comparison script (generates Kaz target comparison above)**
+
+<details>
+  <summary>Full example script (click to expand):</summary>
+
+```
+import numpy as np
+from waveorder import stokes
+from recOrder.io.utils import load_bg
+from recOrder.io.metadata_reader import MetadataReader
+from recOrder.compute.reconstructions import (
+    initialize_reconstructor,
+    reconstruct_qlipp_stokes,
+    reconstruct_qlipp_birefringence,
+)
+from iohub.reader import imread
+from iohub.ngff import open_ome_zarr
+import napari
+
+# Set paths
+base_path = "/hpc/projects/compmicro/rawdata/hummingbird/Talon/2023_02_08_kaz/"
+data_subpath = "kaz-raw_recOrderPluginSnap_0/kaz-raw_RawPolDataSnap.zarr"
+bg_subpath = "BG"
+cal_subpath = "calibration_metadata.txt"
+
+# Read data
+reader = imread(base_path + data_subpath)
+T, C, Z, Y, X = reader.shape
+czyx_data = reader.get_array(position=0)[0, ...]
+
+# Read background data
+cyx_bg_data = load_bg(base_path + bg_subpath, height=Y, width=X)
+
+# Read calibration metadata
+md = MetadataReader(base_path + cal_subpath)
+
+def new_bg_correction(czyx_data, cyx_bg_data, swing, scheme):
+    # Calculate I2S
+    I2S = stokes.I2S_matrix(md.Swing, scheme=md.get_calibration_scheme())
+
+    # Calculate Stokes vectors
+    S_sm = stokes.mmul(I2S, czyx_data)  # Apply I2S to sample data
+    S_bg_meas = stokes.mmul(I2S, cyx_bg_data)  # Apply I2S to measured background
+
+    # Calculate background correction matrix from S_bg
+    M_bg_inv = stokes.mueller_from_stokes(*S_bg_meas)
+
+    # Apply measured background correction to sample data
+    bg_corr_S_sm = stokes.mmul(M_bg_inv, S_sm)
+
+    # Recover ADR parameters
+    ret, ori, tra, dop = stokes.estimate_ADR_from_stokes(*bg_corr_S_sm)
+
+    ret = ret / (2 * np.pi) * 532
+
+    return ret, ori, tra, dop
+
+def old_bg_correction(czyx_data, cyx_bg_data, swing, scheme):
+    reconstructor_args = {
+        "image_dim": (Y, X),
+        "n_slices": 1,  # number of slices in z-stack
+        "wavelength_nm": 532,
+        "swing": swing,
+        "calibration_scheme": scheme,  # "4-State" or "5-State"
+        "bg_correction": "global",
+    }
+    reconstructor = initialize_reconstructor(
+        pipeline="birefringence", **reconstructor_args
+    )
+    # Reconstruct background Stokes
+    bg_stokes = reconstruct_qlipp_stokes(cyx_bg_data, reconstructor)
+
+    # Reconstruct data Stokes w/ background correction
+    stokes = reconstruct_qlipp_stokes(czyx_data, reconstructor, bg_stokes)
+
+    birefringence = reconstruct_qlipp_birefringence(stokes, reconstructor)
+    birefringence[0] = (
+        birefringence[0] / (2 * np.pi) * reconstructor_args["wavelength_nm"]
+    )
+    return birefringence
+
+oldADR = old_bg_correction(czyx_data, cyx_bg_data, md.Swing, md.Calibration_scheme)
+newADR = new_bg_correction(czyx_data, cyx_bg_data, md.Swing, md.Calibration_scheme)
+
+
+v = napari.Viewer()
+v.add_image(oldADR[..., 890:1220, 790:1370], name="old")
+v.add_image(np.stack(newADR)[..., 890:1220, 790:1370], "new")
+import pdb; pdb.set_trace()
+```
+</details>
+
+#### <img src="https://avatars.githubusercontent.com/u/9554101?u=7ab5421e9a6613c01e9c1d3261fa6f93645d48f9&v=4" width="50">[talonchandler](https://github.com/talonchandler) commented at [2023-03-07 21:12](https://github.com/mehta-lab/waveorder/pull/110#issuecomment-1458882074):
+
+I neglected to commit one small change: `stokes.mueller_from_stokes` should be `direction=inverse` by default since this is the most common usage mode (and the usage mode I showed in the snippet from last night).
+
+#### <img src="https://avatars.githubusercontent.com/u/2934183?u=e638cee77e71afc6e0579e50c2712dfe8a707869&v=4" width="50">[mattersoflight](https://github.com/mattersoflight) commented at [2023-03-07 23:07](https://github.com/mehta-lab/waveorder/pull/110#issuecomment-1459006194):
+
+thanks for the offline discussion. Looks great to me!
+
+
+-------------------------------------------------------------------------------
+
+
+
+[Export of Github issue for [mehta-lab/waveorder](https://github.com/mehta-lab/waveorder). Generated on 2023.03.07 at 15:20:38.]

waveorder-2.0.0/examples/README.md

@@ -0,0 +1,7 @@
+`waveorder` is undergoing a significant refactor, and this `examples/` folder serves as a good place to understand the current state of the repository.
+
+The `models/` folder demonstrates the latest functionality of `waveorder`. These scripts will run as is in an environment with `waveorder` and `napari` installed. Each script demonstrates a simulation and reconstruction with a **model**: a specific set of assumptions about the sample and the data being acquired. 
+
+The `maintenance/` folder demonstrates the functionality of `waveorder` that we plan to move to `models/`. These scripts can be run as is, and they are being maintained with tests.
+
+The `documentation/` folder consists of examples that demonstrate reconstruction with real data. These examples require access to the complete datasets, so they are not being actively maintained and serve primarily as documentation.