docs: add for collection methods

docs/tutorial_files/1_InitializeClient.rst

@@ -1,6 +1,7 @@
 Setup
 -----------------
 
+
 Initialize Client
 ^^^^^^^^^^^^^^^^^
 

docs/tutorial_files/2_ExploreCollections.rst

@@ -1,9 +1,34 @@
-Metadata Query Methods
+API Query Methods
 ----------------------
 
 
 Collection Methods
 ^^^^^^^^^^^^^^^^^^
+The simplest way to get a list of collections is to use the
+:meth:`nbiatoolkit.NBIAClient.getCollections` method.
+This method returns a list of all collections available in the NBIA database.
 
-.. autoclass:: nbiatoolkit.NBIAClient
-    :members:
+The method has the following signature:
+
+.. automethod:: nbiatoolkit.NBIAClient.getCollections
+
+Passing no parameters to the method will return a list of all collections available in the NBIA database.
+Passing a `prefix` parameter will return a list of collections that match the prefix.
+
+.. tabs::
+
+   .. tab:: Python
+
+      .. exec_code::
+
+        from nbiatoolkit import NBIAClient
+
+        client = NBIAClient(return_type = "dataframe")
+        collections_df = client.getCollections(prefix='TCGA')
+
+        print(f"The number of available collections is {len(collections_df)}")
+
+        print(collections_df)
+
+
+.. automethod:: nbiatoolkit.NBIAClient.getCollectionDescriptions

src/nbiatoolkit/nbia.py

@@ -37,20 +37,16 @@ def conv_response_list(
     response_json: List[dict[Any, Any]],
     return_type: ReturnType,
 ) -> List[dict[Any, Any]] | pd.DataFrame:
+    """_summary_
+
+    :param response_json: _description_
+    :type response_json: List[dict[Any, Any]]
+    :param return_type: _description_
+    :type return_type: ReturnType
+    :return: _description_
+    :rtype: List[dict[Any, Any]] | pd.DataFrame
     """
-    Convert a response JSON to a list or a pandas DataFrame based on the specified return type.
 
-    Args:
-        response_json (List[dict[Any, Any]]): The response JSON to be converted.
-        return_type (ReturnType): The desired return type (LIST or DATAFRAME).
-
-    Returns:
-        List[dict[Any, Any]] | pd.DataFrame: The converted response in the specified return type.
-
-    Raises:
-        AssertionError: If the response JSON is not a list.
-
-    """
     assert isinstance(response_json, list), "The response JSON must be a list"
 
     if return_type == ReturnType.LIST:
@@ -128,6 +124,13 @@ class NBIAClient:
 
     The NBIAClient class provides a high-level interface for querying the NBIA API and downloading DICOM series.
 
+    Args:
+        username (str, optional): The username for authentication. Defaults to "nbia_guest".
+        password (str, optional): The password for authentication. Defaults to an empty string.
+        log_level (str, optional): The log level for the logger. Defaults to "INFO".
+        return_type (Union[ReturnType, str], optional): The return type for API responses.
+            Defaults to ReturnType.LIST
+
     Attributes:
         OAuth_client (OAuth2): The OAuth2 client used for authentication.
         headers (dict[str, str]): The API headers.
@@ -251,6 +254,17 @@ def query_api(
     def getCollections(
         self, prefix: str = "", return_type: Optional[Union[ReturnType, str]] = None
     ) -> List[dict[Any, Any]] | pd.DataFrame:
+        """
+        Retrieves the collections from the NBIA server.
+
+        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 or DataFrame containing the collections.
+        """
         returnType: ReturnType = self._get_return(return_type)
 
         response: List[dict[Any, Any]]
@@ -268,6 +282,19 @@ def getCollections(
     def getCollectionDescriptions(
         self, collectionName: str, return_type: Optional[Union[ReturnType, str]] = None
     ) -> List[dict[Any, Any]] | pd.DataFrame:
+        """
+        Retrieves the description of a collection from the NBIA server.
+
+        Args:
+            collectionName (str): The name of the collection.
+            return_type (Optional[Union[ReturnType, str]], optional):
+                Return type of the response. Defaults to None.
+
+        Returns:
+            List[dict[Any, Any]] | pd.DataFrame:
+                List of collection descriptions or DataFrame containing the collection descriptions.
+        """
+
         returnType: ReturnType = self._get_return(return_type)
         PARAMS: dict = self.parsePARAMS(params=locals())
 
@@ -291,6 +318,25 @@ def getCollectionDescriptions(
 
         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:
+        returnType: ReturnType = self._get_return(return_type)
+
+        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())
+            ]
+
+        return conv_response_list(response, returnType)
+
     def getModalityValues(
         self,
         Collection: str = "",
@@ -365,25 +411,6 @@ def getPatientsByCollectionAndModality(
 
         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:
-        returnType: ReturnType = self._get_return(return_type)
-
-        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())
-            ]
-
-        return conv_response_list(response, returnType)
-
     def getBodyPartCounts(
         self,
         Collection: str = "",