Metadata-Version: 2.4
Name: dice-score-3d
Version: 1.1.1
Summary: Utility for calculating the Dice Similarity Coefficient (DSC) for 3D segmentation masks.
Author-email: George Stoica <58839912+ancestor-mithril@users.noreply.github.com>
Maintainer-email: George Stoica <58839912+ancestor-mithril@users.noreply.github.com>
License: MIT License
        
        Copyright (c) 2024 ancestor-mithril
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Repository, https://github.com/ancestor-mithril/dice-score-3d
Project-URL: Issues, https://github.com/ancestor-mithril/dice-score-3d/issues
Keywords: image segmentation,dice similarity coefficient,dice score
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Healthcare Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: SimpleITK
Requires-Dist: tqdm
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Dynamic: license-file

# dice-score-3d
Utility for calculating the Dice Similarity Coefficient (DSC) for 3D segmentation masks. Writes the results in a csv or json file and can be used both from the terminal or from a Python script. 
Calculates per-case mean Dice and weighted mean Dice, and per-label mean Dice, weighted mean Dice and Global Dice. The Global Dice for a label is the Dice Score calculated as if all the cases are concatenated into a single big case, aiming to balance out cases in which the Dice Score is 0 but have very few FP voxels or cases in which the Dice Score is 1 but have no positive voxels.

## Installation

```
pip install --upgrade dice-score-3d
```

## Usage

Simple usage (Python):
```py
from dice_score_3d import dice_metrics

results_dict = dice_metrics(gt_dir, pred_dir, output_path=None, indices={'lung': 1, 'heart': 2}, suffix='.nii.gz')
# Write to csv: 
dice_metrics(gt_dir, pred_dir, output_path='results.csv',  indices={'lung': 1, 'heart': 2}, suffix='.nii.gz', num_workers=8)
```

Simple usage (terminal):
```
dice_score_3d GT.nii.gz PRED.nii.gz -output results.json -indices "{'lung': 1, 'heart': 2}" --console
dice_score_3d GT.nii.gz PRED.nii.gz -output results.json -indices indices.json
```

Complete documentation:
```
usage: dice_score_3d [-h] -output OUTPUT -indices INDICES [--reorient] [-dtype {uint8,uint16}] [-prefix PREFIX] [-suffix SUFFIX] [-num_workers NUM_WORKERS] [--console]
                     ground_truths predictions

DICE Score 3D

positional arguments:
  ground_truths         Path to Ground Truth. Can be a single file or a folder with all the GT volumes. The number of GT files must match the number of predictions. When passing a     
                        folder of GT files, the name of the GT files must match the name of the predictions. This is not applicable when passing a single file. Supported file
                        formats: .nii, .nii.gz, .nrrd, .mha, .gipl.
  predictions           Path to Ground Truth. Can be a single file or a folder with all the predicted volumes. The number of prediction files must match the number of GT files. When   
                        passing a folder of prediction files, the name of the prediction files must match the name of the GT files. This is not applicable when passing a single file.  
                        Supported file formats: .nii, .nii.gz, .nrrd, .mha, .gipl.

options:
  -h, --help            show this help message and exit
  -output OUTPUT        The output path to write the computed metrics. Can be a csv or json file, depending on extension. Example: "results.csv", "results.json".
  -indices INDICES      Path to the json file describing the indices used for calculating the Dice Similarity Coefficient. Can also be a json string. Only the indices present in the   
                        json are considered when evaluating the Dice Score. Example: "{"lung_left": 1, "lung_right": 2}".
  --reorient            Reorients both the GT and the prediction to the default "LPS" orientation before calculating the Dice Score.
  -dtype {uint8,uint16}
                        Must be either "uint8" when having less than 255 classes, or "uint16" otherwise. Default: uint8.
  -prefix PREFIX        This parameter is used when the ground truth path is a folder. It filters all the files in the folder and selects only the files with this prefix.
  -suffix SUFFIX        This parameter is used when the ground truth path is a folder. It filters all the files in the folder and selects only the files with this suffix. Default: .nii.gz.
  -num_workers NUM_WORKERS
                        Number of parallel processes to be used to calculate the Dice Score in parallel. Default: 0.
  --console             Also prints the Dice metrics to console.
  --ignore_gt_size      Allows the presence of additional GT files in the GT folder.
```
