qmenta-client 1.1.dev1326__py3-none-any.whl → 1.1.dev1349__py3-none-any.whl

qmenta/client/Project.py

@@ -200,14 +200,45 @@ def wrap_search_criteria(search_criteria={}):
     return modality, tags, file_metadata
 
 
+def convert_qc_value_to_qcstatus(value):
+    """
+    Convert input string to QCStatus class.
+
+    Parameters
+    ----------
+    value : str
+        Value to convert.
+
+    Returns
+    -------
+    QCStatus or Bool
+        QCStatus.PASS, QCStatus.FAIL or QCStatus.UNDETERMINED
+        False if the Value cannot be convered.
+    """
+    logger = logging.getLogger(logger_name)
+    if value == "pass":
+        return QCStatus.PASS
+    elif value == "fail":
+        return QCStatus.FAIL
+    elif value == "":
+        return QCStatus.UNDERTERMINED
+    else:
+        logger.error(f"The input value '{value}' cannot be converted "
+                     f"to class QCStatus.")
+        return False
+
+
 class QCStatus(Enum):
     """
     Enum with the following options:
-    FAIL, PASS
+    FAIL, PASS, UNDERTERMINED
+    that are the possible options for the QA/QC status of both
+    analysis and session.
     """
 
     PASS = "pass"
     FAIL = "fail"
+    UNDERTERMINED = ""
 
 
 class Project:
@@ -644,10 +675,27 @@ class Project:
         return data["fields"]
 
     def get_analysis(self, analysis_name_or_id):
+        """
+        Returns the analysis corresponding with the analysis id or analysis name
+
+        Parameters
+        ----------
+        analysis_name_or_id : int, str
+            analysis_id or analysis name to search for
+
+        Returns
+        -------
+        analysis: dict
+            A dictionary containing the analysis information
+        """
         if isinstance(analysis_name_or_id, int):
             search_tag = "id"
         elif isinstance(analysis_name_or_id, str):
-            search_tag = "p_n"
+            if analysis_name_or_id.isdigit():
+                search_tag = "id"
+                analysis_name_or_id = int(analysis_name_or_id)
+            else:
+                search_tag = "p_n"
         else:
             raise Exception("The analysis identifier must be its name or an " "integer")
 
@@ -667,32 +715,37 @@ class Project:
 
     def list_analysis(self, search_condition={}, items=(0, 9999)):
         """
-        List the analysis available to the user.
-        search condition example:
-        search_condition = {
-        "secret_name":"014_S_6920",
-        "from_d": "06.02.2025",
-        "with_child_analysis": 1,
-        "state": "completed"
+        List the analysis available to the user.\n
+
+        Examples
+        --------
+
+        >>> search_condition = {
+            "secret_name":"014_S_6920",
+            "from_d": "06.02.2025",
+            "with_child_analysis": 1,
+            "state": "completed"
         }
+            list_analysis(search_condition=search_condition)
 
         Parameters
         ----------
         search_condition : dict
-            p_n: str # analysis_name
-            type: str # analysis_type
-            from_d: str #  dd.mm.yyyy
-            to_d: str # dd.mm.yyyy
-            qa_status: str # pass/fail/nd
-            secret_name: str # Subject_ID
-            tags: str #
-            with_child_analysis: 1
-            # if 1, child analysis of workflows will appear
-            id: str # container_id
-            state: # running, completed, pending, exception
-            username: str #
-        limit : int
-            Max number of results
+            - p_n: str Analysis name
+            - type: str Type
+            - from_d: str  dd.mm.yyyy Date from
+            - to_d: str dd.mm.yyyy Date to
+            - qa_status: str pass/fail/nd QC status
+            - secret_name: str Subject ID
+            - tags: str
+            - with_child_analysis: 1 if 1, child analysis of workflows will appear
+            - id: str ID
+            - state: running, completed, pending, exception
+            - username: str
+
+        items : List[int]
+            list containing two elements [min, max] that correspond to the
+            mininum and maximum range of analysis listed
 
         Returns
         -------
@@ -811,23 +864,48 @@ class Project:
         ]
         return containers
 
-    def list_result_containers(self, limit=1000):
+    def list_result_containers(self, search_condition={}, items=(0, 9999)):
         """
         List the result containers available to the user.
+        Examples
+        --------
+
+        >>> search_condition = {
+            "secret_name":"014_S_6920",
+            "from_d": "06.02.2025",
+            "with_child_analysis": 1,
+            "state": "completed"
+        }
+            list_result_containers(search_condition=search_condition)
 
         Parameters
         ----------
-        limit : int
-            Max number of results
+        search_condition : dict
+            - p_n: str Analysis name
+            - type: str Type
+            - from_d: str  dd.mm.yyyy Date from
+            - to_d: str dd.mm.yyyy Date to
+            - qa_status: str pass/fail/nd QC status
+            - secret_name: str Subject ID
+            - tags: str
+            - with_child_analysis: 1 if 1, child analysis of workflows will appear
+            - id: str ID
+            - state: running, completed, pending, exception
+            - username: str
+        items : List[int]
+            list containing two elements [min, max] that correspond to the
+            mininum and maximum range of analysis listed
 
         Returns
         -------
         dict
             List of containers, each a dictionary
             {"name": "container-name", "id": "container_id"}
+            if "id": None, that analysis did not had an output container,
+            probably it is a workflow
         """
-        analysis = self.list_analysis(limit)
-        return [{"name": a["name"], "id": a["out_container_id"]} for a in analysis]
+        analyses = self.list_analysis(search_condition, items)
+        return [{"name": analysis["name"], "id": (analysis.get("out_container_id") or None)} for analysis in analyses]
 
     def list_container_files(
         self,
@@ -1841,7 +1919,8 @@ class Project:
                 modalities.append(modality)
         return modalities
 
-    def set_qc_status(self, analysis_id, status=QCStatus.PASS, comments=""):
+    def set_qc_status_analysis(self, analysis_id,
+                               status=QCStatus.UNDERTERMINED, comments=""):
         """
         Changes the analysis QC status.
 
@@ -1850,85 +1929,257 @@ class Project:
         analysis_id : int
             Analysis ID number
         status : QCStatus
-            QCStatus.PASS or QCStatus.FAIL
+            QCStatus.PASS, QCStatus.FAIL or QCStatus.UNDETERMINED
         comments : str, optional
-            Additional comments explaining why the QC status has been
-            set to pass or fail.
+            Additional comments explaining why the reasoning of setting the
+            QC status to such state.
+
+        Returns
+        -------
+        bool
+            True if the QC status was correctly changed, False otherwise.
         """
+
         logger = logging.getLogger(__name__)
         logger.info(f"Setting QC status to {status}: {comments}")
 
-        platform.parse_response(
-            platform.post(
-                auth=self._account.auth,
-                endpoint="projectset_manager/set_qa_status",
-                data={"item_ids": analysis_id, "status": status.value, "comments": comments, "entity": "analysis"},
+        if not isinstance(status, QCStatus):
+            raise ValueError("Status should be type 'QCStatus'.")
+
+        try:
+            analysis_id = str(int(analysis_id))
+        except ValueError:
+            raise ValueError(f"analysis_id: '{analysis_id}' not valid. " f"Must be convertible to int.")
+
+        try:
+            platform.parse_response(
+                platform.post(
+                    auth=self._account.auth,
+                    endpoint="projectset_manager/set_qa_status",
+                    data={"item_ids": analysis_id, "status": status.value,
+                          "comments": str(comments), "entity": "analysis"},
+                )
             )
-        )
+        except Exception:
+            logger.error(f"It was not possible to change the QC status of"
+                         f"Analysis ID: {analysis_id}")
+            return False
+        return True
+
+    def set_qc_status_subject(self, patient_id,
+                              status=QCStatus.UNDERTERMINED, comments=""):
+        """
+        Changes the QC status of a Patient ID (equivalent to a
+        Subject ID/Session ID).
+
+        Parameters
+        ----------
+        patient_id : int
+            Patient ID number of the session.
+        status : QCStatus
+            QCStatus.PASS, QCStatus.FAIL or QCStatus.UNDETERMINED
+        comments : str, optional
+            Additional comments explaining why the reasoning of setting the
+            QC status to such state.
+
+        Returns
+        -------
+        bool
+            True if the QC status was correctly changed, False otherwise.
+        """
+        logger = logging.getLogger(__name__)
+        logger.info(f"Setting QC status to {status}: {comments}")
 
-    def get_qc_status(self, patient_secret_name=None, ssid=None, analysis_id=None):
+        if not isinstance(status, QCStatus):
+            raise ValueError("Status should be type 'QCStatus'.")
+
+        try:
+            patient_id = str(int(patient_id))
+        except ValueError:
+            raise ValueError(f"'patient_id': '{patient_id}' not valid. " f"Must be convertible to int.")
+
+        try:
+            platform.parse_response(
+                platform.post(
+                    auth=self._account.auth,
+                    endpoint="projectset_manager/set_qa_status",
+                    data={"item_ids": patient_id, "status": status.value,
+                          "comments": str(comments), "entity": "patients"},
+                )
+            )
+        except Exception:
+            logger.error(f"It was not possible to change the QC status of"
+                         f"Patient ID: {patient_id}")
+            return False
+        return True
+
+    def get_qc_status_analysis(self, analysis_id):
         """
-        Gets the session QC status of a session. If the analysis_id is
-        specified, it returns the QC of the
-        analysis instead.
+        Gets the QC status of an anlaysis provided its Analysis ID.
 
+        Parameters
+        ----------
+        analysis_id : int
+            Analysis ID number
+
+        Returns
+        -------
+        status : QCStatus or False
+            QCStatus.PASS, QCStatus.FAIL or QCStatus.UNDETERMINED
+            False if the status cannot be extracted.
+        comments : str or False
+            Comments defined in the QC Status.
+            False if the comments cannot be extracted.
         """
-        if patient_secret_name and ssid:
+        try:
+            search_criteria = {"id": analysis_id}
+            to_return = self.list_analysis(search_criteria)
+            return convert_qc_value_to_qcstatus(to_return[0]["qa_status"]), to_return[0]["qa_comments"]
+        except IndexError:
+            # Handle the case where no matching analysis is found
+            logging.error(f"No analysis was found with such Analysis ID: '{analysis_id}'.")
+            return False, False
+        except Exception:
+            # Handle other potential exceptions
+            logging.error(f"It was not possible to extract the QC status"
+                          f"from Analysis ID: {analysis_id}")
+            return False, False
+
+    def get_qc_status_subject(self, patient_id=None, subject_name=None,
+                              ssid=None):
+        """
+        Gets the session QC status via the patient ID or the Subject ID
+        and the Session ID.
+
+        Parameters
+        ----------
+        patient_id : int
+            Patient ID number of the session
+        subject_name : string
+            Subject ID of the session
+        ssid : string
+            Session ID
+
+        Returns
+        -------
+        status : QCStatus or False
+            QCStatus.PASS, QCStatus.FAIL or QCStatus.UNDETERMINED
+            False if the status cannot be extracted.
+        comments : str or False
+            Comments defined in the QC Status.
+            False if the comments cannot be extracted.
+        """
+
+        if patient_id:
+            try:
+                patient_id = int(patient_id)
+            except ValueError:
+                raise ValueError(f"patient_id '{patient_id}' should be an "
+                                 f"integer.")
+            sessions = self.get_subjects_metadata(search_criteria={})
+            session = [session for session in sessions if int(session["_id"]) == patient_id]
+            if len(session) < 1:
+                logging.error(f"No session was found with Patient ID: "
+                              f"'{patient_id}'.")
+                return False, False
+            return convert_qc_value_to_qcstatus(session[0]["qa_status"]), session[0]["qa_comments"]
+        elif subject_name and ssid:
             session = self.get_subjects_metadata(
                 search_criteria={
-                    "pars_patient_secret_name": f"string;" f"{patient_secret_name}",
+                    "pars_patient_secret_name": f"string;{subject_name}",
                     "pars_ssid": f"integer;eq|{ssid}",
                 }
             )
-            to_return = session["qa_status"], session["qa_comments"]
-        elif analysis_id:
-            try:
-                to_return = [
-                    analysis["qa_data"] for analysis in self.list_analysis() if analysis["_id"] == analysis_id
-                ][0]
-                to_return = to_return["qa_status"], to_return["qa_comments"]
-            except IndexError:
-                # Handle the case where no matching analysis is found
-                to_return = None
-            except Exception as e:
-                # Handle other potential exceptions
-                print(f"An error occurred: {e}")
-                to_return = None
+            if len(session) < 1:
+                logging.error(f"No session was found with Subject ID: "
+                              f"'{subject_name}' and Session ID: '{ssid}'.")
+                return False, False
+            return convert_qc_value_to_qcstatus(session[0]["qa_status"]), session[0]["qa_comments"]
         else:
-            raise Exception(f"Must specify {patient_secret_name} and {ssid} or {analysis_id}.")
-        return to_return
+            raise ValueError("Either 'patient_id' or 'subject_name' and 'ssid'"
+                             " must not be empty.")
 
-    def set_project_qa_rules(self, rules_file_path, guidance_text=""):
+    def set_project_pa_rules(self, rules_file_path, guidance_text=""):
         """
-        Logs in to the Qmenta platform, retrieves the project ID based on the project name,
-        and updates the project's QA rules using the provided rules file.
+        Updates the active project's protocol adherence rules using the
+        provided rules file.
 
-        Args:
-            rules_file_path (str): The file path to the JSON file containing the QA rules.
-            guidance_text (str): Description of the rules. Only visible for Platform admins.
+        Parameters
+        ----------
+            rules_file_path : str
+                The file path to the JSON file containing the protocol
+                 adherence rules.
+            guidance_text : str
+                Description of the protocol adherence rules.
 
-        Returns:
-            bool: True if the rules were set successfully, False otherwise.
+        Returns
+        -------
+            bool: True if the protocol adherence rules were set successfully,
+            False otherwise.
         """
+        logger = logging.getLogger(logger_name)
         # Read the rules from the JSON file
         try:
             with open(rules_file_path, "r") as fr:
                 rules = json.load(fr)
         except FileNotFoundError:
-            print(f"ERROR: Rules file '{rules_file_path}' not found.")
+            logger.error(f"Pprotocol adherence rule file '{rules_file_path}' "
+                         f"not found.")
             return False
 
         # Update the project's QA rules
-        res = platform.post(
+        res = platform.parse_response(platform.post(
             auth=self._account.auth,
             endpoint="projectset_manager/set_session_qa_requirements",
             data={"project_id": self._project_id, "rules": json.dumps(rules), "guidance_text": guidance_text},
-        )
+        ))
 
-        if res.json().get("success") == 1:
-            print("Rules set up successfully!")
-            return True
-        else:
-            print("ERROR setting the rules")
-            print(res.json())
+        if not res.get("success") == 1:
+            logger.error("There was an error setting up the protocol "
+                         "adherence rules.")
+            logger.error(platform.parse_response(res))
+            return False
+
+        return True
+
+    def get_project_pa_rules(self, rules_file_path):
+        """
+        Retrive the active project's protocol adherence rules
+
+        Parameters
+        ----------
+            rules_file_path : str
+                The file path to the JSON file to store the protocol adherence
+                rules.
+
+        Returns
+        -------
+            guidance_text : str
+                Description of the protocol adherence rules,
+                False if extraction of the protocol adhernece rules is not
+                possible.
+        """
+        logger = logging.getLogger(logger_name)
+
+        # Update the project's QA rules
+        res = platform.parse_response(platform.post(
+            auth=self._account.auth,
+            endpoint="projectset_manager/get_session_qa_requirements",
+            data={"project_id": self._project_id},
+        ))
+
+        if "rules" not in res:
+            logger.error(f"There was an error extracting the protocol "
+                         f"adherence rules from {self._project_name}.")
+            logger.error(platform.parse_response(res))
             return False
+
+        try:
+            with open(rules_file_path, "w") as fr:
+                json.dump(res["rules"], fr, indent=4)
+        except FileNotFoundError:
+            logger.error(f"Protocol adherence rules could not be exported"
+                         f"to file: '{rules_file_path}'.")
+            return False
+
+        return res["guidance_text"]

{qmenta_client-1.1.dev1326.dist-info → qmenta_client-1.1.dev1349.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: qmenta-client
-Version: 1.1.dev1326
+Version: 1.1.dev1349
 Summary: Python client lib to interact with the QMENTA platform.
 Author: QMENTA
 Author-email: dev@qmenta.com

{qmenta_client-1.1.dev1326.dist-info → qmenta_client-1.1.dev1349.dist-info}/RECORD

@@ -1,10 +1,10 @@
 qmenta/__init__.py,sha256=jv2YF__bseklT3OWEzlqJ5qE24c4aWd5F4r0TTjOrWQ,65
 qmenta/client/Account.py,sha256=MEljEy9cmg2uP2FG1d3TZAgfj66EE2_3PQAZ9rvpCXY,9647
 qmenta/client/File.py,sha256=ZgvSqejIosUt4uoX7opUnPnp5XGEaJNMRwFC0mQVB8k,5344
-qmenta/client/Project.py,sha256=T_IoH_CpyFg0IaaXeQW_x1xH76n8FsX_2v0qWJo7Yuk,68063
+qmenta/client/Project.py,sha256=xk-C4kf2i7RLsIp3fiwHQzlEOZpb1sL-KqxGqDex8Mc,76953
 qmenta/client/Subject.py,sha256=lhxxVdQ6d-GNoQC8mrJwa4L1f44nJc4PcJtDspmKN7I,8756
 qmenta/client/__init__.py,sha256=AjTojBhZeW5nl0i605KS8S1Gl5tPNc1hdzD47BGNfoI,147
 qmenta/client/utils.py,sha256=5DK2T_HQprrCwLS0Ycm2CjseaYmAUKaJkJvYoW-Rqzc,2479
-qmenta_client-1.1.dev1326.dist-info/METADATA,sha256=h6qd-k47PLto2IDPKURSwiuRhRyfFA3bZ8a0-IRbGrE,672
-qmenta_client-1.1.dev1326.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
-qmenta_client-1.1.dev1326.dist-info/RECORD,,
+qmenta_client-1.1.dev1349.dist-info/METADATA,sha256=RBQVZKHts7FiBDWvv9C5Nf6lCj8I5YH6N_shy1JRBsc,672
+qmenta_client-1.1.dev1349.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
+qmenta_client-1.1.dev1349.dist-info/RECORD,,