Debugging Timeout and Performance Issues
SeaSketch's overlay engine can perform calculations on large raster and vector datasets, but how your data is structured, and the options you choose when setting up your reports, can have a big impact on whether calculations can complete. Typically, you should expect calculations performed on sketches to complete in 1 - 5 seconds. Calculations for entire geographies can take longer, but will only be performed once during report authoring and then be cached. The overlay engine usually calculates results quickly or fails entirely.
When a failure occurs, you will be given the option to View Details, which opens the above modal window. The status of every metric related to that visualization widget is displayed, and by hovering over the status indicator you can see a popup with further details on the parameters used and nature of the error. This information can be used to fix some issues yourself, or contact the SeaSketch team for further assistance.
If you regularly see timeouts or other errors while authoring a report, consider the following impacts on performance.
Impact of Geography Configuration
Reports currently work best when your geographies are based on the built-in Exclusive Economic Zones, optionally clipping to land. A great deal of effort has gone into optimizing calculations even with the complex open-streetmap-based shoreline using subdivided sources.
Custom Geographies
If you opt to create a custom geography using an uploaded polygon, the complexity of that shape (number of vertices) will have a large impact on how fast overlap can be calculated. Particularly when calculating geography-wide stats. If using a custom layer for your geographies, consider the following best practices:
Polygon layers should be as simple as possible. If your geography consists of many megabytes of vertices, all that data will complicate and slow overlay analysis.
Rather than basing your geography on a custom polygon that includes complex shoreline contours, build a simpler boundary that overlaps the land. Then, when creating the geography, enable the Remove Land option. This will use our subdivided coastline dataset, which SeaSketch is heavily optimized for.
In the future we hope to provide tools to subdivide and better optimize calculations on complex custom geographies, but for now it is important to understand these tradeoffs.
High Seas Planning
When using the built-in High Seas geography, many calculations must consider the entire global contours of the high seas polygon. Performance is similar to using a very complex custom geography as described above. For now, this limits the size and complexity of data that can be used in overlay analysis. We hope to further optimize performance for this use-case in the near future.
Overlapping Polygon Settings
When performing overlapping area calculations on polygon layers, SeaSketch has essentially two different paths it can take — a fast batching algorithm, and a slow algorithm that performs calculations on individual features. The system looks at data during preprocessing and looks for overlap in a sampling of features. If it finds overlap, it will automatically select the slower algorithm when performing calculations. You can manually choose which algorithm to use by adjusting the source options of report widgets like the Overlapping Area Table as shown in the screenshot below. Source options are typically found within the rows submenu.
If you have a dataset where polygons do not ever overlap, you should always use the faster option (Assume no overlap). For very large datasets, it's very common that the slower algorithm cannot even be completed without timing out. If there is overlap and you choose this faster option, it can introduce inaccuracies. The system will union overlapping polygons, eliminating overlap in the area calculation. It can still be acceptable to choose the faster algorithm with overlapping features in these circumstances:
If overlap is negligible. This can occur in vectorized raster sources, but also in other instances, where there is minor overlap in the edges of some polygons.
If overlap only occurs among features belonging to different class keys, and you are using the Group by option with that class key, then the faster batching algorithm will not batch those features and it is completely safe to use it.
Examples of Overlapping Polygon Situations
Here, we have a layer of Ecologically and Biologically Significant Areas. There are two areas here that significantly overlap. If we wanted to report on the percent of EBSAs included in the EEZ that our sketches overlapped, we would want to use the "Polygons are known to overlap" setting. If not, areas covered by both EBSAs could be unioned before overlay analysis, resulting in 50% less area measured. Since this is a simple dataset with few, relatively simple features, it's unlikely that we would have a problem calculating metrics with the slower algorithm anyways.
In the example above, we have a habitat classification layer that has numerous overlapping features. This is a large (58MB) layer covering the entire Brasilian EEZ, so calculating metrics for the entire geography using the slower algorithm was failing. Luckily we were able to safely enable the faster algorithm which ignores overlap, since in our reports we are grouping results by a class key. It appears that when this layer was made, there were possibly multiple datasets with different classification schemes merged, and so there is overlap between them. Importantly though, there is no overlap between features within a habitat class. SeaSketch cannot detect this reliably, but it is easy to identify by looking at the map. Had there been overlap between features within the same classification it would not be possible to use the optimized algorithm without first cleaning up the dataset in desktop GIS.
Raster VRM Settings
This settings controls the amount of virtual resampling applied to raster pixels before calculating metrics on a sketch (or geography). To understand why resampling may be necessary, consider the example below.
In this situation we have an area of interest (AOI) drawn over a raster layer, with pixel values that range from 0 - 1. The majority of the AOI covers very low or zero values, and a small proportion (<10%) covers a pixel valued at 1. Typical desktop GIS tools would calculate zonal statistics using one of two different methods.
All-touched, which in this case would count all 4 pixels the polygon overlaps. 3 very low value pixels and 1 very high value.
Cell-center methods would only count pixels where the AOI overlaps the pixel's centerpoint. In this case, only the single, low-value pixel in the center would count.
Neither of these methods are ideal. Cell-center doesn't represent the high-valued yellow pixel at all in zonal statistics, and all-touched weighs it equally to all the other pixels, skewing statistics.
Ideally we'd count fractional pixel values in statistics, and virtual resampling is how that is done. Depending on the VRM setting, each pixel is divided into up into 4, 8, 16 or up to 100 parts. Only then is intersection calculated against for the area of interest. SeaSketch relies on an open-source library, geoblaze, to perform these virtual resampling and zonal statistics calculations.
SeaSketch automatically assigns VRM settings when you embed a raster reporting widget, and for the most part these settings work well. If you see errors relating to "Invalid array length", or results that don't line up with your expectations, you may need to manually choose your settings.
auto - SeaSketch chooses an appropriate VRM setting based on the size of the sketch being analyzed and the pixel size of the raster. This is the default.
disabled - geoblaze intersection algorithm is applied on unaltered, full-size pixels.
2 - divides each pixel, creating a 2 × 2 grid, or 4 virtual pixels per original pixel.
4 - creates a 4 × 4 grid, or 16 virtual pixels per original pixel.
12
32
64
100 - creates a 100 × 100 grid, or 10,000 virtual pixels per original pixel.
Performance considerations when using virtual resampling
Higher VRM values can produce more accurate statistics, but higher values can quickly exhaust limited memory. Consider a 16-bit raster. If a bounding box around an analyzed feature contains 100x100 pixels, and a setting of 100 VRM is applied, that's 1 trillion pixels which would require 2 TB of memory. This is how "Invalid array length" errors occur. If this happens, reduce or disable virtual resampling using the menu shown below. If the auto setting is resulting in these errors, please create a ticket in github or contact support so we can improve the system.
It is important to note that you can set VRM parameters for analysis of sketches and geography-wide statistics seperately. Usually, geographies are so large compared to pixels that VRM can be disabled or set to a very low value and still calculate very accurate statistics.
Last updated