neurotask 0.2.0__py3-none-any.whl

neurotask/tmt/config.py

@@ -0,0 +1,8 @@
+"""
+Centralized configuration for TMT analysis.
+"""
+
+# Maximum valid speed threshold (in pixels/millisecond).
+# Speeds above this value are considered measurement errors.
+INVALID_SPEED_THRESHOLD = 8.0
+

neurotask/tmt/crosses/crosses.py

@@ -0,0 +1,131 @@
+from typing import List, Tuple
+
+from ..model.tmt_model import TMTTrial, Coordinate
+
+def calculate_crosses_for_trial(
+    trial: TMTTrial,
+    crosses_time_threshold: float,
+) -> Tuple[int, List[Tuple[Tuple[Coordinate, Coordinate], Tuple[Coordinate, Coordinate], float]]]:
+    """
+    Calculates the number of times the cursor trail crosses itself, excluding segments that are very near in time.
+
+    Parameters:
+    - trial: TMTTrial object containing the cursor_trail.
+    - crosses_time_threshold: float, the minimum time gap (in milliseconds) between segments to consider them for intersection.
+      Segments with gap < threshold are excluded as "too close in time".
+
+    Returns:
+    - num_crosses: int, the number of times the cursor trail crosses itself.
+    - cross_segments: list of tuples: (seg1, seg2, time_gap) for each detected crossing.
+      time_gap is in milliseconds.
+    """
+    cursor_trail = trial.get_cursor_trail_from_start()
+
+    # Not enough points to form non-adjacent segments
+    if len(cursor_trail) < 4:
+        return 0, []
+
+    # Build segments with endpoint times
+    segments: List[Tuple[Tuple[Coordinate, float], Tuple[Coordinate, float]]] = []
+    for i in range(len(cursor_trail) - 1):
+        p1 = cursor_trail[i].position
+        p2 = cursor_trail[i + 1].position
+        t1 = cursor_trail[i].time
+        t2 = cursor_trail[i + 1].time
+        segments.append(((p1, t1), (p2, t2)))
+
+    num_crosses = 0
+    cross_segments: List[Tuple[Tuple[Coordinate, Coordinate], Tuple[Coordinate, Coordinate], float]] = []
+
+    for i in range(len(segments)):
+        for j in range(i + 1, len(segments)):
+            # Skip adjacent segments (they share a point)
+            if j == i + 1:
+                continue
+
+            # Time interval for each segment
+            t_start_i = min(segments[i][0][1], segments[i][1][1])
+            t_end_i   = max(segments[i][0][1], segments[i][1][1])
+            t_start_j = min(segments[j][0][1], segments[j][1][1])
+            t_end_j   = max(segments[j][0][1], segments[j][1][1])
+
+            # Compute gap between time intervals (0 if overlapping)
+            if t_end_i < t_start_j:
+                time_gap = t_start_j - t_end_i
+            elif t_end_j < t_start_i:
+                time_gap = t_start_i - t_end_j
+            else:
+                time_gap = 0.0
+
+            # Skip if segments are too close in time
+            if time_gap < crosses_time_threshold:
+                continue
+
+            seg1 = (segments[i][0][0], segments[i][1][0])
+            seg2 = (segments[j][0][0], segments[j][1][0])
+
+            if segments_intersect(seg1[0], seg1[1], seg2[0], seg2[1]):
+                num_crosses += 1
+                cross_segments.append((seg1, seg2, time_gap))
+
+    return num_crosses, cross_segments
+
+
+
+def orientation(p: Coordinate, q: Coordinate, r: Coordinate) -> int:
+    """
+    Determines the orientation of the triplet (p, q, r).
+
+    Returns:
+    - 0 : Colinear
+    - 1 : Clockwise
+    - 2 : Counterclockwise
+    """
+    val = (q.y - p.y) * (r.x - q.x) - (q.x - p.x) * (r.y - q.y)
+    if abs(val) < 1e-10:
+        return 0  # Colinear
+    elif val > 0:
+        return 1  # Clockwise
+    else:
+        return 2  # Counterclockwise
+
+
+def on_segment(p: Coordinate, q: Coordinate, r: Coordinate) -> bool:
+    """
+    Checks if point q lies on segment pr.
+    """
+    if min(p.x, r.x) <= q.x <= max(p.x, r.x) and \
+            min(p.y, r.y) <= q.y <= max(p.y, r.y):
+        return True
+    return False
+
+
+def segments_intersect(p1: Coordinate, q1: Coordinate, p2: Coordinate, q2: Coordinate) -> bool:
+    """
+    Checks if two line segments (p1,q1) and (p2,q2) intersect.
+    """
+    # Find the four orientations needed for general and special cases
+    o1 = orientation(p1, q1, p2)
+    o2 = orientation(p1, q1, q2)
+    o3 = orientation(p2, q2, p1)
+    o4 = orientation(p2, q2, q1)
+
+    # General case
+    if o1 != o2 and o3 != o4:
+        return True
+
+    # Special Cases
+    # p1, q1 and p2 are colinear and p2 lies on segment p1q1
+    if o1 == 0 and on_segment(p1, p2, q1):
+        return True
+    # p1, q1 and q2 are colinear and q2 lies on segment p1q1
+    if o2 == 0 and on_segment(p1, q2, q1):
+        return True
+    # p2, q2 and p1 are colinear and p1 lies on segment p2q2
+    if o3 == 0 and on_segment(p2, p1, q2):
+        return True
+    # p2, q2 and q1 are colinear and q1 lies on segment p2q2
+    if o4 == 0 and on_segment(p2, q1, q2):
+        return True
+
+    return False

neurotask/tmt/crosses/crosses_metric_calculator.py

@@ -0,0 +1,20 @@
+import numpy as np
+from neurotask.tmt.crosses.crosses import calculate_crosses_for_trial
+from neurotask.tmt.metrics.base_metric import BaseMetricCalculator
+from neurotask.tmt.model.tmt_model import TMTTrial, TMTSubject, TMTTarget, CursorInfo
+
+
+class CrossesMetricCalculator(BaseMetricCalculator):
+    def add_metrics(self, metrics: dict, trial: TMTTrial, subject: TMTSubject,
+                    trails_between_targets: list[tuple[TMTTarget, list[CursorInfo]]], calculate_crosses: bool,
+                    speed_threshold, consecutive_points, target_radius_multiplier: float,
+                    crosses_time_threshold: float) -> dict:
+        metric_key = self.get_metric_name("number_of_crosses")
+
+        if calculate_crosses:
+            num_crosses, _ = calculate_crosses_for_trial(trial, crosses_time_threshold)
+            metrics[metric_key] = num_crosses
+        else:
+            metrics[metric_key] = np.nan
+
+        return metrics

neurotask/tmt/cut_criteria/cut_criteria.py

@@ -0,0 +1,6 @@
+from enum import Enum
+
+
+class CutCriteria(Enum):
+
+    MINIMUM_TARGETS = "MINIMUM_TARGETS"

neurotask/tmt/cut_criteria/cut_implementation.py

@@ -0,0 +1,146 @@
+from typing import Optional
+
+from neurotask.tmt.cut_criteria.cut_criteria import CutCriteria
+from neurotask.tmt.metrics.intra_and_inter_target_time import get_intra_target_intervals
+from neurotask.tmt.metrics.targets_touched import count_correctly_touched_targets
+from neurotask.tmt.model.tmt_model import TMTTrial, TMTSubject, TMTTarget, CursorInfo
+
+
+def cut_trial(
+        trial: TMTTrial,
+        correct_targets_minimum: Optional[int],
+        subject: TMTSubject,
+        subject_id: str,
+        cut_criteria: CutCriteria,
+        target_radius_multiplier: float
+) -> TMTTrial:
+    """
+    Process the given trial based on the specified cut criteria.
+
+    Args:
+        trial (TMTTrial): The trial to process.
+        correct_targets_minimum (Optional[int]): The minimum correct target touches required.
+        subject (TMTSubject): The subject associated with the trial.
+        subject_id (str): Unique identifier for the subject.
+        cut_criteria (CutCriteria): The criteria used to cut the trial.
+        target_radius_multiplier (float): Multiplier to apply to the target radius.
+
+    Returns:
+        TMTTrial: The processed (cut) trial.
+
+    Raises:
+        ValueError: If the cut criteria is invalid or if required parameters are missing.
+    """
+    if cut_criteria == CutCriteria.MINIMUM_TARGETS:
+        if correct_targets_minimum is None:
+            raise ValueError("Minimum targets criteria requires a minimum number of correct targets.")
+        return cut_trial_at_minimum_targets(correct_targets_minimum, subject, subject_id, trial, target_radius_multiplier)
+
+    raise ValueError(f"Invalid cut criteria: {cut_criteria}")
+
+
+def cut_trial_at_minimum_targets(
+        correct_targets_minimum: int,
+        subject: TMTSubject,
+        subject_id: str,
+        trial: TMTTrial,
+        target_radius_multiplier: float
+) -> TMTTrial:
+    """
+    Cuts the trial at the point where the minimum number of correct target touches is reached.
+
+    Args:
+        correct_targets_minimum (int): The minimum number of correct touches required.
+        subject (TMTSubject): The subject associated with the trial.
+        subject_id (str): Unique identifier for the subject.
+        trial (TMTTrial): The trial to be processed.
+        target_radius_multiplier (float): Multiplier to apply to the target radius.
+
+    Returns:
+        TMTTrial: The trial cut at the minimum correct target touch.
+
+    Raises:
+        ValueError: If the trial does not meet the required number of correct target touches.
+    """
+    correct_targets_touches = count_correctly_touched_targets(trial, subject.target_radius, target_radius_multiplier)
+
+    if correct_targets_touches < correct_targets_minimum:
+        raise ValueError(
+            f"Trial {trial.id} of subject {subject_id} has {correct_targets_touches} correct target touches, "
+            f"but the minimum required is {correct_targets_minimum}.")
+
+    return cut_trial_at_minimum_correct_targets(trial, correct_targets_minimum, subject, target_radius_multiplier)
+
+
+def cut_trial_at_minimum_correct_targets(
+        trial: TMTTrial,
+        correct_targets_minimum: int,
+        subject: TMTSubject,
+        target_radius_multiplier: float
+) -> TMTTrial:
+    """
+    Cuts the trial at the time corresponding to reaching the minimum correct target touches.
+
+    Args:
+        trial (TMTTrial): The trial to be cut.
+        correct_targets_minimum (int): The required number of correct touches.
+        subject (TMTSubject): The subject with target_radius used to determine correct touches.
+        target_radius_multiplier (float): The radius multiplier to use for target detection.
+
+    Returns:
+        TMTTrial: The trial cut at the appropriate time.
+
+    Raises:
+        ValueError: If the trial does not contain the required number of correct target segments.
+    """
+    intra_target_interval: list[tuple[TMTTarget, CursorInfo, CursorInfo]] = get_intra_target_intervals(
+        trial, subject.target_radius, target_radius_multiplier
+    )
+
+    if len(intra_target_interval) < correct_targets_minimum:
+        raise ValueError(f"Trial {trial.id} has less than {correct_targets_minimum} correct targets.")
+
+    # Get the Nth interval (where N = correct_targets_minimum)
+    # Since correct_touched_targets_for_every_cursor_point ensures targets are touched in order,
+    # the Nth interval corresponds to the Nth target in trial.stimuli
+    cutoff_interval = intra_target_interval[correct_targets_minimum - 1]
+
+    # Use the start cursor (index 1) to cut when the target is first touched
+    cursor_info = cutoff_interval[1]
+
+    return cut_at_time(trial, cursor_info.time, correct_targets_minimum)
+
+
+def cut_at_time(
+        trial: TMTTrial,
+        cutoff_time: float,
+        correct_targets_minimum: int
+) -> TMTTrial:
+    """
+    Cuts the trial at the specified cutoff time.
+
+    This function creates a new trial instance where the cursor trail is truncated
+    at the given cutoff time and only the first 'correct_targets_minimum' stimuli are retained.
+
+    Args:
+        trial (TMTTrial): The trial to be cut.
+        cutoff_time (float): The time at which to cut the trial.
+        correct_targets_minimum (int): The number of stimuli to retain.
+
+    Returns:
+        TMTTrial: A new trial instance cut at the specified time.
+    """
+    new_cursor_trail = [cursor for cursor in trial.cursor_trail if cursor.time <= cutoff_time]
+    new_rt = cutoff_time  # Ensure this behavior is as intended.
+    new_stimuli = trial.stimuli[:correct_targets_minimum]
+
+    return TMTTrial(
+        id=trial.id,
+        stimuli=new_stimuli,
+        cursor_trail=new_cursor_trail,
+        rt=new_rt,
+        trial_type=trial.trial_type,
+        order_of_appearance=trial.order_of_appearance,
+        with_custom_start=trial.with_custom_start,
+        start=trial.start
+    )

neurotask/tmt/invalid_cause.py

@@ -0,0 +1,17 @@
+from enum import Enum
+
+
+class InvalidCause(Enum):
+    """
+    Enumeration of possible causes of invalid trials in TMT.
+    """
+
+    CUT_CRITERIA_ERROR = "CUT_CRITERIA_ERROR"
+    UNKNOWN_ERROR = "UNKNOWN_ERROR"
+    UNDER_CORRECT_TARGETS_MINIMUM = "UNDER_CORRECT_TARGETS_MINIMUM"
+    INVALID_LENGTH = "INVALID_LENGTH"
+    INVALID_START_CONFIGURATION = "INVALID_START_CONFIGURATION"
+    INVALID_MODEL = "INVALID_MODEL"
+    UNABLE_TO_DETERMINE_START = "UNABLE_DETERMINE_START"
+    INVALID_SPEED = "INVALID_SPEED"
+    NON_MONOTONIC_TIME = "NON_MONOTONIC_TIME"

neurotask/tmt/mapper/mapper.py

@@ -0,0 +1,21 @@
+from abc import abstractmethod, ABC
+from typing import Optional
+
+from ..model.tmt_model import TMTExperiment
+
+
+class TMTMapper(ABC):
+
+    @abstractmethod
+    def map(self, data_path: str) -> TMTExperiment:
+        """
+        Método abstracto para mapear los datos (y opcionalmente la metadata) a una instancia de TMTExperiment.
+
+        Parameters:
+        - data_path: str -> La ruta al archivo de datos.
+        - metadata_path: Optional[str] -> La ruta al archivo de metadata. (Opcional)
+
+        Returns:
+        - TMTExperiment -> Instancia de TMTExperiment mapeada a partir de los datos (y la metadata si aplica).
+        """
+        pass

neurotask/tmt/metrics/area_calculation.py

@@ -0,0 +1,82 @@
+from typing import List
+
+import numpy as np
+from neurotask.tmt.metrics.base_metric import BaseMetricCalculator
+from neurotask.tmt.model.tmt_model import CursorInfo, TMTTarget, TMTTrial, TMTSubject
+
+# np.trapz se eliminó en numpy 2.4; np.trapezoid existe desde numpy 2.0
+_trapezoid = getattr(np, "trapezoid", None) or np.trapz
+
+
+def area_between_real_and_ideal(segment: List[CursorInfo]) -> float:
+    # 1) Extraer coordenadas (x, y) de los puntos reales
+    point_coords = np.array([[cursor_info.position.x, cursor_info.position.y] for cursor_info in segment], dtype=float)
+
+    return area_between_real_and_ideal_points(point_coords)
+
+
+def area_between_real_and_ideal_points(point_coords: np.ndarray) -> float:
+    """
+    Integra la distancia perpendicular absoluta entre la trayectoria real
+    y la línea recta ideal que une el primer y último punto del segmento.
+
+    :param segment: lista de CursorInfo reales
+    :return: área bajo la curva de desviación, >= 0
+    """
+    num_points = len(point_coords)
+    if num_points < 2:
+        return 0.0
+
+    # 2) Definir el vector ideal desde el primer al último punto
+    start_point = point_coords[0]
+    end_point = point_coords[-1]
+    ideal_vector = end_point - start_point
+    ideal_length_sq = np.dot(ideal_vector, ideal_vector)
+    ideal_length = np.sqrt(ideal_length_sq)
+
+    # 3) Proyectar cada punto real sobre la línea ideal
+    #    a) desplazamientos desde el inicio
+    offsets = point_coords - start_point[np.newaxis, :]
+    #    b) factor de proyección t ∈ [0,1] sobre el vector ideal
+    projection_factors = (offsets @ ideal_vector) / ideal_length_sq
+    #    c) puntos proyectados en la línea ideal
+    projection_points = start_point + projection_factors[:, np.newaxis] * ideal_vector
+
+    # 4) Calcular distancia perpendicular de cada punto real a la ideal
+    perpendicular_distances = np.linalg.norm(point_coords - projection_points, axis=1)
+
+    # 5) Coordenadas escalarizadas a lo largo de la línea ideal
+    #    (distancia desde el inicio a cada proyección)
+    line_positions = projection_factors * ideal_length
+
+    # 6) Integración por la regla del trapecio
+    area = _trapezoid(perpendicular_distances, line_positions)
+
+    return float(area)
+
+
+class DifferenceFromIdealArea(BaseMetricCalculator):
+
+    def add_metrics(self, metrics: dict, trial: TMTTrial, subject: TMTSubject,
+                    trails_between_targets: list[tuple[TMTTarget, list[CursorInfo]]], calculate_crosses: bool,
+                    speed_threshold, consecutive_points, target_radius_multiplier: float,
+                    crosses_time_threshold: float) -> dict:
+
+        areas = []
+        for trail in trails_between_targets:
+            target, cursor_trail = trail
+            if target is None:
+                continue
+            area = area_between_real_and_ideal(cursor_trail)
+            areas.append(area)
+
+        if areas:
+            metrics[self.get_metric_name('area_difference_from_ideal')] = float(np.mean(areas))
+        else:
+            raise ValueError(
+                f"Cannot calculate area_difference_from_ideal: No valid target segments found. "
+                f"Trial {trial.id} has {len(trails_between_targets)} trails_between_targets, "
+                f"but none had valid targets (all targets were None or segments were invalid)."
+            )
+
+        return metrics

neurotask/tmt/metrics/base_metric.py

@@ -0,0 +1,37 @@
+from abc import ABC, abstractmethod
+from typing import Optional
+
+from neurotask.tmt.model.tmt_model import TMTTrial, TMTSubject, TMTTarget, CursorInfo
+
+
+class BaseMetricCalculator(ABC):
+    def __init__(self, prefix: Optional[str] = None):
+        self.prefix = prefix
+
+    def get_metric_name(self, metric_name: str) -> str:
+        """
+        Devuelve el nombre de la métrica con el prefijo si se ha definido.
+        """
+        if self.prefix:
+            return f'{self.prefix}{metric_name}'
+        return metric_name
+
+    @abstractmethod
+    def add_metrics(self, metrics: dict, trial: TMTTrial, subject: TMTSubject,
+                    trails_between_targets: list[tuple[TMTTarget, list[CursorInfo]]], calculate_crosses: bool,
+                    speed_threshold, consecutive_points, target_radius_multiplier: float,
+                    crosses_time_threshold: float) -> dict:
+        """
+        Añade las claves/valores de esta métrica al dict `metrics`.
+        `trial` es tu objeto TMTTrial (o las estructuras que uses).
+        """
+        pass
+
+
+class ReactionTimeCalculator(BaseMetricCalculator):
+    def add_metrics(self, metrics: dict, trial: TMTTrial, subject: TMTSubject,
+                    trails_between_targets: list[tuple[TMTTarget, list[CursorInfo]]], calculate_crosses: bool,
+                    speed_threshold, consecutive_points, target_radius_multiplier: float,
+                    crosses_time_threshold: float) -> dict:
+        metrics[self.get_metric_name('rt')] = trial.rt
+        return metrics

neurotask/tmt/metrics/difference_from_ideal_distance.py

@@ -0,0 +1,38 @@
+import numpy as np
+from neurotask.tmt.metrics.base_metric import BaseMetricCalculator
+from neurotask.tmt.metrics.distance_calculation import calculate_distance, calculate_total_distance_from_segment
+from neurotask.tmt.model.tmt_model import TMTTrial, CursorInfo, TMTTarget, TMTSubject
+
+
+class DifferenceFromIdealDistance(BaseMetricCalculator):
+
+    def add_metrics(self, metrics: dict, trial: TMTTrial, subject: TMTSubject,
+                    trails_between_targets: list[tuple[TMTTarget, list[CursorInfo]]], calculate_crosses: bool,
+                    speed_threshold, consecutive_points, target_radius_multiplier: float,
+                    crosses_time_threshold: float) -> dict:
+
+        differences = []
+        for trail in trails_between_targets:
+            target, cursor_trail = trail
+            if target is None:
+                continue
+            difference = self.calculate_distance_difference_from_ideal(cursor_trail)
+            differences.append(difference)
+
+        if differences:
+            metrics[self.get_metric_name('distance_difference_from_ideal')] = float(np.mean(differences))
+        else:
+            raise ValueError(
+                f"Cannot calculate distance_difference_from_ideal: No valid target segments found. "
+                f"Trial {trial.id} has {len(trails_between_targets)} trails_between_targets, "
+                f"but none had valid targets (all targets were None or segments were invalid)."
+            )
+
+        return metrics
+
+    def calculate_distance_difference_from_ideal(self, segment: list[CursorInfo]) -> float:
+
+        segment_distance = calculate_total_distance_from_segment(segment)
+        ideal_distance = calculate_distance(segment[0].position, segment[-1].position)
+
+        return abs(segment_distance - ideal_distance)

neurotask/tmt/metrics/distance_calculation.py

@@ -0,0 +1,61 @@
+import math
+from typing import List
+
+from .base_metric import BaseMetricCalculator
+from ..model.tmt_model import Coordinate, TMTTrial, CursorInfo, TMTSubject, TMTTarget
+
+
+class TotalDistanceCalculator(BaseMetricCalculator):
+    def add_metrics(self, metrics: dict, trial: TMTTrial, subject: TMTSubject,
+                    trails_between_targets: list[tuple[TMTTarget, list[CursorInfo]]], calculate_crosses: bool,
+                    speed_threshold, consecutive_points, target_radius_multiplier: float,
+                    crosses_time_threshold: float) -> dict:
+        metrics[self.get_metric_name('total_distance')] = calculate_total_distance(trial)
+        return metrics
+
+
+def calculate_distance(pos1: Coordinate, pos2: Coordinate) -> float:
+    dx = pos1.x - pos2.x
+    dy = pos1.y - pos2.y
+    return math.hypot(dx, dy)
+
+
+def is_inside_target(
+        cursor_pos: Coordinate,
+        target: TMTTarget,
+        target_radius: float,
+        multiplier: float
+) -> bool:
+    """
+    Determine if the cursor is inside the target's effective radius.
+
+    :param cursor_pos: The cursor position.
+    :param target: The target to check.
+    :param target_radius: The base target radius.
+    :param multiplier: The radius multiplier.
+    :return: True if cursor is inside the target's effective radius.
+    """
+    effective_radius = target_radius * multiplier
+    distance = calculate_distance(cursor_pos, target.position)
+    return distance < effective_radius
+
+
+def calculate_total_distance(trial: TMTTrial):
+    """
+    Calculate the total distance of the cursor trail in a TMT trial.
+
+    :param trial: TMTTrial object containing the cursor trail.
+    :return: Total distance traveled by the cursor.
+    """
+    cursor_trail_from_first_click = trial.get_cursor_trail_from_start()
+    return sum(
+        calculate_distance(cursor_trail_from_first_click[i].position, cursor_trail_from_first_click[i + 1].position)
+        for i in range(len(cursor_trail_from_first_click) - 1)
+    )
+
+
+def calculate_total_distance_from_segment(segment_trial: List[CursorInfo]) -> float:
+    return sum(
+        calculate_distance(segment_trial[i].position, segment_trial[i + 1].position)
+        for i in range(len(segment_trial) - 1)
+    )