Apply Mask Changes: Multichannel, Allow Depth, Simplify Fill Value

[ctuguinay]

This PR is meant to address #1204 and #1224.

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 92.97%. Comparing base (7679b96) to head (0b67ea6). Report is 55 commits behind head on main.

Additional details and impacted files

```diff @@ Coverage Diff @@ ## main #1230 +/- ## ========================================== + Coverage 83.29% 92.97% +9.67% ========================================== Files 64 3 -61 Lines 5675 185 -5490 ========================================== - Hits 4727 172 -4555 + Misses 948 13 -935 ``` | [Flag](https://app.codecov.io/gh/OSOceanAcoustics/echopype/pull/1230/flags?src=pr&el=flags&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=OSOceanAcoustics) | Coverage Δ | | |---|---|---| | [unittests](https://app.codecov.io/gh/OSOceanAcoustics/echopype/pull/1230/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=OSOceanAcoustics) | `92.97% <100.00%> (+9.67%)` | :arrow_up: | Flags with carried forward coverage won't be shown. [Click here](https://docs.codecov.io/docs/carryforward-flags?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=OSOceanAcoustics#carryforward-flags-in-the-pull-request-comment) to find out more.

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[ctuguinay]

Original Checklist

Remove np.ndarray from allowed type for fill_value

• [x] Check for the channel dimension for all elements in mask to ensure that they have the same shape in ping_time and range_sample (and depth, see https://github.com/OSOceanAcoustics/echopype/issues/1204) -- this check should already be in place, but the code could use some checking and potentially simplifcation
• [x] If fill_value is of type xr.DataArray, it must have the same dimension as source_ds
• [x] Make sure to broadcast all input masks together before combining them (element-wise multiplication)
• [x] Add an input argument keep_unmasked_channel: bool = True
  • when True: channels that are not in mask will be left as is, i.e. no masking will be applied to the data in chC
  • when False: channels that are not in mask will be masked, i.e. all data in chC will be masked with values in fill_value.

Further Changes

• Modified logic to no longer default to the final mask being 1 channel for all cases. Instead, it checks to see if the channel dimension exists in both final mask and the source da. If it exists in both, then final mask is applied appropriately per channel (behavior of this apply depends on value of keep_unmasked_channel)
• Modified integration tests to include more permutations of mask channel inputs

[ctuguinay]

Thanks for the review @leewujung!

Yeah, I agree with you on there being too many cases that this code tries to accommodate. I also agree with you on all suggestions you posed.

Just to get the cases in order, once we get to the post-broadcast post-logical-reduce stage (once we get to here https://github.com/ctuguinay/echopype/blob/e52e05f33a82d1700d24f5c58d072fe15d319136/echopype/mask/api.py#L335), I should pass only the following:

• No channel in both source and mask, but they have matching ping time and depth
• Source and mask both have matching channel, ping time, and depth
• Source has channel and mask doesn't, but they have matching ping time and depth

[ctuguinay]

@leewujung This PR should be ready to review again

[ctuguinay]

@leewujung I just committed your suggestions, and this should be ready to merge. Thank you for making the docstring more precise! I think I wrote that right after I got tests working so I was at the point of complete familiarity, and I didn't stop to think whether or not someone new could understand it. I will work on that 👍

[leewujung]

Thanks @ctuguinay , I'll merge this now! 🎉

[leewujung]

Oops, I just realized that you target main and not dev, and I used squash and merge. I may have to do hard reset and ask you to another PR...

[leewujung]

Looks like there's no compounding changes from other PRs that have been merged to dev, so this should be ok. We want to simplify our dev workflow anyway #1275 so this forces us to do it, ha.