> For the complete documentation index, see [llms.txt](https://docs.biodock.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.biodock.ai/analysis-and-results/download-results-and-reports.md).

# Download results and reports

*What you'll get: how to export a summary report, per-object data or the predicted outlines from a result, how the file reaches you, and what the mask files contain.*

Most downloads start on the result's **Export data** tab. Exports are prepared in the background, and Biodock sends you a link when the file is ready.

## Export from the Export data tab

1. Open the result and click the **Export data** tab.
2. Under **What to export**, pick **Aggregate report**, **Predicted labels** or **Raw object data**.
3. Set what goes in it on the right (see below). The **You'll get** line shows the files you will receive.
4. Click **Prepare export**. The form says "Preparing. We'll notify you and email a link when it's ready. You can leave this page."
5. When the file is ready, a **Data download ready** notification arrives in the bell in the top bar, and you get an email. Click **Download**.

Download links expire. If a link no longer works, prepare the export again.

### Aggregate report

Use it to compare images or groups by their averages and spread. This is the summary most people want.

* **Image groups**: tick the groups to include. You get `group-data.csv` (one row per group) and `image-data.csv` (one row per image) in a zip.
* **Parent objects** (optional): tick parent classes to add `parent-data.csv`, with one row per parent object and aggregates of the objects inside it.

The aggregate report always covers every population. It can't be filtered by population yet.

### Raw object data

Use it when you need object-by-object data, to analyse in another program or to look at particular objects. You get one CSV with one row per object and every measurement.

* **All objects**: every detected object in the job.
* **Only some populations**: only objects in at least one of the **Populations** you tick. Use **Select all** or **Clear** to tick or untick them all.

These files can be very large and take several minutes if you have hundreds of thousands of objects. Consider the aggregate report instead.

### Predicted labels

The object outlines and their classes as GeoJSON, one file per image, for tools such as QuPath.

1. Choose **By group** or **By image**.
2. Tick the **Image groups** or **Images**. Images that were not analysed are marked **Not analysed** and left out.
3. Tick the **Classes**.

{% hint style="info" %}
Exports reflect the results when they are prepared. After you apply [object edits](https://docs.biodock.ai/analysis-and-results/editing-objects-qc.md) or recompute metrics, counts and columns can change, so prepare the export again.
{% endhint %}

## Export from the Analysis list

You can also start whole-job exports without opening a result. In **Analysis**, open a finished result's **⋯** menu:

* **Export CSV**: a zip with the job's images and a CSV with one row per detected object.
* **Export masks**: a zip with the job's AI-generated object masks in JSON format (see [Mask files](#mask-files)).
* **Export aggregate CSV**: a zip with the job's aggregate CSV data.

These arrive as a link in the bell in the same way.

## Overlay images

To download a high-resolution image with its outlines drawn on it, click **Download** under the image viewer on the **Dashboard** tab. It downloads the image you are viewing. Biodock prepares the file, and the download starts by itself when it is ready.

## Mask files

This section is for people who process masks with their own code: to draw custom overlays, compute custom measurements, or import outlines into another tool.

In **Analysis**, open the result's **⋯** menu and choose **Export masks**. (For older results that open the classic dashboard, you can also use **Generate masks data** on the **Export data** tab.) You get a zip archive of JSON files:

```
|- index.json  # information about the analysis run
|- {image_id}_objects.json  # one per image in the run
```

{% code title="index.json" %}

```json
{
  "resultId": "AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAA",
  "dateRun": "2022-08-08T19:03:06.458Z",
  "classData": {
      "Cyst": {
        "name": "Cyst",
        "type": "Instance"
      }
    }
}
```

{% endcode %}

{% code title="{image\_id}\_objects.json" %}

```json
{
    "filename": "file1.tif",
    "id": "AAAAAAAAAAAAAAAAAAAAAAAA",
    "height": 12288,
    "width": 16384,
    "objects": {
        "1": {
            "bbox": [ 250, 474, 437, 664 ],    // x1, y1, x2, y2
            "id": 1,
            "rle": {                           // COCO-style RLE, base64-encoded counts
                "size": [ 190, 187 ],
                "counts": "WWUwOFo1YTBLMEk7RDlGPE0w="
            },
            "pred_class": "Cyst",
            "derived_objects": {}
        }
    }
}
```

{% endcode %}

### Decoding the masks

The masks are in COCO-style RLE format. You can parse them with the cocoapi tools in Python, Lua or MATLAB. See the [cocoapi GitHub repo](https://github.com/cocodataset/cocoapi) for other languages.

Install pycocotools:

```shell
pip install pycocotools # or conda install -c conda-forge pycocotools
```

Decode the masks of one image into binary masks:

```python
import base64
import json
import pycocotools.mask as maskutil

with open('AAA_objects.json') as maskfile:
  mask_results = json.load(maskfile)
  first_image_objects_encoded = mask_results["objects"]

  first_image_masks = []
  for obj in first_image_objects_encoded.values():
      encoded_mask = obj["rle"]
      encoded_mask["counts"] = base64.b64decode(encoded_mask["counts"])

      first_image_masks.append(maskutil.decode(encoded_mask))
```

You can then convert these binary masks into polygons with a number of libraries, and, for example, load them into FIJI with the [ROI importer](https://imagej.nih.gov/ij/plugins/roi-importer.html).


---

# 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.biodock.ai/analysis-and-results/download-results-and-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.
