Update the exposure func to handle filtering modelled datetimes and combining filters to customise exposure analysis

[erialC-P]

This PR:

• adds extensive functionality to the exposure script.
• The Intertidal_workflow.ipynb is included and demo's calculation of the full timeseries for exposure, as previously.

This PR does not:

• update calls to the exposure function from other notebooks, namely the CLI_notebook.

Notes on the structure of the new exposure function:

• Filter inputs include:
  • temporal filters such as day, night, month, season
  • spatial filters including hightides, lowtides, neap and spring high/low tides
  • combinations of temporal and spatial filters such as wet season lowtides.
• Known issues include consistency in the capitalisation of filter names and the length of the script.

Future work will address the known issues and add a notebook dedicated to showcasing exposure custom options

[robbibt]

Hey Claire, sorry for the super long delay in reviewing this! This new functionality is awesome - the range of different filtering methods is fantastic, and will let our users really narrow in on and answer some very interesting ecological questions relating to specific life history traits/environmental processes.

I think there's a few things we need to change before merging it into main to improve performance and make the code easier to maintain in the future. There's three key changes I'd recommend:

Reduce duplication by packing up analysis into discrete functions that re-use code wherever possible

The exposure function has grown pretty long, and includes quite a few sections of code that are repeated with only small differences each time (e.g. significant overlaps between the neap low/neap high, the spring low/spring high, and the low tide/high tide calculations). My feeling is that we should aim to keep exposure as minimal as possible by packing all those discrete pieces up as re-usable functions instead. That way we can reduce duplication/reuse logic, make it much more difficult for errors and inconsistencies to creep in, and make it easier to read and maintain. These look like priorities for more discrete functions:

• A combined temporal_filter function handling all the basic temporal filtering options, which itself calls another lower-level "daynight_filter" function that performs the day/night filtering
• A combined spring_tides function that supports both "low" and "high" functionality
• A combined neap_tides function that supports both "low" and "high" functionality
• A combined lowhigh_tides function that supports both "low" and "high" tide functionality

Make sure expensive analyses like tide modelling are only performed once in the workflow

Some functionality like the tide modelling is really expensive, but is now run multiple times throughout the workflow (I suspect this might be the cause of some of the Sandbox issues you've been running into). We'll need to ensure that the tide modelling code is only run once in the entire Exposure workflow, likely by moving it up higher and re-using it in other functions below.

Consider shifting spatial filters to run on the low-res tide modelling data instead of the high-res data

I suspect the spatial filter functions are currently slow mainly as they seem to be applied to every high-res pixel. This will scale exponentially as our study area increases, and likely won't be practical for anything larger than a small section of a beach. A more efficient approach would be to run these on the low-res output of the tide modelling functions instead. Combining this with the suggestion above, we could do something like:

1. Calling the tide modelling functions with resample=False and calculate_quantiles=None once at the very top of the workflow, returning a low-res model output
2. Apply spatial filters to the low-res tide modelling output
3. Calculate exposure quantiles and resample back to high-resolution, borrowing code from inside pixel_tides​ here

(That said: one thing to consider could be whether these filters actually need to be run at a pixel level at all. If we switched to simply running them on a 1D timeseries instead (e.g. using average tide height per timestep), we could probably greatly simplify a bunch of code: e.g. all the temporal + spatial filters could simply return equivalent lists of filtered timesteps, rather than the mix of different outputs we currently have.)

---

Given our updated Notebooks plan, some of this work can probably be pushed back until after the April release. A short-term starting point could be to raise a second smaller PR to implement the breaking API changes in exposure (e.g. time_range > start_date/ end_date/freq etc) in the existing version of the function, so that we can start using that syntax now before the larger changes above?

[robbibt]

The block of coordinate conversion code above can probably be simplified by getting the coord directly from the dataset's GeoBox and converting it to EPSG:4326 there:

tidepost_lon_4326, tidepost_lat_4326 = dem.odc.geobox.extent.centroid.to_crs("EPSG:4326").coords[0]

[robbibt]

I don't think we need to do local timezone conversion here - sunset and sunrise should be able to be calculated directly in UTC. I think if we pass in local_tz = 0 to sunriset, we should be able to do the enture calculation in UTC and avoid having to load and manipulate custom timezone polygons.

[robbibt]

Same comment as above - avoid local timezones/timezone conversion and just do everything in UTC / local_tz=0.