simple_sams_api 0.1.0__py3-none-any.whl

simple_sams_api/__init__.py

@@ -0,0 +1,6 @@
+from .base import (
+    SAMSapi,
+    extract_HPO_terms_from_phenopacket,
+    extract_disease_terms_from_phenopacket,
+    filter_phenopacket_by_onset,
+)

simple_sams_api/base.py

@@ -0,0 +1,200 @@
+from typing import List
+import requests
+from dataclasses import dataclass, field
+import logging
+
+logger = logging.getLogger(__name__)
+
+SAMS_URL = "https://www.genecascade.org/sams-cgi"
+LOGIN_URL = f"{SAMS_URL}/login.cgi"
+EXPORT_PHENOPACKETS_URL = f"{SAMS_URL}/ExportPhenopacket.cgi?export_all=1"
+EXPORT_PHENOPACKET_BY_ID_URL = (
+    f"{SAMS_URL}/export_phenopacket.cgi?external_id={{patient_id}}"
+)
+
+
+@dataclass
+class SAMSapi:
+    session: requests.Session = field(default_factory=requests.Session)
+    phenopackets: dict = None
+
+    @property
+    def loggedIn(self):
+        return "SAMSI" in self.session.cookies
+
+    def _login(self, username, password):
+        data = {"email": username, "password": password}
+        resp = self.session.post(LOGIN_URL, data=data)
+        resp.raise_for_status()
+
+    def login_with_credentials_file(self, credentials_file: str):
+        """Login to SAMS using credentials from a file
+
+        Args:
+            credentials_file (str): Path to the file containing the credentials (first line username, second line password)
+
+        Returns:
+            SAMS: Instance of SAMS
+        """
+        with open(credentials_file) as f:
+            username, password = [l.strip() for l in f.readlines()]
+        self._login(username, password)
+
+    def login_with_username(self, username: str, password: str):
+        """Login to SAMS using username and password
+
+        Args:
+            username (str): Name of the user
+            password (str): Password of the user
+
+        Returns:
+            SAMS: Instance of SAMS
+        """
+        self._login(username, password)
+
+    def get_phenopackets(self) -> List[dict]:
+        """Load all phenopackets from SAMS for the current user
+
+        Returns:
+            List[dict]: List of phenopackets
+        """
+        resp = self.session.get(EXPORT_PHENOPACKETS_URL)
+        resp.raise_for_status()
+        all_data = resp.json()
+        return all_data
+
+    def get_phenopacket(self, patient_id: str) -> dict:
+        """Get phenopacket for a specific patient
+
+        Args:
+            patient_id (str): ID of the patient
+
+        Raises:
+            RuntimeError: If the phenopacket for the patient could not be found
+
+        Returns:
+            dict: Phenopacket for the patient
+        """
+        resp = self.session.get(
+            EXPORT_PHENOPACKET_BY_ID_URL.format(patient_id=patient_id)
+        )
+        resp.raise_for_status()
+        patient_data = resp.json()
+        if patient_data["subject"]["id"] != patient_id:
+            raise RuntimeError(
+                f"Failed to obtain phenopacket for external id {patient_id}"
+            )
+        return patient_data
+
+
+def extract_HPO_terms_from_phenopacket(
+    phenopacket: dict, ignore_excluded: bool = True
+) -> str:
+    """Extract HPO terms of a given phenopacket
+
+    Args:
+        phenopacket (dict): Phenopacket containing phenotypic features
+        ignore_excluded (bool, optional): Whether to ignore excluded phenotypic features. Defaults to True.
+
+    Returns:
+        str: String of HPO terms for the phenopacket in the format "HP:0000001 - Phenotype 1; HP:0000002 - Phenotype 2; ..."
+             If feature is excluded, it will be marked as "HP:0000001 - Phenotype 1 (excluded)"
+    """
+    # Check if key exists
+    if "phenotypicFeatures" not in phenopacket:
+        sams_entry = phenopacket["subject"]["id"]
+        logger.warning(f"SAMS: No phenotypicFeatures found for {sams_entry}")
+        return ""
+
+    else:
+        phenotypes = phenopacket["phenotypicFeatures"]  # Get HPO terms from phenopacket
+
+        pheno_strings = []
+        for feature in phenotypes:
+            pheno_string = f"{feature['type']['id']} - {feature['type']['label']}"
+
+            if feature.get("excluded", 0):
+                if ignore_excluded:
+                    continue
+                else:
+                    pheno_string += " (excluded)"
+
+            pheno_strings.append(pheno_string)
+
+        return "; ".join(pheno_strings)
+
+
+def extract_disease_terms_from_phenopacket(
+    phenopacket: dict, ignore_excluded: bool = True
+) -> str:
+    """Extract disease terms (OMIM, ORPHANET)of a given phenopacket
+
+    Args:
+        phenopacket (dict): Phenopacket containing diseases
+        ignore_excluded (bool, optional): Whether to ignore excluded diseases. Defaults to True.
+
+    Returns:
+        str: String of disease terms for the phenopacket in the format "OMIM:0000001 - Disease 1; OMIM:0000002 - Disease 2; ..."
+    """
+    if "diseases" not in phenopacket:
+        sams_entry = phenopacket["subject"]["id"]
+        logger.warning(f"SAMS: No diseases found for {sams_entry}")
+        return ""
+
+    else:
+        diseases = phenopacket["diseases"]  # Get disease terms from phenopacket
+
+        disease_strings = []
+        for disease in diseases:
+            disease_string = f"{disease['term']['id']} - {disease['term']['label']}"
+
+            if disease.get("excluded", 0):
+                if ignore_excluded:
+                    continue
+                else:
+                    disease_string += " (excluded)"
+
+            disease_strings.append(disease_string)
+        return "; ".join(disease_strings)
+
+
+def filter_phenopacket_by_onset(phenopacket: dict, input_onset_timestamp: str) -> dict:
+    """Filter phenopacket by onset timestamp
+
+    Args:
+        phenopacket (dict): Phenopacket containing phenotypic features
+        input_onset_timestamp (str): Onset timestamp to filter by (e.g. "2026-02-12T00:00:00Z")
+        If set to "earliest", it will filter by the earliest onset timestamp in the phenopacket,
+        If set to "latest", it will filter by the latest onset timestamp in the phenopacket
+
+    Returns:
+        dict: Filtered phenopacket containing only phenotypic features with the given onset timestamp
+    """
+
+    def compute_onset_timestamp(onset: str) -> str:
+        if onset == "earliest":
+            onset = min(
+                feature["onset"]["timestamp"]
+                for feature in phenopacket.get("phenotypicFeatures", [])
+            )
+        elif onset == "latest":
+            onset = max(
+                feature["onset"]["timestamp"]
+                for feature in phenopacket.get("phenotypicFeatures", [])
+            )
+        return onset
+
+    onset_timestamp = compute_onset_timestamp(input_onset_timestamp)
+
+    filered_phenotypes = []
+    filtered_diseases = []
+    for feature in phenopacket.get("phenotypicFeatures", []):
+        if feature["onset"]["timestamp"] == onset_timestamp:
+            filered_phenotypes.append(feature)
+    for disease in phenopacket.get("diseases", []):
+        if disease["onset"]["timestamp"] == onset_timestamp:
+            filtered_diseases.append(disease)
+
+    phenopacket["phenotypicFeatures"] = filered_phenotypes
+    phenopacket["diseases"] = filtered_diseases
+    return phenopacket

simple_sams_api-0.1.0.dist-info/METADATA

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: simple_sams_api
+Version: 0.1.0
+Summary: A simple Python API for interacting with the SAMS system
+Author-email: Oliver Küchler <oliver.kuechler@charite.de>
+License: MIT License
+        
+        Copyright (c) [year] [fullname]
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Project-URL: Homepage, https://github.com/Kuechler/simple_sams_api
+Project-URL: Documentation, https://github.com/KuechlerO/simple_sams_api#readme
+Project-URL: Source, https://github.com/KuechlerO/simple_sams_api
+Project-URL: Tracker, https://github.com/KuechlerO/simple_sams_api/issues
+Keywords: SAMS,API,phenopacket,bioinformatics
+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 :: Bio-Informatics
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Dynamic: license-file
+
+# Simple SAMS API
+
+This module provides a Python interface for interacting with the [SAMS](https://www.genecascade.org/sams-cgi/Patients.cgi) (Symptom Annotation Made Simple) web service, allowing you to authenticate, retrieve phenopacket data, and extract relevant medical terms for downstream analysis.
+
+## Features
+- **Authentication**: Login to SAMS using username/password or credentials file.
+- **Phenopacket Retrieval**: Download all phenopackets or a specific phenopacket by patient ID.
+- **HPO Term Extraction**: Extract Human Phenotype Ontology (HPO) terms from phenopacket data.
+- **Disease Term Extraction**: Extract disease terms (OMIM, ORPHANET) from phenopacket data.
+- **Onset Filtering**: Filter phenopacket features and diseases by onset timestamp.
+
+## Usage
+
+### Installation
+Simply copy the module into your project and install the required dependencies:
+
+```
+pip install requests
+```
+
+### Example
+```python
+from simple_sams_api.base import SAMSapi, extract_HPO_terms_from_phenopacket
+
+# Initialize API and login
+api = SAMSapi()
+api.login_with_username('your_email', 'your_password')
+
+# Retrieve all phenopackets
+phenopackets = api.get_phenopackets()
+
+# Extract HPO terms from a phenopacket
+hpo_terms = extract_HPO_terms_from_phenopacket(phenopackets[0])
+print(hpo_terms)
+# Example output:  "HP:0000001 - Phenotype 1; HP:0000002 - Phenotype 2; ..."
+```
+
+## API Reference
+
+### Class: `SAMSapi`
+- `login_with_username(username, password)`: Login using username and password.
+- `login_with_credentials_file(credentials_file)`: Login using a credentials file (first line: username, second line: password).
+- `get_phenopackets()`: Retrieve all phenopackets for the current user.
+- `get_phenopacket(patient_id)`: Retrieve a phenopacket for a specific patient.
+- `loggedIn`: Property indicating login status.
+
+### Functions
+- `extract_HPO_terms_from_phenopacket(phenopacket, ignore_excluded=True)`: Extract HPO terms from a phenopacket.
+- `extract_disease_terms_from_phenopacket(phenopacket, ignore_excluded=True)`: Extract disease terms from a phenopacket.
+- `filter_phenopacket_by_onset(phenopacket, input_onset_timestamp)`: Filter phenopacket features and diseases by onset timestamp ("earliest", "latest", or specific timestamp).
+
+## Testing
+Run `python -m unittest tests/test_base.py`.
+
+## License
+MIT License
+
+## Author
+Oliver Küchler
+
+## Notes
+- Make sure you have access to the SAMS web service and valid credentials.
+- For more details, see the docstrings in the source code.
+- The GitHub Actions workflow is based on: [Using uv in GitHub Actions](https://docs.astral.sh/uv/guides/integration/github/#publishing-to-pypi).

simple_sams_api-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+simple_sams_api/__init__.py,sha256=f7KQ4LYaFbzXQUTMMU0Km9hbP2YSZRJVusnoMfa9WUw,152
+simple_sams_api/base.py,sha256=UbI79tSesCRu990wYZwRuXVFGM9qnhzd92cBOoSF9cs,6845
+simple_sams_api-0.1.0.dist-info/licenses/LICENSE,sha256=pAZXnNE2dxxwXFIduGyn1gpvPefJtUYOYZOi3yeGG94,1068
+simple_sams_api-0.1.0.dist-info/METADATA,sha256=xZEesSp_fbld4dp6yZxtzcr0bdmkxqlC4ID3uwJRuWQ,4791
+simple_sams_api-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+simple_sams_api-0.1.0.dist-info/top_level.txt,sha256=0Kpajvp9FwCfjW-W1lr6oPJox1vCCgc8KWHfi7LALZg,16
+simple_sams_api-0.1.0.dist-info/RECORD,,

simple_sams_api-0.1.0.dist-info/WHEEL

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

simple_sams_api-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [year] [fullname]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

simple_sams_api-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+simple_sams_api