Exposure filtering script

[erialC-P]

This PR includes significant changes to the exposure calculation and custom filtering workflow, based on really helpful review and feedback from the first version.

Major changes to the workflow include the following:

• Restructuring of the exposure.py script, including breaking out sections of the original function into smaller functions and reducing repetition in calculations
• Removed pixel based calculations for all 'spatial and temporal filter' calculations of exposure (calculating exposure using the default (filters=None) settings continues to perform a pixel based calculation for the entirety of the input epoch). This workflow takes the input area of interest and calculates a single high temporal/low spatial resolution tidal model for the central coordinates and calculates exposure % against this. This approach to the exposure calculation is designed specifically for sandbox calculations where big area's of interest are not supported. Consequently, the speed of the exposure calculation in the DEA Sandbox is significantly reduced compared to previous iterations of the workflow.
• Removed timezone conversion to local dates/times in the day/night calculations of exposure, transitioning to UTC time. Testing against local sunrise and sunset times confirmed that UTC was replicating the local dates/times.
• Confirmation that peak detection routines used to identify hightide and lowtide datetimes performed as expected across diurnal, semi-diurnal and mixed tidal regimes
• Finally, a major restructure of the calculation. Unless 'unfiltered' is called (whereby a pixel-based tide model is produced), a single high temporal low spatial resolution tide model is generated, irrespective of how many filters are called. All filter datetimes and tide heights are extracted from the tide model. From these, a tideheight quantile curve is generated and compared against dem elevation per pixel whereby the quantile % is equivalent to the exposure time %.

Incorporation of recommendations from the initial review of this workflow have helped to:

• simplify the structure of the workflow
• streamline the calculations
• significantly speed up the computation

[github-actions]

For full integration test results, refer to the Tests directory README.

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 25.68306% with 136 lines in your changes are missing coverage. Please review.

Project coverage is 57.0%. Comparing base (00fdde3) to head (1177357).

❗ Current head 1177357 differs from pull request most recent head 3a476d4

Please upload reports for the commit 3a476d4 to get more accurate results.

Files	Patch %	Lines
intertidal/exposure.py	24.4%	136 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##            main     #85     +/-   ##
=======================================
- Coverage   65.5%   57.0%   -8.6%     
=======================================
  Files          8       8             
  Lines        714     887    +173     
=======================================
+ Hits         468     506     +38     
- Misses       246     381    +135     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[robbibt]

Hey @erialC-P, thanks so much for all the changes you've made - this version is super super nice. I've pushed a few additional changes myself, mainly:

1. Black formatting and added docstrings
2. Updated all filter options to lowercase_snakes
3. Refactored the tide modelling code so tide modelling only ever happens once
4. Updated spatial_filters and temporal_filters to no longer pass externally created objects in and out of the function - now only the outputs are passed out and then assigned into the external objects outside of the functions
5. Some small changes to variable names and docstrings (e.g. xarray.Datasets were being referred to as dicts in some parts of the code, which I think was probably a legacy of older versions

I think it's pretty much ready to go now as-is, but here's a few other things that I think would be worth focusing a bit of time on if you have capacity:

1. As discussed on Teams, it would be really nice if both temporal_filters and spatial_filters returned exactly the same output: just a filtered list of timesteps. These outputs could then be handled nicely in one single place outside of those functions using the same consistent code, avoiding duplication and ensuring that exactly the same process/logic is applied to every filter, regardless of its type. I think this could lead to cleaner code and a more consistent user experience overall.
2. If you wanted to, you could probably think about pulling out some parts of spatial_filters into even smaller sub-functions (e.g. things like the neap/low/high bits where similar code is repeated a few times), and call those subfuncs inside relevant parts of spatial_filters (would make it super easy to update those methods in the future as you could just tweak the mini sub-function
3. I think there's quite a few places where docstrings haven't been updated for updated code. Would be worth going through the script carefully before we merge just to make sure all the doco is up-to-date.
4. I don't personally like the name "spatial" in spatial_filters. I think it's potentially going to add confusion as it has such geographic connotations... would just something like "tidal_filters" be beter? Or "tidalstage_filters"?
5. Also as discussed, it could be neat if we could do away with combined_filters and instead just use filters, perhaps letting users pass in tuples of filters inside the list. But this is very much a "nice to have" and not a major priority. 🙂