util

basic

Useful functions for general use

ifnone(x, default)

Return type:

Any

dumb()

Dumb function.

A dumb function to test github actions on changes.

images

Useful functions for images.

regular_grid(shape, interval, psize)

Get a regular grid of position on a slide given its dimensions.

Parameters:

• shape (Coord) – (x, y) shape of the window to tile.

• interval (Coord) – (x, y) steps between patch samples.

• psize (Coord) – (w, h) size of the patches (in pixels).

Yields:

(x, y) positions on a regular grid.

Return type:

Iterator[Coord]

get_coords_from_mask(mask, shape, interval, psize)

Get tissue coordinates given a tissue binary mask and slide dimensions.

Parameters:

• mask (bool8)) – binary mask where tissue is marked as True.

• shape (Coord) – (x, y) shape of the window to tile.

• interval (Coord) – (x, y) steps between patch samples.

• psize (Coord) – (w, h) size of the patches (in pixels).

Yields:

(x, y) positions on a regular grid.

Return type:

Iterator[Coord]

unlabeled_regular_grid_list(shape, step, psize)

Get a regular grid of position on a slide given its dimensions.

Parameters:

• shape (Coord) – shape (i, j) of the window to tile.

• step (int) – steps in pixels between patch samples.

• psize (int) – size of the side of the patch (in pixels).

Return type:

List[Coord]

Returns:

Positions (i, j) on the regular grid.

images_in_folder(folder, authorized=('.png', '.jpg', '.jpeg', '.tif', '.tiff'), forbiden=('thumbnail',), randomize=False, datalim=None, paths=False)

Get images in a given folder.

Get all images as numpy arrays (selected by file extension). You can remove terms from the research.

Parameters:

• folder (Union[str, PathLike]) – absolute path to an image directory.

• authorized (Sequence[str]) – authorized image file extensions.

• forbiden (Sequence[str]) – non-authorized words in file names.

• randomize (bool) – whether to randomize output list of files.

• datalim (Optional[int]) – maximum number of file to extract in folder.

• paths (bool) – whether to return absolute path with image data.

Yields:

Images as numpy arrays, optionally with path.

Return type:

Iterator[Union[uint8), Tuple[str, uint8)]]]

sample_img(image, psize, spl_per_image, mask=None)

Split image in patches.

Parameters:

• image (Union[uint8), float32), float64)]) – numpy image to fit on.

• psize (int) – size in pixels of the side of a patch.

• spl_per_image (int) – maximum number of patches to extract in image.

• mask (Optional[bool8)]) – optional boolean array, we sample in true pixels if provided.

Return type:

List[Float)]

Returns:

Patches in the image.

sample_img_sep_channels(image, psize, spl_per_image, mask=None)

Fit vocabulary on a single image.

Split image in patches and fit on them.

Parameters:

• image (uint8)) – numpy image to fit on.

• psize (int) – size in pixels of the side of a patch.

• spl_per_image (int) – maximum number of patches to extract in image.

• mask (Optional[bool8)]) – optional boolean array, we sample in true pixels if provided.

Return type:

Tuple[List[Float)], ...]

Returns:

Patches in the image in separated channels.

management

Helpful function to extract and organize data.

It takes advantage of the common structure of pathaia projects to enable datasets creation and experiment monitoring/evaluation.

exception Error

Bases: Exception

Base of custom errors.

---

exception LevelNotFoundError

Bases: Error

Raise when trying to access unknown level.

---

exception EmptyProjectError

Bases: Error

Raise when trying to access unknown level.

---

exception SlideNotFoundError

Bases: Error

Raise when trying to access unknown level.

---

exception PatchesNotFoundError

Bases: Error

Raise when trying to access unknown level.

---

exception UnknownColumnError

Bases: Error

Raise when trying to access unknown level.

---

get_patch_csv_from_patch_folder(patch_folder)

Give csv of patches given the slide patch folder.

Check existence of the path and return absolute path of the csv.

Parameters:

patch_folder (str) – absolute path to a pathaia slide folder.

Return type:

str

Returns:

Absolute path of csv patch file.

get_patch_folders_in_project(project_folder)

Give pathaia slide folders from a pathaia project folder (direct subfolders).

Check existence of the project and yield slide folders inside.

Parameters:

• project_folder (str) – absolute path to a pathaia project folder.

• exclude – a list of str to exclude from subfolders of the project.

Yields:

Absolute path to folder containing patches csv files.

Return type:

Iterator[Union[str, PathLike]]

get_slide_file(slide_folder, project_folder, patch_folder, extensions=['.mrxs', '.svs'])

Give the absolute path to a slide file.

Get the slide absolute path if slide name and slide folder are provided.

Parameters:

• slide_folder (str) – absolute path to a folder of WSIs.

• project_folder (str) – absolute path to a pathaia folder.

• patch_folder (str) – absolute path to a folder containing a ‘patches.csv’.

Return type:

str

Returns:

Absolute path of the WSI.

read_patch_file(patch_file, slide_path, column=None, level=None)

Read a patch file.

Read lines of the patch csv looking for ‘column’ label.

Parameters:

• patch_file (str) – absolute path to a csv patch file.

• level (Optional[int]) – pyramid level to query patches in the csv.

• slide_path (str) – absolute path to a slide file.

• column (Optional[str]) – header of the column to use to label individual patches.

Yields:

Position and label of patches (x, y, label).

Return type:

Iterator[Tuple[dict, str]]

write_slide_predictions(slide_predictions, slide_csv, column)

Write slide predictions in a pathaia slide csv.

Parameters:

• slide_predictions (Iterator[Patch]) – iterator on patch dicts.

• slide_csv (str) – absolute path to a pathaia slide csv.

• column (str) – name of the prediction column to append in csv.

descriptors_to_csv(descriptors, filename, patch_list)

Write patch embeddings into a csv file.

Parameters:

• descriptors (List[Tuple]) – list of

• filename (str) –

class PathaiaHandler(project_folder, slide_folder)

Bases: object

A class to handle simple patch datasets.

It usually computes the input of tf datasets proposed in pathaia.data.

Parameters:

• project_folder (str) – absolute path to a pathaia project.

• slide_folder (str) – absolute path to a slide folder.

random_split(ratio=0.3)

Split whole slide dataset into training/validation.

Parameters:

ratio (float) – ratio of slides to keep for validation.

Return type:

Tuple[List[Tuple[str, str]], List[Tuple[str, str]]]

Returns:

Training and validation datasets.

list_patches(level, dim, column=None, slides=None)

Create labeled patch dataset.

Parameters:

• level (int) – pyramid level to extract patches in csv.

• dim (Tuple[int, int]) – dimensions of the patches in pixels.

• label – column header in csv to use as a category.

Return type:

Tuple[List[Patch], List[str]]

Returns:

List of patch dicts and list of labels.

extract_features(model_name='ResNet50', slides=None, patch_size=224, level=None, layer='', batch_size=128)

Extract features from patches with a model from keras applications.

paths

Useful functions for handling patches in WSIs.

slides_in_folder(folder, extensions=('.mrxs',))

Return slide files inside a folder for a given extension.

Parameters:

• folder (str) – absolute path to a directory containing slides.

• extension – file extensions of the slides.

Return type:

List[str]

Returns:

List of absolute paths of slide files.

slide_basename(slidepath)

Give the basename of a slide from its absolutepath.

Parameters:

slidepath (str) – absolute path to a slide.

Returns:

basename of the slide.

Return type:

basename

imfiles_in_folder(folder, authorized=('.png', '.jpg', '.jpeg', '.tif', '.tiff'), forbiden=('thumbnail',), randomize=False, datalim=None)

Get image files in a given folder.

Get all image files (selected by file extension). You can remove terms from the research.

Parameters:

• folder (str) – absolute path to an image directory.

• authorized (Sequence[str]) – authorized image file extensions.

• forbiden (Sequence[str]) – non-authorized words in file names.

• randomize (bool) – whether to randomize output list of files.

• datalim (Optional[int]) – maximum number of file to extract in folder.

Return type:

List[str]

Returns:

Absolute paths of image files in folder.

dataset2folders(projfolder, level, randomize=False, slide_data_lim=None)

Link slidenames to their pathaia patch folder.

A pathaia patch folder is named with an int corresponding to the level of patch extraction.

Parameters:

• projfolder (Union[str, PathLike]) – absolute path to a pathaia project folder.

• level (int) – pyramid level of patch extraction to consider.

• randomize (bool) – whether to randomize output list of slides.

• slide_data_lim (Optional[int]) – number of slides to consider in project.

Return type:

Dict[str, str]

Returns:

Dictionary mapping slidenames and absolute paths to patch dirs.

get_files(path, extensions=None, recurse=True, folders=None, followlinks=True)

Find all files in a folder recursively.

Parameters:

• path (Union[str, PathLike]) – Path to input folder.

• extensions (Optional[Sequence[str]]) – list of acceptable file extensions.

• recurse (bool) – whether to perform a recursive search or not.

• folders (Optional[Sequence[str]]) – direct subfolders to explore (if None explore all).

• followlinks (bool) – whether to follow symlinks or not.

Return type:

List[Path]

Returns:

List of all absolute paths to found files.

safe_rmtree(path, ignore_errors=True, erase_tree=None)

Safe version of rmtree that asks for permission before deleting.

Parameters:

• path (Union[str, PathLike]) – path to folder to be deleted.

• ignore_error – whether to ignore errors or not.

• erase_tree (Optional[bool]) – whether to remove tree or not. If None asks for permission.

Return type:

bool

Returns:

True if erase_tree==True or if user gave permission.

types

class Coord(x: Union[int, Iterable], y: Optional[int] = None)

Bases: _CoordBase

An (x, y) tuple representing integer coordinates. If only x is given then takes value (x, x).

class Patch(id, slidename, position, level, size, size_0, parent=None)

Bases: object

id: str

slidename: str

position: Coord

level: int

size: Coord

size_0: Coord

parent: Optional[Patch] = None

classmethod get_fields()

Return type:

List[str]

to_csv_row()

Return type:

Dict[str, Union[str, int]]

classmethod from_csv_row(row, slidename=None)

class Slide(path, backend='openslide')

Bases: object

property dimensions

get_best_level_for_downsample(downsample)

read_region(location, level, size, **kwargs)

get_thumbnail(size)