pycli-trials 0.1.0__py3-none-any.whl

pycli_trials-0.1.0.dist-info/METADATA

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: pycli-trials
+Version: 0.1.0
+Summary: A Python wrapper for the ClinicalTrials.gov API (v2) with full pagination support and a few extra features
+Home-page: https://github.com/YOUSSEFSAIDHOM/pyct
+Author: Youssef Sidhom
+Author-email: youssefsidhom8@gmail.com
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests
+Requires-Dist: pandas
+Requires-Dist: tqdm
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+
+# PyCT 🧬 (v0.1.0)
+
+### About 💭
+
+PyCT is a python wrapper for the ClinicalTrials.org API (v2). Although a python-wrapper already exists for this API, it doesn't feature full pagination support, thus is unable to give you all the studies that match the search-terms. Moreover, PyCT enables you to search with more accuracy by specifying the conditions and the interventions separately
+
+### Basic usage 🪛
+Get started with:
+```python
+from pyct import ClinicalTrials
+
+ct = ClinicalTrials()
+```
+
+Checking API info:
+
+```python
+print(ct)
+```
+Fetching studies:
+
+```python
+
+# Specify each field
+
+df = ct.get_studies(
+    condition="Dementia",
+    intervention="Non-pharmacological",
+    status="RECRUITING"
+)
+
+# Alternatively you can get one specific study using the NCT number
+study = ct.get_study("NCT06210035")
+
+```
+and finally you can export with the following options below:
+
+```python
+ct.to_csv(df, "alzheimer_trials.csv") # CSV
+
+ct.to_excel(df, "alzheimer_trials.xlsx") # Excel
+
+ct.to_json(df, "alzheimer_trials.json") # JSON
+```
+It will automatically give a name if you don't specify
+### Installation 📦
+
+```
+pip install pyct
+```

pycli_trials-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+pyct/__init__.py,sha256=zzw8AnjqBlV_oNG3hItuGTmHg9E2obbEiRKyIbNvn9w,117
+pyct/client.py,sha256=plssAearEgmshVS6OtYi7D56345heXynFQbTD01hp7I,5835
+pyct/utils.py,sha256=-jhz_PLrD7J0jvQkbmS74EQ_sOgrEzN8lJMRjazhiVw,2077
+pycli_trials-0.1.0.dist-info/METADATA,sha256=_HDUsThsPttz1KJWD7n4teAMtFaDM4F9I0-IwyfQy0Y,2016
+pycli_trials-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+pycli_trials-0.1.0.dist-info/top_level.txt,sha256=ZtmUS758G8VBqkWk0n5b358fegRExYlWLm6suEQZfnQ,5
+pycli_trials-0.1.0.dist-info/RECORD,,

pycli_trials-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pycli_trials-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyct

pyct/__init__.py

@@ -0,0 +1,6 @@
+from .client import ClinicalTrials
+
+__version__ = "0.1.0"
+__author__ = "Youssef Sidhom"
+
+__all__ = ["ClinicalTrials"]

pyct/client.py

@@ -0,0 +1,193 @@
+import requests
+import pandas as pd
+from tqdm import tqdm
+import datetime
+from .utils import get_with_retry
+
+
+class ClinicalTrials:
+    """
+    PYCT is a Python-wrapper for the ClinicalTrials.gov API
+    which supports full pagination, mutliple query fields and built-in export options
+
+    Basic usage:
+
+        ct = ClinicalTrials()
+        df = ct.get_studies(conditions="Alzheimer", intervention="Non-pharmacological")
+        ct.to_csv(df, "trials.csv")
+
+    """
+
+    # Base URL for the ClinicalTrials API
+    BASE  = "https://clinicaltrials.gov/api/v2"
+
+    def __init__(self):
+        info = self._get_api_info()
+        self.api_version = info.get("apiVersion")
+        self.last_updated = info.get("dataTimestamp")
+
+    def __repr__(self):
+        return (
+            f"PYCT | "
+            f"ClinicalTrials API v{self.api_version} | "
+            f"Data base last updated {self.last_updated}"
+        )
+
+    # ---------------------------- #
+    #       Public methods         #
+    # ---------------------------- #
+
+    def get_studies(self,
+                    condition = None,
+                    intervention = None,
+                    term = None, 
+                    status = None,
+                    page_size=1000):
+
+        """
+        Retrieves all the studies that match with a given query
+
+        Args:
+            condition (str) : e.g. "Dementia", "Covid"
+
+            intervention (str) : e.g. "excercise", "ECT"
+
+            term (str) : General keyword search across all fields
+
+            status (str) : Studies may have one of the following recuirtment statuses:
+                - RECRUITING, COMPLETED, NOT_YET_RECRUITING, ACTIVE_NOT_RECRUITING, and TERMINATED
+
+            page_size (int) : Number of results per page (max 1000). Defaults to 1000.
+
+        Returns:
+            A requests.Response
+        """
+
+        params = {"format":"json", "pageSize":page_size}
+
+        params["query.cond"] = condition if condition is not None else None
+        params["query.intr"] = intervention if intervention is not None else None
+        params["query.term"] = term if term is not None else None
+        params["filter.status"] = status if status is not None else None
+
+        params = {k: v for k, v in params.items() if v is not None}
+
+        return self._paginate(params)
+
+    def get_study(self, nct):
+        """
+        All studies can be identified with an NCT number. This method allows you to fetch one study
+        
+        Args:
+            nct (str) : eg. NCT06210035
+
+        Returns:
+            dict: the full study record as a dictionary
+
+        Raises:
+            requests.HTTPError: A HTTP error code if something goes wrong, e.g. (404) If study is not found
+        """
+        resp = get_with_retry(f"{self.BASE}/studies/{nct}")
+        return resp.json()
+
+
+    # ---------------------------- #
+    #       Private methods        #
+    # ---------------------------- #
+
+    def _get_api_info(self):
+        """
+        Returns API version and date last updated.
+        """
+        resp = requests.get(f"{self.BASE}/version")
+        resp.raise_for_status()
+        return resp.json()
+
+    def _paginate(self, params):
+        """
+        Handle pagination automatically
+
+        It fetches all pages from the /studies endpoint, by passing the limit using a nextPageToken,
+        and returns a single combined DataFrame.
+
+        Args:
+            params (dict) : Query parameters to send with each request
+
+        Returns:
+            A requests.Response
+        """
+
+        all_dfs = []
+
+        with tqdm(desc="Fetching studies", unit="page") as pbar:
+            while True:
+                resp = get_with_retry(f"{self.BASE}/studies", params=params)
+                data = resp.json()
+
+                studies = data.get("studies", [])
+                if not studies:
+                    break
+
+                all_dfs.append(pd.json_normalize(studies))
+
+                pbar.update(1)
+                pbar.set_postfix({"Found ": sum(len(d) for d in all_dfs)})
+
+                next_token = data.get("nextPageToken")
+                if not next_token:
+                    break
+
+                params["pageToken"] = next_token
+
+
+        if not all_dfs:
+            return pd.DataFrame()
+
+        return pd.concat(all_dfs, ignore_index=True)
+
+    # ---------------------------- #
+    #       Export methods         #
+    # ---------------------------- #
+
+    def to_csv(self, df, filename=None):
+        """
+        Usage:
+            df = ClinicalTrials().get_studies(...
+            ClinicalTrials().to_csv(df, "name.csv")
+
+        Generates a name automatically if you can't come up with one
+        """
+        if not filename:
+            filename = f"studies_{datetime.datetime.now().strftime('%Y%m%d_%H%M%S')}.csv"
+
+        df.to_csv(filename, index=False)
+        print(f"{len(df)} saved to {filename}")
+
+    def to_excel(self, df, filename=None):
+        """
+        Usage:
+            df = ClinicalTrials().get_studies(...
+            ClinicalTrials().to_excel(df, "name.xlsx")
+
+        Generates a name automatically if you can't come up with one
+        """
+        if not filename:
+            filename = f"studies_{datetime.datetime.now().strftime('%Y%m%d_%H%M%S')}.xlsx"
+
+        df.to_excel(filename, index=False)
+        print(f"{len(df)} saved to {filename}")
+
+    def to_json(self, df, filename=None, indent=2):
+        """
+        Usage:
+            df = ClinicalTrials().get_studies(...
+            ClinicalTrials().to_json(df, "name.json")
+
+        Generates a name automatically if you can't come up with one
+        """
+        if not filename:
+            filename = f"studies_{datetime.datetime.now().strftime('%Y%m%d_%H%M%S')}.json"
+
+        df.to_json(filename, orient="records" ,indent=2)
+        print(f"{len(df)} saved to {filename}")
+

pyct/utils.py

@@ -0,0 +1,74 @@
+import time
+import requests
+import sys
+
+def get_with_retry(url, params=None, max_attempts=3, wait=2):
+
+    """
+    Instead of attempting to retrieve studies and failing,
+    This enables you to retry until successful.
+
+    Args:
+        url (str) : The base URL for the API
+
+        params (dict) : The parameters for the search may include condition, interventions etc
+
+        max_attempts (int)
+
+        wait (int) : how long you wait between each attempt in seconds
+
+    Returns:
+
+        request.Response : can then be maniuplated as a pandas dataframe
+
+    Raises:
+        If all else fails, a HTTPError is raised, with the last error printed to terminal
+        
+    """
+
+    last_error = None
+
+    for attempt in range(1, max_attempts+1):
+
+        try:
+            resp = requests.get(url, params=params)
+            resp.raise_for_status()
+            print(f"Succeeded in {attempt}/{max_attempts} attempts")
+            return resp
+
+        except requests.HTTPError as e:
+            last_error = e
+            status_code = e.response.status_code
+
+            # Retrying 4xx errors e.g. 404 or 400 won't succeed
+            # ...Except for error 429 which is 'too many requests'
+
+            if 400 <= status_code < 500 and status_code != 429:
+                raise
+
+            print(f"Attempt {attempt}/{max_attempts} has failed with {status_code}")
+
+            waiting(wait)
+
+        except requests.ConnectionError as e:
+            last_error = e
+            print(f"Attempt {attempt}/{max_attempts} failed due to a connection error")
+
+            waiting(wait)
+
+        except requests.Timeout as e:
+            last_error = e
+            print(f"Attempt {attempt}/{max_attempts} failed, request timed out") 
+
+    raise requests.HTTPError(f"{max_attempts}/{max_attempts} attemps failed :(\nLast Error:\n\t{last_error} ")
+
+def waiting(wait):
+    """
+    Procedure for the waiting text 'animation'
+    """
+    while wait > 0:
+        sys.stdout.write("\r" + f"Retrying in {wait}s")
+        time.sleep(1)
+        wait -= 1
+        sys.stdout.flush()
+    print()