boris-behav-obs 9.7.7__py3-none-any.whl

boris/gui_utilities.py

@@ -0,0 +1,135 @@
+"""
+BORIS
+Behavioral Observation Research Interactive Software
+Copyright 2012-2025 Olivier Friard
+
+  This program is free software; you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation; either version 2 of the License, or
+  (at your option) any later version.
+
+  This program is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with this program; if not, write to the Free Software
+  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
+  MA 02110-1301, USA.
+"""
+
+import pathlib as pl
+import logging
+from PySide6.QtCore import QSettings
+from PySide6.QtWidgets import QWidget, QApplication
+from PySide6.QtGui import QIcon
+
+
+def theme_mode() -> str:
+    """
+    return the theme mode (dark or light) of the OS
+    """
+    palette = QApplication.instance().palette()
+    color = palette.window().color()
+    return "dark" if color.value() < 128 else "light"  # Dark mode if the color value is less than 128
+
+
+def save_geometry(widget: QWidget, widget_name: str):
+    """
+    save window geometry in ini file
+    """
+
+    ini_file_path = pl.Path.home() / pl.Path(".boris")
+    if ini_file_path.is_file():
+        try:
+            settings = QSettings(str(ini_file_path), QSettings.IniFormat)
+            settings.setValue(f"{widget_name} geometry", widget.saveGeometry())
+        except Exception:
+            logging.warning(f"error during saving {widget_name} geometry")
+
+
+def restore_geometry(widget: QWidget, widget_name: str, default_width_height):
+    """
+    restore window geometry in ini file
+    """
+
+    def default_resize(widget, default_width_height):
+        if default_width_height != (0, 0):
+            try:
+                widget.resize(default_width_height[0], default_width_height[1])
+            except Exception:
+                logging.warning("Error during restoring default")
+
+    logging.debug(f"restore geometry function for {widget_name}")
+    try:
+        ini_file_path = pl.Path.home() / pl.Path(".boris")
+        if ini_file_path.is_file():
+            settings = QSettings(str(ini_file_path), QSettings.IniFormat)
+            widget.restoreGeometry(settings.value(f"{widget_name} geometry"))
+            logging.debug(f"geometry restored for {widget_name}  {settings.value(f'{widget_name} geometry')}")
+        else:
+            default_resize(widget, default_width_height)
+    except Exception:
+        logging.warning(f"error during restoring {widget_name} geometry")
+        default_resize(widget, default_width_height)
+
+
+def set_icons(self, theme_mode: str) -> None:
+    """
+    set icons of actions
+    """
+
+    # menu
+    self.action_obs_list.setIcon(QIcon(f":/observations_list_{theme_mode}"))
+
+    self.actionTime_budget.setIcon(QIcon(f":/time_budget_{theme_mode}"))
+    self.actionPlot_events2.setIcon(QIcon(f":/plot_events_{theme_mode}"))
+    self.action_advanced_event_filtering.setIcon(QIcon(f":/filter_{theme_mode}"))
+
+    self.actionPreferences.setIcon(QIcon(f":/preferences_{theme_mode}"))
+
+    self.actionPlay.setIcon(QIcon(f":/play_{theme_mode}"))
+    self.actionReset.setIcon(QIcon(f":/reset_{theme_mode}"))
+    self.actionJumpBackward.setIcon(QIcon(f":/jump_backward_{theme_mode}"))
+    self.actionJumpForward.setIcon(QIcon(f":/jump_forward_{theme_mode}"))
+
+    self.actionFaster.setIcon(QIcon(f":/faster_{theme_mode}"))
+    self.actionSlower.setIcon(QIcon(f":/slower_{theme_mode}"))
+    self.actionNormalSpeed.setIcon(QIcon(f":/normal_speed_{theme_mode}"))
+
+    self.actionPrevious.setIcon(QIcon(f":/previous_{theme_mode}"))
+    self.actionNext.setIcon(QIcon(f":/next_{theme_mode}"))
+
+    self.actionSnapshot.setIcon(QIcon(f":/snapshot_{theme_mode}"))
+
+    self.actionFrame_backward.setIcon(QIcon(f":/frame_backward_{theme_mode}"))
+    self.actionFrame_forward.setIcon(QIcon(f":/frame_forward_{theme_mode}"))
+    self.actionCloseObs.setIcon(QIcon(f":/close_observation_{theme_mode}"))
+    self.actionCurrent_Time_Budget.setIcon(QIcon(f":/time_budget_{theme_mode}"))
+    self.actionPlot_current_observation.setIcon(QIcon(f":/plot_events_{theme_mode}"))
+
+    self.actionPlot_events_in_real_time.setIcon(QIcon(f":/plot_real_time_{theme_mode}"))
+
+    self.actionBehavior_bar_plot.setIcon(QIcon(f":/plot_time_budget_{theme_mode}"))
+    self.actionPlot_current_time_budget.setIcon(QIcon(f":/plot_time_budget_{theme_mode}"))
+    self.action_geometric_measurements.setIcon(QIcon(f":/measurement_{theme_mode}"))
+    self.actionFind_in_current_obs.setIcon(QIcon(f":/find_{theme_mode}"))
+    self.actionExplore_project.setIcon(QIcon(f":/explore_{theme_mode}"))
+
+
+def resize_center(app, window, width: int, height: int) -> None:
+    """
+    resize and center window
+    """
+    window.resize(width, height)
+    screen_geometry = app.primaryScreen().geometry()
+    if window.height() > screen_geometry.height():
+        window.resize(window.width(), int(screen_geometry.height() * 0.8))
+    if window.width() > screen_geometry.width():
+        window.resize(screen_geometry.width(), window.height())
+    # center
+    center_x = (screen_geometry.width() - window.width()) // 2
+    center_y = (screen_geometry.height() - window.height()) // 2
+
+    window.move(center_x, center_y)

boris/image_overlay.py

@@ -0,0 +1,72 @@
+"""
+BORIS
+Behavioral Observation Research Interactive Software
+Copyright 2012-2025 Olivier Friard
+
+
+  This program is free software; you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation; either version 2 of the License, or
+  (at your option) any later version.
+
+  This program is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with this program; if not, write to the Free Software
+  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
+  MA 02110-1301, USA.
+
+"""
+
+import logging
+from . import config as cfg
+from . import dialog
+
+
+def add_image_overlay(self) -> None:
+    """
+    add an image overlay on video from an image
+    """
+
+    logging.debug("function add_image_overlay")
+
+    try:
+        w = dialog.Video_overlay_dialog()
+        items = [f"Player #{i + 1}" for i, _ in enumerate(self.dw_player)]
+        w.cb_player.addItems(items)
+        if not w.exec_():
+            return
+
+        idx = w.cb_player.currentIndex()
+
+        if cfg.OVERLAY not in self.pj[cfg.OBSERVATIONS][self.observationId][cfg.MEDIA_INFO]:
+            self.pj[cfg.OBSERVATIONS][self.observationId][cfg.MEDIA_INFO][cfg.OVERLAY] = {}
+        self.pj[cfg.OBSERVATIONS][self.observationId][cfg.MEDIA_INFO][cfg.OVERLAY][str(idx + 1)] = {
+            "file name": w.le_file_path.text(),
+            "overlay position": w.le_overlay_position.text(),
+            "transparency": w.sb_overlay_transparency.value(),
+        }
+        self.overlays[idx] = self.dw_player[idx].player.create_image_overlay()
+        self.project_changed()
+        self.resize_dw(idx)
+
+    except Exception:
+        logging.debug("error in add_image_overlay function")
+
+
+def remove_image_overlay(self) -> None:
+    """
+    remove image overlay from all players
+    """
+    keys_to_delete: list = []
+    for n_player in self.pj[cfg.OBSERVATIONS][self.observationId][cfg.MEDIA_INFO].get(cfg.OVERLAY, {}):
+        keys_to_delete.append(n_player)
+        try:
+            self.overlays[int(n_player) - 1].remove()
+        except Exception:
+            logging.debug("Error removing image overlay")
+    for n_player in keys_to_delete:
+        del self.pj[cfg.OBSERVATIONS][self.observationId][cfg.MEDIA_INFO][cfg.OVERLAY][n_player]

boris/import_observations.py

@@ -0,0 +1,242 @@
+"""
+BORIS
+Behavioral Observation Research Interactive Software
+Copyright 2012-2025 Olivier Friard
+
+  This program is free software; you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation; either version 2 of the License, or
+  (at your option) any later version.
+
+  This program is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with this program; if not, write to the Free Software
+  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
+  MA 02110-1301, USA.
+"""
+
+import datetime
+import gzip
+import json
+import pandas as pd
+from pathlib import Path
+
+from PySide6.QtWidgets import (
+    QMessageBox,
+    QFileDialog,
+)
+
+from . import config as cfg
+from . import dialog
+from . import utilities as util
+
+
+def load_observations_from_boris_project(self, project_file_path: str):
+    """
+    import observations from a BORIS project file
+    """
+
+    if self.projectFileName and project_file_path == self.projectFileName:
+        QMessageBox.critical(
+            None,
+            cfg.programName,
+            "This project is already open",
+            QMessageBox.Ok | QMessageBox.Default,
+            QMessageBox.NoButton,
+        )
+        return
+
+    if project_file_path.endswith(".boris.gz"):
+        file_in = gzip.open(project_file_path, mode="rt", encoding="utf-8")
+    else:
+        file_in = open(project_file_path, "r")
+    file_content = file_in.read()
+
+    try:
+        fromProject = json.loads(file_content)
+    except Exception:
+        QMessageBox.critical(self, cfg.programName, "This project file seems corrupted")
+        return
+
+    # transform time to decimal
+    fromProject = util.convert_time_to_decimal(fromProject)  # function in utilities.py
+
+    dbc = dialog.ChooseObservationsToImport("Choose the observations to import:", sorted(list(fromProject[cfg.OBSERVATIONS].keys())))
+
+    if not dbc.exec_():
+        return
+    selected_observations = dbc.get_selected_observations()
+    if selected_observations:
+        flagImported = False
+
+        # set of behaviors in current projet ethogram
+        behav_set = set([self.pj[cfg.ETHOGRAM][idx][cfg.BEHAVIOR_CODE] for idx in self.pj[cfg.ETHOGRAM]])
+
+        # set of subjects in current projet
+        subjects_set = set([self.pj[cfg.SUBJECTS][idx][cfg.SUBJECT_NAME] for idx in self.pj[cfg.SUBJECTS]])
+
+        for obs_id in selected_observations:
+            # check if behaviors are in current project ethogram
+            new_behav_set = set(
+                [
+                    event[cfg.EVENT_BEHAVIOR_FIELD_IDX]
+                    for event in fromProject[cfg.OBSERVATIONS][obs_id][cfg.EVENTS]
+                    if event[cfg.EVENT_BEHAVIOR_FIELD_IDX] not in behav_set
+                ]
+            )
+            if new_behav_set:
+                diag_result = dialog.MessageDialog(
+                    cfg.programName,
+                    (f"Some coded behaviors in <b>{obs_id}</b> are not defined in the ethogram:<br><b>{', '.join(new_behav_set)}</b>"),
+                    ["Interrupt import", "Skip observation", "Import observation"],
+                )
+                if diag_result == "Interrupt import":
+                    return
+                if diag_result == "Skip observation":
+                    continue
+
+            # check if subjects are in current project
+            new_subject_set = set(
+                [
+                    event[cfg.EVENT_SUBJECT_FIELD_IDX]
+                    for event in fromProject[cfg.OBSERVATIONS][obs_id][cfg.EVENTS]
+                    if event[cfg.EVENT_SUBJECT_FIELD_IDX] not in subjects_set
+                ]
+            )
+            if new_subject_set and new_subject_set != {""}:
+                diag_result = dialog.MessageDialog(
+                    cfg.programName,
+                    (f"Some coded subjects in <b>{obs_id}</b> are not defined in the project:<br><b>{', '.join(new_subject_set)}</b>"),
+                    ["Interrupt import", "Skip observation", "Import observation"],
+                )
+
+                if diag_result == "Interrupt import":
+                    return
+
+                if diag_result == "Skip observation":
+                    continue
+
+            if obs_id in self.pj[cfg.OBSERVATIONS].keys():
+                diag_result = dialog.MessageDialog(
+                    cfg.programName,
+                    (f"The observation <b>{obs_id}</b>already exists in the current project.<br>"),
+                    ["Interrupt import", "Skip observation", "Rename observation"],
+                )
+                if diag_result == "Interrupt import":
+                    return
+
+                if diag_result == "Rename observation":
+                    self.pj[cfg.OBSERVATIONS][f"{obs_id} (imported at {util.datetime_iso8601(datetime.datetime.now())})"] = dict(
+                        fromProject[cfg.OBSERVATIONS][obs_id]
+                    )
+                    flagImported = True
+            else:
+                self.pj[cfg.OBSERVATIONS][obs_id] = dict(fromProject[cfg.OBSERVATIONS][obs_id])
+                flagImported = True
+
+        if flagImported:
+            QMessageBox.information(self, cfg.programName, "Observations imported successfully")
+            self.project_changed()
+
+
+def load_observations_from_spreadsheet(self, project_file_path: str):
+    """
+    import observations from a spreadsheet file
+    """
+
+    if Path(project_file_path).suffix.lower() == ".xlsx":
+        engine = "openpyxl"
+    elif Path(project_file_path).suffix.lower() == ".ods":
+        engine = "odf"
+    else:
+        return
+
+    try:
+        df = pd.read_excel(project_file_path, sheet_name=0, engine=engine)
+    except Exception:
+        QMessageBox.warning(
+            None,
+            cfg.programName,
+            ("The type of file was not recognized. Must be Microsoft-Excel XLSX format or OpenDocument ODS"),
+            QMessageBox.Ok | QMessageBox.Default,
+            QMessageBox.NoButton,
+        )
+        return
+
+    expected_labels: list = ("time", "subject", "code", "modifier", "comment")
+
+    df.columns = df.columns.str.upper()
+
+    for column in expected_labels:
+        if column.upper() not in list(df.columns):
+            QMessageBox.warning(
+                None,
+                cfg.programName,
+                (
+                    f"The {column} column was not found in the file header.<br>"
+                    "For information the current file header contains the following labels:<br>"
+                    f"{'<br>'.join(['<b>' + util.replace_leading_trailing_chars(x, ' ', '&#9608;') + '</b>' for x in df.columns])}<br>"
+                    "<br>"
+                    "The first row of the spreadsheet must contain the following labels:<br>"
+                    f"{'<br>'.join(['<b>' + x + '</b>' for x in expected_labels])}<br>"
+                    "<br>The order is not mandatory."
+                ),
+                QMessageBox.Ok | QMessageBox.Default,
+                QMessageBox.NoButton,
+            )
+            return 1
+    event: dict = {}
+    events: list = []
+    for _, row in df.iterrows():
+        for label in expected_labels:
+            event[label] = row[label.upper()] if str(row[label.upper()]) != "nan" else ""
+        events.append([event["time"], event["subject"], event["code"], event["modifier"], event["comment"]])
+
+    if events:
+        self.pj[cfg.OBSERVATIONS][self.observationId]["events"].extend(events)
+        self.load_tw_events(self.observationId)
+
+        QMessageBox.information(self, cfg.programName, "Observations imported successfully")
+        self.project_changed()
+
+
+def import_observations(self):
+    """
+    import observations from project file
+    """
+
+    file_name, _ = QFileDialog().getOpenFileName(
+        None, "Choose a file", "", "BORIS project files (*.boris *.boris.gz);;Spreadsheet files (*.ods *.xlsx *);;All files (*)"
+    )
+
+    if not file_name:
+        return
+
+    if file_name.endswith(".boris") or file_name.endswith(".boris.gz"):
+        load_observations_from_boris_project(self, file_name)
+
+    elif Path(file_name).suffix.lower() in (".ods", ".xlsx"):
+        if not self.observationId:
+            QMessageBox.warning(
+                None,
+                cfg.programName,
+                ("Please open or create a new observation before importing from a spreadsheet file"),
+                QMessageBox.Ok,
+                QMessageBox.NoButton,
+            )
+            return
+
+        load_observations_from_spreadsheet(self, file_name)
+
+    else:
+        QMessageBox.warning(
+            None,
+            cfg.programName,
+            ("The type of file was not recognized. Must be a BORIS project or a Microsoft-Excel XLSX format or OpenDocument ODS"),
+            QMessageBox.Ok | QMessageBox.Default,
+            QMessageBox.NoButton,
+        )