XY and Z drift stabilization; replaces #108

[ieivanov]

TODO (01/19/24):

• [x] Merge main after registration_v2
• [x] Move functions between /mantis/cli/stabilization and /mantis/analysis/stabilize
• [x] fix tests @edyoshikun
• [x] Test the stabilization calculations @ieivanov , use verbose mode
• [x] Update slurmkit call for CLI @edyoshikun
• [x] estimate_xy_stabilization should use the z indices calculated by estimate_z_stabilization @ieivanov
• [x] estimate_stabilization should use channel_name rather than channel_index, like estimate_affine. Is there ever a case where we'd want to use different channels for focus finding and xy stabilization? In not, the config can have just "channel_name" rather than focus_finding_channel_index @ieivanov
• [x] Can we try to reduce the number of CLI input parameters of estimate_stabilization? Should we collect them using input or is it useful for this function to be non-interactive? - These should be CLI options
• [x] Can we reuse process_single_position and apply_function_to_zyx_and_save in apply_stabilization?
• [x] remove analysis/stabilize.py if not used
• [x] Optional: can we estimate the XY stabilization in parallel across timepoints? See discussion here: https://github.com/glichtner/pystackreg/issues/14. Can we supply the algorithm with pairs of (t_{n}, t_{n+1}) images? Does this computation take a lot of time and is it worth parallelizing? - limiting step is z stabilization, no need to parallelize for now
• [ ] Add optional argument to estimate_stabilization to specify which position name is used for xy stabilization @ieivanov

This PR has the code for:

• [x] Calculating the z-drift and returning a z-translation matrix for timelapses estimate_stabilization_affine()
• [x] Calculating the xy-translation and returning a xy-translation matrices for timelapses stabilize_timalpse()
• [x] CLI call for running the stabilization
• [x] Save the translation matrices for XY and Z drift as yml
• [x] add tests

For the XY stabilization, you can use: /hpc/projects/comp.micro/mantis/2023_09_22_A549_0.52NA_illum/3-registration/A549_MitoViewGreen_LysoTracker_W3_FOV5_1_phase.zarr

For Z drift, any of the timelapses: /hpc/projects/comp.micro/mantis/2023_11_01_OpenCell_infection/4-registration/timelapse_7/timelapse_7_phase_registered.zarr

[ieivanov]

@edyoshikun I see that we need to move some functions between /mantis/cli/stabilization and /mantis/analysis/stabilize. Here is the logic I've been using to decide if functions should go in the analysis or cli modules. Functions in analysis operate on numpy arrays. Functions in cli provide wrappers that would read in data (using iohub), apply analysis functions, and save the results. This may not be so clean-cut every time, but we should aim to format the code in a way that would also allow us to analyze data from a python script rather than thru CLI calls.

[edyoshikun]

@ieivanov yes! I actually had changed those in the other branch. I agree with the refactoring to keep separate the functions between the cli and the analysis. We can just wrap the parts of the cli that should be a different stabilize_timelapse() and have the cli call this one.

[ieivanov]

Quick note: calculate_yx_stabilization should use the z indices calculated by calculate_z_drift. If they are not present, then use the focus index of the first time point as we do currently

[edyoshikun]

@ieivanov I added some functions needed to apply stabilization to the config file. Similar to apply_affine the apply_stabilization takes in a config file where we can choose the timepoints and the channels to process. This will allow us to process certain channels within a dataset without modifying the rest. Additionally, I could merge the apply_stabilization_over_time into process_single_position_v2 by appending t_idx to the kwargs if the function needs it. For example, look at apply_stabilization_transform(). This is good because now we could implement any function that applies different conditions per timepoint.

Also, I fixed the channel_name_index to channel_name to match the apply_affine.

[ieivanov]

I am happy with this PR. The Z stabilization is well-tested. The XY stabilization is not used as much and not tested quite as well.