Pipeline for automated cell selection along a gradient with conservation of spatial information

This repository contains the computational workflow that enables the systematic identification and selection of representative cells across liver zonation gradients. Microscopy images are input for automated vein identification and characterization based on marker proteins. The user then selects suitable trajectories, either automatically or manually. Pre-segmented cell contours (turquoise in the figure above) are the basis for the farthest-first traversal algorithm, maximizing minimum distances between selected shapes to achieve uniform cell distribution along the portal-central axis. Selected shapes are assigned a portal score (S) from 0 to 1 based on their relative position. In addition, we provide a GUI which allows selection of the two endpoints of the trajectory of interest by mouse click, making the pipeline adaptable to different tissue architectures.

Installation

To install the software, first create an isolated conda environment, and add pipx to its dependencies:

conda create -n humanscDVP python=3.10 pipx
conda activate humanscDVP

Use pipx to install poetry, our dependency manager of choice:

pipx install poetry

Navigate to the repository folder, and run:

poetry install

Example usage

The pipeline assumes a series of files for a given DVP experiment were already generated, such as:

• SAMPLE.xml containing cell segmentation coordinates compatible with laser microdissection, where SAMPLE refers to an arbitrary sample ID
• SAMPLE_meta.txt metadata file, containing calibration metadata for laser microdissection
• SAMPLE_Alexa488.tif full slide image with membrane marker staining, used for cell segmentation
• SAMPLE_PORTAL.tif full slide image with portain vein staining
• SAMPLE_CENTRAL.tif full slide image with central vein staining

Image processing pipeline

This command outputs markers for ease of visualization. Output: SAMPLE_markers.png.

python vein_selection/detect_veins.py --xml-path SAMPLE.xml --metadata-path SAMPLE_meta.txt --cell-image-path SAMPLE_Alexa488.tif --portal-image-path SAMPLE_PORTAL.tif --central-image-path SAMPLE_CENTRAL.tif  --slide SAMPLE --reduction <REDUCTION-FACTOR> --scores-path <OUTPUT-PATH> --n-cells <CELLS-TO-SAMPLE> --n-cores <PARALLEL-CORES> --sigma 15 --markers

This command lets us see all the thresholds, veins are color coded. Output: SAMPLE_all_veins.png

python vein_selection/detect_veins.py --xml-path SAMPLE.xml --metadata-path SAMPLE_meta.txt --cell-image-path SAMPLE_Alexa488.tif --portal-image-path SAMPLE_PORTAL.tif --central-image-path SAMPLE_CENTRAL.tif --slide SAMPLE --reduction <REDUCTION-FACTOR> --scores-path <OUTPUT-PATH> --n-cells <CELLS-TO-SAMPLE> --n-cores <PARALLEL-CORES> --sigma 15

This command, once we select the threshold multiplier and the area of interest from the previous image, shows us all the veins in such area. Output: SAMPLE_select_veins.png

python detect_veins.py --xml-path SAMPLE.xml --metadata-path SAMPLE_meta.txt --cell-image-path SAMPLE_Alexa488.tif --portal-image-path SAMPLE_PORTAL.tif --central-image-path SAMPLE_CENTRAL.tif --slide SAMPLE --reduction <REDUCTION-FACTOR> --scores-path <OUTPUT-PATH> --n-cells <CELLS-TO-SAMPLE> --n-cores <PARALLEL-CORES> --sigma 15 --th-mult 0.8 --xmin 350 --xmax 625 --ymin 575 --ymax 900

This command, once we select the central and portal vein from the previous image, completes the pipeline by selecting the shapes in the trajectory of interest. Outputs:

• SAMPLE_veins.png selected veins
• SAMPLE_shape_scores.png visual of selected shapes and scores
• SAMPLE_filtered.xml output xml file (with ids but not scores)
• SAMPLE_scores.txt output selected shape ids and scores

python vein_selection/detect_veins.py --xml-path SAMPLE.xml --metadata-path SAMPLE_meta.txt --cell-image-path SAMPLE_Alexa488.tif --portal-image-path SAMPLE_PORTAL.tif --central-image-path SAMPLE_CENTRAL.tif --slide SAMPLE --reduction <REDUCTION-FACTOR> --scores-path <OUTPUT-PATH> --n-cells <CELLS-TO-SAMPLE> --n-cores <PARALLEL-CORES> --sigma 15 --th-mult 0.8 --xmin 350 --xmax 625 --ymin 575 --ymax 900 --n-cen 03 --n-por 05

Additional useful parameters:

• --boost-ctr (float): boosts the central markers, making easier to classify veins as central rather than portal. Default: 1.0
• --angl-thr (int): angle constraint on shape position. Default: 130 (degrees)

Merging two trajectories

Given the input xml (e.g. SAMPLE.xml) and two score files of two distinct trajectories (e.g. --scores-path-1 SAMPLE_scores_1.txt --scores-path-2 SAMPLE_scores_2.txt), it outputs merged xml and score files. Fails if there is a shared cell in the two trajectories.

python vein_selection/merge_xmls.py --xml-path SAMPLE.xml --metadata-path SAMPLE_meta.txt --cell-image-path SAMPLE_Alexa488.tif --slide SAMPLE --scores-path-1 SAMPLE_scores_1.txt --scores-path-2 SAMPLE_scores_1.txt --out SAMPLE_scores

Annotating difficult slides manually with a graphical interface

If slides are difficult to process automatically, a graphical interface is provided to manually annotate the veins. The interface is launched with the following command, which includes the --gui flag:

python vein_selection/detect_veins.py --xml-path SAMPLE.xml --metadata-path SAMPLE_meta.txt --cell-image-path SAMPLE_Alexa488.tif --portal-image-path SAMPLE_PORTAL.tif --central-image-path SAMPLE_CENTRAL.tif --slide SAMPLE --reduction <REDUCTION-FACTOR> --scores-path <OUTPUT-PATH> --n-cells <CELLS-TO-SAMPLE> --n-cores <PARALLEL-CORES> --sigma 1 --markers --gui

When running the script, a first window will pop up with an overlay of cell shapes and portal markers. Clink anywhere to select the desired vein, press d on your keyboard to delete your selection, or q to continue. Repeat the process for central veins. All intermediate results will also pop up interactively (press q to move on) and be automatically saved to disk.