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

boris/advanced_event_filtering.py

@@ -0,0 +1,455 @@
+"""
+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
+import re
+import statistics
+import sys
+
+import tablib
+from PySide6.QtCore import Qt
+from PySide6.QtGui import QIcon
+from PySide6.QtWidgets import (
+    QDialog,
+    QFileDialog,
+    QHBoxLayout,
+    QLabel,
+    QLineEdit,
+    QListWidget,
+    QMessageBox,
+    QPushButton,
+    QRadioButton,
+    QSizePolicy,
+    QSpacerItem,
+    QTableWidget,
+    QTableWidgetItem,
+    QVBoxLayout,
+)
+
+from . import config as cfg
+from . import db_functions, dialog, observation_operations
+from . import portion as Interval
+from . import project_functions, select_observations, select_subj_behav
+from . import utilities as util
+
+
+def icc(i: list):
+    """
+    create a closed-closed interval
+    """
+    return Interval.closed(i[0], i[1])
+
+
+def ico(i: list):
+    """
+    create a closed-open interval
+    """
+    return Interval.closedopen(i[0], i[1])
+
+
+def io(i: list):
+    """
+    create a open interval
+    """
+    return Interval.open(i[0], i[1])
+
+
+class Advanced_event_filtering_dialog(QDialog):
+    """
+    Dialog for visualizing advanced event filtering results
+    """
+
+    summary_header: tuple = (
+        "Observation id",
+        "Number of occurences",
+        "Total duration (s)",
+        "Duration mean (s)",
+        "Std Dev",
+    )
+    details_header: tuple = ("Observation id", "Comment", "Start time", "Stop time", "Duration (s)")
+
+    def __init__(self, events):
+        super().__init__()
+
+        self.events = events
+        self.out = []
+        self.setWindowTitle("Advanced event filtering")
+
+        vbox = QVBoxLayout()
+
+        self.lb_time_interval = QLabel()
+        vbox.addWidget(self.lb_time_interval)
+
+        hbox = QHBoxLayout()
+        hbox.addWidget(QLabel("Filter"))
+        self.logic = QLineEdit("")
+        hbox.addWidget(self.logic)
+        self.pb_filter = QPushButton("Filter events", clicked=self.filter)
+        hbox.addWidget(self.pb_filter)
+        self.pb_clear = QPushButton("Clear", clicked=self.logic.clear)
+        self.pb_clear.setIcon(QIcon.fromTheme("edit-clear"))
+        hbox.addWidget(self.pb_clear)
+        vbox.addLayout(hbox)
+
+        hbox = QHBoxLayout()
+        self.rb_summary = QRadioButton("Summary", toggled=self.filter)
+        self.rb_summary.setChecked(True)
+        hbox.addWidget(self.rb_summary)
+        self.rb_details = QRadioButton("Details", toggled=self.filter)
+        hbox.addWidget(self.rb_details)
+        vbox.addLayout(hbox)
+
+        hbox = QHBoxLayout()
+        vbox2 = QVBoxLayout()
+        vbox2.addWidget(QLabel("Subjects"))
+        self.lw1 = QListWidget()
+        vbox2.addWidget(self.lw1)
+        hbox.addLayout(vbox2)
+
+        vbox2 = QVBoxLayout()
+        vbox2.addWidget(QLabel("Behaviors"))
+        self.lw2 = QListWidget()
+        vbox2.addWidget(self.lw2)
+        hbox.addLayout(vbox2)
+        self.add_subj_behav_button = QPushButton("", clicked=self.add_subj_behav)
+        self.add_subj_behav_button.setIcon(QIcon.fromTheme("go-up"))
+        hbox.addWidget(self.add_subj_behav_button)
+
+        vbox2 = QVBoxLayout()
+        vbox2.addWidget(QLabel("Logical operators"))
+        self.lw3 = QListWidget()
+        self.lw3.addItems(["AND", "OR"])
+        vbox2.addWidget(self.lw3)
+        hbox.addLayout(vbox2)
+        self.add_logic_button = QPushButton("", clicked=self.add_logic)
+        self.add_logic_button.setIcon(QIcon.fromTheme("go-up"))
+        hbox.addWidget(self.add_logic_button)
+
+        vbox.addLayout(hbox)
+
+        self.lb_results = QLabel("Results")
+        vbox.addWidget(self.lb_results)
+
+        self.tw = QTableWidget(self)
+        vbox.addWidget(self.tw)
+
+        hbox = QHBoxLayout()
+        hbox.addItem(QSpacerItem(241, 20, QSizePolicy.Expanding, QSizePolicy.Minimum))
+        self.pb_save = QPushButton("Save results", clicked=self.save_results)
+        hbox.addWidget(self.pb_save)
+        self.pb_close = QPushButton(cfg.CLOSE, clicked=self.close)
+        hbox.addWidget(self.pb_close)
+        vbox.addLayout(hbox)
+
+        self.setLayout(vbox)
+
+        subjects_list, behaviors_list = [], []
+        for obs_id in events:
+            for subj_behav in events[obs_id]:
+                subj, behav = subj_behav.split("|")
+                subjects_list.append(subj)
+                behaviors_list.append(behav)
+        subjects_set = sorted(set(subjects_list))
+        behaviors_set = sorted(set(behaviors_list))
+
+        self.lw1.addItems(subjects_set)
+        self.lw2.addItems(behaviors_set)
+
+        self.resize(640, 640)
+
+    def add_subj_behav(self):
+        """
+        add subject|behavior of selected listwidgets items in lineEdit
+        """
+        if self.lw1.currentItem() and self.lw2.currentItem():
+            self.logic.insert(f'"{self.lw1.currentItem().text()}|{self.lw2.currentItem().text()}" ')
+        else:
+            QMessageBox.warning(self, cfg.programName, "Select a subject and a behavior")
+
+    def add_logic(self):
+        """
+        add selected logic operaton to lineedit
+        """
+        if self.lw3.currentItem():
+            text = ""
+            if self.lw3.currentItem().text() == "AND":
+                text = " & "
+            if self.lw3.currentItem().text() == "OR":
+                text = " | "
+            if text:
+                self.logic.insert(text)
+        else:
+            QMessageBox.warning(self, cfg.programName, "Select a logical operator")
+
+    def filter(self):
+        """
+        filter events
+        """
+        if not self.logic.text():
+            return
+        if self.logic.text().count('"') % 2:
+            QMessageBox.warning(self, cfg.programName, 'Wrong number of double quotes (")')
+            return
+
+        sb_list = re.findall('"([^"]*)"', self.logic.text())
+
+        self.out = []
+        flag_error = False
+        for obs_id in self.events:
+            logic = self.logic.text()
+            for sb in set(sb_list):
+                logic = logic.replace(f'"{sb}"', f'self.events[obs_id]["{sb}"]')
+                if sb not in self.events[obs_id]:
+                    self.events[obs_id][sb] = io([0, 0])
+
+            try:
+                eval_result = eval(logic)
+                for i in eval_result:
+                    if not i.empty:
+                        self.out.append([obs_id, "", f"{i.lower}", f"{i.upper}", f"{i.upper - i.lower:.3f}"])
+            except KeyError:
+                self.out.append([obs_id, "subject / behavior not found", cfg.NA, cfg.NA, cfg.NA])
+            except Exception:
+                error_type, _, _ = util.error_info(sys.exc_info())
+                self.out.append([obs_id, f"Error in {self.logic.text()}: {error_type} ", cfg.NA, cfg.NA, cfg.NA])
+                flag_error = True
+
+        self.tw.clear()
+
+        if flag_error or self.rb_details.isChecked():
+            self.lb_results.setText(f"Results ({len(self.out)} event{'s' * (len(self.out) > 1)})")
+
+            self.tw.setRowCount(len(self.out))
+            self.tw.setColumnCount(len(self.details_header))  # obs_id, comment, start, stop, duration
+            self.tw.setHorizontalHeaderLabels(self.details_header)
+
+        if not flag_error and self.rb_summary.isChecked():
+            summary = {}
+            for row in self.out:
+                obs_id, _, start, stop, duration = row
+                if obs_id not in summary:
+                    summary[obs_id] = []
+                summary[obs_id].append(float(duration))
+
+            self.out = []
+            for obs_id in summary:
+                self.out.append(
+                    [
+                        obs_id,
+                        str(len(summary[obs_id])),
+                        str(round(sum(summary[obs_id]), 3)),
+                        str(round(statistics.mean(summary[obs_id]), 3)),
+                        str(round(statistics.stdev(summary[obs_id]), 3)) if len(summary[obs_id]) > 1 else "NA",
+                    ]
+                )
+
+            self.lb_results.setText(f"Results ({len(summary)} observation{'s' * (len(summary) > 1)})")
+            self.tw.setRowCount(len(summary))
+            self.tw.setColumnCount(len(self.summary_header))  # obs_id, mean, stdev
+            self.tw.setHorizontalHeaderLabels(self.summary_header)
+
+        for r in range(len(self.out)):
+            for c in range(self.tw.columnCount()):
+                item = QTableWidgetItem()
+                item.setText(self.out[r][c])
+                item.setFlags(Qt.ItemIsEnabled)
+                self.tw.setItem(r, c, item)
+
+    def save_results(self):
+        """
+        save results
+        """
+
+        file_formats = [
+            cfg.TSV,
+            cfg.CSV,
+            cfg.ODS,
+            cfg.XLSX,
+            cfg.XLS,
+            cfg.HTML,
+        ]
+
+        file_name, filter_ = QFileDialog().getSaveFileName(None, "Save results", "", ";;".join(file_formats))
+        if not file_name:
+            return
+
+        output_format = cfg.FILE_NAME_SUFFIX[filter_]
+
+        if pathlib.Path(file_name).suffix != "." + output_format:
+            file_name = str(pathlib.Path(file_name)) + "." + output_format
+            # check if file with new extension already exists
+            if pathlib.Path(file_name).is_file():
+                if (
+                    dialog.MessageDialog(cfg.programName, f"The file {file_name} already exists.", [cfg.CANCEL, cfg.OVERWRITE])
+                    == cfg.CANCEL
+                ):
+                    return
+
+        if self.rb_details.isChecked():
+            tablib_dataset = tablib.Dataset(headers=self.details_header)
+        if self.rb_summary.isChecked():
+            tablib_dataset = tablib.Dataset(headers=self.summary_header)
+        tablib_dataset.title = util.safe_xl_worksheet_title(self.logic.text(), output_format)
+
+        [tablib_dataset.append(x) for x in self.out]
+
+        try:
+            with open(file_name, "wb") as f:
+                if filter_ in (cfg.TSV, cfg.CSV, cfg.HTML):
+                    f.write(str.encode(tablib_dataset.export(output_format)))
+                if filter_ in (cfg.ODS, cfg.XLSX, cfg.XLS):
+                    f.write(tablib_dataset.export(output_format))
+
+        except Exception:
+            QMessageBox.critical(self, cfg.programName, f"The file {file_name} can not be saved")
+
+
+def event_filtering(self):
+    """
+    advanced event filtering
+    the portion module is used to do operations on intervals (intersection, union)
+    """
+
+    _, selected_observations = select_observations.select_observations2(
+        self, cfg.MULTIPLE, "Select observations for advanced event filtering"
+    )
+    if not selected_observations:
+        return
+
+    not_ok, selected_observations = project_functions.check_state_events(self.pj, selected_observations)
+    if not_ok or not selected_observations:
+        return
+
+    start_coding, end_coding, _ = observation_operations.coding_time(self.pj[cfg.OBSERVATIONS], selected_observations)
+    # exit with message if events do not have timestamp
+    if start_coding.is_nan():
+        QMessageBox.critical(
+            None,
+            cfg.programName,
+            ("This function is not available for observations with events that do not have a timestamp"),
+            QMessageBox.Ok | QMessageBox.Default,
+            QMessageBox.NoButton,
+        )
+        return
+
+    max_media_duration_all_obs, _ = observation_operations.media_duration(self.pj[cfg.OBSERVATIONS], selected_observations)
+
+    start_interval, end_interval = observation_operations.time_intervals_range(self.pj[cfg.OBSERVATIONS], selected_observations)
+
+    parameters = select_subj_behav.choose_obs_subj_behav_category(
+        self,
+        selected_observations,
+        start_coding=start_coding,
+        end_coding=end_coding,
+        # start_interval=start_interval,
+        # end_interval=end_interval,
+        start_interval=None,
+        end_interval=None,
+        maxTime=max_media_duration_all_obs,
+        show_include_modifiers=False,
+        show_exclude_non_coded_behaviors=False,
+        by_category=False,
+        n_observations=len(selected_observations),
+    )
+
+    if not parameters:
+        return
+
+    if not parameters[cfg.SELECTED_SUBJECTS] or not parameters[cfg.SELECTED_BEHAVIORS]:
+        QMessageBox.warning(None, cfg.programName, "Select subject(s) and behavior(s) to analyze")
+        return
+
+    _, _, db_connector = db_functions.load_aggregated_events_in_db(
+        self.pj, parameters[cfg.SELECTED_SUBJECTS], selected_observations, parameters[cfg.SELECTED_BEHAVIORS]
+    )
+
+    cursor = db_connector.cursor()
+
+    if parameters[cfg.TIME_INTERVAL] in (cfg.TIME_EVENTS, cfg.TIME_FULL_OBS):
+        cursor.execute("SELECT MIN(start), MAX(stop) FROM aggregated_events")
+        min_time, max_time = cursor.fetchone()
+
+    if parameters[cfg.TIME_INTERVAL] in (cfg.TIME_ARBITRARY_INTERVAL, cfg.TIME_OBS_INTERVAL):
+        min_time = float(parameters[cfg.START_TIME])
+        max_time = float(parameters[cfg.END_TIME])
+
+    cursor.execute(
+        "UPDATE aggregated_events SET start = ? WHERE start < ? AND stop BETWEEN ? AND ?",
+        (
+            min_time,
+            min_time,
+            min_time,
+            max_time,
+        ),
+    )
+    cursor.execute(
+        "UPDATE aggregated_events SET stop = ? WHERE stop > ? AND start BETWEEN ? AND ?",
+        (
+            max_time,
+            max_time,
+            min_time,
+            max_time,
+        ),
+    )
+    cursor.execute(
+        "UPDATE aggregated_events SET start = ?, stop = ? WHERE start < ? AND stop > ?",
+        (
+            min_time,
+            max_time,
+            min_time,
+            max_time,
+        ),
+    )
+
+    cursor.execute(
+        "DELETE FROM aggregated_events WHERE (start < ? AND stop < ?) OR (start > ? AND stop > ?)",
+        (
+            min_time,
+            min_time,
+            max_time,
+            max_time,
+        ),
+    )
+
+    # create intervals from DB
+    cursor.execute("SELECT observation, subject, behavior, start, stop FROM aggregated_events")
+
+    events: dict = {}
+    for row in cursor.fetchall():
+        obs, subj, behav, start, stop = row
+        if obs not in events:
+            events[obs] = {}
+
+        # use function in base at event (state or point)
+        interval_func = icc if start == stop else ico
+
+        if f"{subj}|{behav}" not in events[obs]:
+            # create new interval
+            events[obs][f"{subj}|{behav}"] = interval_func([start, stop])
+        else:
+            # append to existing interval
+            events[obs][f"{subj}|{behav}"] |= interval_func([start, stop])
+
+    w = Advanced_event_filtering_dialog(events)
+    w.lb_time_interval.setText(
+        (f"Time interval: {util.smart_time_format(min_time, self.timeFormat)} - {util.smart_time_format(max_time, self.timeFormat)}")
+    )
+    w.exec_()

boris/analysis_plugins/_latency.py

@@ -0,0 +1,59 @@
+"""
+BORIS plugin
+
+number of occurences of behaviors
+"""
+
+import pandas as pd
+
+__version__ = "0.0.1"
+__version_date__ = "2025-04-10"
+__plugin_name__ = "Behavior latencyxxx"
+__author__ = "Olivier Friard - University of Torino - Italy"
+
+
+import itertools
+
+
+def run(df: pd.DataFrame):
+    """
+    Latency of a behavior after another.
+    """
+
+    df["start_time"] = pd.to_datetime(df["Start (s)"])
+    df["end_time"] = pd.to_datetime(df["Stop (s)"])
+
+    latency_by_subject: dict = {}
+
+    for subject, group in df.groupby("subject"):
+        behaviors = group["behavior"].tolist()
+        # combinations = []
+        # Utiliser itertools pour créer des combinaisons 2 à 2 des comportements
+        for comb in itertools.combinations(behaviors, 2):
+            # combinations.append(comb)
+
+            last_A_end_time = None
+
+            # Liste pour stocker les latences de chaque sujet
+            subject_latency = []
+
+            for index, row in group.iterrows():
+                if row["behavior"] == comb[0]:
+                    # Si on rencontre un comportement A, on réinitialise le temps de fin du comportement A
+                    last_A_end_time = row["end_time"]
+                    subject_latency.append(None)  # Pas de latence pour A
+                elif row["behavior"] == comb[1] and last_A_end_time is not None:
+                    # Si on rencontre un comportement B et qu'on a déjà vu un A avant
+                    latency_time = row["start_time"] - last_A_end_time
+                    subject_latency.append(latency_time)
+                else:
+                    # Si on rencontre un B mais sans A avant
+                    subject_latency.append(None)
+
+            # Ajout des latences calculées au DataFrame
+            df.loc[group.index, f"latency {comb[1]} after {comb[0]}"] = subject_latency
+
+            # Calcul de la latence totale ou moyenne par sujet
+            latency_by_subject[(subject, comb)] = df.groupby("subject")["latency"].agg(["sum", "mean"])
+
+    return str(latency_by_subject)

boris/analysis_plugins/irr_cohen_kappa.py

@@ -0,0 +1,109 @@
+"""
+BORIS plugin
+
+Inter Rater Reliability (IRR) Unweighted Cohen's Kappa
+"""
+
+import pandas as pd
+from typing import Dict, Tuple
+
+from sklearn.metrics import cohen_kappa_score
+from PySide6.QtWidgets import QInputDialog
+
+
+__version__ = "0.0.3"
+__version_date__ = "2025-09-02"
+__plugin_name__ = "Inter Rater Reliability - Unweighted Cohen's Kappa"
+__author__ = "Olivier Friard - University of Torino - Italy"
+__description__ = """
+This plugin calculates Cohen's Kappa to measure inter-rater reliability between two observers who code categorical behaviors over time intervals.
+Unlike the weighted version, this approach does not take into account the duration of the intervals.
+Each segment of time is treated equally, regardless of how long it lasts.
+This plugin does not take into account the modifiers.
+
+How it works:
+
+Time segmentation
+The program identifies all the time boundaries (start and end points) used by both observers.
+These boundaries are merged into a common timeline, which is then divided into a set of non-overlapping elementary intervals.
+
+Assigning codes
+For each elementary interval, the program determines which behavior was coded by each observer.
+
+Comparison of codes
+The program builds two parallel lists of behavior codes, one for each observer.
+Each elementary interval is counted as one unit of observation, no matter how long the interval actually lasts.
+
+Cohen's Kappa calculation
+Using these two lists, the program computes Cohen's Kappa using the cohen_kappa_score function of the sklearn package.
+(see https://scikit-learn.org/stable/modules/generated/sklearn.metrics.cohen_kappa_score.html for details)
+This coefficient measures how much the observers agree on their coding, adjusted for the amount of agreement that would be expected by chance.
+
+"""
+
+
+def run(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Calculate the Inter Rater Reliability - Unweighted Cohen's Kappa
+    """
+
+    # Attribute all active codes for each interval
+    def get_code(t_start, obs):
+        active_codes = [seg[2] for seg in obs if seg[0] <= t_start < seg[1]]
+        if not active_codes:
+            return ""
+        # Sort to ensure deterministic representation (e.g., "A+B" instead of "B+A")
+        return "+".join(sorted(active_codes))
+
+    # ask user for the number of decimal places for rounding (can be negative)
+    round_decimals, ok = QInputDialog.getInt(
+        None, "Rounding", "Enter the number of decimal places for rounding (can be negative)", value=3, minValue=-5, maxValue=3, step=1
+    )
+
+    # round times
+    df["Start (s)"] = df["Start (s)"].round(round_decimals)
+    df["Stop (s)"] = df["Stop (s)"].round(round_decimals)
+
+    # Get unique values
+    unique_obs_list = df["Observation id"].unique().tolist()
+
+    # Convert to tuples grouped by observation
+    grouped = {
+        obs: [
+            (row[0], row[1], row[2] + "|" + row[3])  # concatenate subject and behavior with |
+            for row in group[["Start (s)", "Stop (s)", "Subject", "Behavior"]].itertuples(index=False, name=None)
+        ]
+        for obs, group in df.groupby("Observation id")
+    }
+
+    ck_results: Dict[Tuple[str, str], str] = {}
+    for idx1, obs_id1 in enumerate(unique_obs_list):
+        obs1 = grouped[obs_id1]
+
+        # Perfect agreement with itself
+        ck_results[(obs_id1, obs_id1)] = "1.000"
+
+        for obs_id2 in unique_obs_list[idx1 + 1 :]:
+            obs2 = grouped[obs_id2]
+
+            # get all the break points
+            time_points = sorted(set([t for seg in obs1 for t in seg[:2]] + [t for seg in obs2 for t in seg[:2]]))
+
+            # elementary intervals
+            elementary_intervals = [(time_points[i], time_points[i + 1]) for i in range(len(time_points) - 1)]
+
+            obs1_codes = [get_code(t[0], obs1) for t in elementary_intervals]
+
+            obs2_codes = [get_code(t[0], obs2) for t in elementary_intervals]
+
+            # Cohen's Kappa
+            kappa = cohen_kappa_score(obs1_codes, obs2_codes)
+            print(f"{obs_id1} -  {obs_id2}:  Cohen's Kappa : {kappa:.3f}")
+
+            ck_results[(obs_id1, obs_id2)] = f"{kappa:.3f}"
+            ck_results[(obs_id2, obs_id1)] = f"{kappa:.3f}"
+
+    # DataFrame conversion
+    df_results = pd.Series(ck_results).unstack()
+
+    return df_results