> For the complete documentation index, see [llms.txt](https://docs.seasketch.org/seasketch-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.seasketch.org/seasketch-documentation/administrators-guide/reports.md).

# Reports

Analytical reports in SeaSketch enable you to evaluate user-drawn sketches and collections in your projects. These reports are easy to author, and our overlay analysis engine is fast and accurate so that stakeholders recieve near instant feedback on their sketches.

## Prerequisite Inputs

Before authoring your first report, you will need to setup your project with appropriate geographies, overlay layers, and sketch classes for evaluation. Please reference the following documentation for each of these topics and configure your proejct before authoring reports.

<table data-view="cards"><thead><tr><th></th><th></th><th data-type="content-ref"></th><th data-hidden data-card-cover data-type="image">Cover image</th></tr></thead><tbody><tr><td><strong>Geographies</strong></td><td>Define the areas where users draw spatial plans, and can also subdivide those areas for reporting summary statistics. Think EEZ + offshore and nearshore planning areas.</td><td><a href="https://docs.seasketch.org/seasketch-documentation/administrators-guide/geographies.md">Geographies</a></td><td><a href="https://3101925571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmrOjheW9v23epAZJDsmJ%2Fuploads%2FQR3BP2HWCJv55OWmaL2U%2FIsometric%20Ocean%20Zones%20Infographic.png?alt=media&amp;token=6abbac88-8014-4634-8e2d-489176f64f86">Isometric Ocean Zones Infographic.png</a></td></tr><tr><td><strong>Overlay Layers</strong></td><td>You'll reference the exact same vector and raster layers uploaded for map visualization in your reports. SeaSketch will do the necessary data prep.</td><td><a href="https://docs.seasketch.org/seasketch-documentation/administrators-guide/overlay-layers/uploading-spatial-data.md">Uploading Spatial Data</a></td><td><a href="https://3101925571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmrOjheW9v23epAZJDsmJ%2Fuploads%2FYI0Jo05XqgAiZvAx4WMo%2FLayered%20Raster%20Data%20Tiles%20Infographic.png?alt=media&amp;token=829db068-d751-44ab-a5ef-3d43074d9622">Layered Raster Data Tiles Infographic.png</a></td></tr><tr><td><strong>Sketch Classes</strong></td><td>Feature classes that are a combination of geometry type and an attribute form. They ensure stakeholder plans follow the constraints of a planning process and enter necessary information.</td><td><a href="https://docs.seasketch.org/seasketch-documentation/administrators-guide/sketch-classes.md">Sketch Classes</a></td><td><a href="https://3101925571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmrOjheW9v23epAZJDsmJ%2Fuploads%2FrGOTYOFA2LRVyQufoeoG%2Fseasketch_sketch_class_transparent.png?alt=media&amp;token=d35efe7e-3d62-4071-bc37-d04d14e798d5">seasketch_sketch_class_transparent.png</a></td></tr></tbody></table>

{% hint style="info" %}
When adding Overlay Layers to your project that will be used in reports, consider the following.

* SeaSketch can perform overlay analysis on both vector and raster layers. Try to avoid vectorized raster data (or rasterized vectors) as it can lead to performance and accuracy problems.
* Raster data should be uploaded in a a suitable equal-area projection for best accuracy.
* Vector data analyzed in unprojected space — uploaded CRS makes no difference.
  {% endhint %}

#### Example Sketches

When using the report authoring interface, you will need to have digitized and saved some sketches to your account in the same project. We recommend creating several sketches (and collections, if using) that represent reasonable examples of what might be drawn by users of your project. For example, if you are planning both nearshore and offshore Marine Protected Areas, draw examples of both coastal and offshore MPAs in different parts of the planning region. The report authoring environment has tools to quickly swap between these examples in order to evaluate different outputs.

## Authoring a Report

### The Authoring Environment

To start, choose **Reports** from the sidebar of the administrative interface.

<figure><img src="https://3101925571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmrOjheW9v23epAZJDsmJ%2Fuploads%2FyWsdxB73mMflyhkwymgy%2FSeaSketch%20Reports%20Dashboard%20Callouts.png?alt=media&amp;token=c20b0e71-4f11-400a-bbdc-92863871cac7" alt=""><figcaption></figcaption></figure>

* **Report listing and selection** is where you can create new reports, and select which to edit. Projects start with *Default report*, which is tied to new Sketch Classes.
* The **Toolbar** includes actions such as *Add Card*, *Manage Tabs*, *Print* and *Export* options, and is where you will see an indication of draft changes ready to *Publish*.
* **Example dropdown** enabled you to select which of the sketches in your account is used as a subject for report authoring. You can change this at any time to compare calculated values for different areas or Sketch Classes.
* The **Report actions** menu is a stand-in for the actions menu available in the public-facing view of reports. It contains some of the same actions as the Edit and Export toolbar menus.
* The **Card controls** element includes e*xport options*, a *drag handle* to sort cards, and the *card actions* menu which can put a card into edit mode.

### Components of a Report

{% columns %}
{% column width="50%" %} <img src="https://3101925571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmrOjheW9v23epAZJDsmJ%2Fuploads%2Fm2W165gVktbTJ5KkyxuW%2Ftabs.png?alt=media&amp;token=332408f2-dea2-403c-a903-b0810ed550ce" alt="" data-size="line"> **Tabs.** The primary way of organizing content thematically within a report. They are optional and the tab bar disappears when not used.

<img src="https://3101925571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmrOjheW9v23epAZJDsmJ%2Fuploads%2FGUA1kSpDio6uy11eC1s8%2Fcards.png?alt=media&amp;token=cd4db09c-9c38-4644-9e54-fa42bab0fae0" alt="" data-size="line"> **Cards.** Rich-text documents that contain a mix of prose, formatting, images, and visualization widgets. Authored using a WYSIWYG editor.

<img src="https://3101925571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmrOjheW9v23epAZJDsmJ%2Fuploads%2F2zGr73jAhziJiuOQWLc7%2Finline_metrics.png?alt=media&amp;token=112ce032-c7ce-44d1-8484-4cf472ec562e" alt="" data-size="line"> **Inline Metrics.** Calculated stats designed to be placed inline with the text of a card.

<img src="https://3101925571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmrOjheW9v23epAZJDsmJ%2Fuploads%2FzyU25h4yxniNRdtQELs8%2Fblock_widgets.png?alt=media&amp;token=91b4baa4-c997-46b4-9299-84d285394966" alt="" data-size="line"> **Block Widgets.** Data visualization elements such as tables, charts and maps. These display stats calculated from your project's overlay layers.
{% endcolumn %}

{% column width="50%" %}

<div align="center"><img src="https://3101925571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmrOjheW9v23epAZJDsmJ%2Fuploads%2FAlCZD822lQLpJp2sdwj9%2Freport_with_markers_2x.png?alt=media&amp;token=4b6c0320-a75e-46ac-a8fd-cb2642c925dd" alt=""></div>
{% endcolumn %}
{% endcolumns %}

Tabs and Cards are created, sorted, removed, and duplicated using actions in the top toolbar and card control menus. The content of cards is edited using a rich text editor that supports undo and copy+paste. To add Inline Metrics or Block Widgets to the card, use the [slash command menu](#adding-widgets-using-the-slash-command-menu).

### Adding widgets using the slash-command menu

<figure><img src="https://3101925571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmrOjheW9v23epAZJDsmJ%2Fuploads%2FsxBOJGgw3EFChybBJD1A%2FScreenshot%202026-11-18%20at%202.12.19%E2%80%AFPM.png?alt=media&amp;token=43f515ac-a274-4b08-b18d-02e9069f5bb4" alt="" width="464"><figcaption><p>Authoring content often starts with the slash-command menu.</p></figcaption></figure>

Type `/` in the card editor to open the slash-command menu. From this menu you will see a grouped list of options for content you can insert into your Card document. This pattern was popularized by the Notion knowledge management tool, but has spread to many other rich-text editors.

* With **Basic Blocks** you can insert headers, images, lists, and collapsible blocks. Familiar rich-text content to structure your card's content.
* **Inline Sketch Metrics** are facts about the subject Sketch such as the area, percent of a geography captured within, or distance to shore. They are in the form of a simple number with a unit, so that they can be displayed inline with your text.
* **Sketch Block Widgets** are also facts about a subject, but in richer form such as a distance to port map, a table of sketch size as a proportion of different geographies, or a list of user-entered attributes about the sketch.
* Finally, there are **Overlay Layer Widgets**. Each hosted overlay layer in your project gets an entry, from which a submenu lists all the visualization widget options that are compatible with that layer.

When first choosing a layer to use in a report, press the **Process for Reporting** button. This will start a job to optimize the underlying data for analysis, and also immediately present a list of compatible widgets that can be used. Hovering over an option will review a thumbnail image and description of the widget.

{% hint style="info" %}
The list of layer options can be long. After typing *slash*, start typing the name of a layer you want to report on. The list of options will be filtered by your search. In the example below, `/benthos` was typed.
{% endhint %}

<figure><img src="https://3101925571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmrOjheW9v23epAZJDsmJ%2Fuploads%2FzwqZHvqSfAO5GQOewIqT%2FScreenshot%202026-11-18%20at%202.39.31%E2%80%AFPM.png?alt=media&amp;token=447b8c8c-1305-4b8d-94b8-4ada6a59e77c" alt=""><figcaption></figcaption></figure>

The list of widgets is always growing as new use-cases are found and presentation options are requested. Please contact <support@seasketch.org> to make such requests.&#x20;

Once a report widget is added, results may be calculated for the first time on that overlay layer. That means the system needs to finish optimizing the source data, and calculate geography-level stats, before finally calculating results for your example sketch. These first set of products may take longer to calculate, but analysis of subsequent sketches will be much faster. Progress estimates and calculation details can be revealed from the *Card controls* menu.

<figure><img src="https://3101925571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmrOjheW9v23epAZJDsmJ%2Fuploads%2F12tYpB8gUsOhsdH3MaQJ%2FScreenshot%202026-11-18%20at%202.49.10%E2%80%AFPM.png?alt=media&amp;token=f9896f42-29ec-4f9a-9efb-dbf8d401614b" alt=""><figcaption></figcaption></figure>

Clicking on a widget or inline metric while in edit mode will reveal a popover menu with various options specific to the component. These options control presentation modes, hidden columns or values, units displayed, or performance tuning parameters.

#### Tips for authoring card content

* Copy & Paste, and undo and redo via keyboard commands are fully supported while a card is in edit mode. Even for inline metrics, widgets, and their configuration.
* It can be hard to know which widget to pick. Play with them all! The system is designed to support fast calculations and cache results. Don't be afraid to experiment.
* The best way to become familiar with a widget or metric's numerous options is to play with them. If you make a change you don't like, just Undo!  <mark style="color:$secondary;">⌘+Z or Ctrl+Z</mark>
* Be sure to use the slash-command as a search tool, rather than hunting for options in a long list. Your text will be matched against both overlay layer and widget names. (e.g. `/area` )

## Publishing Reports

Changes to reports are staged in the administrative interface, similar to the overlay layers list. These draft changes are not shown on the public-facing side of a project until they are published. A blue dot in the toolbar indicates when there are draft changes, and clicking on the menu will show the most recent publication date.

{% hint style="info" %}
Reports do not currently support a changelog like in the overlay layers list, but this feature is planned for the future.
{% endhint %}

### Improving Performance and Handling Errors

If a particular report card is loading slowly, or you encounter errors with certain outputs or layers, please reference the following guide. You can also always contact <support@seasketch.org>.

[Debugging Timeout and Performance Issues](https://docs.seasketch.org/seasketch-documentation/administrators-guide/reports/debugging-timeout-and-performance-issues.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.seasketch.org/seasketch-documentation/administrators-guide/reports.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
