<!---[](https://pypi.org/project/frd-score/)--->
# Fréchet Radiomics Distance (FRD)
This repository contains code implementing the FRD, proposed in [Towards Learning Contrast Kinetics with Multi-Condition Latent Diffusion Models](https://arxiv.org/abs/2403.13890).
FRD measures similarity of radiomics features between two datasets.
<img src="docs/frd.png" alt="frd overview" width="400"/>
The lower the FRD, the more similar the datasets are in terms of radiomics features.
FRD is applicable to both _3D_ (nii.gz) and _2D_ (png, jpg, tiff) radiological images.
It is calculated by computing the [Fréchet distance](https://en.wikipedia.org/wiki/Fr%C3%A9chet_distance) between two Gaussians fitted to the extracted and normalized radiomics features.
In general, the variability (e.g. measured via FRD) of imaging biomarkers (e.g. radiomics features) between two datasets (e.g. a real and a synthetic dataset) can be interpreted as quality/utility metric (e.g. of a synthetic dataset).
## Installation
<!--- Install from [pip](https://pypi.org/project/frd-score/): --->
Install frd:
```
pip install frd-score
```
Requirements:
- python3
- pyradiomics
- SimpleITK
- pillow
- numpy
- opencv_contrib_python_headless
- scipy
## Usage
### Run via CLI:
To compute the FID score between two datasets, where images of each dataset are contained in an individual folder:
```
python -m frd_score path/to/dataset_A path/to/dataset_B
```
If you would like to use masks to localize radiomics features, you can provide the path to the masks as follows:
```
python -m frd_score path/to/dataset_A path/to/dataset_B -M path/to/mask_A path/to/mask_B
```
### Run in your code:
If you would like to import frd as a module, you can use the following code snippet:
```
from frd_score import frd
paths=['path/to/dataset_A', 'path/to/dataset_B']
# optionally, use masks.
paths_masks=[path_mask_A, path_mask_B]
frd_value = frd.compute_frd(paths, paths_masks=paths_masks)
```
Instead of providing the path to a folder, you may also directly provide a list to image paths (and/or masks).
```
img_paths_A = ['path/to/image1', 'path/to/image2']
img_paths_B = ['path/to/image3', 'path/to/image4']
paths=[img_paths_A, img_paths_B]
frd_value = frd.compute_frd(paths)
```
## Additional arguments
`--paths_masks` or `-M`: The two paths to the masks of the two datasets. The masks should have the same dimensions as the images. The masks should be binary images, where the region of interest is white (pixel value 255) and the background is black (pixel value 0). Masks are used to localize radiomics features.
`--feature_groups` or `-f`: You may define a subset of [radiomics features](https://pyradiomics.readthedocs.io/en/latest/customization.html#enabled-features) to calulate the FRD. Currently, a list of all features is used as default, i.e. `firstorder`, `glcm`, `glrlm`, `gldm`, `glszm`, `ngtdm`, `shape`, `shape2D`
`--norm_range` or `-R`: The allowed value range of features in format `[min, max]`. Based on these values the frd features will be normalized. For comparability with FID, the default is `[0, 7.45670747756958]` which is an observed range for features of the Inception classifier in [FID](https://arxiv.org/abs/1706.08500).
`--norm_type` or `-T`: The strategy with which the frd features will be normalized. Can be `minmax` or `zscore`.
`--norm_across` or `-A`: If set, indicates that normalization will be computed on all features from both datasets (e.g. synthetic, real) instead of on the features of each dataset separately.
`--resize_size` or `-r`: You may indicate an integer here to resize the x and y pixel/voxel dimensions of the input images (and masks) using `cv2.INTER_LINEAR` interpolation. For example `resize_size=512` will resize an image of dims of e.g. `(224, 244, 120)` to `(512, 512, 120)`.
`--save_features` or `-F`: Indicates whether radiomics feature values (normalized and non-normalized) should be stored in a csv file in the parent dir of `path/to/dataset_A`. This can be useful for reproducibility and interpretability.
`--verbose` or `-v`: You may enable more detailed logging.info and logging.debug console logs by providing the `verbose` argument.
`--num_workers` or `-w`: The number of cpu workers used for multiprocessing during feature extraction. If set to None, then the system's number of available cpu cores minus 2 will be taken as default (1 is the minimum value for num_workers).
`--save-stats` or `-s`:
As in [pytorch-fid](https://github.com/mseitzer/pytorch-fid), you can generate a compatible `.npz` archive of a dataset using the `--save-stats` flag.
You may use the `.npz` archive as dataset path, which can be useful to compare multiple models against an original dataset without recalculating the statistics multiple times.
```
python -m frd_score --save-stats path/to/dataset path/to/npz_outputfile
```
## Citing
If you use this repository in your research, consider citing it using the following Bibtex entry:
```
@article{osuala2024towards,
title={{Towards Learning Contrast Kinetics with Multi-Condition Latent Diffusion Models}},
author={Osuala, Richard and Lang, Daniel and Verma, Preeti and Joshi, Smriti and Tsirikoglou, Apostolia and Skorupko, Grzegorz and Kushibar, Kaisar and Garrucho, Lidia and Pinaya, Walter HL and Diaz, Oliver and others},
journal={arXiv preprint arXiv:2403.13890},
year={2024}
```
## Acknowledgements
An initial implementation was provided by [Preeti Verma](https://github.com/preeti-verma8600).
This repository borrows code from the [pytorch-fid](https://github.com/mseitzer/pytorch-fid) repository, the official pytorch implementation of the [Fréchet Inception Distance](https://arxiv.org/abs/1706.08500).
Raw data
{
"_id": null,
"home_page": "https://github.com/RichardObi/frd-score",
"name": "frd-score",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "Radiomics, Frechet, Distance, medical, imaging, radiology, generative, synthetic, evaluation",
"author": "Richard Osuala, Preeti Verma",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/a1/cf/72705db1154e8e499ac06a7b98541bc89c41dfeade768211e8fc7e7b72f3/frd_score-0.0.1.tar.gz",
"platform": null,
"description": "<!---[](https://pypi.org/project/frd-score/)--->\n\n# Fr\u00e9chet Radiomics Distance (FRD)\n\nThis repository contains code implementing the FRD, proposed in [Towards Learning Contrast Kinetics with Multi-Condition Latent Diffusion Models](https://arxiv.org/abs/2403.13890).\n\nFRD measures similarity of radiomics features between two datasets. \n\n<img src=\"docs/frd.png\" alt=\"frd overview\" width=\"400\"/>\n\nThe lower the FRD, the more similar the datasets are in terms of radiomics features.\n\nFRD is applicable to both _3D_ (nii.gz) and _2D_ (png, jpg, tiff) radiological images.\n\nIt is calculated by computing the [Fr\u00e9chet distance](https://en.wikipedia.org/wiki/Fr%C3%A9chet_distance) between two Gaussians fitted to the extracted and normalized radiomics features.\n\nIn general, the variability (e.g. measured via FRD) of imaging biomarkers (e.g. radiomics features) between two datasets (e.g. a real and a synthetic dataset) can be interpreted as quality/utility metric (e.g. of a synthetic dataset).\n\n## Installation\n\n<!--- Install from [pip](https://pypi.org/project/frd-score/): --->\nInstall frd:\n\n```\npip install frd-score\n```\n\nRequirements:\n- python3\n- pyradiomics\n- SimpleITK\n- pillow\n- numpy\n- opencv_contrib_python_headless\n- scipy\n\n## Usage\n\n### Run via CLI:\n\nTo compute the FID score between two datasets, where images of each dataset are contained in an individual folder:\n```\npython -m frd_score path/to/dataset_A path/to/dataset_B\n```\n\nIf you would like to use masks to localize radiomics features, you can provide the path to the masks as follows:\n```\npython -m frd_score path/to/dataset_A path/to/dataset_B -M path/to/mask_A path/to/mask_B\n```\n\n### Run in your code:\nIf you would like to import frd as a module, you can use the following code snippet:\n```\nfrom frd_score import frd\n\npaths=['path/to/dataset_A', 'path/to/dataset_B']\n\n# optionally, use masks.\npaths_masks=[path_mask_A, path_mask_B] \n\nfrd_value = frd.compute_frd(paths, paths_masks=paths_masks) \n```\n\nInstead of providing the path to a folder, you may also directly provide a list to image paths (and/or masks).\n```\nimg_paths_A = ['path/to/image1', 'path/to/image2']\nimg_paths_B = ['path/to/image3', 'path/to/image4']\n\npaths=[img_paths_A, img_paths_B]\n\nfrd_value = frd.compute_frd(paths) \n```\n\n## Additional arguments\n \n`--paths_masks` or `-M`: The two paths to the masks of the two datasets. The masks should have the same dimensions as the images. The masks should be binary images, where the region of interest is white (pixel value 255) and the background is black (pixel value 0). Masks are used to localize radiomics features.\n\n`--feature_groups` or `-f`: You may define a subset of [radiomics features](https://pyradiomics.readthedocs.io/en/latest/customization.html#enabled-features) to calulate the FRD. Currently, a list of all features is used as default, i.e. `firstorder`, `glcm`, `glrlm`, `gldm`, `glszm`, `ngtdm`, `shape`, `shape2D` \n\n`--norm_range` or `-R`: The allowed value range of features in format `[min, max]`. Based on these values the frd features will be normalized. For comparability with FID, the default is `[0, 7.45670747756958]` which is an observed range for features of the Inception classifier in [FID](https://arxiv.org/abs/1706.08500). \n\n`--norm_type` or `-T`: The strategy with which the frd features will be normalized. Can be `minmax` or `zscore`.\n\n`--norm_across` or `-A`: If set, indicates that normalization will be computed on all features from both datasets (e.g. synthetic, real) instead of on the features of each dataset separately.\n\n`--resize_size` or `-r`: You may indicate an integer here to resize the x and y pixel/voxel dimensions of the input images (and masks) using `cv2.INTER_LINEAR` interpolation. For example `resize_size=512` will resize an image of dims of e.g. `(224, 244, 120)` to `(512, 512, 120)`.\n\n`--save_features` or `-F`: Indicates whether radiomics feature values (normalized and non-normalized) should be stored in a csv file in the parent dir of `path/to/dataset_A`. This can be useful for reproducibility and interpretability.\n\n`--verbose` or `-v`: You may enable more detailed logging.info and logging.debug console logs by providing the `verbose` argument.\n\n`--num_workers` or `-w`: The number of cpu workers used for multiprocessing during feature extraction. If set to None, then the system's number of available cpu cores minus 2 will be taken as default (1 is the minimum value for num_workers).\n\n`--save-stats` or `-s`:\nAs in [pytorch-fid](https://github.com/mseitzer/pytorch-fid), you can generate a compatible `.npz` archive of a dataset using the `--save-stats` flag. \nYou may use the `.npz` archive as dataset path, which can be useful to compare multiple models against an original dataset without recalculating the statistics multiple times.\n```\npython -m frd_score --save-stats path/to/dataset path/to/npz_outputfile\n```\n\n\n## Citing\n\nIf you use this repository in your research, consider citing it using the following Bibtex entry:\n```\n@article{osuala2024towards,\n title={{Towards Learning Contrast Kinetics with Multi-Condition Latent Diffusion Models}},\n author={Osuala, Richard and Lang, Daniel and Verma, Preeti and Joshi, Smriti and Tsirikoglou, Apostolia and Skorupko, Grzegorz and Kushibar, Kaisar and Garrucho, Lidia and Pinaya, Walter HL and Diaz, Oliver and others},\n journal={arXiv preprint arXiv:2403.13890},\n year={2024}\n```\n\n## Acknowledgements\n\nAn initial implementation was provided by [Preeti Verma](https://github.com/preeti-verma8600).\n\nThis repository borrows code from the [pytorch-fid](https://github.com/mseitzer/pytorch-fid) repository, the official pytorch implementation of the [Fr\u00e9chet Inception Distance](https://arxiv.org/abs/1706.08500).\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Package for calculating Fr\u00e9chet Radiomics Distance (FRD)",
"version": "0.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/RichardObi/frd-score/issues",
"Download": "https://github.com/RichardObi/frd-score/archive/refs/tags/v.0.0.1.tar.gz",
"Homepage": "https://github.com/RichardObi/frd-score"
},
"split_keywords": [
"radiomics",
" frechet",
" distance",
" medical",
" imaging",
" radiology",
" generative",
" synthetic",
" evaluation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a1cf72705db1154e8e499ac06a7b98541bc89c41dfeade768211e8fc7e7b72f3",
"md5": "a9d0871115c2e76db0dc0d11feeff222",
"sha256": "e6ea0fef533790bc285a735c95dfa271f4fe62b2ea19b68df296f1db48e46406"
},
"downloads": -1,
"filename": "frd_score-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "a9d0871115c2e76db0dc0d11feeff222",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 23445,
"upload_time": "2024-05-01T12:30:28",
"upload_time_iso_8601": "2024-05-01T12:30:28.915560Z",
"url": "https://files.pythonhosted.org/packages/a1/cf/72705db1154e8e499ac06a7b98541bc89c41dfeade768211e8fc7e7b72f3/frd_score-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-01 12:30:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "RichardObi",
"github_project": "frd-score",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "frd-score"
}
JSON
