boris-behav-obs 8.16.6__py3-none-any.whl → 9.7.1__py3-none-any.whl

boris/export_observation.py

@@ -1,7 +1,7 @@
 """
 BORIS
 Behavioral Observation Research Interactive Software
-Copyright 2012-2023 Olivier Friard
+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
@@ -29,7 +29,7 @@ import math
 import pathlib
 from io import StringIO
 import pandas as pd
-from typing import List, Tuple, Dict
+from typing import Tuple
 
 try:
     import pyreadr
@@ -79,9 +79,7 @@ def export_events_jwatcher(
 
         total_length = 0  # in seconds
         if observation[cfg.EVENTS]:
-            total_length = (
-                observation[cfg.EVENTS][-1][0] - observation[cfg.EVENTS][0][0]
-            )  # last event time - first event time
+            total_length = observation[cfg.EVENTS][-1][0] - observation[cfg.EVENTS][0][0]  # last event time - first event time
 
         file_name_subject = str(pathlib.Path(file_name).parent / pathlib.Path(file_name).stem) + "_" + subject + ".dat"
 
@@ -119,14 +117,13 @@ def export_events_jwatcher(
             behav_code = event[cfg.EVENT_BEHAVIOR_FIELD_IDX]
 
             try:
-                behavior_key = [
-                    ethogram[k][cfg.BEHAVIOR_KEY] for k in ethogram if ethogram[k][cfg.BEHAVIOR_CODE] == behav_code
-                ][0]
+                behavior_key = [ethogram[k][cfg.BEHAVIOR_KEY] for k in ethogram if ethogram[k][cfg.BEHAVIOR_CODE] == behav_code][0]
             except Exception:
                 # coded behavior not defined in ethogram
                 continue
-            if [ethogram[k][cfg.TYPE] for k in ethogram if ethogram[k][cfg.BEHAVIOR_CODE] == behav_code] == [
-                cfg.STATE_EVENT
+            if [ethogram[k][cfg.TYPE] for k in ethogram if ethogram[k][cfg.BEHAVIOR_CODE] == behav_code] in [
+                [cfg.STATE_EVENT],
+                [cfg.STATE_EVENT_WITH_CODING_MAP],
             ]:
                 if behav_code in mem_number_of_state_events:
                     mem_number_of_state_events[behav_code] += 1
@@ -154,7 +151,7 @@ def export_events_jwatcher(
         if fmf_file_path.exists():
             fmf_creation_answer = dialog.MessageDialog(
                 cfg.programName,
-                (f"The {fmf_file_path} file already exists.<br>" "What do you want to do?"),
+                (f"The {fmf_file_path} file already exists.<br>What do you want to do?"),
                 [cfg.OVERWRITE, "Skip file creation", cfg.CANCEL],
             )
 
@@ -169,9 +166,7 @@ def export_events_jwatcher(
         rows.append("#-----------------------------------------------------------")
         for behav, key in all_observed_behaviors:
             rows.append(f"Behaviour.name.{key}={behav}")
-            behav_description = [
-                ethogram[k][cfg.DESCRIPTION] for k in ethogram if ethogram[k][cfg.BEHAVIOR_CODE] == behav
-            ][0]
+            behav_description = [ethogram[k][cfg.DESCRIPTION] for k in ethogram if ethogram[k][cfg.BEHAVIOR_CODE] == behav][0]
             rows.append(f"Behaviour.description.{key}={behav_description}")
 
         rows.append(f"DurationMilliseconds={int(float(total_length) * 1000)}")
@@ -198,7 +193,7 @@ def export_events_jwatcher(
         if faf_file_path.exists():
             faf_creation_answer = dialog.MessageDialog(
                 cfg.programName,
-                (f"The {faf_file_path} file already exists.<br>" "What do you want to do?"),
+                (f"The {faf_file_path} file already exists.<br>What do you want to do?"),
                 [cfg.OVERWRITE, "Skip file creation", cfg.CANCEL],
             )
             if faf_creation_answer == cfg.CANCEL:
@@ -318,6 +313,7 @@ def export_tabular_events(
     interval = parameters["time"]
 
     start_coding, end_coding, coding_duration = observation_operations.coding_time(pj[cfg.OBSERVATIONS], [obs_id])
+    start_interval, end_interval = observation_operations.time_intervals_range(pj[cfg.OBSERVATIONS], [obs_id])
 
     if interval == cfg.TIME_EVENTS:
         min_time = start_coding
@@ -338,6 +334,12 @@ def export_tabular_events(
         min_time = parameters[cfg.START_TIME]
         max_time = parameters[cfg.END_TIME]
 
+    if interval == cfg.TIME_OBS_INTERVAL:
+        max_media_duration, _ = observation_operations.media_duration(pj[cfg.OBSERVATIONS], [obs_id])
+        min_time = start_interval
+        # Use max media duration for max time if no interval is defined (=0)
+        max_time = end_interval if end_interval != 0 else max_media_duration
+
     logging.debug(f"min_time: {min_time}  max_time: {max_time}")
 
     events_with_status = project_functions.events_start_stop(ethogram, observation[cfg.EVENTS], observation[cfg.TYPE])
@@ -366,6 +368,7 @@ def export_tabular_events(
         "Observation duration": float,
         "Observation type": str,
         "Source": str,
+        "Time offset (s)": str,
     }
     if media_nb == 1:
         fields_type["Media duration (s)"] = float
@@ -434,9 +437,7 @@ def export_tabular_events(
                         for media_file in observation[cfg.FILE][player]:
                             media_file_lst.append(media_file)
                             fps_lst.append(f"{observation[cfg.MEDIA_INFO][cfg.FPS].get(media_file, cfg.NA):.3f}")
-                            media_durations_lst.append(
-                                f"{observation[cfg.MEDIA_INFO][cfg.LENGTH].get(media_file, cfg.NA):.3f}"
-                            )
+                            media_durations_lst.append(f"{observation[cfg.MEDIA_INFO][cfg.LENGTH].get(media_file, cfg.NA):.3f}")
                         if player > "1":
                             media_file_str += "|"
                             fps_str += "|"
@@ -486,6 +487,9 @@ def export_tabular_events(
             else:
                 fields.append("")
 
+            # time offset
+            fields.append(observation[cfg.TIME_OFFSET])
+
             # media duration
             fields.append(media_durations_str)
 
@@ -524,9 +528,7 @@ def export_tabular_events(
 
             # check video file name containing the event
             if observation[cfg.TYPE] == cfg.MEDIA:
-                video_file_name = observation_operations.event2media_file_name(
-                    observation, event[cfg.EVENT_TIME_FIELD_IDX]
-                )
+                video_file_name = observation_operations.event2media_file_name(observation, event[cfg.EVENT_TIME_FIELD_IDX])
                 if video_file_name is None:
                     video_file_name = "Not found"
 
@@ -571,9 +573,7 @@ def export_tabular_events(
     return r, msg
 
 
-def dataset_write(
-    dataset: tablib.Dataset, file_name: str, output_format: str, dtype: dict = {}
-) -> tuple:  # -> tuple[bool, str]:
+def dataset_write(dataset: tablib.Dataset, file_name: str, output_format: str, dtype: dict = {}) -> tuple:  # -> tuple[bool, str]:
     """
     write a tablib dataset with aggregated events or tabular events to file in specified format (output_format)
 
@@ -593,7 +593,7 @@ def dataset_write(
     try:
         if output_format in (cfg.PANDAS_DF_EXT, cfg.RDS_EXT):
             # build pandas dataframe from the tsv export of tablib dataset
-            date_type = []
+            date_type: list = []
             for field_name in dtype:
                 if dtype[field_name] == dt.datetime:
                     date_type.append(field_name)
@@ -611,12 +611,12 @@ def dataset_write(
             if output_format == cfg.PANDAS_DF_EXT:
                 df.to_pickle(file_name)
 
-            if flag_pyreadr_loaded and output_format == cfg.RDS_EXT:
+            if output_format == cfg.RDS_EXT and flag_pyreadr_loaded:
                 pyreadr.write_rds(file_name, df)
 
             return True, ""
 
-        if output_format in (cfg.CSV_EXT, cfg.TSV_EXT, cfg.HMTL_EXT):
+        if output_format in (cfg.CSV_EXT, cfg.TSV_EXT, cfg.HTML_EXT):
             with open(file_name, "wb") as f:
                 f.write(str.encode(dataset.export(output_format)))
             return True, ""
@@ -634,7 +634,7 @@ def dataset_write(
         return False, str(sys.exc_info()[1])
 
 
-def export_aggregated_events(pj: dict, parameters: dict, obsId: str) -> Tuple[tablib.Dataset, int]:
+def export_aggregated_events(pj: dict, parameters: dict, obsId: str, force_number_modifiers: int = 0) -> Tuple[tablib.Dataset, int]:
     """
     export aggregated events of one observation
 
@@ -642,6 +642,7 @@ def export_aggregated_events(pj: dict, parameters: dict, obsId: str) -> Tuple[ta
         pj (dict): BORIS project
         parameters (dict): subjects, behaviors
         obsId (str): observation id
+        force_number_modifiers (int): force the number of modifiers to return
 
     Returns:
         tablib.Dataset:
@@ -656,6 +657,8 @@ def export_aggregated_events(pj: dict, parameters: dict, obsId: str) -> Tuple[ta
     data = tablib.Dataset()
 
     start_coding, end_coding, coding_duration = observation_operations.coding_time(pj[cfg.OBSERVATIONS], [obsId])
+    start_interval, end_interval = observation_operations.time_intervals_range(pj[cfg.OBSERVATIONS], [obsId])
+
     if start_coding is None and end_coding is None:  # no events
         return data, 0
 
@@ -677,21 +680,22 @@ def export_aggregated_events(pj: dict, parameters: dict, obsId: str) -> Tuple[ta
         min_time = float(parameters[cfg.START_TIME])
         max_time = float(parameters[cfg.END_TIME])
 
+    if interval == cfg.TIME_OBS_INTERVAL:
+        max_media_duration, _ = observation_operations.media_duration(pj[cfg.OBSERVATIONS], [obsId])
+        min_time = float(start_interval)
+        # Use max media duration for max time if no interval is defined (=0)
+        max_time = float(end_interval) if end_interval != 0 else float(max_media_duration)
+
     logging.debug(f"min_time: {min_time}  max_time: {max_time}")
 
     # obs description
     obs_description = util.eol2space(observation[cfg.DESCRIPTION])
 
-    """
-    obs_length = observation_operations.observation_total_length(pj[cfg.OBSERVATIONS][obsId])
-    logging.debug(f"obs_length: {obs_length}")
-    """
-
     _, _, connector = db_functions.load_aggregated_events_in_db(
         pj, parameters[cfg.SELECTED_SUBJECTS], [obsId], parameters[cfg.SELECTED_BEHAVIORS]
     )
     if connector is None:
-        logging.critical(f"error when loading aggregated events in DB")
+        logging.critical("error when loading aggregated events in DB")
         return data, 0
 
     cursor = connector.cursor()
@@ -745,10 +749,14 @@ def export_aggregated_events(pj: dict, parameters: dict, obsId: str) -> Tuple[ta
     behavioral_category = project_functions.behavior_category(pj[cfg.ETHOGRAM])
 
     cursor.execute("SELECT DISTINCT modifiers FROM aggregated_events")
-    max_modifiers = 0
-    for row in cursor.fetchall():
-        if row["modifiers"]:
-            max_modifiers = max(max_modifiers, row["modifiers"].count("|") + 1)
+
+    if not force_number_modifiers:
+        max_modifiers: int = 0
+        for row in cursor.fetchall():
+            if row["modifiers"]:
+                max_modifiers = max(max_modifiers, row["modifiers"].count("|") + 1)
+    else:
+        max_modifiers = force_number_modifiers
 
     for subject in parameters[cfg.SELECTED_SUBJECTS]:
         # calculate observation duration by subject (by obs)
@@ -785,6 +793,7 @@ def export_aggregated_events(pj: dict, parameters: dict, obsId: str) -> Tuple[ta
                     if observation[cfg.TYPE] == cfg.MEDIA:
                         observation_type = "Media file"
 
+                        # get the media file name of the start of event
                         media_file_name = observation_operations.event2media_file_name(observation, row["start"])
                         if media_file_name is None:
                             media_file_name = "Not found"
@@ -796,12 +805,8 @@ def export_aggregated_events(pj: dict, parameters: dict, obsId: str) -> Tuple[ta
                             if observation[cfg.FILE][player]:
                                 for media_file in observation[cfg.FILE][player]:
                                     media_file_lst.append(media_file)
-                                    fps_lst.append(
-                                        f"{observation[cfg.MEDIA_INFO][cfg.FPS].get(media_file, cfg.NA):.3f}"
-                                    )
-                                    media_durations_lst.append(
-                                        f"{observation[cfg.MEDIA_INFO][cfg.LENGTH].get(media_file, cfg.NA):.3f}"
-                                    )
+                                    fps_lst.append(f"{observation[cfg.MEDIA_INFO][cfg.FPS].get(media_file, cfg.NA):.3f}")
+                                    media_durations_lst.append(f"{observation[cfg.MEDIA_INFO][cfg.LENGTH].get(media_file, cfg.NA):.3f}")
                                 if player > "1":
                                     media_file_str += "|"
                                     fps_str += "|"
@@ -833,7 +838,8 @@ def export_aggregated_events(pj: dict, parameters: dict, obsId: str) -> Tuple[ta
                             observation["date"].replace("T", " "),
                             obs_description,
                             observation_type,
-                            media_file_str,
+                            media_file_str,  # list of media used in observation
+                            pj[cfg.OBSERVATIONS][obsId][cfg.TIME_OFFSET],
                             f"{coding_duration:.3f}" if not coding_duration.is_nan() else cfg.NA,
                             media_durations_str,
                             fps_str,
@@ -843,13 +849,8 @@ def export_aggregated_events(pj: dict, parameters: dict, obsId: str) -> Tuple[ta
                     # independent variables
                     if cfg.INDEPENDENT_VARIABLES in pj:
                         for idx_var in util.sorted_keys(pj[cfg.INDEPENDENT_VARIABLES]):
-                            if (
-                                pj[cfg.INDEPENDENT_VARIABLES][idx_var]["label"]
-                                in observation[cfg.INDEPENDENT_VARIABLES]
-                            ):
-                                var_value = observation[cfg.INDEPENDENT_VARIABLES][
-                                    pj[cfg.INDEPENDENT_VARIABLES][idx_var]["label"]
-                                ]
+                            if pj[cfg.INDEPENDENT_VARIABLES][idx_var]["label"] in observation[cfg.INDEPENDENT_VARIABLES]:
+                                var_value = observation[cfg.INDEPENDENT_VARIABLES][pj[cfg.INDEPENDENT_VARIABLES][idx_var]["label"]]
                                 if pj[cfg.INDEPENDENT_VARIABLES][idx_var]["type"] == "timestamp":
                                     var_value = var_value.replace("T", " ")
 
@@ -892,9 +893,7 @@ def export_aggregated_events(pj: dict, parameters: dict, obsId: str) -> Tuple[ta
                                 f"{row['start']:.3f}" if row["start"] is not None else cfg.NA,
                                 f"{row['stop']:.3f}" if row["stop"] is not None else cfg.NA,
                                 # duration
-                                f"{row['stop'] - row['start']:.3f}"
-                                if (row["stop"] is not None) and (row["start"] is not None)
-                                else cfg.NA,
+                                f"{row['stop'] - row['start']:.3f}" if (row["stop"] is not None) and (row["start"] is not None) else cfg.NA,
                                 media_file_name,  # Media file name
                             ]
                         )
@@ -943,9 +942,7 @@ def events_to_behavioral_sequences(pj, obs_id: str, subj: str, parameters: dict,
         if event[cfg.EVENT_BEHAVIOR_FIELD_IDX] not in parameters[cfg.SELECTED_BEHAVIORS]:
             continue
 
-        if event[cfg.EVENT_SUBJECT_FIELD_IDX] == subj or (
-            subj == cfg.NO_FOCAL_SUBJECT and event[cfg.EVENT_SUBJECT_FIELD_IDX] == ""
-        ):
+        if event[cfg.EVENT_SUBJECT_FIELD_IDX] == subj or (subj == cfg.NO_FOCAL_SUBJECT and event[cfg.EVENT_SUBJECT_FIELD_IDX] == ""):
             # if event[cfg.EVENT_STATUS_FIELD_IDX] == cfg.POINT:
             if event[-1] == cfg.POINT:  # status is last element
                 if current_states:
@@ -1000,9 +997,7 @@ def events_to_behavioral_sequences(pj, obs_id: str, subj: str, parameters: dict,
     return out
 
 
-def events_to_behavioral_sequences_all_subj(
-    pj, obs_id: str, subjects_list: list, parameters: dict, behav_seq_separator: str
-) -> str:
+def events_to_behavioral_sequences_all_subj(pj, obs_id: str, subjects_list: list, parameters: dict, behav_seq_separator: str) -> str:
     """
     return the behavioral sequences for all selected subjects in obs_id
 
@@ -1035,9 +1030,7 @@ def events_to_behavioral_sequences_all_subj(
 
             if event[-1] == cfg.POINT:
                 if current_states[subject]:
-                    out += (
-                        f"[{subject}]" + "+".join(current_states[subject]) + "+" + event[cfg.EVENT_BEHAVIOR_FIELD_IDX]
-                    )
+                    out += f"[{subject}]" + "+".join(current_states[subject]) + "+" + event[cfg.EVENT_BEHAVIOR_FIELD_IDX]
                 else:
                     out += f"[{subject}]" + event[cfg.EVENT_BEHAVIOR_FIELD_IDX]
 
@@ -1139,9 +1132,7 @@ def events_to_timed_behavioral_sequences(
     return out
 
 
-def observation_to_behavioral_sequences(
-    pj, selected_observations, parameters, behaviors_separator, separated_subjects, timed, file_name
-):
+def observation_to_behavioral_sequences(pj, selected_observations, parameters, behaviors_separator, separated_subjects, timed, file_name):
     try:
         with open(file_name, "w", encoding="utf-8") as out_file:
             for obs_id in selected_observations:
@@ -1179,9 +1170,7 @@ def observation_to_behavioral_sequences(
                     out_file.write("# Independent variables\n")
 
                     for variable in pj[cfg.OBSERVATIONS][obs_id][cfg.INDEPENDENT_VARIABLES]:
-                        out_file.write(
-                            f"# {variable}: {pj[cfg.OBSERVATIONS][obs_id][cfg.INDEPENDENT_VARIABLES][variable]}\n"
-                        )
+                        out_file.write(f"# {variable}: {pj[cfg.OBSERVATIONS][obs_id][cfg.INDEPENDENT_VARIABLES][variable]}\n")
                 out_file.write("\n")
 
                 # one sequence for all subjects
@@ -1202,9 +1191,7 @@ def observation_to_behavioral_sequences(
                             out = events_to_behavioral_sequences(pj, obs_id, subject, parameters, behaviors_separator)
 
                         if timed:
-                            out = events_to_timed_behavioral_sequences(
-                                pj, obs_id, subject, parameters, 0.001, behaviors_separator
-                            )
+                            out = events_to_timed_behavioral_sequences(pj, obs_id, subject, parameters, 0.001, behaviors_separator)
 
                         if out:
                             out_file.write(out + "\n")