Return peak stats in focus_from_transverse_band

[ieivanov]

On the mantis microscope, I find it useful to return some statistics about the detected peak, even if it doesn't pass the FWHM threshold. This allows me then to extend the search range during O3 autofocus.

This is a breaking change since we are returning multiple arguments. Other software would need to be updated as:

focus_index = focus_from_transverse_band[0]

An alternative implementation would be to have a optional function argument return_peak_stats=False and a statement like

if return_peak_stats:
    return in_focus_index, peak_stats
else:
    return in_focus_index

but I think that's not ideal from a programming standpoint. Leaving this in a branch is not a blocker for me, but it would be nice to see it merged with the next major release of waveorder.

[talonchandler]

I 100% agree that we need these features, but I'm hesitant to make breaking changes here. I also think the focus_from_transverse_band[0] syntax is a bit confusing.

I think there's an opportunity for a smoother refactor. What do you think about the following:

• Leave focus_from_transverse_band(zyx_array) -> in_focus_index as is.
• Factor out a new transverse_band_power(zyx_array) -> z_array_of_transverse_power function from focus_from_transverse_band. This is inspired in part by your suggestion, @edyoshikun's needs, and my needs---I think all three of us have needed something like this.
• Add a new focus_statistics(z_array_of_transverse_power) -> Dict function that returns as many statistics as you need.

[ieivanov]

I also think the focus_from_transverse_band[0] syntax is a bit confusing.

The alternative would be to use focus_index, _ = focus_from_transverse_band(zyx_array), which I agree looks a little cleaner.

Happy if we can refactor this further. If we make a new focus_statistics(z_array_of_transverse_power) function how would we get the focus index - would that be one of the keys in the dict it returns?