Merge pull request #70 from oncoray/dev2.2.1

Release version 2.2.1

.coveragerc

@@ -0,0 +1,11 @@
+[run]
+concurrency = multiprocessing
+parallel = true
+
+[report]
+exclude_also =
+    raise ValueError
+    raise TypeError
+    raise NotImplementedError
+    raise FileNotFoundError
+    warnings.warn

.github/ISSUE_TEMPLATE/general-issue.md

@@ -0,0 +1,29 @@
+---
+name: Bugs and problems
+about: General issue template
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+Please use the below template to submit your issue:
+
+# Expected behaviour
+
+What did you expect MIRP to do?
+
+# Observed behaviour
+
+What did MIRP actually do? What error (if any) was produced?
+
+# Steps to reproduce the problem
+
+What steps are required to reproduce the problem? If possible, provide code and data that led to the problem.
+
+# Specifications
+
+- MIRP version: 
+- Python version:
+- Operating system:
+- Other package versions (*if relevant*):

.github/ISSUE_TEMPLATE/version-release.md

@@ -12,6 +12,7 @@ assignees: ''
   - [ ] `mirp\docs_source\source\conf.py`
   - [ ] `mirp\conda\meta.yaml` (if build for conda)
 - [ ] Check that all unit tests successfully pass.
+  - [ ] Run `python -m pytest test`
 - [ ] Update `NEWS.md`.
 - [ ] Update `README.md` if required.
 - [ ] Check long-form documentation locally.
@@ -34,9 +35,9 @@ assignees: ''
   - [ ] Check package on testPyPI:
 	- [ ] Check landing page for obvious errors.
 	- [ ] Create virtual environment or temporary conda environment
-	- [ ] Install mirp: `pip install mirp --index-url https://test.pypi.org/mirp/ --no-deps
+	- [ ] Install mirp: `pip install mirp --index-url https://test.pypi.org/mirp/ --no-deps`
   - [ ] Upload package to PyPI:
-    - [ ] Run `python -m twine upload dist\*
+    - [ ] Run `python -m twine upload dist\*`
 	- [ ] username: `__token__`
 	- [ ] password: pypi API token
 - [ ] Merge with main branch.

.github/workflows/auto-test-package_pull.yml

@@ -0,0 +1,31 @@
+# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+
+name: Run automated tests on multiple platforms
+
+on: [pull_request, workflow_dispatch]
+
+jobs:
+  build:
+
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [ "3.10", "3.11"]
+        os: [ ubuntu-latest, macos-latest, windows-latest ]
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install .
+        python -m pip install .[test]
+    - name: Test with pytest
+      run: |
+        python -m pytest -m ci test

.gitignore

@@ -11,3 +11,7 @@ test/data/temp
 docs_source/build/*
 test/data/configuration_files/settings.xml
 /test/data/temp_data/
+.coverage
+/docs_source/source/.ipynb_checkpoints
+/docs_source/source/sts_images
+/prof

CONTRIBUTING.md

@@ -1,16 +1,18 @@
-# How to contribute
+# Contributing
 
-If you have ideas or code to contribute, please first open an [issue](https://github.com/oncoray/mirp/issues). We will then discuss your ideas and create an implementation roadmap.
+IRP is open-source software, hosted on [GitHub](https://github.com/oncoray/mirp). Contributions that enable
+new DICOM modalities are especially welcome! If you have ideas or code to contribute, please first open an
+`issue <https://github.com/oncoray/mirp/issues>`_ and describe your ideas.
 
-Please keep the following in mind when contributing:
+Technical documentation is forthcoming. For now, please keep the following in mind when contributing:
 
 - The main branch of `mirp` is protected. You can therefore make a pull request for your contribution to a 
   development branch of the intended future version.
-- If you introduce new functionality, this functionality should be tested as part of the tests in the `test`directory. 
+- If you introduce new functionality, this functionality should be tested as part of the tests in the `test` directory. 
   After implementation, please ensure that all tests complete without errors by running `pytest` from your IDE or 
   console using `python -m pytest test` from the mirp main directory.  
 - Code is styled according to [PEP8](https://peps.python.org/pep-0008/). Using a linter or IDE with automated linter 
   is recommended.
 - Function, class and method documentation is done using Numpy-flavoured [docstrings](https://numpydoc.readthedocs.io/en/latest/format.html).
   [Long-form documentation](https://oncoray.github.io/mirp/) is partially created from function, class and method 
-  documentation, embedded in restructured text files in `docs_source`.
+  documentation, embedded in restructured text files in the `docs_source` directory.

NEWS.md

@@ -1,3 +1,31 @@
+# Version 2.2.1
+
+## Minor changes
+
+- If mask-related parameters are not provided for computing features or processing of images for deep learning, a 
+  mask is generated that covers the entire image.
+
+- Add fall-back methods for missing installation of the `ray` package for parallel processing. This can happen when 
+  a python version is not supported by the `ray` package. `ray` is now a conditional dependency, until that package 
+  is released for python `3.12`.
+
+- The default export format for `deep_learning_processing` and `deep_learning_processing_generator` is now `dict`, 
+  because the sample name is important for matching against observed outcomes.
+
+- `write_file` arguments of `extract_mask_labels` and `extract_image_parameters` were deprecated as these were 
+  redundant.
+
+## Fixes
+
+- Streamlined importing and reading DICOM files results in faster processing of DICOM-based imaging.
+
+- Fixed an indexing issue when attempting to split masks into bulk and rim sections in a slice-wise fashion.
+
+- Fixed an indexing issue in Rank's method for noise estimation.
+
+- Fixed incorrectly named image parameters file export. Instead of `mask_labels.csv`, image parameters are now 
+  correctly exported to `image_metadata.csv`.
+
 # Version 2.2.0
 
 ## Major changes

README.md

@@ -2,13 +2,36 @@
 
 # Medical Image Radiomics Processor
 
-Medical Image Radiomics Processor (MIRP) is an IBSI-compliant python package for medical image analysis.
-MIRP focuses on radiomics applications and supports computation of features for conventional radiomics
-and image processing for deep-learning applications.
+Medical Image Radiomics Processor (MIRP) is a python package for medical image analysis that is compliant with the 
+reference standards of the Image Biomarker Standardisation Initiative (IBSI). MIRP focuses on radiomics applications 
+and supports computation of features for conventional radiomics and image processing for deep-learning applications.
 
-## Documentation
+## Documentation and tutorials
 
-Documentation can be found here: https://oncoray.github.io/mirp/
+Documentation and tutorials can be found here: https://oncoray.github.io/mirp/
+
+## Supported Python and OS
+
+MIRP currently supports the following Python versions and operating systems: 
+
+| Python | Linux     | Win       | OSX       |
+|--------|-----------|-----------|-----------|
+| 3.10   | Supported | Supported | Supported |
+| 3.11   | Supported | Supported | Supported |
+
+## Supported imaging and mask modalities
+
+MIRP currently supports the following image modalities:
+
+| File format | File type | Supported modality |
+|-------------|-----------|--------------------|
+| DICOM       | image     | CT, MR, PT, RTDOSE |
+| DICOM       | mask      | RTSTRUCT, SEG      |
+| NIfTI       | any       | any                |
+| NRRD        | any       | any                |
+| numpy       | any       | any                |
+
+NIfTI, NRRD, and numpy files support any kind of (single-channel) image. MIRP cannot process RGB or 4D images.
 
 ## Installing MIRP
 MIRP is available from PyPI and can be installed using `pip`, or other installer tools:
@@ -17,39 +40,6 @@ MIRP is available from PyPI and can be installed using `pip`, or other installer
 pip install mirp
 ```
 
-## Transitioning to version 2
-
-Version 2 is a major refactoring of the previous code base. For users this brings the following noticeable changes:
-
-- MIRP was previously configured using two `xml` files: [`config_data.xml`](mirp/config_data.xml) for configuring
-  directories, data to be read, etc., and [`config_settings.xml`](mirp/config_settings.xml) for configuring experiments.
-  While these two files can still be used, MIRP can now be configured directly, without using these files.
-- The main functions of MIRP (`mainFunctions.py`) have all been re-implemented.
-  - `mainFunctions.extract_features` is now `extract_features` (functional form) or
-    `extract_features_generator` (generator). The replacements allow for both writing
-    feature values to a directory and returning them as function output. 
-  - `mainFunctions.extract_images_to_nifti` is now `extract_images` (functional form) or
-     `extract_images_generator` (generator). The replacements allow for both writing 
-     images to a directory (e.g., in NIfTI or numpy format) and returning them as function output.
-  - `mainFunctions.extract_images_for_deep_learning` has been replaced by 
-    `deep_learning_preprocessing` (functional form) and 
-    `deep_learning_preprocessing_generator` (generator).
-  - `mainFunctions.get_file_structure_parameters` and `mainFunctions.parse_file_structure` are deprecated, as the
-    the file import system used in version 2 no longer requires a rigid directory structure.
-  - `mainFunctions.get_roi_labels` is now `extract_mask_labels`.
-  - `mainFunctions.get_image_acquisition_parameters` is now `extract_image_parameters`.
-
-For advanced users and developers, the following changes are relevant:
-- MIRP previously relied on `ImageClass` and `RoiClass` objects. These have been completely replaced by `GenericImage`
-  (and its subclasses, e.g. `CTImage`) and `BaseMask` objects, respectively. New image modalities can be added as
-  subclass of `GenericImage` in the `mirp.images` submodule.
-- File import, e.g. from DICOM or NIfTI files, in version 1 was implemented in an ad-hoc manner, and required a rigid
-  directory structure. Since version 2, file import is implemented using an object-oriented approach, and directory
-  structures are more flexible. File import of new modalities can be implemented as a relevant subclass of `ImageFile`.
-- MIRP uses type hinting, and makes use of the `Self` type hint introduced in Python 3.11. MIRP 
-  therefore requires Python 3.11 or later.
-- MIRP now uses the `ray` package for parallel processing.
-
 ## Examples - Computing Radiomics Features
 
 MIRP can be used to compute quantitative features from regions of interest in images in an IBSI-compliant manner 
@@ -155,6 +145,37 @@ mask_labels = extract_mask_labels(
 )
 ```
 
+## Transitioning to version 2
+
+Version 2 is a major refactoring of the previous code base. For users this brings the following noticeable changes:
+
+- MIRP was previously configured using two `xml` files: [`config_data.xml`](mirp/config_data.xml) for configuring
+  directories, data to be read, etc., and [`config_settings.xml`](mirp/config_settings.xml) for configuring experiments.
+  While these two files can still be used, MIRP can now be configured directly, without using these files.
+- The main functions of MIRP (`mainFunctions.py`) have all been re-implemented.
+  - `mainFunctions.extract_features` is now `extract_features` (functional form) or
+    `extract_features_generator` (generator). The replacements allow for both writing
+    feature values to a directory and returning them as function output. 
+  - `mainFunctions.extract_images_to_nifti` is now `extract_images` (functional form) or
+     `extract_images_generator` (generator). The replacements allow for both writing 
+     images to a directory (e.g., in NIfTI or numpy format) and returning them as function output.
+  - `mainFunctions.extract_images_for_deep_learning` has been replaced by 
+    `deep_learning_preprocessing` (functional form) and 
+    `deep_learning_preprocessing_generator` (generator).
+  - `mainFunctions.get_file_structure_parameters` and `mainFunctions.parse_file_structure` are deprecated, as the
+    the file import system used in version 2 no longer requires a rigid directory structure.
+  - `mainFunctions.get_roi_labels` is now `extract_mask_labels`.
+  - `mainFunctions.get_image_acquisition_parameters` is now `extract_image_parameters`.
+
+For advanced users and developers, the following changes are relevant:
+- MIRP previously relied on `ImageClass` and `RoiClass` objects. These have been completely replaced by `GenericImage`
+  (and its subclasses, e.g. `CTImage`) and `BaseMask` objects, respectively. New image modalities can be added as
+  subclass of `GenericImage` in the `mirp.images` submodule.
+- File import, e.g. from DICOM or NIfTI files, in version 1 was implemented in an ad-hoc manner, and required a rigid
+  directory structure. Since version 2, file import is implemented using an object-oriented approach, and directory
+  structures are more flexible. File import of new modalities can be implemented as a relevant subclass of `ImageFile`.
+- MIRP now uses the `ray` package for parallel processing.
+
 # Citation info
 A publication for MIRP is forthcoming. For now, please cite the following work:
 ```Zwanenburg A, Leger S, Agolli L, Pilz K, Troost EG, Richter C, Löck S. Assessing robustness of radiomic features by image perturbation. Scientific reports. 2019 Jan 24;9(1):614.```

docs/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 17cbf7e65c49e001bf222ac3d01664cc
+config: 9361bdd63c38ffe1be89d15a43241fd1
 tags: 645f666f9bcd5a90fca523b33c5a78b7