.. _modify-metadata-label: Metadata Handling ================= Within a Project, there are two types of metadata: - **Project-level Metadata**: Configured at Project level and applies to each session (Subject ID/Session ID) - **File-level Metadata**: Applies to files within a session This section covers programmatic modification of metadata in the active Project. Begin by logging in and activating a Project (see :ref:`login-label`). Project-level Metadata ---------------------- Retrieve Project-level metadata: .. code-block:: python p_metadata = project.metadata_parameters :code:`p_metadata` is a dictionary where each key is a metadata field with these sub-keys: - :code:`title`: Parameter title - :code:`id`: Identification code (matches :code:`PROJECTMETADATAKEY` in :ref:`data-asearch-label`) - :code:`type`: Parameter type - :code:`visible`: Visibility in QMENTA Platform - :code:`readonly`: Editability status - :code:`mandatory`: Required status - :code:`description`: Parameter description - :code:`options`: Allowed values for single/multiple-option types - :code:`order`: Display order in QMENTA Platform Example output: .. code-block:: python { 'gender': { 'title': 'Gender', 'id': 'gender', 'type': 'single_option', 'visible': 1, 'readonly': 1, 'mandatory': 0, 'description': '', 'options': [ {'value': 'male', 'label': 'M'}, {'value': 'female', 'label': 'F'}, {'value': 'unknown', 'label': 'UN'} ], 'order': 1 } } .. note:: New Projects start without configurable Project-level metadata parameters. These can only be configured via the QMENTA Platform. All Projects include these default metadata parameters: - :code:`age_at_scan`: Subject age at acquisition - :code:`date_at_scan`: Acquisition date - :code:`qa_status`: Session QC status - :code:`qa_comments`: Session QC comments For DICOM data, :code:`age_at_scan` and :code:`date_at_scan` are auto-populated during upload. Retrieve session metadata: .. code-block:: python subject_name = "0001" subjects = [subject for subject in project.subjects_metadata if subject["patient_secret_name"] == subject_name] Each session dictionary contains Project-level metadata like: - :code:`age_at_scan` - :code:`date_at_scan` - :code:`md_gender` (note :code:`md_` prefix is auto-added) - :code:`qa_status` - :code:`qa_comments` View all session info: .. code-block:: python print(subjects[0]) .. figure:: figs/modify_metadata/1.webp :alt: Example Project-level metadata in QMENTA Platform Project-level Metadata Modification ----------------------------------- Modify Project-level parameters: .. code-block:: python subject_name = "0001" ssid = "1" session = [subject for subject in project.subjects_metadata if subject["patient_secret_name"] == subject_name and subject["ssid"] == ssid] patient_id = session[0]["_id"] age_at_scan = session[0]["age_at_scan"] tags = list(set(subject["tags"] + ["new tag"])) # Add tag metadata = {"gender":"male"} # Update gender project.change_subject_metadata( patient_id, subject_name, ssid, tags, age_at_scan, metadata ) .. note:: All metadata except :code:`patient_id` can be modified. .. _file-metadata-label: File-level Metadata ------------------- Access file metadata via Container ID: .. code-block:: python subject_name = "0001" ssid = "1" container_id = project.get_subject_container_id(subject_name, ssid) files_metadata = project.list_container_files_metadata(container_id) Each file's metadata dictionary contains: - :code:`name`: File name - :code:`size`: File size (bytes) - :code:`tags`: Associated tags - :code:`metadata`: Additional file info .. note:: DICOM Series are stored in ZIP files. Metadata extraction depends on file type - DICOM has extensive metadata while NIfTI/PNG have minimal. View file metadata: .. code-block:: python print(f"File Name: {files_metadata[0]['name']}") print(f"File Tags: {files_metadata[0]['tags']}") print(f"File Modality: {files_metadata[0]['metadata']['modality']}") print(f"File Metadata: \n\n{files_metadata[0]['metadata']['info']}") .. figure:: figs/modify_metadata/2.webp :alt: Example File-level metadata showing DICOM tags File-level Metadata Modification -------------------------------- Only File Modality and Tags can be modified: .. code-block:: python new_modality = "DWI" new_tags = files_metadata[0]['tags'] + ["modified"] project.change_file_metadata( container_id, files_metadata[0]['name'], new_modality, new_tags ) .. _qc-subjects-label: Quality Check (QC) Status ------------------------- QC Status ensures data quality for: - Protocol adherence - Image quality Read and modify QC metadata: .. code-block:: python from qmenta.client.Project import QCStatus qc_status, qc_comments = project.get_qc_status_subject( subject_name=subject_name, ssid=ssid ) patient_id = project.get_subject_id(subject_name, ssid) qc_comments = "Images meet quality standards." qc_status = QCStatus.PASS project.set_qc_status_subject(patient_id, qc_status, qc_comments) :code:`QCStatus` values: - :code:`PASS` - :code:`FAIL` - :code:`UNDETERMINED` .. figure:: figs/modify_metadata/3.webp :alt: QC Status visualization in QMENTA Platform .. _paa-label: Protocol Adherence Automation Analysis --------------------------------------- This analysis compares session data against predefined rules to identify protocol deviations. Example rules for ADNI 4 protocol: `ADNI4 rules `_ Execution updates QC Status automatically: .. code-block:: python analysis_id = project.start_analysis( script_name='qmenta_protocol_adherence_automation', version='1.9', settings={"input":container_id}, analysis_name="Protocol Adherence Automation (v.1.9)", ) .. figure:: figs/modify_metadata/4.webp :alt: Example Protocol Adherence Automation results Protocol Adherence Rules +++++++++++++++++++++++++ Get current Project rules: .. code-block:: python description = project.get_project_pa_rules("Rules.json") Set modified rules: .. code-block:: python project.set_project_pa_rules("Rules.json", description) .. note:: Rules are Project-specific. Next Steps ---------- - :ref:`launch-analysis-label` – Execute analyses - :ref:`download-results-label` – Retrieve analysis outputs