> 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/scripts.md).

# Scripts

*What you'll get: how to run your own Python script over the images and results of an analysis from the **Scripts** page, and how to prepare a script so it runs there.*

{% hint style="info" %}
Scripts are available on request. If you don't see **Scripts** in the sidebar, contact [Biodock support](/about/contact-us.md) to turn it on.
{% endhint %}

A script runs in the background over every image of an analysis you pick. It gets each image and its predicted outlines, and any files it writes are returned to you. You only need view access to the analysis.

## Upload a script

1. Click **Scripts** in the sidebar.
2. Click **Upload script**.
3. In **Upload a script**, add exactly one `.py` file and one `requirements.txt`. Each file must be smaller than 1 MB. In a [workspace](/workspaces/workspaces/sharing-and-visibility.md), also choose who can see the script.
4. Click **Upload**.

## Run a script

1. On the **Scripts** page, click **Run script** (or **Run a script** in **All activity**).
2. In **Submit a script run**, pick the analysis under **Job**, from **My jobs** or **Shared jobs**, and pick the **Script**.
3. Tick the box to accept the script run terms.
4. Click **Submit**. The dialog shows how long the run is allowed to take (up to 48 hours) and what it uses. See [Credits, storage and limits](/account/credits-storage-and-limits.md).

## Check a run

Click the run in the run history to see its progress. When it finishes, check:

* **Outputs**: the files your script wrote. Click **Download outputs** to save them.
* **Console**: what your script printed.
* **Errors**: error messages, if any.

To delete a finished run, click **Delete run**. This deletes its outputs too, so download them first. Deleting a run does not delete the script.

## Prepare your script

Biodock runs your script with Python 3.10, in a new environment for every run.

### 1. Use a single .py file

Convert a Jupyter notebook (`.ipynb`) to one Python script (`.py`), with all the code it needs. Remove imports for Google Colab or Google Cloud; they are not needed.

### 2. Read the input list

Biodock downloads every image and its predictions before your script starts, so your script does not download anything. It runs your script as:

```
python your_script.py input_items.json output_dir
```

with `output_dir` as the working directory. `input_items.json` is a list with one entry per image:

```json
[
  {
    "image_name": "Control_01.tif",
    "image_path": "/path/to/images/Control_01.tif",
    "geojson_path": "/path/to/geojson/Control_01.geojson"
  }
]
```

The GeoJSON file holds the image's predicted outlines and classes, in the same format as the **Predicted labels** export (see [Download results and reports](/analysis-and-results/download-results-and-reports.md#predicted-labels)).

Read the paths from the command line:

```python
import sys
import json

input_items_path = sys.argv[1]  # the input list
output_dir = sys.argv[2]  # where to write your outputs

with open(input_items_path, "r") as f:
    input_items = json.load(f)
print(f"Loaded {len(input_items)} input items.")

# The first image and its GeoJSON file
json_file_path = input_items[0]["geojson_path"]
image_path = input_items[0]["image_path"]
```

### 3. Write outputs to output\_dir

Every file in `output_dir` is collected and returned to you when the run finishes. Anything your script prints is shown under **Console**.

```python
import os

example_output_path = os.path.join(output_dir, "example_output.txt")
with open(example_output_path, "w") as f:
    f.write("This is an example output file.")
```

Save plots instead of showing them: replace every `plt.show()` with `plt.savefig()` into `output_dir`.

```python
import matplotlib.pyplot as plt

plt.savefig(os.path.join(output_dir, "area_histogram.png"))
```

### 4. List your dependencies in requirements.txt

List every package your script needs. Biodock installs them before every run. Pinned versions that have prebuilt wheels install faster.

```
matplotlib
numpy
pandas
shapely
tifffile
scikit-image
```

If you have questions, contact [Biodock support](/about/contact-us.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.biodock.ai/analysis-and-results/scripts.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.
