Dedicated Basin of Attraction types

#### Creation of dedicated basins types: `BasinsOfAttraction` and the sub-types `ArrayBasinsOfAttraction`, `SampledBasinsOfAttraction` as detailed in #187. - `BasinsOfAttraction{ID}` an abstract type with parameter `ID` which is the type of the attractor label or more generally the type of "each element" of the basin, typically an `Int`. Extending this interface involves creating a sub-type and implementing 3 functions `extract_basins`, `extract_attractors`, and `extract_domain` which access the 3 key fields. - `ArrayBasinsOfAttraction{ID}` sub-type of `BasinsOfAttraction{ID}` containing: - - `basins`: An array with element type `ID`, the result of `extract_basins` - - `attractors`: A dictionary mapping attractor labels to state space sets, the result of `extract_attractors` - - `grid`: An instance of a sub-type of `Grid` for which the basin was calculated for, the result of `extract_domain` - SampledBasinsOfAttraction{ID} sub-type of `BasinsOfAttraction{ID}` containing: - - `points_ids`: A vector with element type `ID`, the result of `extract_basins` - - `attractors`: A dictionary mapping attractor labels to state space sets, the result of `extract_attractors` - - `sampled_points`: A state space set of length equal to that of `points_ids` for which the vector basin / labels was calculated for, the result of `extract_domain` Doc strings have been added for these. #### An aside on the load order The `ArrayBasinsOfAttraction` type requires `Grid` to be defined which is included in `mapping/recurrences` this is initially fine as the load order is mapping -> basins, however several functions and types in the mapping folder e.g. BasinsInfo, and basins_of_attraction will require ArrayBasinsOfAttraction once they have been modified. I think the cleanest solution to this with minimal changes to the load order or general file structure is to have the new basin types in a new file, `basins_types.jl` potentially in `/basins` or perhaps `/mapping`, with all the constructors which might rely on several parts of `/mapping` to be located in `basins_utilities.jl` so that it is loaded after mapping. Then if we move the definition of abstract type `Grid` from `attractor_mapping_recurrences.jl` we can then include `basins_types.jl` before the recurrences stuff is loaded without conflict. This is definitely not the only way, if anyone had a better idea I'd like to hear it! #### Constructors Most of the constructors for the new types are found in `basins_utilities.jl`, in particular all the new ones are. The ones that are the result of a modification to existing functions are: - `basins_of_attraction(mapper::AttractorsViaRecurrences; show_progress = true)` in `attractor_mapping_recurrences.jl` returns an instance of `ArrayBasinsOfAttraction` - `basins_of_attraction(mapper::AttractorMapper, grid::Tuple; kwargs...)` in `basins_utilities.jl` returns an instance of `ArrayBasinsOfAttraction` Defining these `extract_...` functions allows us to make `BasinsOfAttraction`, in general, iterable which is essential for ensuring the backwards compatibility for functions that used to return `basins, attractors` like in the above `basins_of_attraction` functions. Note that the function `convergence_and_basins_of_attraction` in `basins_utilities.jl` is not able to be converted in the same iterable manner as it returns 3 items: basins, attractors, iterations. So wrapping the first two in one of the new types would form a 2-tuple of the form ((basins, attractors), iterations). I have noted this in the doc string. Doc strings have been added / modified accordingly. #### Wrapper functions Wrapper functions have been created allowing for compatibility with these new types on all basins-related functions, whilst preserving backwards-compatibility, here is a list: - In `ext/plotting.jl`: `heatmap_basins_attractors`, `shaded_basins_heatmap`, and their in-place versions - In `basin/`: `basins_fractions`,`basin_entropy`, `basin_fractal_test`, `basin_fractal_dimension`, `uncertainty_exponent`, `test_wad_merge` - In `matching/basin_overlap.jl`: `matching_map` and the in-place version - In `tipping/tipping_probabilities.jl`: `tipping_probabilities` All the documentation strings have been modified to include these wrapper functions. #### Recurrences The `BasinsInfo` structure has been modified to contain an instance of the `ArrayBasinsOfAttraction` instead of carrying `basins`, `attractors`, `grid_nfo` separately. Accordingly all references to those fields in `attractor_mapping_recurrences.jl` and `finite_state_machine.jl` have been updated, in addition to a minor reference in `docs/src/recurrences_animation.md`. #### Interpolating basin functions Also detailed in a comment in #187, the function `map_to_basin` has been defined in `basins_utilities.jl` for the 2 basin of attraction sub-types. #### Still To-Do Add tests