Generalized deskewing for mantis

[talonchandler]

@ieivanov and I discussed deskewing workflows yesterday, and I've now added a complete deskewing workflow to this PR.

1. python estimate_deskew.py <path/to/mm-folder> will open the raw data in a napari window and prompt you to make two annotations:

• a rectangle on a region that you expect to be square in the deskewed space, and
• a line that you expect to be normal to the coverslip in the deskewed space

From these two annotations, this workflow will compute the two parameters that the deskewing routine needs (px_to_scan_ratio and theta_deg) and saves them in a deskew_params.yaml file (optional -o parameter to rename the output .yml file).

2. python deskew.py </path/to/mmfolder/> </path/to/deskew_params.yml> -o </path/to/output.zarr> will load the data, apply the deskewing, save the result with metadata (including the deskewing parameters and new voxel sizes) using iohub, and optionally view the deskewed result with the -v flag.

---

I'm much happier with the interactive workflow (no iteration to find good deskewing parameters), and the results on the 03_30 data look much better than the data I showed on Monday (improvements in the data and deskewing).

The figure below shows single slices in each direction---the fact that the rings of the sphere appear in a single slice in all three directions and that the target appears circular is encouraging.

More deskewed data lives in /projects/mantis/2023_03_30_argolight/deskewed.

---

One puzzle remains: I'm consistently finding the best tilt angles to be between ~34-36 degrees. This is very likely because of an incorrect parametrization (trig error?, index of refraction error?). I've managed to keep my transformations consistent when I estimate from the raw data, so this puzzle does not affect the self-consistent interactive workflow here. I will keep an eye out.

[mattersoflight]

Thanks for a clean and readable implementation! My main input is around interpolation and fill value. LGTM once those are addressed.

[ieivanov]

One puzzle remains: I'm consistently finding the best tilt angles to be between ~34-36 degrees. This is very likely because of an incorrect parametrization (trig error?, index of refraction error?).

We set the tilt angle roughly and by hand with the help of a protractor printout. It's quite possible that the real tilt angle is around 34-36 deg as you estimate. We should trust the data on this

[ieivanov]

The Argolight target from 2023_03_30 looks good! I'll look closer and I'll let you know if I see anything else. One minor issue - currently the z axis in the deskewed volumes is flipped, it goes from deep in the sample at low z index and towards the coverslip at increasing z index

[talonchandler]

currently the z axis in the deskewed volumes is flipped, it goes from deep in the sample at low z index and towards the coverslip at increasing z index

Good call, fixed. Compare the new /2023_03_30_argolight/deskewed_flipped/sphere_1.zarr to the old sphere_1 to see the proposed new convention with z=0 at the coverslip.

[mattersoflight]

@ieivanov , @talonchandler great idea to use an interactive workflow to estimate the skew angle from data. This strategy can be extended to the registration of channels.

[mattersoflight]

Great idea to use yml file to track the parameters. I suggest renaming this to analysis_params.yml and creating two sections deskew and register.

[talonchandler]

I think that a single-step analyze pipeline is extremely useful, and I would suggest that we develop it in addition to, not instead of, the individual substeps (e.g. deskew, register, deconvolve).

I have two motivations:

• debugging and developing individual steps is easier, and it's nice to be able to optimize the steps individually. (e.g. some steps might require an interactive estimate, others might require an optimization)
• if modularity of the processing pipeline isn't a priority, then the number of options can get large and tangled very quickly (I think recOrder's earlier offline mode is a great example)

As the substeps reach maturity, we can start consolidating into a single mantis analyze <lf-path> <fl-path> -c analysis_params.yml pipeline like you're suggesting. On the technical side, pydantic can enable this as well...we can specify a higher-level data class that consists of the substeps' dataclasses, and this will create the multiple sections for deskew, register, deconvolve, etc. in our final parameter files.

I'm open to comments/experience here, since I know that keeping track of proliferating configuration files can be a major problem.

[mattersoflight]

This module can be renamed analysis_settings.py and have data classes for all analysis steps.

[talonchandler]

My comment above is related to this suggestion.

I agree that this file can be renamed more generally, and I'm anticipating a DeskewSettings(BaseModel) class for now with RegisterSettings(BaseModel) and others to follow. Later we can have an AnalyzeSettings(BaseModel) class that has [DeskewSettings, RegisterSettings, ...] as its members.

[mattersoflight]

The interactive workflow and use of orthogonal rings make a lot of sense. A similar workflow can be implemented for registering the channels too after this PR is merged.

[mattersoflight]

@talonchandler Looking at the data from the sphere target and the ring target, I think that deskewing is working well. We can merge and start to use it.

It will make sense to contribute this to dexp and depend on it.
After merging this PR, can you and @JoOkuma figure out how to go about that?

[JoOkuma]

@mattersoflight Thanks for tagging me. dexp is going through a rework, I'll use this implementation as a reference and make sure the new dexp deskewing works on daxi and mantis.

However, It won't be implemented in the coming days.

[talonchandler]

@mattersoflight thanks for reviewing and testing.

@JoOkuma thanks! We're in no major rush to move/contribute this to dexp, but we'd like to keep our groups' deskewing code consolidated and clean. Please let me know when dexp2 is ready, and we can work together to merge it.

@ieivanov feel free to merge this whenever you're ready, or let me know if you have other changes you'd like to make.

[ieivanov]

Thanks @talonchandler, I'll take it from here. I'm using this PR to deskew the cell data from last week, and can make changes as necessary.

When you were working on this, you likely made drawings/sketches of how the data should be transformed. It will be helpful to include those in a docs page with matching nomenclature to the variables in mantis_deskew

[mattersoflight]

@ieivanov please also address #9 while you are updating the deskewing code.

[talonchandler]

I just added a commit that changes the default to "crop the corner". I renamed the suggested name --crop-corner to --keep-overhang, so that it could be a command-line flag (false by default).

The following figure demonstrates the new option and shows a situation where you might benefit from using this option.

[ieivanov]

Thanks Talon! I had to restructure the code a bit to make it run for multiple positions (create_zeros was called inside the channels loop). I'll merge these changes today, and I'll merge this branch into main.

[ieivanov]

Figured I'll finish what I started on the multiprocessing side, but I ran into bigger problems, see micro-manager/NDTiffStorage/#108

[ieivanov]

@talonchandler @edyoshikun par_deskew.py shows my indented way to deskew data along the TPC dimensions in parallel, but it currently doesn't work because of a bug in ndtiff. This should work on MM ome.tiff dataset, it's worth a try

[ieivanov]

We agreed that we will merge this PR with its single-process implementation and we'll work on multiprocessing in #33. @talonchandler it would be great if you could take another look at this before we merge.

[talonchandler]

I just reread and tested the code, and everything looks good.

I found one bug where a numpy float was being passed to the .yaml dump, which resulted in a non-readable config file. Reinstating the float() in the validator fixed the issue.

Merging.