Merge pull request #125 from jjjermiah/development

Development

.github/workflows/main.yml

@@ -4,7 +4,7 @@ name: CI-CD
 on:
   push:
     # push to any branch *
-    branches: [ "*"]
+    branches: [ "*" ]
   pull_request:
     branches: [ main , development]
 
@@ -13,8 +13,10 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
+        # os: [ubuntu-latest]
+        # python-version: ["3.12"]
         os: [ubuntu-latest, macos-latest, macos-14]
-        python-version: ["3.12", "3.11"] # "3.10",
+        python-version: ["3.12", "3.11"]
 
     steps:
       - uses: actions/checkout@v3
@@ -133,6 +135,12 @@ jobs:
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
 
+    - name: Test Outputs of semantic release step
+      run: |
+        echo "${{ steps.release.outputs.released }}"
+        echo "${{ steps.release.outputs.version }}"
+        echo "${{ steps.release.outputs.tag }}"
+
     - name: Install packaging-related tool
       run:
         python3 -m pip install build twine
@@ -145,9 +153,8 @@ jobs:
     - name: Build package
       if: steps.release.outputs.released == 'true'
       run: |
-        poetry version $(git describe --tags --abbrev=0 | sed 's/^v//')
+        poetry version ${{ steps.release.outputs.version }}
         python -m build --sdist --wheel --outdir dist/ .
-        echo "LATEST_TAG=$(poetry version | sed 's/^nbiatoolkit //')" >> "$GITHUB_ENV"
 
     - name: Publish package distributions to PyPI
       if: steps.release.outputs.released == 'true'
@@ -157,23 +164,6 @@ jobs:
         user: __token__
         password: ${{ secrets.PYPI_API_TOKEN }}
 
-    - name: Print branch name
-      run: |
-        printf "LATEST TAG: %s\n" "${LATEST_TAG}"
-        echo "DOCKER_IMAGE_TAG=${LATEST_TAG}" >> "$GITHUB_ENV"
-        printf "DOCKER_IMAGE_TAG: %s\n" "${DOCKER_IMAGE_TAG}"
-
-    - name: Print outputs from semantic release
-      run: |
-        # Semantic release gha provides the following outputs:
-        # - released: true if a new release was created, false otherwise
-        # - version: the new version number
-        # - tag: The Git tag that was created
-        echo "${{ steps.release.outputs.released }}"
-        echo "${{ steps.release.outputs.version }}"
-        echo "${{ steps.release.outputs.tag }}"
-        echo "${{ steps.release.outputs.release_notes }}"
-
     - name: Set up QEMU
       if: steps.release.outputs.released == 'true'
       uses: docker/setup-qemu-action@v3
@@ -202,8 +192,8 @@ jobs:
       uses: docker/metadata-action@v3
       with:
         images: |
-          ${{ secrets.DOCKERHUB_USERNAME }}/nbiatoolkit:${{ env.DOCKER_IMAGE_TAG }}
-          ghcr.io/${{ github.repository }}/nbiatoolkit:${{ env.DOCKER_IMAGE_TAG }}
+          ${{ secrets.DOCKERHUB_USERNAME }}/nbiatoolkit:${{ steps.release.outputs.tag }}
+          ghcr.io/${{ github.repository }}/nbiatoolkit:${{ steps.release.outputs.tag }}
 
     - name: Build
       if: steps.release.outputs.released == 'true'
@@ -214,9 +204,9 @@ jobs:
         file: ./Dockerfile
         push: true
         tags: |
-          ${{ secrets.DOCKERHUB_USERNAME }}/nbiatoolkit:${{ env.DOCKER_IMAGE_TAG }}
+          ${{ secrets.DOCKERHUB_USERNAME }}/nbiatoolkit:${{ steps.release.outputs.tag }}
           ${{ secrets.DOCKERHUB_USERNAME }}/nbiatoolkit:latest
-          ghcr.io/${{ github.repository }}/nbiatoolkit:${{ env.DOCKER_IMAGE_TAG }}
+          ghcr.io/${{ github.repository }}/nbiatoolkit:${{ steps.release.outputs.tag }}
           ghcr.io/${{ github.repository }}/nbiatoolkit:latest
         labels: ${{ steps.meta.outputs.labels }}
 
@@ -226,7 +216,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest, macos-14]
-        python-version: ["3.12", "3.11"]
+        python-version: ["3.12", "3.11", "3.10"]
 
     steps:
       - uses: actions/checkout@v3
@@ -251,15 +241,9 @@ jobs:
 
       - name: Test Image With new Tag
         run: |
-          # get latest tag
-          LATEST_TAG=$(curl -s \
-            "https://api.github.com/repos/${{ github.repository }}/releases/latest" \
-            | jq -r .tag_name | sed 's/^v//')
-          echo "LATEST_TAG=${LATEST_TAG}"
-
           # test image with latest tag
           docker run --rm \
-            ${{ secrets.DOCKERHUB_USERNAME }}/nbiatoolkit:${LATEST_TAG} \
+            ${{ secrets.DOCKERHUB_USERNAME }}/nbiatoolkit:${{ steps.release.outputs.tag }} \
             NBIAToolkit
 
 
@@ -279,7 +263,7 @@ jobs:
   Update-README:
     needs: Continuous-Deployment
     runs-on: ubuntu-latest
-    # if: github.ref == 'refs/heads/development'
+    # if: jobs.Continuous-Deployment.outputs.released == 'true'
     steps:
       - name: Checkout code
         uses: actions/checkout@v3

.gitignore

@@ -157,3 +157,5 @@ src/nbiatoolkit/.DS_Store
 .vscode
 download.ipynb
 driver*.py
+logs
+logdir

.pre-commit-config.yaml

@@ -1,10 +1,11 @@
 repos:
 -   repo: https://github.com/psf/black
-    rev: 22.10.0
+    rev: 24.2.0
     hooks:
     -   id: black
+
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v3.2.0
+    rev: v4.5.0
     hooks:
     -   id: trailing-whitespace
     -   id: end-of-file-fixer

README.md

@@ -37,7 +37,7 @@
   - ***Validate doownloads with MD5 checksums*** for downloaded images
   - **Auto-sort** DICOM files using a user-defined pattern of DICOM tags with specialized ***DICOMSorter class***
 
-
+![SequenceDiagram](https://www.mermaidchart.com/raw/ce7f489f-bf58-4827-aedb-e379ed7bffd3?theme=dark&version=v0.1&format=svg)
 
 ## Installation
 
@@ -85,10 +85,10 @@ For quick access to the NBIA, the toolkit also provides a command line interface
       /  |/ / __  |/ // /| | / / / __ \/ __ \/ / //_/ / __/
      / /|  / /_/ // // ___ |/ / / /_/ / /_/ / / ,< / / /_
     /_/ |_/_____/___/_/  |_/_/  \____/\____/_/_/|_/_/\__/
-    
+
 Version: 0.33.0
 
-Available CLI tools: 
+Available CLI tools:
 
 getCollections [-h] [-u USERNAME] [-pw PASSWORD] [-p PREFIX]
                [-o OUTPUTFILE] [--version]

docs/conf.py

@@ -15,6 +15,11 @@
 copyright = "2023, Jermiah Joseph"
 author = "Jermiah Joseph"
 
+import nbiatoolkit
+
+# The full version, including alpha/beta/rc tags
+release: str = nbiatoolkit.__version__
+
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
@@ -28,6 +33,7 @@
     "sphinx.ext.viewcode",
     "sphinx_tabs.tabs",
     "sphinx_exec_code",
+    "sphinx.ext.autosectionlabel",
 ]
 autoapi_dirs = ["../src/nbiatoolkit"]
 

docs/download_api/DownloadSeries.rst

@@ -0,0 +1,77 @@
+Download Series
+^^^^^^^^^^^^^^
+
+
+The :meth:`downloadSeries` method is used to download an entire SeriesInstanceUID
+from the NBIA Database.
+
+One of the features provided by the `nbiatoolkit` is the ability to configure
+the folder structure of the downloaded files. This functionality is handled internally
+by the `DICOMSorter` class.
+
+Configuration of the folder structure is done by passing a **`filePattern`** argument to the
+:meth:`downloadSeries` method. The **`filePattern`** argument is a string constructed from
+tags in the DICOM header. Tags are enclosed in `%` characters. For example, the following
+**`filePattern`** string:
+
+.. code-block:: python
+
+    filePattern = '%PatientID/%StudyInstanceUID/%SeriesInstanceUID/%InstanceNumber.dcm'
+
+will create a folder structure that looks like this:
+
+.. code-block:: bash
+
+    PatientID
+    ├── StudyInstanceUID
+    │   └── SeriesInstanceUID
+    │       ├── 1.dcm
+    │       ├── 2.dcm
+    │       └── ...
+    ├── StudyInstanceUID
+    │   └── SeriesInstanceUID
+    │       ├── 1.dcm
+    │       ├── 2.dcm
+    │       └── ...
+    └── ...
+
+The **`filePattern`** string can be constructed from any DICOM tag. The following tags are
+good candidates for constructing a **`filePattern`** string:
+
+- PatientID
+- BodyPartExamined
+- Modality
+- StudyInstanceUID
+- SeriesInstanceUID
+- InstanceNumber
+- SOPInstanceUID
+
+
+To download a SeriesInstanceUID from the NBIA Database, use the :meth:`downloadSeries` method.
+
+.. automethod:: nbiatoolkit.NBIAClient.downloadSeries
+
+
+.. tabs::
+   .. tab:: Python
+        .. exec_code::
+
+            # --- hide: start ---
+            from nbiatoolkit import NBIAClient
+            # --- hide: stop ---
+
+            filePattern = '%PatientID/%StudyInstanceUID/%SeriesInstanceUID/%InstanceNumber.dcm'
+            downloadDir = './NBIA-Download'
+            nParallel = 5
+
+            with NBIAClient(return_type="dataframe") as client:
+                series = client.getSeries(
+                    PatientID='TCGA-G2-A2EK'
+                )
+
+                client.downloadSeries(
+                    series.SeriesInstanceUID,
+                    downloadDir,
+                    filePattern,
+                    nParallel
+                )

docs/tutorial_files/1_InitializeClient.rst → docs/getting_started/InitializeClient.rst

@@ -118,7 +118,8 @@ If you would like to return the data as a pandas DataFrame, you can pass the
       Feel free to open an issue on the GitHub repository if you would like to see this feature added.
 
 
-Alternatively, you can set the return type for all methods by passing the `return_type` argument to the NBIAClient class.
+Alternatively, you can set the return type for all methods by passing the `return_type` argument when
+initializing the NBIAClient class.
 
 .. tabs::
 
@@ -141,7 +142,8 @@ Alternatively, you can set the return type for all methods by passing the `retur
 
 Logging
 ^^^^^^^
-The client can be initialized with a log level to control the verbosity of the logs. This is primarily intended for debugging and development purposes.
+The client can be initialized with a log level to control the verbosity of the logs. This is primarily
+intended for debugging and development purposes.
 The default log level is 'INFO' and the available log levels are `DEBUG`, `INFO`, `WARNING`, `ERROR`.
 
 .. tabs::

docs/getting_started/Installation.rst

@@ -0,0 +1,40 @@
+Installation
+____________
+
+`nbiatoolkit` is currently under development and is not guaranteed to be stable.
+Please refer to the `1.0.0 Stable Release Milestone <https://github.com/jjjermiah/nbia-toolkit/milestone/1>`_
+for the roadmap to the first stable release.
+
+PyPi Installation
+~~~~~~~~~~~~~~~~~
+
+The easiest way to install `nbiatoolkit` is to use `pip` to install it from the
+`Python Package Index (PyPi) <https://pypi.org/project/nbiatoolkit/>`_.
+
+.. code-block:: console
+
+    $ pip install nbiatoolkit
+
+***NOTE: It is recommended that you install the package in a conda or virtual environment.***
+
+Conda Installation
+~~~~~~~~~~~~~~~~~~
+
+Though the package is not available on conda, you can create a conda environment and install the package using pip:
+
+.. code-block:: console
+
+    $ conda create -n nbia python=3.12
+    $ conda activate nbia
+    $ pip install nbiatoolkit
+
+Virtual Environment Installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you prefer to use a virtual environment, you can create one and install the package using pip:
+
+.. code-block:: console
+
+    $ python3 -m venv nbia
+    $ source nbia/bin/activate
+    $ pip install nbiatoolkit

docs/index.rst

@@ -0,0 +1,43 @@
+.. include:: ../README.md
+   :parser: myst_parser.sphinx_
+
+.. toctree::
+    :caption: Getting started
+    :name: getting-started
+    :hidden:
+    :maxdepth: 2
+
+    getting_started/NBIA.md
+    getting_started/Installation.rst
+    getting_started/InitializeClient.rst
+    getting_started/logger.rst
+
+.. toctree::
+    :caption: Querying API
+    :name: querying-api
+    :hidden:
+    :maxdepth: 2
+
+    querying_api/ExploringCollections.rst
+    querying_api/ExploringModalities.rst
+    querying_api/ExploringPatients.rst
+    querying_api/ExploringStudies.rst
+    querying_api/ExploringSeries.rst
+
+.. toctree::
+    :caption: Downloading API
+    :name: downloading-api
+    :hidden:
+    :maxdepth: 2
+
+    download_api/DownloadSeries.rst
+
+.. toctree::
+    :caption: Project Info
+    :name: project-info
+    :hidden:
+    :maxdepth: 2
+
+    project_info/CONTRIBUTING.md
+    project_info/CHANGELOG.md
+    project_info/CONDUCT.md