baby-seg 0.30.8

Birth Annotator for Budding Yeast

BABY

Birth Annotation for Budding Yeast

An image processing pipeline for accurate single-cell growth estimation of budding cells from bright-field stacks. The Birth Annotator for Budding Yeast (BABY) features:

• segmentation of overlapping cells, e.g., where small buds overlap with their mothers/sisters,
• automated assignment of buds to mothers, and
• estimation of the time of birth (cytokinesis) from growth rate.

The algorithm is described in:

Julian MJ Pietsch, Alán F Muñoz, Diane-Yayra A Adjavon, Iseabail Farquhar, Ivan BN Clark, Peter S Swain. (2023). Determining growth rates from bright-field images of budding cells through identifying overlaps. eLife. 12:e79812.

Installation

We recommend installing BABY and all its requirements in a virtual environment (e.g., conda create if you are using Anaconda, or python3 -m venv otherwise).

NB: If you want to install with GPU support see below.

Otherwise, if you simply wish to use install with the latest compatible versions of all packages, then simply run the following in your virtual environment:

> pip install baby-seg

NB: You can update by running: pip install -U baby-seg.

Python and TensorFlow version

BABY requires Python 3 and TensorFlow. Different versions of TensorFlow have different Python version requirements. You can find a table of matching versions here.

Our models were trained with TensorFlow version 2.8, but have been tested up to version 2.14.

By default, BABY will trigger installation of the highest compatible version of TensorFlow. If you want to use an earlier version, then first install that version in your virtual environment by running:

> pip install tensorflow==2.8

and then follow the instructions for installing BABY as above.

Running with GPU

To make use of a GPU you should follow the TensorFlow set up instructions before installing BABY.

BABY can make use of Metal on M1/M2 Macs by following the instructions here.

For developers

You may prefer to install an editable version by first obtaining this repo and then pip installing the cloned directory:

> git clone https://git.ecdf.ed.ac.uk/swain-lab/baby.git
> cd baby
> pip install -e .

Quickstart using the Python API

The BABY algorithm makes use of several machine learning models that are defined as a model set. Various model sets are available, and each has been optimised for a particular species, microfluidics device, pixel size, channel and number of input Z sections.

You can get a list of available model sets and the types of input they were trained for using the meta function in the modelsets module:

>>> from baby import modelsets
>>> modelsets.meta()

You then load your favourite model set as a BabyBrain object, which coordinates all the models and parameters in the set to produce tracked and segmented outlines from input images. You can get a BabyBrain for a given model set using the get function in the modelsets module:

>>> brain = modelsets.get('yeast-alcatras-brightfield-EMCCD-60x-5z')

For each time course you want to process, instantiate a new BabyCrawler. The crawler keeps track of cells between time steps.

>>> from baby import BabyCrawler
>>> crawler = BabyCrawler(brain)

Load an image time series (from the tests subdirectory in this repository). The image should have shape (x, y, z).

>>> from baby.io import load_tiled_image
>>> image_series = [load_tiled_image(
...     'tests/images/evolve_testG_tp{:d}_Brightfield.png'.format(t))
...     for t in range(1,6)]

Send images to the crawler in time-order (here a batch of size 1). We additionally request that outlines are optimised to edge predictions, and that lineage assignments, binary edge-masks and volume estimates (using the conical method) should be output at each time point.

>>> segmented_series = [crawler.step(
...     img[None, ...], refine_outlines=True, assign_mothers=True,
...     with_edgemasks=True, with_volumes=True)
...     for img, _ in image_series]

Finally, save the segmentation outlines, labels, volumes and lineage assignments as an annotated tiled png:

>>> from baby.io import save_tiled_image
>>> for t, s in enumerate(segmented_series): 
...     save_tiled_image(255 * s[0]['edgemasks'].astype('uint8').transpose((1, 2, 0)), 
...     '../segout_tp{:d}.png'.format(t + 1), 
...     {k: s[0][k] for k in ('cell_label', 'mother_assign', 'volumes')})

Jupyter notebooks

More extensive examples for using BABY can be found in the python/notebooks folder. To maintain the repository in a clean state, it's probably best to copy these to another directory for routine use. If you want to share a notebook, you can then specifically add it back to the repository at a useful checkpoint.

The notebooks include:

1. a complete example for reproducing Figure 1e in the associated paper.
2. the basic training workflow demonstrating how to train the BABY algorithm from scratch. This notebook can be adapted to train BABY for new cell types or imaging modes.

Run via a server

Once installed, you should be able to start a server to accept segmentation requests using:

> baby-phone

The server runs by default on http://0.0.0.0:5101. The recommended way to send requests to the server is by using the BABY GUI, which requires Matlab.

The HTTP API is currently undocumented, but examples showing how to correctly send requests using Python are given in the client-api notebook.