Auto-configuration

The auto-configuration is used after the pre-processing to display in the terminal the training hyper-parameters, such as the batch size, the patch size, the augmentation patch size and the number of pooling in the U-Net model. The main function here is biom3d.auto_config.auto_config

Auto-configuration.

This script can be used to compute and display: - the batch size - the patch size - the augmentation patch size - the number of poolings in the 3D U-Net

biom3d.auto_config.auto_config(img_path: str | None = None, median: list[int] | tuple[int] | None = None, max_dims: tuple[int] = (128, 128, 128), max_batch: int = 16, min_batch: int = 2) → tuple[ndarray, ndarray, ndarray, ndarray][source]

Given an image collection, return the batch size, the patch size and the number of pooling.

Provide either an image collection path or a median shape. If a median shape is provided it will not be recomputed and the auto-configuration will be much faster.

Parameters:

  • img_path (str, optional) – Image collection path. If not provided, must give a median shape.

  • median (list or tuple, optional) – Median size of the images in the image collection. If not provided, must give an image path.

  • max_dims (tuple, default=(128,128,128)) – Maximum patch size. The product of max_dims is used to determine the maximum patch size

  • max_batch (int, default=16) – Maximum batch size. Clamp computed batch size if needed.

  • min_batch (int, default=16) – Minimum batch size. Clamp computed batch size if needed.

Raises:

AssertionError – If img_path and median are both None.

Returns:

  • batch (numpy.ndarray) – Batch size.

  • aug_patch (numpy.ndarray) – Augmentation patch size.

  • patch (numpy.ndarray) – Patch size.

  • pool (numpy.ndarray) – Number of pooling.

biom3d.auto_config.compute_median(path: str, return_spacing: bool = False) → ndarray | tuple[ndarray, ndarray][source]

Compute the median shape of a folder of images. If return_spacing is True, then also return the median spacing.

Parameters:

  • path (str) – Folder path.

  • return_spacing (bool) – Whether to return the mean image spacing. Works only for Nifti format.

Raises:

  • AssertionError – If no image is found at path, or size couldn’t be retrieved.

  • AssertionError – If images has inconsistents dimensions

Returns:

  • median (numpy.ndarray) – Median shape of the images in the folder.

  • spacing (numpy.ndarray) – Median spacing of the images in the folder.

biom3d.auto_config.data_fingerprint(img_path: str, msk_path: str | None = None, num_samples: int = 10000, seed: int = 42) → tuple[ndarray, ndarray, float, float, float, float][source]

Compute the data fingerprint.

The fingerprint consist of: - Median size of the images. - Median spacing of the images. - Mean value of the images’ voxels (or pixels). - Standard deviation of the images’ voxels (or pixels). - Percentil 0.5% of the images’ voxels (or pixels) intensity. - Percentil 99.5% of the images’ voxels (or pixels) intensity.

Parameters:

  • img_path (str) – Path to the images collection.

  • msk_path (str, optional) – (Optional) Path to the corresponding collection of masks. If provided the function will compute the mean, the standard deviation, the 0.5% percentile and the 99.5% percentile of the intensity values of the images located inside the masks. If not provide, the function returns zeros for each of these values.

  • num_samples (int, default=10000) – We compute the intensity characteristic on only a sample of the candidate voxels.

  • seed (int, default=42) – (Optional) Random generator seed, is used if msk_path isn’t None.

Raises:

AssertionError | ValueError – If inconsistent number of dimension across dataset.

Returns:

  • median_size (numpy.ndarray) – Median size of the images in the image folder.

  • median_spacing (numpy.ndarray) – Median spacing of the images in the image folder.

  • mean (float) – Mean of the intensities.

  • std (float) – Standard deviation of the intensities.

  • perc_005 (float) – 0.5% percentile of the intensities.

  • perc_995 (float) – 99.5% percentile of the intensities.

biom3d.auto_config.display_info(patch: ndarray, pool: ndarray, batch: ndarray) → None[source]

Print in terminal the patch size, the number of pooling, augmented patch size and the batch size.

The output follow the config file syntaxe and can copied into.

Parameters:

  • patch (numpy.ndarray) – Patch size.

  • pool (numpy.ndarray) – Pool size.

  • batch (numpy.ndarray) – batch size.

Return type:

None

biom3d.auto_config.find_patch_pool_batch(dims: tuple[int] | list[int], max_dims: tuple[int] = (128, 128, 128), max_pool: int = 5, epsilon: float = 0.001) → tuple[ndarray, ndarray, ndarray][source]

Given the median image size, compute the patch size, the number of pooling and the batch size.

The generated patch size is repecting the input dimension proportions. The product of the patch dimensions is lower than the product of the max_dims dimensions.

Parameters:

  • dims (tuple of int or list of int) – A median size of an image dataset.

  • max_dims (tuple, default=(128,128,128)) – Maximum patch size. The product of max_dims is used to determine the maximum patch size

  • max_pool (int, default=5) – Maximum pooling size.

  • epsilon (float, default=1e-3) – Used to reduce the input dimensions if they are too big. Input dimensions will be divided by (1+epsilon) an sufficient number times so they resulting dimensions respect the max_dims limit.

Raises:

  • AssertionError – If dims not in 3D or 4D.

  • AssertionError – If a dimension is negative.

  • AssertionError – If max_pool has at least 1 element that is less than 2 times bigger than an element of max_dims

Returns:

  • patch (numpy.ndarray) – Patch size.

  • pool (numpy.ndarray) – Number of pooling.

  • batch (numpy.ndarray) – Batch size.

biom3d.auto_config.get_aug_patch(patch_size: tuple[int] | list[int] | ndarray) → ndarray[source]

Return augmentation patch size.

The current solution is to use the diagonal of the rectagular cuboid of the patch size, for isotripic images and, for anisotropic images, the diagonal of the rectangle spaned by the non-anisotropic dimensions.

Parameters:

patch_size (tuple, list or numpy.ndarray) – Patch size.

Returns:

aug_patch – Augmentation patch size.

Return type:

numpy.ndarray

biom3d.auto_config.parameters_return(patch: ndarray, pool: ndarray, batch: ndarray, config_path: str, median_spacing: ndarray | None = None) → None[source]

Display the provided parameters.

Parameters:

  • patch (numpy.ndarray) – Patch size.

  • pool (numpy.ndarray) – Pool size.

  • batch (numpy.ndarray) – batch size.

  • config_path (str) – Path to configuration file

  • median_spacing (numpy.ndarray, optional) – Median spacing over the dataset.

Return type:

None