dicom-modality-predictor 0.1.0
A package to predict DICOM image modalities
Requires Python: >=3.6

# DICOM Modality Predictor

DICOM Modality Predictor is a Python package that predicts the modality of DICOM (Digital Imaging and Communications in Medicine) images using a pre-trained scikit-learn model. It provides functionality to process individual DICOM files, lists of files, and entire directories, with options for sampling and skipping specific folders.

## Features

- Predict modality for individual DICOM files
- Process lists of DICOM file paths
- Analyze entire directories of DICOM files, including nested subdirectories
- Option to sample a subset of files for faster processing of large datasets
- Skip specific folders based on keywords
- Multithreaded processing for improved performance
- Command-line interface for easy use
- Comprehensive error handling and reporting

## Installation

You can install the DICOM Modality Predictor package using pip:

```
pip install dicom-modality-predictor
```

## Usage

### Python API

#### Predicting a Single File

```python
from dicom_modality_predictor import DicomModalityPredictor

predictor = DicomModalityPredictor()
result = predictor.predict_single_file('/path/to/your/dicom/file.dcm')
print(result)
```

#### Predicting a List of Files

```python
from dicom_modality_predictor import DicomModalityPredictor

predictor = DicomModalityPredictor()

dicom_files = [
    '/path/to/file1.dcm',
    '/path/to/file2.dcm',
    '/path/to/file3.dcm',
]

results = predictor.predict_file_list(dicom_files)

for result in results:
    if result['error'] is None:
        print(f"File: {result['filename']}")
        print(f"Predicted Modality: {result['predicted_modality']}")
        print(f"Probability: {result['probability']:.4f}")
    else:
        print(f"Error processing {result['filename']}: {result['error']}")
    print("---")
```

#### Processing a Directory

```python
from dicom_modality_predictor import DicomModalityPredictor
from dicom_modality_predictor.utils import process_anat_folders

predictor = DicomModalityPredictor()

base_path = '/path/to/dicom/folders'
skip_keywords = ['localizer', 'scout', 'symri', 'swi'] # It will skip the folders that include these keywords
sample_size = 20  # Process randomly up to 20 files per folder

results = process_anat_folders(base_path, predictor, sample_size=sample_size, skip_keywords=skip_keywords)

for folder, result in results.items():
    print(f"Folder: {folder}")
    print(f"Predicted Modality: {result['predicted_modality']}")
    print(f"Average Probability: {result['average_probability']:.4f}")
    print(f"Files Processed: {result['files_processed']} / {result['total_files']}")
    print("---")
```

### Command-line Interface

The package also provides a command-line interface for easy use:

```
dicom_modality_predictor /path/to/dicom/folders --sample 20 --skip localizer scout symri swi --output results.json
```

Options:
- `--sample`: Number of DICOM files to sample from each folder
- `--skip`: Keywords to skip folders (can provide multiple)
- `--output`: Path to save the results JSON file
- `--model`: Path to a custom trained model file (optional)

## Customization

### Using a Custom Model

You can use your own trained scikit-learn model by providing the path to the model file:

```python
predictor = DicomModalityPredictor(model_path='/path/to/your/custom_model.pkl')
```

### Adjusting Thread Pool Size

The `predict_file_list` method uses a `ThreadPoolExecutor` for parallel processing. You can adjust the number of worker threads:

```python
results = predictor.predict_file_list(dicom_files, max_workers=4)
```

## Error Handling

The package includes error handling. When processing multiple files, if an error occurs with one file, the package will continue processing the remaining files and include error information in the results.

## Contributing

Contributions to the DICOM Modality Predictor package are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Acknowledgments

- This package uses scikit-learn for the underlying machine learning model.
- The model is trained over KI mri scans.
- DICOM file handling is done using the pydicom library.

## Support

If you encounter any problems or have any questions, please open an issue on the GitHub repository.