docs: Merge branch 'development' into docs and add more collections d…

…ocumentation

docs/tutorial_files/2_ExploreCollections.rst

@@ -21,14 +21,55 @@ Passing a `prefix` parameter will return a list of collections that match the pr
 
       .. exec_code::
 
-        from nbiatoolkit import NBIAClient
+         from nbiatoolkit import NBIAClient
 
-        client = NBIAClient(return_type = "dataframe")
-        collections_df = client.getCollections(prefix='TCGA')
+         client = NBIAClient(return_type = "dataframe")
+         collections_df = client.getCollections(prefix='TCGA')
 
-        print(f"The number of available collections is {len(collections_df)}")
+         print(f"The number of available collections is {len(collections_df)}")
 
-        print(collections_df)
+         print(collections_df)
 
 
 .. automethod:: nbiatoolkit.NBIAClient.getCollectionDescriptions
+
+.. tabs::
+
+   .. tab:: Python
+
+      .. exec_code::
+
+         # --- hide: start ---
+         from nbiatoolkit import NBIAClient
+         from pprint import pprint as print
+         # --- hide: stop ---
+
+         with NBIAClient() as client:
+            desc = client.getCollectionDescriptions(collectionName = "TCGA-BLCA")[0]
+
+         print(desc['Description'])
+         print(desc['DescriptionURI'])
+         print(desc['LastUpdated'])
+
+
+
+.. automethod:: nbiatoolkit.NBIAClient.getCollectionPatientCount
+
+
+.. tabs::
+
+   .. tab:: Python
+
+      .. exec_code::
+
+         # --- hide: start ---
+         from nbiatoolkit import NBIAClient
+         # --- hide: stop ---
+
+         with NBIAClient() as client:
+            counts_df = client.getCollectionPatientCount(
+               prefix = "TCGA",
+               return_type="dataframe"
+            )
+
+         print(counts_df)

src/nbiatoolkit/nbia.py

@@ -308,34 +308,52 @@ def getCollectionDescriptions(
         ), "The response from the API is empty. Please check the collection name."
 
         response[0] = {
-            "collectionName": response[0]["collectionName"],
-            "description": clean_html(response[0]["description"]),
-            "descriptionURI": response[0]["descriptionURI"],
-            "lastUpdated": convertMillis(
+            "Collection": response[0]["collectionName"],
+            "Description": clean_html(response[0]["description"]),
+            "DescriptionURI": response[0]["descriptionURI"],
+            "LastUpdated": convertMillis(
                 millis=int(response[0]["collectionDescTimestamp"])
             ),
         }
 
         return conv_response_list(response, returnType)
 
-    # returns a list of dictionaries with the collection name and patient count
     def getCollectionPatientCount(
         self,
         prefix: str = "",
         return_type: Optional[Union[ReturnType, str]] = None,
     ) -> List[dict[Any, Any]] | pd.DataFrame:
+        """Retrieves the patient count for collections.
+
+        Args:
+            prefix (str, optional):
+                Prefix to filter the collections by. Defaults to "".
+            return_type (Optional[Union[ReturnType, str]], optional):
+                Return type of the response. Defaults to None which uses the default return type.
+
+        Returns:
+            List[dict[Any, Any]] | pd.DataFrame:
+                List of collections and their patient counts or DataFrame containing the collections and their patient counts.
+        """
+
         returnType: ReturnType = self._get_return(return_type)
 
+        response: List[dict[Any, Any]]
         response = self.query_api(NBIA_ENDPOINTS.GET_COLLECTION_PATIENT_COUNT)
 
-        if prefix:
-            response = [
-                response_dict
-                for response_dict in response
-                if response_dict["criteria"].lower().startswith(prefix.lower())
-            ]
+        parsed_response: List[dict[Any, Any]] = []
 
-        return conv_response_list(response, returnType)
+        for collection in response:
+            Collection = collection["criteria"]
+            if Collection.lower().startswith(prefix.lower()):
+                parsed_response.append(
+                    {
+                        "Collection": Collection,
+                        "PatientCount": collection["count"],
+                    }
+                )
+
+        return conv_response_list(parsed_response, returnType)
 
     def getModalityValues(
         self,
@@ -421,6 +439,7 @@ def getBodyPartCounts(
 
         PARAMS = self.parsePARAMS(locals())
 
+        response: List[dict[Any, Any]]
         response = self.query_api(
             endpoint=NBIA_ENDPOINTS.GET_BODY_PART_PATIENT_COUNT, params=PARAMS
         )
@@ -438,6 +457,7 @@ def getStudies(
 
         PARAMS: dict = self.parsePARAMS(locals())
 
+        response: List[dict[Any, Any]]
         response = self.query_api(endpoint=NBIA_ENDPOINTS.GET_STUDIES, params=PARAMS)
 
         return conv_response_list(response, returnType)
@@ -458,6 +478,7 @@ def getSeries(
 
         PARAMS: dict = self.parsePARAMS(locals())
 
+        response: List[dict[Any, Any]]
         response = self.query_api(endpoint=NBIA_ENDPOINTS.GET_SERIES, params=PARAMS)
 
         return conv_response_list(response, returnType)
@@ -519,6 +540,7 @@ def getDICOMTags(
         returnType: ReturnType = self._get_return(return_type)
         PARAMS = self.parsePARAMS({"SeriesUID": SeriesInstanceUID})
 
+        response: List[dict[Any, Any]]
         response = self.query_api(endpoint=NBIA_ENDPOINTS.GET_DICOM_TAGS, params=PARAMS)
 
         return conv_response_list(response, returnType)