jinko-sdk 0.3.4__tar.gz

jinko_sdk-0.3.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Nova In Silico
+
+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.

jinko_sdk-0.3.4/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.1
+Name: jinko-sdk
+Version: 0.3.4
+Summary: A Python package containing jinko_helpers, jinko_stats, and crabbit modules aimed to be used with Jinko.ai API
+Author: SSE Team
+Author-email: oss@novainsilico.ai
+Requires-Python: >=3.10
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: black (>=24.4.2,<25.0.0)
+Requires-Dist: pandas (>=2.2.2,<3.0.0)
+Requires-Dist: requests (>=2.25.1,<3.0.0)
+Requires-Dist: tqdm (>=4.66.5,<5.0.0)
+Description-Content-Type: text/markdown
+
+# Jinko API Helpers
+
+Python helpers function to ease use of Jinko's API
+
+Jinko is an innovative SaaS and CaaS platform focused on trial simulation and design optimization. The Jinko API offers programmatic access to a wide range of functionalities, facilitating integration with various tools and enhancing collaboration.
+
+## Usage
+
+```sh
+pip install git+https://github.com/novainsilico/jinko-api-helpers-python.git
+
+# Or
+
+poetry add git+https://github.com/novainsilico/jinko-api-helpers-python.git
+
+```
+
+```python
+import jinko_helpers as jinko
+
+# Connect to Jinko
+jinko.initialize(
+    projectId='016140de-1753-4133-8cbf-e67d9a399ec1',
+    apiKey='50b5085e-3675-40c9-b65b-2aa8d0af101c'
+)
+
+# Check authentication
+response = jinko.makeRequest('/app/v1/auth/check')
+
+# Make a few requests
+projectItem = jinko.makeRequest(
+    '/app/v1/project-item/tr-EUsp-WjjI',
+    method='GET',
+).json()
+
+```
+
+
+
+
+Find out more at [Jinko Doc](https://doc.jinko.ai)
+

jinko_sdk-0.3.4/README.md

@@ -0,0 +1,41 @@
+# Jinko API Helpers
+
+Python helpers function to ease use of Jinko's API
+
+Jinko is an innovative SaaS and CaaS platform focused on trial simulation and design optimization. The Jinko API offers programmatic access to a wide range of functionalities, facilitating integration with various tools and enhancing collaboration.
+
+## Usage
+
+```sh
+pip install git+https://github.com/novainsilico/jinko-api-helpers-python.git
+
+# Or
+
+poetry add git+https://github.com/novainsilico/jinko-api-helpers-python.git
+
+```
+
+```python
+import jinko_helpers as jinko
+
+# Connect to Jinko
+jinko.initialize(
+    projectId='016140de-1753-4133-8cbf-e67d9a399ec1',
+    apiKey='50b5085e-3675-40c9-b65b-2aa8d0af101c'
+)
+
+# Check authentication
+response = jinko.makeRequest('/app/v1/auth/check')
+
+# Make a few requests
+projectItem = jinko.makeRequest(
+    '/app/v1/project-item/tr-EUsp-WjjI',
+    method='GET',
+).json()
+
+```
+
+
+
+
+Find out more at [Jinko Doc](https://doc.jinko.ai)

jinko_sdk-0.3.4/crabbit/__init__.py

@@ -0,0 +1,5 @@
+"""
+crabbit package initialization.
+
+This package provides utilities for biomodelers for interacting with the Jinko API.
+"""

jinko_sdk-0.3.4/crabbit/__main__.py

@@ -0,0 +1,31 @@
+import argparse
+
+from crabbit import launcher
+from crabbit.utils import bold_text
+
+
+def get_usage():
+    """Show usage of the "crabbit" app."""
+    return (
+        bold_text("python -m crabbit {mode} {URL} {path}")
+        + f"\n\nexample: {bold_text('python -m crabbit download https://jinko.ai/my-project-item my-project/download-folder')}"
+    )
+
+
+# parse the command line arguments
+parser = argparse.ArgumentParser(usage=get_usage())
+parser.add_argument(
+    "mode",
+    choices=["download", "launch"],
+    help='The running mode of crabbit: currently only "download" mode is available.',
+)
+parser.add_argument("url", help="URL of the jinko project item or jinko folder.")
+parser.add_argument(
+    "path",
+    help="Path to the local working folder of crabbit, e.g. folder for downloading the results of a trial.",
+)
+crab = launcher.CrabbitAppLauncher()
+parser.parse_args(namespace=crab)
+
+# run the app launcher
+crab.run()

jinko_sdk-0.3.4/crabbit/cli.py

@@ -0,0 +1,330 @@
+"""Module containing the command-line apps of crabbit."""
+
+__all__ = ["CrabbitDownloader"]
+
+import os
+import json
+import zipfile
+import io
+import requests
+import pandas as pd
+
+import jinko_helpers as jinko
+from crabbit.utils import bold_text
+
+
+class CrabbitDownloader:
+    """CLI app for running the crabbit "download" mode."""
+
+    def __init__(self, project_item, output_path):
+        self.project_item = project_item
+        self.output_path = output_path
+        self.core_id = (
+            self.project_item["coreId"] if "coreId" in self.project_item else ""
+        )
+
+        self.pretty_patient_name = (
+            "CalibratedPatient"  # nice name to be used in calibration visualization
+        )
+
+    def run(self):
+        """Main function of the download app."""
+        if (
+            not self.check_valid_item_type()
+            or not self.check_calib_status()
+            or not self.download_calib_inputs()
+        ):
+            return
+        if self.project_item["type"] == "Calibration":
+            best_patient = self.find_best_calib_patient()
+            if best_patient is None:
+                return
+            self.download_calib_patient_timeseries(best_patient)
+            self.download_calib_patient_scalar_results(best_patient)
+            print(
+                bold_text("Done!"), f"To visualize: crabbit trialViz {self.output_path}"
+            )
+        else:  # placeholder for future download types
+            pass
+
+    def check_valid_item_type(self):
+        """Check whether the project item can be downloaded (currently only "Calibration" is supported) and get its CoreItemId."""
+        if (
+            "type" not in self.project_item
+            or self.project_item["type"] != "Calibration"
+            or not self.core_id
+        ):
+            print(
+                'Currently "crabbit download" only supports the "Calibration" item type.'
+            )
+            return False
+        print(
+            bold_text(
+                'Note: for the "Calibration" item type, only the results of the "best patient", i.e. highest optimizationWeightedScore, will be downloaded.'
+            ),
+            end="\n\n",
+        )
+        return True
+
+    def check_calib_status(self):
+        """Check whether the calibration can be downloaded depending on its status."""
+        status = jinko.get_calib_status(self.core_id)
+        if not status:
+            return False
+        elif status == "not_launched":
+            print("Error: calibration is not launched! (is it the correct version?)")
+            return False
+        elif status != "completed":
+            print("Warning: the status of the calibration is", status)
+        return True
+
+    def find_best_calib_patient(self):
+        """Return the "patientNumber" of the best calibration patient, i.e. highest optimizationWeightedScore."""
+        print("Finding the ID of the best calib patient...")
+        response = jinko.make_request(
+            path=f"/core/v2/result_manager/calibration/sorted_patients",
+            method="POST",
+            json={
+                "calibId": {
+                    "coreItemId": self.core_id["id"],
+                    "snapshotId": self.core_id["snapshotId"],
+                },
+                "sortBy": "optimizationWeightedScore",
+            },
+        )
+        if not response.json():
+            print("Warning: best patient cannot be found! (is it the correct version?)")
+            return None
+        best_patient = response.json()[0]["patientNumber"]
+        print("Best patient is", best_patient, end="\n\n")
+        return best_patient
+
+    def download_calib_inputs(self):
+        """Download calibration inputs (currently only scorings and data tables are downloaded)."""
+        csv_data = {}
+        json_data = []
+        try:
+            response = jinko.make_request(
+                path=f"/core/v2/calibration_manager/calibration/{self.core_id['id']}/snapshots/{self.core_id['snapshotId']}/bundle",
+                method="GET",
+            )
+            archive = zipfile.ZipFile(io.BytesIO(response.content))
+            for item in archive.namelist():
+                if item.startswith("data_tables"):
+                    if not item.endswith(".csv"):
+                        continue
+                    csv_data[item.split("/")[1]] = pd.read_csv(
+                        io.StringIO(archive.read(item).decode("utf-8")), sep=","
+                    )
+                elif item.startswith("scorings"):
+                    json_data.append(json.loads(archive.read(item).decode("utf-8")))
+        except requests.exceptions.HTTPError:
+            print(
+                "Error: failed to download calibration inputs (scorings and data tables)."
+            )
+            return False
+        assert (
+            json_data or csv_data
+        ), "Something wrong happened (calibration without scoring nor data table)."
+        if json_data:
+            merged_json_scorings = {
+                "objectives": sum((item["objectives"] for item in json_data), [])
+            }
+            if merged_json_scorings["objectives"]:
+                json_path = os.path.join(self.output_path, "Scorings.json")
+                json.dump(merged_json_scorings, open(json_path, "w", encoding="utf-8"))
+        if csv_data:
+            try:
+                merged_csv_data = pd.concat(csv_data.values(), ignore_index=True)
+                # when data tables can be merged, save them in one single file
+                merged_csv_data.to_csv(
+                    os.path.join(self.output_path, "ReferenceTimeSeries.csv"),
+                    index=False,
+                )
+            except:
+                try:
+                    # trim the data tables to the minimum columns then try merge again
+                    trimmed_csv = []
+                    mandatory_columns = [
+                        "armScope",
+                        "obsId",
+                        "time",
+                        "value",
+                        "narrowRangeLowBound",
+                        "narrowRangeHighBound",
+                        "wideRangeLowBound",
+                        "wideRangeHighBound",
+                    ]
+                    for csv_name, csv_df in csv_data.items():
+                        data_table_id = csv_name.split(".csv")[0]
+                        sub_csv_df = csv_df.loc[:, mandatory_columns]
+                        sub_csv_df["dataTableID"] = data_table_id
+                        trimmed_csv.append(sub_csv_df)
+                    merged_csv_data = pd.concat(trimmed_csv, ignore_index=True)
+                    # when data tables can be merged, save them in one single file
+                    merged_csv_data.to_csv(
+                        os.path.join(self.output_path, "ReferenceTimeSeries.csv"),
+                        index=False,
+                    )
+                except:
+                    # if still cannot merge, save the data table separately
+                    for csv_name, csv_df in csv_data.items():
+                        csv_df.to_csv(
+                            os.path.join(self.output_path, csv_name), index=False
+                        )
+        print("Downloaded calibration inputs (scorings and data tables).", end="\n\n")
+        return True
+
+    def download_calib_patient_timeseries(self, patient_id):
+        """Download one calibration patient's timeseries."""
+        print("Downloading the timeseries of the best calib patient...")
+        timeseries_path = os.path.join(self.output_path, "ModelResult")
+        os.mkdir(timeseries_path)
+        arms = []
+        try:
+            response = jinko.make_request(
+                path=f"/core/v2/result_manager/calibration/model_result",
+                method="POST",
+                json={
+                    "calibId": {
+                        "coreItemId": self.core_id["id"],
+                        "snapshotId": self.core_id["snapshotId"],
+                    },
+                    "patientId": patient_id,
+                },
+            )
+            for arm_item in response.json():
+                arm_name = arm_item["group"][0]["contents"]
+                arms.append(arm_name)
+                assert (
+                    arm_item["indexes"]["patientNumber"] == patient_id
+                ), "Something wrong happened (patient number mismatch between requests)!"
+                result_path = os.path.join(
+                    timeseries_path, f"{self.pretty_patient_name}_{arm_name}.json"
+                )
+                json.dump(
+                    {"res": arm_item["res"]}, open(result_path, "w", encoding="utf-8")
+                )
+        except (requests.exceptions.HTTPError, TypeError, KeyError):
+            print("Error: failed to download the timeseries.")
+            return
+        arm_count = len(arms)
+        print(
+            f'Successfully downloaded the timeseries of {arm_count} protocol arm{"s" if arm_count > 1 else ""}.',
+            end="\n\n",
+        )
+
+    def download_calib_patient_scalar_results(self, patient_id):
+        """Download one calibration patient's scalar results (into scalar arrays, categorical arrays and scalar metadata)."""
+        print("Downloading the scalar results of the best calib patient...")
+        scalar_array_path = os.path.join(self.output_path, "ScalarArrays")
+        categorical_array_path = os.path.join(self.output_path, "CategoricalArrays")
+        metadata_path = os.path.join(self.output_path, "ScalarMetaData.json")
+        os.mkdir(scalar_array_path)
+        os.mkdir(categorical_array_path)
+        scalars, categoricals, scalars_cross, categoricals_cross = {}, {}, {}, {}
+        arms = set()
+        try:
+            response = jinko.make_request(
+                path=f"/core/v2/result_manager/calibration/scalar_result",
+                method="POST",
+                json={
+                    "calibId": {
+                        "coreItemId": self.core_id["id"],
+                        "snapshotId": self.core_id["snapshotId"],
+                    },
+                    "patientId": patient_id,
+                },
+            )
+            response = response.json()
+            for (
+                response_subtype,
+                multi_field,
+                array_path,
+                metadata_dict,
+                cross_metadata_dict,
+                has_unit,
+            ) in zip(
+                ["outputs", "outputsCategorical"],
+                ["scalarValues", "categoricalLevels"],
+                [scalar_array_path, categorical_array_path],
+                [scalars, categoricals],
+                [scalars_cross, categoricals_cross],
+                [True, False],
+            ):
+                for arm_item in response[response_subtype]:
+                    arm_name = arm_item["group"][0]["contents"]
+                    is_cross = arm_name == "crossArms"
+                    if not is_cross:
+                        arms.add(arm_name)
+                    assert (
+                        arm_item["indexes"]["patientNumber"] == patient_id
+                    ), "Something wrong happened (patient number mismatch between requests)!"
+                    scalar_array = []
+                    for one_scalar in arm_item["res"]:
+                        # fetch scalar metadata
+                        scalar_id = one_scalar["id"]
+                        scalar_unit = (
+                            one_scalar["unit"] if "unit" in one_scalar else None
+                        )
+                        if is_cross:
+                            if scalar_id not in cross_metadata_dict:
+                                cross_metadata_dict[scalar_id] = {
+                                    "description": None,
+                                    "id": scalar_id,
+                                    "type": one_scalar["type"],
+                                }
+                                if has_unit:
+                                    cross_metadata_dict[scalar_id]["unit"] = scalar_unit
+                        else:
+                            if scalar_id not in metadata_dict:
+                                metadata_dict[scalar_id] = {
+                                    "arms": set(),
+                                    "description": None,
+                                    "id": scalar_id,
+                                    "type": one_scalar["type"],
+                                }
+                                if has_unit:
+                                    metadata_dict[scalar_id]["unit"] = scalar_unit
+                            metadata_dict[scalar_id]["arms"].add(arm_name)
+
+                        # turn the scalar array record into multi-patient format
+                        one_scalar[multi_field] = []
+                        one_scalar["errors"] = []
+                        if "value" in one_scalar:
+                            one_scalar[multi_field] = [one_scalar["value"]]
+                            del one_scalar["value"]
+                        if "error" in one_scalar:
+                            one_scalar["errors"] = [one_scalar["error"]]
+                            del one_scalar["error"]
+                        scalar_array.append(one_scalar)
+
+                    # save the scalar array
+                    result_path = os.path.join(array_path, f"{arm_name}.json")
+                    json.dump(scalar_array, open(result_path, "w", encoding="utf-8"))
+
+        except (requests.exceptions.HTTPError, TypeError, KeyError):
+            print("Error: failed to download the scalar results.")
+            return
+
+        # save the scalar metadata
+        metadata_json = {"arms": list(arms), "patients": [self.pretty_patient_name]}
+        for metadata_dict, metadata_array in zip(
+            [scalars, categoricals, scalars_cross, categoricals_cross],
+            ["scalars", "categoricals", "scalarsCrossArm", "categoricalsCrossArm"],
+        ):
+            metadata_json[metadata_array] = []
+            # flatten the metadata dict (scalarID-indexed) into array
+            for scalar_id, one_scalar_metadata in metadata_dict.items():
+                if "arms" in one_scalar_metadata:
+                    one_scalar_metadata["arms"] = list(one_scalar_metadata["arms"])
+                metadata_json[metadata_array].append(
+                    {"id": scalar_id} | one_scalar_metadata
+                )
+        json.dump(metadata_json, open(metadata_path, "w", encoding="utf-8"))
+
+        arm_count = len(arms)
+        print(
+            f'Successfully downloaded the scalar results of {arm_count} protocol arm{"s" if arm_count > 1 else ""}.',
+            end="\n\n",
+        )

jinko_sdk-0.3.4/crabbit/launcher.py

@@ -0,0 +1,53 @@
+"""Crabbit app launcher module."""
+
+__all__ = ["CrabbitAppLauncher"]
+
+import os
+import requests
+
+import jinko_helpers as jinko
+import crabbit.cli as cli
+from crabbit.utils import bold_text, clear_directory, get_sid_revision_from_url
+
+
+class CrabbitAppLauncher:
+    """Crabbit app launcher, connecting argparse to cli apps (and gui apps in the future)."""
+
+    def __init__(self):
+        self.mode = ""
+        self.url = ""
+        self.path = ""
+
+    def run(self):
+        self.path = os.path.abspath(self.path)
+        try:
+            jinko.initialize()
+        except:
+            return
+
+        if self.mode == "download":
+            project_item = self.check_project_item_url()
+            if project_item is None:
+                return
+            crab = cli.CrabbitDownloader(project_item, self.path)
+            print(
+                "Downloading jinko project item", self.url, "to", self.path, end="\n\n"
+            )
+            if clear_directory(self.path):
+                crab.run()
+        else:
+            print(f'The mode "{self.mode}" is still under development!')
+
+    def check_project_item_url(self):
+        """Get the project item from URL or print a nice error message."""
+        message = f'{bold_text("Error:")} {self.url} is not a valid project item URL!'
+        sid, revision = get_sid_revision_from_url(self.url)
+        if sid is None:
+            print(message)
+            return None
+        try:
+            project_item = jinko.get_project_item(sid, revision)
+        except requests.exceptions.HTTPError:
+            print(message)
+            return None
+        return project_item

jinko_sdk-0.3.4/crabbit/utils.py

@@ -0,0 +1,100 @@
+"""Utility functions used in the crabbit package."""
+
+__all__ = [
+    "get_sid_revision_from_url",
+    "bold_text",
+    "clear_directory",
+    "get_calib_status",
+]
+
+import shutil
+import os
+import re
+import requests
+
+import jinko_helpers as jinko
+
+
+def get_sid_revision_from_url(url):
+    """Return the sid and revision number from a jinko URL."""
+    # start with a generic URL match
+    pattern = (
+        r"^"
+        r"((?P<schema>.+?)://)?"
+        r"(?P<host>.*?)"
+        r"(:(?P<port>\d+?))?"
+        r"(/(?P<path>.*?))?"
+        r"(?P<query>[?].*?)?"
+        r"$"
+    )
+    regex = re.compile(pattern)
+    match = regex.match(url)
+    if match is None:
+        return None, None
+    # sid should directly follow the base URL
+    path = match.groupdict()["path"]
+    if not path or "/" in path:
+        return None, None
+    sid = path
+    # revision number should be an integer
+    query = match.groupdict()["query"]
+    try:
+        revision = int(query.split("revision=")[1]) if query is not None else None
+    except ValueError:
+        revision = None
+    return sid, revision
+
+
+def bold_text(text):
+    """Return bold text to print in console application."""
+    return "\033[1m" + text + "\033[0m"
+
+
+def clear_directory(directory):
+    """Remove files and folders, so that the directory becomes empty (except for hidden files)."""
+    if not os.path.exists(directory):
+        print("(The folder does not exist; it will be created.)")
+        os.makedirs(directory, exist_ok=True)
+        return True
+
+    old_files = []
+    old_dirs = []
+    try:
+        with os.scandir(directory) as it:
+            for entry in it:
+                if not entry.name.startswith(".") and entry.is_file():
+                    old_files.append(entry)
+                elif entry.is_dir():
+                    old_dirs.append(entry)
+    except NotADirectoryError:
+        print('Error: the output path is not a folder')
+        return False
+    if not old_files and not old_dirs:
+        return True
+
+    max_tries = 5
+    k = 0
+    while k < max_tries:
+        print(
+            "Folder already exists! Do you want to clean it up (existing content will be removed)? (y/n)",
+            end=" ",
+        )
+        answer = input()
+        if answer == "n":
+            return False
+        elif answer == "y":
+            try:
+                for entry in old_files:
+                    os.remove(entry)
+                for entry in old_dirs:
+                    shutil.rmtree(entry)
+            except:
+                print(
+                    "Something wrong happened when cleaning the folder (maybe some files are locked by other application?)!"
+                )
+                return False
+            return True
+        k += 1
+    return False
+
+