feat: progressBar option

docs/querying_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/querying_api/ExploringSeries.rst

@@ -23,19 +23,19 @@ The following examples demonstrate using the :meth:`getSeries`.
 .. tabs::
    .. tab:: Python
       .. tabs::
-         .. tab:: Filter by Collection
+        .. tab:: Filter by Collection
             .. exec_code::
 
                 # --- hide: start ---
                 from nbiatoolkit import NBIAClient
                 # --- hide: stop ---
 
                 with NBIAClient(return_type="dataframe") as client:
-                    series = client.Series(
+                    series = client.getSeries(
                         Collection = "TCGA-BLCA"
                     )
 
-               print(series.iloc[0])
+                print(series.iloc[0])
 
         .. tab:: Filter by Collection and PatientID
             .. exec_code::

src/nbiatoolkit/nbia.py

@@ -42,6 +42,7 @@ def downloadSingleSeries(
     api_headers: dict[str, str],
     base_url: NBIA_BASE_URLS,
     log: Logger,
+    Progressbar: bool = False,
 ):
     """
     Downloads a single series from the NBIA server.
@@ -54,6 +55,7 @@ def downloadSingleSeries(
         api_headers (dict[str, str]): The headers to be included in the API request.
         base_url (NBIA_ENDPOINTS): The base URL of the NBIA server.
         log (Logger): The logger object for logging messages.
+        Progressbar (bool, optional): Flag indicating whether to display a progress bar. Defaults to False.
 
     Returns:
         bool: True if the series is downloaded and sorted successfully, False otherwise.
@@ -89,7 +91,10 @@ def downloadSingleSeries(
         )
         # sorter.sortDICOMFiles(option="move", overwrite=overwrite)
         if not sorter.sortDICOMFiles(
-            shutil_option="move", overwrite=overwrite, progressbar=False, n_parallel=1
+            shutil_option="move",
+            overwrite=overwrite,
+            progressbar=Progressbar,
+            n_parallel=1,
         ):
             log.error(
                 f"Error sorting DICOM files for series {SeriesInstanceUID}\n \
@@ -616,6 +621,7 @@ def downloadSeries(
         filePattern: str = "%PatientName/%Modality-%SeriesNumber-%SeriesInstanceUID/%InstanceNumber.dcm",
         overwrite: bool = False,
         nParallel: int = 1,
+        Progressbar: bool = False,
     ) -> bool:
         if isinstance(SeriesInstanceUID, str):
             SeriesInstanceUID = [SeriesInstanceUID]
@@ -627,15 +633,16 @@ def downloadSeries(
         results = []
         for series in SeriesInstanceUID:
             result = pool.apply_async(
-                downloadSingleSeries,
-                (
+                func=downloadSingleSeries,
+                args=(
                     series,
                     downloadDir,
                     filePattern,
                     overwrite,
                     self._api_headers,
                     self._base_url,
                     self._log,
+                    Progressbar,
                 ),
             )
             results.append(result)