new tcia endpoints

Author: ernestoarbitrio

src/__init__.py

@@ -0,0 +1,5 @@
+# encoding: utf-8
+
+"""Initialization module for gdcapiwrapper package."""
+
+__version__ = "0.1"

src/gdcapiwrapper/__init__.py

@@ -1,31 +0,0 @@
-# encoding: utf-8
-
-import os
-import requests
-
-__version__ = "0.1"
-GDC_API_TOKEN = os.environ.get("GCC_API_TOKEN", None)
-GDC_API_BASE_URL = os.environ.get("GDC_API_BASE_URL", "https://api.gdc.cancer.gov/")
-
-
-class APIBaseURLStatusError(Exception):
-    pass
-
-
-class APITokenMissingError(Exception):
-    pass
-
-
-request = requests.get(f"{GDC_API_BASE_URL}/status")
-
-
-if request.status_code != 200:
-    raise APIBaseURLStatusError(
-        f"{GDC_API_BASE_URL} status: {request.status_code}."
-        "The resource seems to be unavailable"
-    )
-
-session = requests.Session()
-session.params = {"api_token": GDC_API_TOKEN, "api_base_url": GDC_API_BASE_URL}
-
-from .data import Data  # isort:skip # noqa

src/gdcapiwrapper/enums.py

@@ -0,0 +1,16 @@
+# encoding: utf-8
+
+from enum import Enum
+
+
+class FORMAT_TYPE(Enum):
+    """Enumerated values representing the various types of file format."""
+
+    # ---member definitions---
+    CSV = "CSV"
+    HTML = "HTML"
+    JSON = "JSON"
+    XML = "XML"
+
+    # ---allowed formats for TCIA apis---
+    TCIA_ALLOWED_FORMATS = frozenset((CSV, HTML, JSON, XML))

src/gdcapiwrapper/exceptions.py

@@ -0,0 +1,9 @@
+# encoding: utf-8
+
+
+class APIBaseURLStatusError(Exception):
+    pass
+
+
+class APITokenMissingError(Exception):
+    pass

src/gdcapiwrapper/tcga/__init__.py

@@ -0,0 +1,25 @@
+# encoding: utf-8
+
+import os
+import requests
+
+from ..exceptions import APIBaseURLStatusError
+
+
+TCGA_API_TOKEN = os.environ.get("TCGA_API_TOKEN", None)
+TCGA_API_BASE_URL = os.environ.get("TCGA_API_BASE_URL", "https://api.gdc.cancer.gov/")
+
+
+request = requests.get(f"{TCGA_API_BASE_URL}/status")
+
+
+if request.status_code != 200:
+    raise APIBaseURLStatusError(
+        f"{TCGA_API_BASE_URL} status: {request.status_code}."
+        "The resource seems to be unavailable"
+    )
+
+session = requests.Session()
+session.params = {"api_token": TCGA_API_TOKEN, "api_base_url": TCGA_API_BASE_URL}
+
+from .tcga import Data  # isort:skip # noqa

src/gdcapiwrapper/data.py renamed to src/gdcapiwrapper/tcga/tcga.py

@@ -1,6 +1,5 @@
 # encoding: utf-8
 
-
 import os
 import re
 from datetime import datetime
@@ -11,15 +10,15 @@
 from tqdm import tqdm
 
 from . import session
-from .util import copyfileobj
+from ..util import copyfileobj
 
 __data_endpoint__ = "data"
 
 base_url = f"{session.params.get('api_base_url')}/{__data_endpoint__}"
 
 
 class Data(object):
-    """ Provides Data objects for https://api.gdc.cancer.gov/data/ `Data Endpoints`
+    """Provides Data objects for https://api.gdc.cancer.gov/data/ `Data Endpoints`
 
     Includes endpoints for file(s) download
     """
@@ -46,7 +45,7 @@ def download(
         """
         url = f"{base_url}/{uuid}"
 
-        local_filename = uuid if not name else name
+        local_filename = name if name else uuid
         with requests.get(url, stream=True) as r:
             total_size = int(r.headers.get("content-length", 0))
             bar = tqdm(total=total_size, unit="iB", unit_scale=True)

src/gdcapiwrapper/tcia/__init__.py

@@ -0,0 +1,16 @@
+# encoding: utf-8
+
+import os
+import requests
+
+
+TCIA_API_TOKEN = os.environ.get("TCIA_API_TOKEN", None)
+TCIA_API_BASE_URL = os.environ.get(
+    "TCIA_API_BASE_URL", "https://services.cancerimagingarchive.net/services/v4/TCIA"
+)
+
+
+session = requests.Session()
+session.params = {"api_token": TCIA_API_TOKEN, "api_base_url": TCIA_API_BASE_URL}
+
+from .tcia import Data  # isort:skip # noqa

src/gdcapiwrapper/tcia/tcia.py

@@ -0,0 +1,136 @@
+# encoding: utf-8
+
+import os
+from typing import Tuple
+
+import requests
+from responses import Response
+from tqdm import tqdm
+
+from ..enums import FORMAT_TYPE as FT
+from . import session
+from ..util import copyfileobj
+
+__data_endpoint__ = "query"
+
+base_url = f"{session.params.get('api_base_url')}/{__data_endpoint__}"
+
+
+class Data(object):
+    """Provides Data objects for
+    https://services.cancerimagingarchive.net/services/v4/TCIA/ `Data Endpoints`
+    """
+
+    @classmethod
+    def download_single_image(
+        cls,
+        series_instance_uid: str,
+        sop_instance_uid: str,
+        path: str = ".",
+        name: str = None,
+    ) -> Tuple[Response, str]:
+        """Returns a SINGLE DICOM Object.
+
+        A single image is identified by its SeriesInstanceUID and SOPInstanceUID.
+        This API will always be used following the `sop_instance_uids`
+
+        Parameters
+        ---------
+        series_instance_uid : str
+            SeriesInstance UID
+        sop_instance_uid: str
+            SOPInstanceUID UID
+        path: str
+            Local path where save file (default: current path)
+        name: str
+            Filename. If not provided it will be saved with SOPInstance UID as name
+
+        Returns
+        -------
+        tuple
+            response, filename absolute path
+        """
+        url = (
+            f"{base_url}/getSingleImage?SeriesInstanceUID={series_instance_uid}&"
+            f"SOPInstanceUID={sop_instance_uid}"
+        )
+        local_filename = name if name else f"{sop_instance_uid}.dcm"
+        with requests.get(url, stream=True) as r:
+            total_size = int(r.headers.get("content-length", 0))
+            bar = tqdm(total=total_size, unit="iB", unit_scale=True)
+            with open(os.path.join(path, local_filename), "wb") as f:
+                copyfileobj(r.raw, f, bar)
+        return r, local_filename
+
+    @classmethod
+    def download_series_instance_images(
+        cls, series_instance_uid: str, path: str = ".", name: str = None
+    ) -> Tuple[Response, str]:
+        """Returns a single Zip file with set of images for the given SeriesInstance.
+
+        Parameters
+        ---------
+        series_instance_uid : str
+            SeriesInstance UID
+        path: str
+            Local path where save file (default: current path)
+        name: str
+            Filename. If not provided it will be saved with SOPInstance UID as name
+
+        Returns
+        -------
+        tuple
+            response, filename absolute path
+        """
+        url = f"{base_url}/getImage?SeriesInstanceUID={series_instance_uid}"
+        local_filename = name if name else f"{series_instance_uid}.zip"
+        with requests.get(url, stream=True) as r:
+            total_size = int(r.headers.get("content-length", 0))
+            bar = tqdm(total=total_size, unit="iB", unit_scale=True)
+            with open(os.path.join(path, local_filename), "wb") as f:
+                copyfileobj(r.raw, f, bar)
+        return r, local_filename
+
+    @classmethod
+    def sop_instance_uids(
+        cls,
+        series_instance_uid: str,
+        format_: str = "JSON",
+        path: str = ".",
+        name: str = None,
+    ) -> Tuple[Response, str]:
+        """Return a list of SOPInstanceUID for a given SeriesInstanceUID
+
+        Parameters
+        ---------
+        series_instance_uid : str
+            SeriesInstance UID
+        format_ : str
+            Output format. This endpoint supports CSV/HTML/XML/JSON
+        path: str
+            Local path where save file (default: current path)
+        name: str
+            Filename. If not provided it will be saved with SeriesInstance UID as name
+
+        Returns
+        -------
+        tuple
+            response, filename absolute path or json
+        """
+        if format_.upper() not in FT.TCIA_ALLOWED_FORMATS.value:
+            raise ValueError(
+                f"Format not allowed. Allowed formats:"
+                f"{list(FT.TCIA_ALLOWED_FORMATS.value)}, got {format_}."
+            )
+        url = (
+            f"{base_url}/getSOPInstanceUIDs?SeriesInstanceUID={series_instance_uid}&"
+            f"format={format_}"
+        )
+        r = requests.get(url)
+        if format_.upper() == "JSON":
+            return r, r.json()
+
+        local_filename = name if name else f"{series_instance_uid}.{format_.lower()}"
+        with open(os.path.join(path, local_filename), "wb") as f:
+            f.write(r.content)
+        return r, local_filename

tests/mockserver.py

@@ -11,7 +11,7 @@
 
 
 class MockServerRequestHandler(BaseHTTPRequestHandler):
-    API_PATTERN = re.compile(r"/data|/")
+    API_PATTERN = re.compile(r"/data|query|/")
 
     def do_GET(self):
         if re.search(self.API_PATTERN, self.path):

tests/unit/test_data.py

@@ -6,12 +6,13 @@
 import pytest
 from requests.exceptions import ChunkedEncodingError
 
-from gdcapiwrapper.data import Data
+from gdcapiwrapper.tcga import Data as TCGAData
+from gdcapiwrapper.tcia import Data as TCIAData
 
 from ..mockserver import get_free_port, start_mock_server
 
 
-class TestData(object):
+class TestTCGAData(object):
     @classmethod
     def setup_class(cls):
         cls.mock_server_port = get_free_port()
@@ -20,8 +21,10 @@ def setup_class(cls):
     def test_download(self, tmpdir):
         base_url = "http://localhost:{port}/data".format(port=self.mock_server_port)
 
-        with mock.patch.dict("gdcapiwrapper.data.__dict__", {"base_url": base_url}):
-            response, filename = Data.download(
+        with mock.patch.dict(
+            "gdcapiwrapper.tcga.tcga.__dict__", {"base_url": base_url}
+        ):
+            response, filename = TCGAData.download(
                 uuid="fakeuuid", path=tmpdir, name="fakefilename"
             )
 
@@ -31,12 +34,69 @@ def test_download(self, tmpdir):
     def test_download_multiple(self, tmpdir):
         base_url = "http://localhost:{port}".format(port=self.mock_server_port)
         try:
-            with mock.patch.dict("gdcapiwrapper.data.__dict__", {"base_url": base_url}):
-                response, filename = Data.download_multiple(
+            with mock.patch.dict(
+                "gdcapiwrapper.tcga.tcga.__dict__", {"base_url": base_url}
+            ):
+                response, filename = TCGAData.download_multiple(
                     uuid_list=["1", "2"], path=tmpdir
                 )
         except ChunkedEncodingError:
             pytest.skip("Flaky ConnectionResetError")
 
         assert response.ok is True
         assert os.path.exists(os.path.join(tmpdir, "fake.gzip")) is True
+
+
+class TestTCIAData(object):
+    @classmethod
+    def setup_class(cls):
+        cls.mock_server_port = get_free_port()
+        start_mock_server(cls.mock_server_port)
+
+    def test_json_sop_instance_uids(self):
+        base_url = "http://localhost:{port}/query".format(port=self.mock_server_port)
+        with mock.patch.dict(
+            "gdcapiwrapper.tcia.tcia.__dict__", {"base_url": base_url}
+        ):
+            response, json = TCIAData.sop_instance_uids(series_instance_uid="fakeuid")
+
+        assert response.ok is True
+        assert json == []
+
+    def test_other_formats_sop_instance_uids(self, tmpdir):
+        base_url = "http://localhost:{port}/query".format(port=self.mock_server_port)
+        with mock.patch.dict(
+            "gdcapiwrapper.tcia.tcia.__dict__", {"base_url": base_url}
+        ):
+            response, filename = TCIAData.sop_instance_uids(
+                series_instance_uid="fakeuid", format_="CSV", path=tmpdir
+            )
+
+        assert response.ok is True
+        assert os.path.exists(os.path.join(tmpdir, "fakeuid.csv")) is True
+
+    def test_download_single_image(self, tmpdir):
+        base_url = "http://localhost:{port}/query".format(port=self.mock_server_port)
+        with mock.patch.dict(
+            "gdcapiwrapper.tcia.tcia.__dict__", {"base_url": base_url}
+        ):
+            response, filename = TCIAData.download_single_image(
+                series_instance_uid="fakeuid",
+                sop_instance_uid="sopfakeuid",
+                path=tmpdir,
+            )
+
+        assert response.ok is True
+        assert os.path.exists(os.path.join(tmpdir, "sopfakeuid.dcm")) is True
+
+    def download_series_instance_images(self, tmpdir):
+        base_url = "http://localhost:{port}/query".format(port=self.mock_server_port)
+        with mock.patch.dict(
+            "gdcapiwrapper.tcia.tcia.__dict__", {"base_url": base_url}
+        ):
+            response, filename = TCIAData.download_series_instance_images(
+                series_instance_uid="fakeuid", path=tmpdir
+            )
+
+        assert response.ok is True
+        assert os.path.exists(os.path.join(tmpdir, "fakeuid.zip")) is True