# How do I do batch processing?


```{admonition} What will I learn?
* How to use the InstanSeg extension to detect nuclei and cells
* How to use the workflow editor to create a script
* How to use batch processing to run a script for multiple images in a project
```

We rarely need to analyze just **one** image.
Usually, we have multiple similar images that we we want to analyze in a similar way.


This chapter uses images from the Broad bioimage benchmarking challenge, available to download from [GitHub](https://github.com/user-attachments/files/20163968/BBBC007_project.zip) or from the link provided in the [setup guide](../../setup/images.md).

```{admonition} What to do
1. Unzip `BBBC007_project.zip`
2. Drag the resulting folder onto QuPath to open the project.
```

## Cell detection with InstanSeg

At the start of the workshop we advised installing some extensions, one of which was InstanSeg (alongside the Deep Java Library extension).


```{admonition} What to do
1. Run {menuselection}`Extensions --> InstanSeg --> Run InstanSeg`.
  The InstanSeg dialog will appear as shown below.
   :::{figure} ../../images/batch_processing/instanseg.png
   InstanSeg dialog
   :::
2. Select the model from the dropdown called `fluorescence_nuclei_and_cells-0.1.0` and click the download button {{ icon_download }} next to it.
3. Select an annotation tool and create an annotation.
4. Ensure that an annotation is selected (in yellow by default).
5. Click {guilabel}`Run` in the InstanSeg window.
```


It may take longer to process than the standard QuPath cell detection method, but once complete should look like below.

```{figure} ../../images/batch_processing/instanseg-results.png
InstanSeg results
```

```{tip}
You can create an annotation covering the entire image with {menuselection}`Objects --> Annotations --> Create full image annotation` or using {kbd}`Control/Command+Shift+A`.

For large images, a whole image annotation may take a very long time to run! 
It's often better to run analysis only on a subset of the image, perhaps by restricting to only relevant tissue regions first, as shown in [How do I detect tissue?](../part2/how_do_i_detect_tissue.md)
```

There are many more options to explore in InstanSeg, such as:

- Choosing a device (GPU if you have one), changing the number of threads or tile size --- these may change how long it takes to process images.
- Selecting the channels that InstanSeg uses, rather than just using all channels.
  This can reduce memory usage and processing time with very large images.
- Whether to produce cells or nuclei as the output.
  This is limited by the model used (some models only segment nuclei).
  For more information on InstanSeg, please check out the [readTheDocs](https://qupath.readthedocs.io/en/latest/docs/deep/instanseg.html).


```{admonition} What to do
6. Experiment with the options in InstanSeg until you find a combination that you are happy with.
7. Save the work you have done on this image via {menuselection}`File --> Save`, or the keyboard shortcut of {kbd}`Control/Command+S`.
```


## QuPath workflows

The Workflow tab in the side bar is the workflow tab.
This records each of the steps performed on the current image.

```{figure} ../../images/batch_processing/workflow.png
QuPath with the workflow pane open
```

Often, the workflow history on an image isn't a perfect step-by-step workflow.
For example, some steps (like creating annotations) aren't captured.
Furthermore, it's rare that everything works perfectly first time.
It often takes a few "test runs" to identify the right settings and order of operations for a good analysis.

Thankfully, QuPath allows you to edit the workflow.

```{admonition} What to do
1. Click {guilabel}`Create workflow` in the lower left corner.
  This will produce a very similar window to the workflow pane.
2. Delete things that aren't needed by clicking {guilabel}`Remove selected items`.
3. Re-order the remaining steps until it represents a sensible order of operations.

:::{figure} ../../images/batch_processing/workflow-editor.png
QuPath with the workflow pane open
:::

4. Select {guilabel}`Create script`.
```

Congratulations, you have just created your first script! 


After clicking {guilabel}`Create script`, the script editor will open showing a script:

```{figure} ../../images/batch_processing/script-editor.png
QuPath's script editor
```


### Running a script for all images in a project

Once you are happy with your script, you could now open a different image in the project and run it.
This would be quicker and less error-prone than repeating it manually, but it would still be very time-consuming for projects containing many images.

Alternatively, QuPath's script editor allows you to run a script for every image in a project.


```{admonition} What to do
1. In the script editor, select {menuselection}`Run --> Run for project`.
  This will open a dialog allowing you to select which images should be processed.
2. Click the double right arrow {guilabel}`>>` to move all images into the right {guilabel}`Selected` pane to run the script on every image in the current project.
```

```{figure} ../../images/batch_processing/run-dialog-full.png
The run dialog filled in
```

Then, QuPath will open each image in the project, run through each step of the workflow, and save the resulting changes.
This makes it very convenient to reproduce exact analysis steps on many images with no manual intervention.

```{figure} ../../images/batch_processing/instanseg-running.png
InstanSeg running for project
```

```{admonition} What to do
3. Open another image in the project.
  This should show the results of running InstanSeg cell detection on that image.
```

```{figure} ../../images/batch_processing/other-image.png
InstanSeg results on another image
```

```{tip}
InstanSeg also has an available model for nucleus detection in brightfield images.
Models for other types of objects (and other image types) may be coming soon, watch this space!  
```