qmenta-client 1.1.dev1245__py3-none-any.whl → 1.1.dev1289__py3-none-any.whl

qmenta/client/Project.py

@@ -11,7 +11,6 @@ from enum import Enum
 from qmenta.client import Account
 from qmenta.core import errors
 from qmenta.core import platform
-from .Subject import Subject
 
 if sys.version_info[0] == 3:
     # Note: this branch & variable is only needed for python 2/3 compatibility
@@ -161,45 +160,137 @@ class Project:
         dict
             A list of dictionary of {"metadata_name": "metadata_value"}
         """
-        return self.get_subjects_metadata(cache=False)
+        return self.get_subjects_metadata()
 
-    def get_subjects_metadata(self, cache=True, search_criteria=None):
+    def get_subjects_metadata(self, search_criteria={}, items=(0, 9999)):
         """
-        List all subject data from the selected project.
+        List all subjects data from the selected project that meet the defined
+            search criteria.
+
         Parameters
         ----------
-        cache: bool
-            Whether to use the cached metadata or not
-
         search_criteria: dict
             Each element is a string and is built using the formatting
-        "type;value", or "type;operation|value"
+            "type;value", or "type;operation|value"
+
+        Complete search_criteria Dictionary Explanation:
+
+        search_criteria = {
+            "pars_patient_secret_name": "string;SUBJECTID",
+            "pars_ssid": "integer;OPERATOR|SSID",
+            "pars_modalities": "string;MODALITY",
+            "pars_tags": "tags;TAGS",
+            "pars_age_at_scan": "integer;OPERATOR|AGE_AT_SCAN",
+            "pars_[dicom]_KEY": "KEYTYPE;KEYVALUE",
+            "pars_PROJECTMETADATA": "METADATATYPE;METADATAVALUE",
+            }
+
+        Where:
+        "pars_patient_secret_name": Applies the search to the 'Subject ID'.
+        SUBJECTID is a comma separated list of strings.
+        "pars_ssid": Applies the search to the 'Session ID'.
+        SSID is an integer.
+        OPERATOR is the operator to apply. One of:
+            - Equal: eq
+            - Different Than: ne
+            - Greater Than: gt
+            - Greater/Equal To: gte
+            - Lower Than: lt
+            - Lower/Equal To: lte
+
+        "pars_modalities": Applies the search to the file 'Modalities'
+            available within each Subject ID.
+        MODALITY is a comma separated list of string.
+        "pars_tags": Applies the search to the file 'Tags' available within
+            each Subject ID and to the subject-level 'Tags'.
+        TAGS is a comma separated list of strings.
+        "pars_age_at_scan": Applies the search to the 'age_at_scan' metadata
+            field.
+        AGE_AT_SCAN is an integer.
+        "pars_[dicom]_KEY": Applies the search to the metadata fields
+            available within each file. KEY must be one of the
+        metadata keys of the files. The full list of KEYS is shown above via
+            'file_m["metadata"]["info"].keys()'.
+        KEYTYPE is the type of the KEY. One of:
+            - integer
+            - string
+            - list
+
+            if 'integer' you must also include an OPERATOR
+                (i.e., "integer;OPERATOR|KEYVALUE").
+        KEYVALUE is the expected value of the KEY.
+        "pars_[dicom]_PROJECTMETADATA": Applies to the metadata defined
+            within the 'Metadata Manager' of the project.
+        PROJECTMETADATA is the ID of the metadata field.
+        METADATATYPE is the type of the metadata field. One of:
+            - string
+            - integer
+            - list
+            - decimal
+            - single_option
+            - multiple_option
+
+            if 'integer' or 'decimal' you must also include an OPERATOR
+                (i.e., "integer;OPERATOR|METADATAVALUE").
+        KEYVALUE is the expected value of the metadata.
+
+        1) Example:
+        search_criteria = {
+            "pars_patient_secret_name": "string;abide",
+            "pars_ssid": "integer;eq|2"
+        }
+
+        2) Example:
+        search_criteria = {
+            "pars_modalities": "string;T1",
+            "pars_tags": "tags;flair",
+            "pars_[dicom]_Manufacturer": "string;ge",
+            "pars_[dicom]_FlipAngle": "integer;gt|5",
+        }
 
-        Example:
-        search_criteria = {"pars_patient_secret_name": "string;abide",
-        "pars_ssid": "integer;eq|2"}
+        Note the search criteria applies to all the files included within a
+            session. Hence, it does not imply that all the criteria conditions
+            are applied to the same files. In example 2) above, it means that
+            any Subject ID/Session ID that has a file classified with a 'T1'
+            modality, a file with a 'flair' tag, a file whose Manufacturer
+            contains 'ge', and a file whose FlipAngle is greater than '5º' will
+            be selected.
 
         Returns
         -------
         dict
             A list of dictionary of {"metadata_name": "metadata_value"}
+
         """
 
-        if not cache or not self._subjects_metadata:
-            content = platform.parse_response(platform.post(
-                self._account.auth, "patient_manager/get_patient_list",
-                data=search_criteria,
-                headers={"X-Range": "items=0-9999"}
-            ))
-            self._subjects_metadata = content
-        else:
-            content = self._subjects_metadata
+        assert len(items) == 2, f"The number of elements in items " \
+                                f"'{len(items)}' should be equal to two."
+        assert all([isinstance(item, int) for item in items]), \
+            f"All items elements '{items}' should be integers."
+
+        assert all([key[:5] == "pars_" for key in search_criteria.keys()]), \
+            f"All keys of the search_criteria dictionary " \
+            f"'{search_criteria.keys()}' must start with 'pars_'."
+
+        operator_list = ["eq", "ne", "gt", "gte", "lt", "lte"]
+        for key, value in search_criteria.items():
+            if value.split(";")[0] in ["integer", "decimal"]:
+                assert value.split(";")[1].split("|")[0] in operator_list, \
+                    f"Search criteria of type '{value.split(';')[0]}' must " \
+                    f"include an operator ({', '.join(operator_list)})."
+
+        content = platform.parse_response(platform.post(
+            self._account.auth, "patient_manager/get_patient_list",
+            data=search_criteria,
+            headers={"X-Range": f"items={items[0]}-{items[1]}"}
+        ))
         return content
 
     @property
     def subjects(self):
         """
-        Return the list of subject names from the selected project.
+        Return the list of subject names (Subject ID) from the selected
+        project.
 
         :return: a list of subject names
         :rtype: List(Strings)
@@ -211,12 +302,13 @@ class Project:
 
     def check_subject_name(self, subject_name):
         """
-        Check if a given subject name exists in the selected project.
+        Check if a given subject name (Subject ID) exists in the selected
+        project.
 
         Parameters
         ----------
         subject_name : str
-            name of the subject to check
+            Subject ID of the subject to check
 
         Returns
         -------
@@ -403,48 +495,81 @@ class Project:
             data=search_condition
         ))
 
-    def get_container(self, subject_name):
-        search_condition = {
+    def get_subject_container_id(self, subject_name, ssid):
+        """
+        Given a Subject ID and Session ID, return its Container ID.
+
+        Parameters
+        ----------
+        subject_name : str
+            Subject ID of the subject in the project.
+        ssid : str
+            Session ID of the subject in the project.
+
+        Returns
+        -------
+        int or bool
+            The Container ID of the subject in the project, or False if
+            the subject is not found.
+        """
+
+        search_criteria = {
             "s_n": subject_name,
+            "ssid": ssid
         }
         response = self.list_input_containers(
-            search_condition=search_condition
+            search_criteria=search_criteria
         )
 
-        if len(response) > 1:
-            raise Exception(f"multiple containers for subject {subject_name} "
-                            f"found")
-        elif len(response) == 1:
-            return response[0]
-        else:
-            return None
+        for subject in response:
+            if subject["patient_secret_name"] == subject_name and \
+                    subject["ssid"] == ssid:
+                return subject["container_id"]
+        return False
 
-    def list_input_containers(self, search_condition=None, limit=1000):
+    def list_input_containers(self, search_criteria={}, items=(0, 9999)):
         """
-        List the containers available to the user.
+        Retrieve the list of input containers available to the user under a
+        certain search criteria.
 
         Parameters
         ----------
-        search_condition : dict
-            d_n: container_name
-            s_n: subject_id
-            from_d: from date
-            to_d: to date
-            sets: data sets (modalities)
-        limit : int
-            Max number of results
+        search_criteria : dict
+            Each element is a string and is built using the formatting
+        "type;value".
+
+        List of possible keys:
+        d_n: container_name # TODO: WHAT IS THIS???
+        s_n: subject_id
+            Subject ID of the subject in the platform.
+        ssid: session_id
+            Session ID of the subejct in the platform.
+        from_d: from date
+            Starting date in which perform the search. Format: DD.MM.YYYY
+        to_d: to date
+            End date in which perform the search. Format: DD.MM.YYYY
+        sets: data sets (modalities)  # TODO: WHAT IS THIS???
+
+        items: Tuple(int, int)
+            Starting and ending element of the search.
 
         Returns
         -------
         dict
-            List of containers, each a dictionary
-            {"name": "container-name", "id": "container_id"}
+        List of containers, each a dictionary containing the following
+        information:
+            {"container_name", "container_id", "patient_secret_name", "ssid"}
         """
 
-        req_headers = {"X-Range": "items=0-" + str(limit - 1)}
+        assert len(items) == 2, f"The number of elements in items " \
+                                f"'{len(items)}' should be equal to two."
+        assert all([isinstance(item, int) for item in items]), \
+            f"All items elements '{items}' should be integers."
+
         response = platform.parse_response(platform.post(
             self._account.auth, "file_manager/get_container_list",
-            data=search_condition, headers=req_headers
+            data=search_criteria,
+            headers={"X-Range": f"items={items[0]}-{items[1]}"}
         ))
         containers = [
             {
@@ -545,12 +670,15 @@ class Project:
         Returns
         -------
         dict
-            Dictionary with the metadata.
+            Dictionary with the metadata. False otherwise.
         """
         all_metadata = self.list_container_files_metadata(container_id)
-        for file_meta in all_metadata:
-            if file_meta["name"] == filename:
-                return file_meta
+        if all_metadata:
+            for file_meta in all_metadata:
+                if file_meta["name"] == filename:
+                    return file_meta
+        else:
+            return False
 
     def change_file_metadata(self, container_id, filename, modality, tags):
         """
@@ -673,16 +801,17 @@ class Project:
             container_id, zip_name))
         return True
 
-    def get_subject_id(self, subject_name, cache=False):
+    def get_subject_id(self, subject_name, ssid):
         """
-        Given a subject name, return its ID in the project.
+        Given a Subject ID and Session ID, return its Patient ID in the
+        project.
 
         Parameters
         ----------
         subject_name : str
-            Name of the subject in the project.
-        cache : bool
-            Whether to use the cached metadata or not
+            Subject ID of the subject in the project.
+        ssid : str
+            Session ID of the subject in the project.
 
         Returns
         -------
@@ -691,37 +820,12 @@ class Project:
             the subject is not found.
         """
 
-        for user in self.get_subjects_metadata(cache):
-            if user["patient_secret_name"] == subject_name:
+        for user in self.get_subjects_metadata():
+            if user["patient_secret_name"] == str(subject_name) and \
+                    user["ssid"] == str(ssid):
                 return int(user["_id"])
         return False
 
-    def get_subject(self, subject_name, cache=True):
-        """
-        Return a subject object, representing a subject from the project.
-
-        Parameters
-        ----------
-        subject_name : str
-            Name of the subject.
-        cache: bool
-            Whether to use the cached metadata or not
-
-        Returns
-        -------
-        Subject or bool
-            A Subject instance representing the desired subject, or
-            False if the subject was not found.
-
-        """
-        subject_id = self.get_subject_id(subject_name, cache=cache)
-        if subject_id is False:
-            return False
-        subj = Subject(subject_name)
-        subj.subject_id = subject_id
-        subj.project = self
-        return subj
-
     def add_subject(self, subject):
         """
         Add a subject to the project.
@@ -757,18 +861,114 @@ class Project:
             "Subject {0} was successfully created".format(subject.name))
         return True
 
-    def delete_session(self, subject_name, session_id, cache=False):
+    def change_subject_metadata(self, patient_id, subject_name, ssid, tags,
+                                age_at_scan, metadata):
+        """
+        Change the Subject ID, Session ID, Tags, Age at Scan and Metadata of
+        the session with Patient ID
+
+        Parameters
+        ----------
+        patient_id : Integer
+            Patient ID representing the session to modify.
+        subject_name : String
+            Represents the new Subject ID.
+        ssid : String
+            Represents the new Session ID.
+        tags : list of strings in lowercase
+            Represents the new tags of the session.
+        age_at_scan : Integer
+            Represents the new Age at Scan of the Session.
+        metadata : Dictionary
+            Each pair key/value representing the new metadata values.
+
+            The keys must either all start with "md\\_" or none start
+            with "md\\_".
+
+            The key represents the ID of the metadata field.
+
+        Returns
+        -------
+        bool
+            True if correctly modified, False otherwise
+        """
+        logger = logging.getLogger(logger_name)
+
+        try:
+            patient_id = str(int(patient_id))
+        except ValueError:
+            raise ValueError(f"'patient_id': '{patient_id}' not valid. "
+                             f"Must be convertible to int.")
+
+        assert isinstance(tags, list) and \
+               all(isinstance(item, str) for item in tags), \
+               f"tags: '{tags}' should be a list of strings."
+        tags = [tag.lower() for tag in tags]
+
+        assert subject_name is not None and subject_name != "", \
+            "subject_name must be a non empty string."
+        assert ssid is not None and ssid != "", \
+            "ssid must be a non empty string."
+
+        try:
+            age_at_scan = str(int(age_at_scan)) if age_at_scan else None
+        except ValueError:
+            raise ValueError(f"age_at_scan: '{age_at_scan}' not valid. "
+                             f"Must be an integer.")
+
+        assert isinstance(metadata, dict), \
+            f"metadata: '{metadata}' should be a dictionary."
+
+        assert all("md_" == key[:3] for key in metadata.keys()) or \
+               all("md_" != key[:3] for key in metadata.keys()), \
+               f"metadata: '{metadata}' must be a dictionary whose keys " \
+               f"are either all starting with 'md_' or none."
+
+        metadata_keys = self.metadata_parameters.keys()
+        assert \
+            all([key[3:] in metadata_keys
+                 if "md_" == key[:3] else key in metadata_keys
+                 for key in metadata.keys()]), \
+            f"Some metadata keys provided ({', '.join(metadata.keys())}) " \
+            f"are not available in the project. They can be added via the " \
+            f"Metadata Manager via the QMENTA Platform graphical user " \
+            f"interface (GUI)."
+
+        post_data = {
+            "patient_id": patient_id,
+            "secret_name": str(subject_name),
+            "ssid": str(ssid),
+            "tags": ",".join(tags),
+            "age_at_scan": age_at_scan,
+        }
+        for key, value in metadata.items():
+            id = key[3:] if "md_" == key[:3] else key
+            post_data[f"last_vals.{id}"] = value
+
+        try:
+            platform.parse_response(platform.post(
+                self._account.auth,
+                "patient_manager/upsert_patient",
+                data=post_data
+            ))
+        except errors.PlatformError:
+            logger.error(f"Patient ID '{patient_id}' could not be modified.")
+            return False
+
+        logger.info(f"Patient ID '{patient_id}' successfully modified.")
+        return True
+
+    def delete_session(self, subject_name, session_id):
         """
-        Delete a session from a subject within a project.
+        Delete a session from a subject within a project providing the
+        Subject ID and Session ID.
 
         Parameters
         ----------
         subject_name : str
-            Name of the subject
+            Subject ID of the subject
         session_id : int
-            The SSID of the session that will be deleted
-        cache : bool
-            Whether to use the cached metadata or not
+            The Session ID of the session that will be deleted
 
         Returns
         -------
@@ -776,31 +976,31 @@ class Project:
             True if correctly deleted, False otherwise.
         """
         logger = logging.getLogger(logger_name)
-        all_sessions = self.get_subjects_metadata(cache)
+        all_sessions = self.get_subjects_metadata()
 
-        sessions_to_del = [
+        session_to_del = [
             s for s in all_sessions if
-            s["patient_secret_name"] == subject_name and int(
-                s["ssid"]
-            ) == session_id
+            s["patient_secret_name"] == subject_name and
+            s["ssid"] == session_id
         ]
 
-        if not sessions_to_del:
+        if not session_to_del:
             logger.error(
                 f"Session {subject_name}/{session_id} could not be found "
                 f"in this project."
             )
             return False
-        elif len(sessions_to_del) > 1:
+        elif len(session_to_del) > 1:
             raise RuntimeError(
-                "Multiple sessions with same SID and SSID. Contact support."
+                "Multiple sessions with same Subject ID and Session ID."
+                " Contact support."
             )
         else:
             logger.info("{}/{} found (id {})".format(
-                subject_name, session_id, sessions_to_del[0]["_id"]
+                subject_name, session_id, session_to_del[0]["_id"]
             ))
 
-        session = sessions_to_del[0]
+        session = session_to_del[0]
 
         try:
             platform.parse_response(platform.post(
@@ -820,14 +1020,46 @@ class Project:
         )
         return True
 
+    def delete_session_by_patientid(self, patient_id):
+        """
+        Delete a session from a subject within a project providing the
+        Patient ID.
+
+        Parameters
+        ----------
+        patient_id : str
+            Patient ID of the Session ID/Subject ID
+
+        Returns
+        -------
+        bool
+            True if correctly deleted, False otherwise.
+        """
+        logger = logging.getLogger(logger_name)
+
+        try:
+            platform.parse_response(platform.post(
+                self._account.auth, "patient_manager/delete_patient",
+                data={
+                    "patient_id": str(int(patient_id)), "delete_files": 1
+                }
+            ))
+        except errors.PlatformError:
+            logger.error(f"Patient ID {patient_id} could not be deleted.")
+            return False
+
+        logger.info(f"Patient ID {patient_id} successfully deleted.")
+        return True
+
     def delete_subject(self, subject_name):
         """
-        Delete a subject from the project.
+        Delete a subject from the project. It deletes all its available
+        sessions only providing the Subject ID.
 
         Parameters
         ----------
         subject_name : str
-            Name of the subject to be deleted.
+            Subject ID of the subject to be deleted.
 
         Returns
         -------
@@ -837,7 +1069,7 @@ class Project:
 
         logger = logging.getLogger(logger_name)
         # Always fetch the session IDs from the platform before deleting them
-        all_sessions = self.get_subjects_metadata(False)
+        all_sessions = self.get_subjects_metadata()
 
         sessions_to_del = [
             s for s in all_sessions if s["patient_secret_name"] == subject_name
@@ -852,7 +1084,7 @@ class Project:
             return False
 
         for ssid in [s["ssid"] for s in sessions_to_del]:
-            if not self.delete_session(subject_name, ssid, cache=True):
+            if not self.delete_session(subject_name, ssid):
                 return False
         return True
 
@@ -937,16 +1169,16 @@ class Project:
                     add_to_container_id=0, chunk_size=2 ** 9,
                     split_data=False):
         """
-        Upload a file to the platform, associated with the current user.
+        Upload a ZIP file to the platform.
 
         Parameters
         ----------
         file_path : str
-            Path to the file to upload.
+            Path to the ZIP file to upload.
         subject_name : str
-            Subject to which this file will belong
+            Subject ID of the data to upload in the project in QMENTA Platform.
         ssid : str
-            The ID of the timepoint
+            Session ID of the Subject ID (i.e., ID of the timepoint).
         date_of_scan : str
             Date of scan/creation of the file
         description : str
@@ -956,7 +1188,7 @@ class Project:
         name : str
             Name of the file in the platform
         input_data_type : str
-            mri_brain_data:1.0 or gametection:1.0
+            qmenta_medical_image_data:3.11
         add_to_container_id : int
             ID of the container to which this file should be added (if id > 0)
         chunk_size : int

{qmenta_client-1.1.dev1245.dist-info → qmenta_client-1.1.dev1289.dist-info}/METADATA

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

{qmenta_client-1.1.dev1245.dist-info → qmenta_client-1.1.dev1289.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=hWow6ZjVNh_mAtUs4joLJ801oMfXuBqkxUc3Ov0zuQ4,50310
+qmenta/client/Project.py,sha256=Y0G5vSVODThAL8kGwmtkcZrE49vB2LVlNf2eRrqr8dg,59767
 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.dev1245.dist-info/METADATA,sha256=HbS0xu5wSlXrV-7QB9Dr_gi0jRwwDj1zTQ0roFEr5p8,672
-qmenta_client-1.1.dev1245.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
-qmenta_client-1.1.dev1245.dist-info/RECORD,,
+qmenta_client-1.1.dev1289.dist-info/METADATA,sha256=khcRoMKuV0hhGvxc-9tjMy9RRIXugkzyE5sKZ_PuF4M,672
+qmenta_client-1.1.dev1289.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
+qmenta_client-1.1.dev1289.dist-info/RECORD,,