# How do I write scripts?


```{admonition} What will I learn?
* What is a script?
* How to find existing scripts
* How to create a basic script from scratch
```

The user interface is the most user-friendly way of working with QuPath.
However, it has some limits:

* Analysis is done by hand and takes some time.
* It doesn't allow processing similar images in batch mode.
* It doesn’t encourage reproducibility in analysis.

QuPath supports **scripts** as an alternative.

Scripts represent sequences of instructions that are interpreted by QuPath, for example:

* Setting the image type.
* Setting the colour deconvolution stains.
* Applying a cell detection algorithm.

In QuPath, scripts are written in the **script editor**.
You can open it by clicking on {menuselection}`Automate --> Show script editor`.

```{figure} ../../images/scripts/script-editor.png
The QuPath script editor
```

## Groovy

Scripts are written in **Groovy**.
This is a language similar to Python but for the Java platform.

We created a script containg an [overview of the Groovy syntax](https://github.com/qupath/i2k2024/blob/main/workshops/groovy-scripters/0-Basic%20Groovy%20syntax.groovy).
This can be useful to have when beginning with Groovy scripting.

## Finding existing scripts

Before writing your own scripts, you can check if the script you want to write already exists.
The [user forum](https://forum.image.sc/tag/qupath) is a good source for scripts.

Be aware that scripts found on the Internet can be **outdated**: a script written for an earlier version is not guaranteed to work for the latest version.

```{admonition} What to do
1. Create an empty folder on your computer.
2. Open the `LuCa-7color_[13860,52919]_1x1component_data.tif` image in QuPath.
3. Create a few rectangle annotations.
4. Go to [this image.sc topic](https://forum.image.sc/t/qupath-batch-exporting-10-regions-of-interest/115913/2?u=leo_leplat).
5. The post contains a script that exports all parts of the image located below annotations. Copy the script.
6. Go to QuPath and click on {menuselection}`Automate --> Show script editor`. This opens up the script editor.
7. Paste the script.
8. Change `/path/to/some/folder/` to the path of the folder you created on step 1. On Windows, the path should look like `C:\Users\User\someFolder`. On MacOS, the path should look like `/Users/user/someFolder`.
9. Click on `Run` in the bottom right corner of the script editor. After some time, `Done` should be printed at the bottom of the script editor.
10. Check the folder you created on step 1. It should now contain images named `1.ome.tiff`, `2.ome.tiff`, and so on.
11. Drag `1.ome.tiff` to QuPath to check the first image. It should represent a subset of the original image.
```

## Creating basic scripts

QuPath has some functions dedicated to scripting in two classes:

* [QP](https://qupath.github.io/javadoc/docs/qupath/lib/scripting/QP.html#method-summary) for general functions.
* [QPEx](https://qupath.github.io/javadoc/docs/qupath/lib/gui/scripting/QPEx.html#method-summary) for GUI functions.

These functions should be enough for common use cases.

```{admonition} What to do
1. Go to [QP](https://qupath.github.io/javadoc/docs/qupath/lib/scripting/QP.html#method-summary).
2. Find a function that returns the name of the current image. You can use {kbd}`Control/Command+F` to search for the function.
3. Open any image in QuPath.
4. Open the script editor.
5. Use the function of step 2 to print the name of the current image.
```

Hint: you can use:

```groovy
println someFunction()
```

to print the result of `someFunction()`.


```{tip}
**ChatGPT** is **not good** at generating QuPath scripts.
```

## Asking help

You can use [image.sc](https://forum.image.sc/tag/qupath) if you need help regarding a script (or anything else related to QuPath).

If you embed a script in your post, please surround your code with ```. This adds special formatting that makes it easier for others to copy the script.