feat: Update NBIA client to include new method getNewPatients()

jjjermiah · Feb 3, 2024 · 22895a4 · 22895a4
1 parent 5d77524
commit 22895a4
Show file tree

Hide file tree

Showing 5 changed files with 120 additions and 5 deletions.
diff --git a/docs/Tutorial.ipynb b/docs/Tutorial.ipynb
@@ -23,7 +23,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": 2,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -393,6 +393,77 @@
     "pprint(patients[0:5])"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### getNewPatients In Collection\n",
+    "\n",
+    "``` python\n",
+    "getNewPatients(\n",
+    "    Collection: str,   # (required)\n",
+    "    Date: str,      # (required) accepted formats:\n",
+    "                    # \"%Y-%m-%d\", \"%Y/%m/%d\", \"%Y%m%d\", \n",
+    "                    # \"%m/%d/%Y\", \"%d/%m/%Y\", \"%d-%m-%Y\"\n",
+    ")\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Total new patients in TCGA-BLCA after 2019-01-01: 15\n",
+      "[{'Collection': 'TCGA-BLCA',\n",
+      "  'PatientId': 'TCGA-4Z-AA86',\n",
+      "  'PatientName': 'TCGA-4Z-AA86',\n",
+      "  'PatientSex': 'M',\n",
+      "  'Phantom': 'NO',\n",
+      "  'SpeciesCode': '337915000',\n",
+      "  'SpeciesDescription': 'Homo sapiens'},\n",
+      " {'Collection': 'TCGA-BLCA',\n",
+      "  'PatientId': 'TCGA-G2-A2EC',\n",
+      "  'PatientName': 'TCGA-G2-A2EC',\n",
+      "  'PatientSex': 'F',\n",
+      "  'Phantom': 'NO',\n",
+      "  'SpeciesCode': '337915000',\n",
+      "  'SpeciesDescription': 'Homo sapiens'},\n",
+      " {'Collection': 'TCGA-BLCA',\n",
+      "  'EthnicGroup': 'W',\n",
+      "  'PatientId': 'TCGA-G2-A2EF',\n",
+      "  'PatientName': 'TCGA-G2-A2EF',\n",
+      "  'PatientSex': 'M',\n",
+      "  'Phantom': 'NO',\n",
+      "  'SpeciesCode': '337915000',\n",
+      "  'SpeciesDescription': 'Homo sapiens'},\n",
+      " {'Collection': 'TCGA-BLCA',\n",
+      "  'PatientId': 'TCGA-G2-A2EJ',\n",
+      "  'PatientName': 'TCGA-G2-A2EJ',\n",
+      "  'PatientSex': 'F',\n",
+      "  'Phantom': 'NO',\n",
+      "  'SpeciesCode': '337915000',\n",
+      "  'SpeciesDescription': 'Homo sapiens'},\n",
+      " {'Collection': 'TCGA-BLCA',\n",
+      "  'EthnicGroup': 'W',\n",
+      "  'PatientId': 'TCGA-G2-A2EK',\n",
+      "  'PatientName': 'TCGA-G2-A2EK',\n",
+      "  'PatientSex': 'M',\n",
+      "  'Phantom': 'NO',\n",
+      "  'SpeciesCode': '337915000',\n",
+      "  'SpeciesDescription': 'Homo sapiens'}]\n"
+     ]
+    }
+   ],
+   "source": [
+    "newPatients = client.getNewPatients(Collection=\"TCGA-BLCA\", Date=\"2019-01-01\")\n",
+    "print(f\"Total new patients in TCGA-BLCA after 2019-01-01: {len(newPatients)}\")\n",
+    "pprint(newPatients[0:5])"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

diff --git a/src/nbiatoolkit/nbia.py b/src/nbiatoolkit/nbia.py
@@ -1,6 +1,6 @@
 from .auth import OAuth2
 from .logger.logger import setup_logger
-from .utils import NBIA_ENDPOINTS, validateMD5, clean_html, convertMillis
+from .utils import NBIA_ENDPOINTS, validateMD5, clean_html, convertMillis, convertDateFormat
 from .dicomsort import DICOMSorter
 
 import requests
@@ -172,6 +172,34 @@ def getPatients(self, Collection: str = "") -> Union[list[dict[str, str]], None]
 
         return patientList
 
+    def getNewPatients(self, Collection: str, Date: str) -> Union[list[dict[str, str]], None]:
+        assert Collection is not None
+        assert Date is not None
+
+        # convert date to %Y/%m/%d format
+        Date = convertDateFormat(input_date=Date, format="%Y/%m/%d")
+
+        PARAMS = self.parsePARAMS(locals())
+
+        response = self.query_api(endpoint=NBIA_ENDPOINTS.GET_NEW_PATIENTS_IN_COLLECTION, params=PARAMS)
+        assert isinstance(response, list), "Expected list, but received: %s" % type(response)
+
+        patientList = []
+        for patient in response:
+            assert isinstance(patient, dict), "Expected dict, but received: %s" % type(
+                patient
+            )
+            assert "PatientId" in patient, "PatientId not in patient dict"
+            assert isinstance(
+                patient["PatientId"], str
+            ), "PatientId must be a string, but received: %s" % type(
+                patient["PatientId"]
+            )
+
+            patientList.append(patient)
+
+        return patientList
+
     def getPatientsByCollectionAndModality(
         self, Collection: str, Modality: str
     ) -> Union[list[str], None]:

diff --git a/src/nbiatoolkit/utils/__init__.py b/src/nbiatoolkit/utils/__init__.py
@@ -1,4 +1,4 @@
 from .nbia_endpoints import NBIA_ENDPOINTS
 from .md5 import validateMD5
-from .parsers import convertMillis, clean_html
-__all__ = ["NBIA_ENDPOINTS", "validateMD5", "convertMillis", "clean_html"]
+from .parsers import convertMillis, clean_html, convertDateFormat
+__all__ = ["NBIA_ENDPOINTS", "validateMD5", "convertMillis", "clean_html", "convertDateFormat"]
diff --git a/src/nbiatoolkit/utils/nbia_endpoints.py b/src/nbiatoolkit/utils/nbia_endpoints.py
@@ -15,9 +15,9 @@ class NBIA_ENDPOINTS(Enum):
     GET_MODALITY_VALUES = "v2/getModalityValues"
 
     GET_PATIENTS = "v2/getPatient"
+    GET_NEW_PATIENTS_IN_COLLECTION = "v2/NewPatientsInCollection"
     GET_PATIENT_BY_COLLECTION_AND_MODALITY = "v2/getPatientByCollectionAndModality"
     GET_BODY_PART_PATIENT_COUNT = "getBodyPartValuesAndCounts"
-    GET_NEW_PATIENTS_IN_COLLECTION = "NewPatientsInCollection"
 
     GET_STUDIES = "v2/getPatientStudy"
 

diff --git a/tests/test_nbia.py b/tests/test_nbia.py
@@ -92,6 +92,22 @@ def test_getPatients(nbia_patients):
     assert "Collection" in nbia_patients[0]
     assert "PatientSex" in nbia_patients[0]
 
+def test_getNewPatients(nbia_client):
+    patients = nbia_client.getNewPatients('TCGA-BLCA', Date = "2019-01-01")
+    assert isinstance(patients, list)
+    assert len(patients) > 0
+    assert isinstance(patients[0], dict)
+    assert "PatientId" in patients[0]
+    assert "PatientName" in patients[0]
+    assert "Collection" in patients[0]
+    assert "PatientSex" in patients[0]
+
+def test_failed_getNewPatients(nbia_client):
+    with pytest.raises(Exception):
+        patients = nbia_client.getNewPatients('TCGA-BLCA', Date = "bad_date")
+    with pytest.raises(Exception):
+        patients = nbia_client.getNewPatients('bad_collection', Date = "2019-01-01")
+
 def test_getPatientsByCollectionAndModality(nbia_patientsByCollectionAndModality):
     assert isinstance(nbia_patientsByCollectionAndModality, list)
     assert len(nbia_patientsByCollectionAndModality) > 0