qmenta-client 1.1.dev1295__py3-none-any.whl → 1.1.dev1311__py3-none-any.whl

qmenta/client/Project.py

@@ -17,6 +17,7 @@ if sys.version_info[0] == 3:
     unicode = str
 
 logger_name = "qmenta.client"
+OPERATOR_LIST = ["eq", "ne", "gt", "gte", "lt", "lte"]
 
 
 def show_progress(done, total, finish=False):
@@ -67,6 +68,138 @@ def check_upload_file(file_path):
         return True
 
 
+def operation(reference_value, operator, input_value):
+    """
+    The method performs an operation by comparing the two input values.
+    The Operation is applied to the Input Value in comparison to the Reference
+    Value.
+
+    Parameters
+    ----------
+    reference_value : str, list, or int
+        Reference value.
+    operator : str
+        Operation.
+    input_value : str, list, or int
+        Input value.
+
+    Returns
+    -------
+    bool
+        True if the operation is satisfied, False otherwise.
+    """
+    if input_value is None or input_value == "":
+        return False
+
+    if operator == "in":
+        return reference_value in input_value
+
+    elif operator == "in-list":
+        return all([el in input_value for el in reference_value])
+
+    elif operator == "eq":
+        return input_value == reference_value
+
+    elif operator == "gt":
+        return input_value > reference_value
+
+    elif operator == "gte":
+        return input_value >= reference_value
+
+    elif operator == "lt":
+        return input_value < reference_value
+
+    elif operator == "lte":
+        return input_value <= reference_value
+    else:
+        return False
+
+
+def wrap_search_criteria(search_criteria={}):
+    """
+    Wraps the conditions specified within the Search Criteria in order for
+    other methods to handle it easily. The conditions are grouped only into
+    three groups: Modality, Tags and the File Metadata (if DICOM it corresponds
+    to the DICOM information), and each of them is output in a different
+    variable.
+
+    Parameters
+    ----------
+    search_criteria : dict
+        Each element is a string and is built using the formatting
+            "KEYTYPE;VALUE", or "KEYTYPE;OPERATOR|VALUE".
+
+            Full list of keys avaiable for the dictionary:
+
+            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",
+                }
+
+            See documentation for a complete definition.
+
+    Returns
+    -------
+    modality : str
+        String containing the modality of the search criteria extracted from
+        'pars_modalities'
+
+    tags : list of str
+        List of strings containing the tags of the search criteria extracted
+        'from pars_tags'
+
+    file_metadata : Dict
+        Dictionary containing the file metadata of teh search criteria
+        exgtracted from 'pars_[dicom]_KEY'
+    """
+
+    # The keys not included bellow apply to the whole session.
+    modality, tags, file_metadata = "", list(), dict()
+    for key, value in search_criteria.items():
+        if key == "pars_modalities":
+            modalities = value.split(";")[1].split(",")
+            if len(modalities) != 1:
+                raise ValueError(f"A file can only have one modality. "
+                                 f"Provided Modalities: "
+                                 f"{', '.join(modalities)}.")
+            modality = modalities[0]
+        elif key == "pars_tags":
+            tags = value.split(";")[1].split(",")
+        elif "pars_[dicom]_" in key:
+            d_tag = key.split("pars_[dicom]_")[1]
+            d_type = value.split(";")[0]
+            if d_type == "string":
+                file_metadata[d_tag] = {
+                    "operation": "in",
+                    "value": value.replace(d_type + ";", "")
+                }
+            elif d_type == "integer":
+                d_operator = value.split(";")[1].split("|")[0]
+                d_value = value.split(";")[1].split("|")[1]
+                file_metadata[d_tag] = {
+                    "operation": d_operator,
+                    "value": int(d_value)}
+            elif d_type == "decimal":
+                d_operator = value.split(";")[1].split("|")[0]
+                d_value = value.split(";")[1].split("|")[1]
+                file_metadata[d_tag] = {
+                    "operation": d_operator,
+                    "value": float(d_value)
+                }
+            elif d_type == "list":
+                value.replace(d_type + ";", "")
+                file_metadata[d_tag] = {
+                    "operation": "in-list",
+                    "value": value.replace(d_type + ";", "").split(";")
+                }
+    return modality, tags, file_metadata
+
+
 class QCStatus(Enum):
     """
     Enum with the following options:
@@ -162,8 +295,8 @@ class Project:
 
     def get_subjects_metadata(self, search_criteria={}, items=(0, 9999)):
         """
-        List all subjects data from the selected project that meet the defined
-            search criteria.
+        List all Subject ID/Session ID from the selected project that meet the
+            defined search criteria at a session level.
 
         Parameters
         ----------
@@ -198,10 +331,12 @@ class Project:
 
         "pars_modalities": Applies the search to the file 'Modalities'
             available within each Subject ID.
-        MODALITY is a comma separated list of string.
+        MODALITY is a comma separated list of string. A session is provided as
+            long as one MODALITY is available.
         "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.
+        TAGS is a comma separated list of strings. A session is provided as
+            long as one tag is available.
         "pars_age_at_scan": Applies the search to the 'age_at_scan' metadata
             field.
         AGE_AT_SCAN is an integer.
@@ -211,11 +346,15 @@ class Project:
             'file_m["metadata"]["info"].keys()'.
         KEYTYPE is the type of the KEY. One of:
             - integer
+            - decimal
             - string
             - list
 
-            if 'integer' you must also include an OPERATOR
+            if 'integer' or 'decimal' you must also include an OPERATOR
                 (i.e., "integer;OPERATOR|KEYVALUE").
+            if 'list' the KEYVALUE should be a semicolon separated list of
+                values. (i.e., "list;KEYVALUE1;KEYVALUE2;KEYVALUE3)
+                KEYVALUEs must be strings.
         KEYVALUE is the expected value of the KEY.
         "pars_[dicom]_PROJECTMETADATA": Applies to the metadata defined
             within the 'Metadata Manager' of the project.
@@ -244,6 +383,7 @@ class Project:
             "pars_tags": "tags;flair",
             "pars_[dicom]_Manufacturer": "string;ge",
             "pars_[dicom]_FlipAngle": "integer;gt|5",
+            "pars_[dicom]_ImageType": "list;PRIMARY;SECONDARY",
         }
 
         Note the search criteria applies to all the files included within a
@@ -251,8 +391,9 @@ class Project:
             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.
+            contains 'ge', a file whose FlipAngle is greater than '5º', and a
+            file with ImageType with any of the values: PRIMARY or SECONDARY
+            will be selected.
 
         Returns
         -------
@@ -268,12 +409,11 @@ class Project:
             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, (
+                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)})."
+                    f"include an operator ({', '.join(OPERATOR_LIST)})."
                 )
 
         content = platform.parse_response(
@@ -286,6 +426,160 @@ class Project:
         )
         return content
 
+    def get_subjects_files_metadata(self, search_criteria={}, items=(0, 9999)):
+        """
+        List all Subject ID/Session ID from the selected project that meet the
+            defined search criteria at a file level.
+
+        Note, albeit the search criteria is similar to the one defined in
+            method 'get_subjects_metadata()' (see differences below), the
+            output is different as this method provides the sessions which
+            have a file that satisfy all the conditions of the search criteria.
+            This method is slow.
+
+        Parameters
+        ----------
+        search_criteria: dict
+            Each element is a string and is built using the formatting
+            "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 string.
+        "pars_tags": Applies only the search to the file 'Tags' available
+            within each Subject ID.
+        TAGS is a comma separated list of strings. All tags must be present in
+            the same file.
+        "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()'.  # TODO: SEE HOW TO WRITE THIS
+        KEYTYPE is the type of the KEY. One of:
+            - integer
+            - decimal
+            - string
+            - list
+
+            if 'integer' or 'decimal' you must also include an OPERATOR
+                (i.e., "integer;OPERATOR|KEYVALUE").
+            if 'list' the KEYVALUE should be a semicolon separated list of
+                values. (i.e., "list;KEYVALUE1;KEYVALUE2;KEYVALUE3)
+                KEYVALUEs must be strings.
+        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_patient_secret_name": "string;001"
+            "pars_modalities": "string;T2",
+            "pars_tags": "tags;flair",
+            "pars_[dicom]_Manufacturer": "string;ge",
+            "pars_[dicom]_FlipAngle": "integer;gt|5",
+            "pars_[dicom]_ImageType": "list;PRIMARY;SECONDARY",
+        }
+
+        Note the search criteria might apply to both the files metadata
+            information available within a session and the metadata of the
+            session. And the method provides a session only if all the file
+            related conditions are satisfied within the same file.
+            In example 2) above, it means that the output will contain any
+            session whose Subject ID contains '001', and there is a file with
+            modality 'T2', tag 'flair', FlipAngle greater than 5º, and
+            ImageType with both values PRIMARY and SECONDARY.
+            Further, the acquisition had to be performed in a Manufacturer
+            containing 'ge'.
+
+        Returns
+        -------
+        dict
+            A list of dictionary of {"metadata_name": "metadata_value"}
+
+        """
+
+        content = self.get_subjects_metadata(search_criteria, items=(0, 9999))
+
+        # Wrap search criteria.
+        modality, tags, dicoms = wrap_search_criteria(search_criteria)
+
+        # Iterate over the files of each subject selected to include/exclude
+        # them from the results.
+        subjects = list()
+        for subject in content:
+            files = platform.parse_response(platform.post(
+                self._account.auth, "file_manager/get_container_files",
+                data={"container_id": str(int(subject["container_id"]))}
+                ))
+
+            for file in files["meta"]:
+                if modality and \
+                   modality != (file.get("metadata") or {}).get("modality"):
+                    continue
+                if tags and not all([tag in file.get("tags") for tag in tags]):
+                    continue
+                if dicoms:
+                    result_values = list()
+                    for key, dict_value in dicoms.items():
+                        f_value = ((file.get("metadata") or {})
+                                   .get("info") or {}).get(key)
+                        d_operator = dict_value["operation"]
+                        d_value = dict_value["value"]
+                        result_values.append(
+                            operation(d_value, d_operator, f_value)
+                        )
+
+                    if not all(result_values):
+                        continue
+                subjects.append(subject)
+                break
+        return subjects
+
     @property
     def subjects(self):
         """
@@ -321,10 +615,14 @@ class Project:
     @property
     def metadata_parameters(self):
         """
-        List all the parameters in the subject metadata.
+        List all the parameters in the subject-level metadata.
 
-        Each project has a set of parameters that define the subjects metadata.
-        This function returns all these parameters and its properties.
+        Each project has a set of parameters that define the subjects-level
+        metadata. This function returns all these parameters and its
+        properties. New subject-level metadata parameters can be creted in the
+        QMENTA Platform via the Metadata Manager. The API only allow
+        modification of these subject-level metadata parameters via the
+        'change_subject_metadata()' method.
 
         Returns
         -------
@@ -345,49 +643,6 @@ class Project:
             return None
         return data["fields"]
 
-    def add_metadata_parameter(self, title, param_id=None, param_type="string", visible=False):
-        """
-        Add a metadata parameter to the project.
-
-        Parameters
-        ----------
-        title : str
-            Identifier of this new parameter
-        param_id : str
-            Title of this new parameter
-        param_type : str
-            Type of the parameter. One of:
-            "integer", "date", "string", "list", "decimal"
-        visible : bool
-            whether the parameter will be visible in the table of patients
-
-        Returns
-        -------
-        bool
-            True if parameter was correctly added, False otherwise.
-        """
-        # use param_id equal to title if param_id is not provided
-        param_id = param_id or title
-
-        param_properties = [title, param_id, param_type, str(int(visible))]
-
-        post_data = {"add": "|".join(param_properties), "edit": "", "delete": ""}
-
-        logger = logging.getLogger(logger_name)
-        try:
-            answer = platform.parse_response(
-                platform.post(self._account.auth, "patient_manager/save_metadata_changes", data=post_data)
-            )
-        except errors.PlatformError:
-            answer = {}
-
-        if title not in answer:
-            logger.error(f"Could not add new parameter: {title}")
-            return False
-
-        logger.info("New parameter added:", title, param_properties)
-        return True
-
     def get_analysis(self, analysis_name_or_id):
         if isinstance(analysis_name_or_id, int):
             search_tag = "id"
@@ -788,38 +1043,6 @@ class Project:
                 return int(user["_id"])
         return False
 
-    def add_subject(self, subject):
-        """
-        Add a subject to the project.
-
-        Parameters
-        ----------
-        subject : Subject
-            Instance of Subject representing the subject to add.
-
-        Returns
-        -------
-        bool
-            True if correctly added, False otherwise
-        """
-        logger = logging.getLogger(logger_name)
-        if self.check_subject_name(subject.name):
-            logger.error(f"Subject with name {subject.name} already exists in " f"project!")
-            return False
-
-        try:
-            platform.parse_response(
-                platform.post(self._account.auth, "patient_manager/upsert_patient", data={"secret_name": subject.name})
-            )
-        except errors.PlatformError:
-            logger.error(f"Subject {subject.name} could not be created.")
-            return False
-
-        subject.subject_id = self.get_subject_id(subject.name)
-        subject.project = self
-        logger.info("Subject {0} was successfully created".format(subject.name))
-        return True
-
     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

{qmenta_client-1.1.dev1295.dist-info → qmenta_client-1.1.dev1311.dist-info}/METADATA

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

{qmenta_client-1.1.dev1295.dist-info → qmenta_client-1.1.dev1311.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=XXwsd2QKk_p61Mg2ahXxS9MHl1KENDPeNTsooQoXNkE,58955
+qmenta/client/Project.py,sha256=u2fGizvjr3uU9476m_tV0padhlKxqcSR7i2xp07jrps,68234
 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.dev1295.dist-info/METADATA,sha256=G87kykIBmTLL0ebfHvfT0J-0as4u-HCWPzpdDnTiuds,672
-qmenta_client-1.1.dev1295.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
-qmenta_client-1.1.dev1295.dist-info/RECORD,,
+qmenta_client-1.1.dev1311.dist-info/METADATA,sha256=7Zesw_sWgPMQYv9ByAllGzdmTCCQcQo4u-o4Q2EHyso,672
+qmenta_client-1.1.dev1311.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
+qmenta_client-1.1.dev1311.dist-info/RECORD,,