fix: update parameters

docs/index.rst

@@ -20,6 +20,10 @@
 
     querying_api/ExploringCollections.rst
     querying_api/ExploringModalities.rst
+    querying_api/ExploringPatients.rst
+    querying_api/ExploringStudies.rst
+    querying_api/ExploringSeries.rst
+
 
 .. toctree::
     :caption: Project Info

docs/querying_api/ExploringModalities.rst

@@ -1,7 +1,5 @@
-
-
 Modality Methods
-^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^
 The :meth:`getModalityValues` method can provide insight to the available modality types in the NBIA database.
 
 The method has the following signature:

docs/querying_api/ExploringPatients.rst

@@ -0,0 +1,91 @@
+Patient Methods
+^^^^^^^^^^^^^^^
+
+The :meth:`getPatients` method can provide insight to the
+patient metadata available in the NBIA database.
+
+.. automethod:: nbiatoolkit.NBIAClient.getPatients
+
+
+By default, the :meth:`getPatients` method will return all
+patients in the NBIA database. However, the method can be
+filtered by `Collection`.
+
+.. tabs::
+
+   .. tab:: Python
+
+      .. tabs::
+
+         .. tab:: Get all patients
+            .. exec_code::
+
+               # --- hide: start ---
+               from nbiatoolkit import NBIAClient
+               # --- hide: stop ---
+
+               with NBIAClient(return_type="dataframe") as client:
+                  patients = client.getPatients()
+
+               print(patients.head())
+
+         .. tab:: Filter by Collection
+
+            .. exec_code::
+
+               # --- hide: start ---
+               from nbiatoolkit import NBIAClient
+               # --- hide: stop ---
+
+               with NBIAClient(return_type="dataframe") as client:
+                  patients = client.getPatients(Collection = "TCGA-BLCA")
+
+               print(patients.head())
+
+
+For more granular filtering, the :meth:`getPatientsByCollectionAndModality` method
+can be used to filter by `Collection` **and** `Modality` as both are required.
+Unlike the :meth:`getPatients` method which returns additional metadata such as
+`SpeciesCode`, `SpeciesDescription`, `PatientSex`, and `EthnicGroup`, this method will
+only return a list of Patient IDs.
+
+.. automethod:: nbiatoolkit.NBIAClient.getPatientsByCollectionAndModality
+
+.. tabs::
+
+   .. tab:: Python
+
+      .. exec_code::
+
+        # --- hide: start ---
+        from nbiatoolkit import NBIAClient
+        # --- hide: stop ---
+
+        with NBIAClient(return_type="dataframe") as client:
+           patients = client.getPatientsByCollectionAndModality(Collection = "TCGA-BLCA", Modality = "MR")
+
+        print(patients.head())
+
+
+.. automethod:: nbiatoolkit.NBIAClient.getNewPatients
+
+The :meth:`getNewPatients` method can be used to retrieve a list of patients that
+have been added to the NBIA database within a specified time frame.
+
+.. tabs::
+
+   .. tab:: Python
+
+      .. exec_code::
+
+        # --- hide: start ---
+        from nbiatoolkit import NBIAClient
+        # --- hide: stop ---
+
+        with NBIAClient(return_type="dataframe") as client:
+            patients = client.getNewPatients(
+                Collection="CMB-LCA",
+                Date="2022/12/06",
+            )
+
+        print(patients.head())

docs/querying_api/ExploringSeries.rst

@@ -0,0 +1,53 @@
+Series Methods
+^^^^^^^^^^^^^^
+
+The :meth:`getSeries` method can provide insight to the available series
+in the NBIA database.
+
+.. automethod:: nbiatoolkit.NBIAClient.getSeries
+
+By default, the method will return all the series in the database. However,
+it can be filtered by the following parameters:
+
+- **Collection**
+- **PatientID**
+- **StudyInstanceUID**
+- **Modality**
+- **SeriesInstanceUID**
+- **BodyPartExamined**
+- **ManufacturerModelName**
+- **Manufacturer**
+
+The following examples demonstrate using the :meth:`getSeries`.
+
+.. tabs::
+   .. tab:: Python
+      .. tabs::
+         .. tab:: Filter by Collection
+            .. exec_code::
+
+                # --- hide: start ---
+                from nbiatoolkit import NBIAClient
+                # --- hide: stop ---
+
+                with NBIAClient(return_type="dataframe") as client:
+                    series = client.Series(
+                        Collection = "TCGA-BLCA"
+                    )
+
+               print(series.iloc[0])
+
+        .. tab:: Filter by Collection and PatientID
+            .. exec_code::
+
+                # --- hide: start ---
+                from nbiatoolkit import NBIAClient
+                # --- hide: stop ---
+
+                with NBIAClient(return_type="dataframe") as client:
+                    series = client.getSeries(
+                        Collection = "TCGA-BLCA",
+                        PatientID = "TCGA-G2-A2EK"
+                    )
+
+                print(series.iloc[0])

docs/querying_api/ExploringStudies.rst

@@ -0,0 +1,50 @@
+Studies Methods
+^^^^^^^^^^^^^^^
+
+The :meth:`getStudies` method can provide insight to the available studies in the
+NBIA database.
+
+
+.. automethod:: nbiatoolkit.NBIAClient.getStudies
+
+By default, the method requires filtering by **Collection**, but can optionally
+be also filtered by **PatientID** and/or **StudyInstanceUID** as well.
+
+
+The following example demonstrates how to use the :meth:`getStudies` method to filter the studies by the collection name.
+
+.. tabs::
+
+   .. tab:: Python
+
+      .. tabs::
+
+         .. tab:: Get all studies
+            .. exec_code::
+
+               # --- hide: start ---
+               from nbiatoolkit import NBIAClient
+               # --- hide: stop ---
+
+               with NBIAClient(return_type="dataframe") as client:
+                  studies = client.getStudies(
+                    Collection = "TCGA-BLCA"
+                )
+
+               print(studies.iloc[0])
+
+         .. tab:: Filter by Collection
+
+            .. exec_code::
+
+               # --- hide: start ---
+               from nbiatoolkit import NBIAClient
+               # --- hide: stop ---
+
+               with NBIAClient(return_type="dataframe") as client:
+                    studies = client.getStudies(
+                        Collection = "TCGA-BLCA",
+                        PatientID = "TCGA-G2-A2EK"
+                    )
+
+               print(studies.iloc[0])

src/nbiatoolkit/nbia.py

@@ -389,6 +389,17 @@ def getPatients(
         Collection: str = "",
         return_type: Optional[Union[ReturnType, str]] = None,
     ) -> List[dict[Any, Any]] | pd.DataFrame:
+        """
+        Retrieves a list of patients from the NBIA API.
+
+        Args:
+            Collection (str, optional): The name of the collection to filter the patients. Defaults to "".
+            return_type (Optional[Union[ReturnType, str]], optional): The desired return type. Defaults to None.
+
+        Returns:
+            List[dict[Any, Any]] | pd.DataFrame: A list of patient dictionaries or a pandas DataFrame, depending on the return type.
+
+        """
         returnType: ReturnType = self._get_return(return_type)
 
         PARAMS: dict = self.parsePARAMS(locals())
@@ -404,6 +415,21 @@ def getNewPatients(
         Date: Union[str, datetime],
         return_type: Optional[Union[ReturnType, str]] = None,
     ) -> List[dict[Any, Any]] | pd.DataFrame:
+        """
+        Retrieves new patients from the NBIA API based on the specified collection and date.
+
+        Args:
+            Collection (str): The name of the collection to retrieve new patients from.
+            Date (Union[str, datetime]): The date to filter the new patients. Can be a string in the format "YYYY/MM/DD" or a datetime object.
+            return_type (Optional[Union[ReturnType, str]]): The desired return type. Defaults to None.
+
+        Returns:
+            List[dict[Any, Any]] | pd.DataFrame: A list of dictionaries or a pandas DataFrame containing the new patients.
+
+        Raises:
+            AssertionError: If the Date argument is None.
+
+        """
         returnType: ReturnType = self._get_return(return_type)
 
         assert Date is not None
@@ -426,6 +452,20 @@ def getPatientsByCollectionAndModality(
         Modality: str,
         return_type: Optional[Union[ReturnType, str]] = None,
     ) -> List[dict[Any, Any]] | pd.DataFrame:
+        """
+        Retrieves patients by collection and modality.
+
+        Args:
+            Collection (str): The collection name.
+            Modality (str): The modality name.
+            return_type (Optional[Union[ReturnType, str]], optional): The desired return type. Defaults to None.
+
+        Returns:
+            List[dict[Any, Any]] | pd.DataFrame: The list of patients or a pandas DataFrame, depending on the return type.
+
+        Raises:
+            AssertionError: If Collection or Modality is None.
+        """
         assert Collection is not None
         assert Modality is not None
 
@@ -465,6 +505,18 @@ def getStudies(
         StudyInstanceUID: str = "",
         return_type: Optional[Union[ReturnType, str]] = None,
     ) -> List[dict[Any, Any]] | pd.DataFrame:
+        """
+        Retrieves studies from the NBIA API based on the specified parameters.
+
+        Args:
+            Collection (str): The name of the collection to retrieve studies from.
+            PatientID (str, optional): The patient ID to filter the studies by. Defaults to "".
+            StudyInstanceUID (str, optional): The study instance UID to filter the studies by. Defaults to "".
+            return_type (Optional[Union[ReturnType, str]], optional): The desired return type. Defaults to None.
+
+        Returns:
+            List[dict[Any, Any]] | pd.DataFrame: A list of dictionaries or a pandas DataFrame containing the retrieved studies.
+        """
         returnType: ReturnType = self._get_return(return_type)
 
         PARAMS: dict = self.parsePARAMS(locals())