neurotask 0.2.0__py3-none-any.whl

neurotask/tmt/metrics/intra_and_inter_target_time.py

@@ -0,0 +1,148 @@
+from neurotask.tmt.metrics.base_metric import BaseMetricCalculator
+from neurotask.tmt.metrics.targets_touched import correct_touched_targets_for_every_cursor_point
+from neurotask.tmt.model.tmt_model import TMTTrial, TMTSubject, TMTTarget, CursorInfo
+
+
+class TargetTime(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:
+
+        if subject is None:
+            raise ValueError("Subject must be provided")
+
+        intra_time = calculate_intra_target_time(trial, subject.target_radius, target_radius_multiplier)
+        metrics[self.get_metric_name('intra_target_time')] = intra_time
+        metrics[self.get_metric_name('inter_target_time')] = calculate_inter_target_time(trial, intra_time)
+
+        return metrics
+
+
+def get_intra_target_intervals(
+        trial: TMTTrial,
+        target_radius: float,
+        multiplier: float
+) -> list[tuple[TMTTarget, CursorInfo, CursorInfo]]:
+    """
+    Identify continuous intervals where the cursor is on a correct target.
+
+    Returns a list of tuples (target, start_cursor, end_cursor) representing
+    continuous periods where the cursor is on the correct expected target.
+
+    An interval starts when the cursor enters a correct target and ends when:
+    - The cursor leaves the target (moves to a non-target position)
+    - The cursor moves to a different correct target
+    - We reach the last cursor point (interval ends at that point)
+
+    :param trial: TMTTrial instance
+    :param target_radius: The target radius for touch detection
+    :param multiplier: The radius multiplier
+    :return: List of (target, start_cursor, end_cursor) tuples
+    """
+    if not trial.cursor_trail:
+        return []
+
+    # Get correct touched targets for every cursor point
+    correct_touches = correct_touched_targets_for_every_cursor_point(trial, target_radius, multiplier)
+
+    if not correct_touches:
+        return []
+
+    intervals = []
+    current_interval_target = None
+    current_interval_start_cursor = None
+
+    for i in range(len(correct_touches)):
+        target, cursor_info = correct_touches[i]
+
+        if target is not None:
+            # We're on a correct target
+            if current_interval_target is None:
+                # Start a new interval
+                current_interval_target = target
+                current_interval_start_cursor = cursor_info
+            elif current_interval_target != target:
+                # Different target - close previous interval at current point and start new one
+                intervals.append((current_interval_target, current_interval_start_cursor, cursor_info))
+
+                # Start new interval
+                current_interval_target = target
+                current_interval_start_cursor = cursor_info
+        else:
+            # Not on a target - close current interval if exists
+            if current_interval_target is not None:
+                # Close interval at current point (when we left the target)
+                intervals.append((current_interval_target, current_interval_start_cursor, cursor_info))
+
+                current_interval_target = None
+                current_interval_start_cursor = None
+
+    # Close any open interval at the end
+    if current_interval_target is not None:
+        # Use the last cursor as end of interval
+        last_cursor = correct_touches[-1][1]
+        intervals.append((current_interval_target, current_interval_start_cursor, last_cursor))
+
+    return intervals
+
+
+def calculate_intra_target_time(
+        trial: TMTTrial,
+        target_radius: float,
+        multiplier: float
+) -> float:
+    """
+    Calculate the intra-target time for a given trial and subject.
+    The intra-target time is defined as the sum of the times spent within each target area.
+
+    This function first identifies continuous intervals where the cursor is on correct targets,
+    then sums the duration of all those intervals.
+
+    :param trial: TMTTrial instance
+    :param target_radius: The target radius for touch detection
+    :param multiplier: The radius multiplier
+    :return: Total time spent on correct targets in seconds
+    """
+    # Get all intervals where cursor is on correct targets
+    intervals = get_intra_target_intervals(trial, target_radius, multiplier)
+
+    # Sum the duration of all intervals
+    total_time = sum(end_cursor.time - start_cursor.time for _, start_cursor, end_cursor in intervals)
+
+    return total_time
+
+
+def calculate_inter_target_time(
+        trial: TMTTrial,
+        intra_time
+) -> float:
+    """
+    Calculate the inter-target time for a given trial and subject.
+    The inter-target time is defined as the time spent moving between targets
+    (i.e., not on any correct target).
+
+    This is calculated as: (last_cursor_time - first_cursor_time) - intra-target time
+
+    :param trial: TMTTrial instance
+    :param intra_time: Pre-calculated intra-target time
+    :return: Total time spent between targets in seconds
+    """
+    # Get the cursor trail (respecting custom start if present)
+
+    cursor_trail = trial.get_cursor_trail_from_start()
+
+    # If no cursor trail, return 0
+    if not cursor_trail:
+        return 0.0
+
+    # Calculate total time from first to last cursor point
+    total_time = cursor_trail[-1].time - cursor_trail[0].time
+
+    # Get the intra-target time
+
+    # Inter-target time is the complement: total time minus time on targets
+    inter_time = total_time - intra_time
+
+    return inter_time
+

neurotask/tmt/metrics/metrics_calculator.py

@@ -0,0 +1,417 @@
+import logging
+from typing import List, Dict, Any, Optional
+
+import numpy as np
+import pandas as pd
+
+from neurotask.tmt.crosses.crosses_metric_calculator import CrossesMetricCalculator
+from neurotask.tmt.metrics.area_calculation import DifferenceFromIdealArea
+from neurotask.tmt.metrics.difference_from_ideal_distance import DifferenceFromIdealDistance
+from neurotask.tmt.metrics.intra_and_inter_target_time import TargetTime
+from neurotask.tmt.metrics.sampling_period import SamplingPeriodCalculator
+from neurotask.tmt.metrics.speed_metrics import SpeedMetricsCalculator, InvalidSpeedError, NonMonotonicTimeError
+from neurotask.tmt.metrics.zig_zag_amplitud import ZigZagAmplitude
+from .base_metric import ReactionTimeCalculator, BaseMetricCalculator
+from .distance_calculation import TotalDistanceCalculator
+from .targets_touched import TargetsTouchesCalculator, get_all_trails_between_targets, \
+    count_correctly_touched_targets
+from ..cut_criteria.cut_criteria import CutCriteria
+from ..cut_criteria.cut_implementation import cut_trial
+from ..invalid_cause import InvalidCause
+from ..model.tmt_model import TMTExperiment, TMTSubject, TMTTrial, TMTTarget, CursorInfo
+from ..segmentation.segmentation import calculate_speed_threshold_for_all_subjects
+from ..segmentation.segmentation_metric import SegmentationMetricCalculator
+
+
+def generate_rows_for_subject(subject_id: str, subject: TMTSubject, correct_targets_minimum: int,
+                              speed_threshold: float, consecutive_points: int, cut_criteria: CutCriteria,
+                              calculate_crosses: bool, target_radius_multiplier: float,
+                              crosses_time_threshold: float) -> List[Dict[str, Any]]:
+    """
+    Generate a list of row dictionaries, each describing metrics and information
+    for valid and invalid trials of a single subject.
+
+    For each trial:
+      1. If the trial is invalid from the start, mark it as invalid.
+      2. Otherwise, if cut criteria are provided, attempt to cut the trial.
+         If cutting fails, mark the trial as invalid.
+      3. Compute the number of correct and incorrect target touches.
+         If the correct targets count is below the minimum, mark the trial invalid.
+      4. If all checks pass, compute trial metrics and combine with general trial info.
+
+    :param subject_id: A unique identifier for the subject.
+    :param subject: The subject object containing personal info and trials.
+    :param correct_targets_minimum: The minimum number of correct target touches required.
+    :param speed_threshold: The speed threshold for calculations.
+    :param consecutive_points: The number of consecutive points to consider.
+    :param cut_criteria: The criteria to use for cutting trials; if None, no cutting is performed.
+    :param calculate_crosses: Whether to calculate crosses.
+    :param target_radius_multiplier: Multiplier to apply to the target radius.
+    :return: A list of dictionaries, each representing a trial (valid or invalid).
+    """
+    rows = []
+
+    for trial in subject.testing_trials:
+        # Check initial validity.
+        try:
+            if not trial.is_valid():
+                logging.warning(f"Trial {trial.id} of subject {subject_id} is not valid from the mapper.")
+                rows.append(
+                    create_invalid_trial_row(
+                        subject, subject_id, trial, speed_threshold,
+                        error_msg="Trial is_valid function return false."
+                    )
+                )
+                continue
+        except Exception as e:
+            logging.exception(f"Error checking validity of trial {trial.id} for subject {subject_id}: {e}")
+            rows.append(
+                create_invalid_trial_row(
+                    subject, subject_id, trial, speed_threshold,
+                    invalid_cause=InvalidCause.UNABLE_TO_DETERMINE_START,
+                    error_msg=str(e)
+                )
+            )
+            continue
+
+        try:
+            processed_trial = trial
+
+            # Apply cut criteria if provided.
+            if cut_criteria is not None:
+                processed_trial = _attempt_cut_trial(
+                    trial, correct_targets_minimum, subject, subject_id, cut_criteria, speed_threshold, rows,
+                    target_radius_multiplier
+                )
+                if processed_trial is None:
+                    continue
+
+            # Compute target touches.
+            correct_touches = count_correctly_touched_targets(
+                processed_trial, subject.target_radius, target_radius_multiplier
+            )
+
+            # Check if the trial meets the minimum correct touches.
+            if correct_targets_minimum is not None:
+                if correct_touches < correct_targets_minimum:
+                    logging.warning(
+                        f"Trial {trial.id} of subject {subject_id} has {correct_touches} correct target touches, "
+                        f"but the minimum required is {correct_targets_minimum}."
+                    )
+                    rows.append(
+                        create_invalid_trial_row(
+                            subject, subject_id, trial, speed_threshold,
+                            invalid_cause=InvalidCause.UNDER_CORRECT_TARGETS_MINIMUM,
+                            error_msg="Not enough correct target touches"
+                        )
+                    )
+                    continue
+
+            valid_row = general_trial_info(speed_threshold, subject, subject_id, trial)
+
+            if cut_criteria is not None:
+                non_cut_trial_metrics = get_non_cut_trial_metrics(calculate_crosses, consecutive_points, trial,
+                                                                  speed_threshold, subject, target_radius_multiplier,
+                                                                  crosses_time_threshold)
+                valid_row.update(non_cut_trial_metrics)
+
+            cut_trial_metrics = get_cut_trial_metrics(calculate_crosses, consecutive_points, processed_trial,
+                                                      speed_threshold, subject, target_radius_multiplier,
+                                                      crosses_time_threshold)
+            valid_row.update(cut_trial_metrics)
+
+            rows.append(valid_row)
+
+        except InvalidSpeedError as e:
+            print(f"ERROR: Trial {trial.id} for subject {subject_id}: {e}")
+            error_msg = str(e)
+            logging.exception(f"Invalid speed in trial {trial.id} for subject {subject_id}: {e}")
+            rows.append(
+                create_invalid_trial_row(
+                    subject, subject_id, trial, speed_threshold,
+                    invalid_cause=InvalidCause.INVALID_SPEED,
+                    error_msg=error_msg
+                )
+            )
+
+        except NonMonotonicTimeError as e:
+            error_msg = str(e)
+            logging.warning(f"Non-monotonic time in trial {trial.id} for subject {subject_id}: {e}")
+            rows.append(
+                create_invalid_trial_row(
+                    subject, subject_id, trial, speed_threshold,
+                    invalid_cause=InvalidCause.NON_MONOTONIC_TIME,
+                    error_msg=error_msg
+                )
+            )
+
+        except Exception as e:
+            print(f"ERROR: Trial {trial.id} for subject {subject_id}: {e}")
+            error_msg = str(e)
+            logging.exception(f"Error processing trial {trial.id} for subject {subject_id}: {e}")
+            rows.append(
+                create_invalid_trial_row(
+                    subject, subject_id, trial, speed_threshold,
+                    invalid_cause=InvalidCause.UNKNOWN_ERROR,
+                    error_msg=error_msg
+                )
+            )
+
+    return rows
+
+
+def get_cut_trial_metrics(calculate_crosses, consecutive_points, trial, speed_threshold, subject,
+                          target_radius_multiplier: float, crosses_time_threshold: float):
+    metric_calculators = get_cut_trial_metric_calculators()
+    return compute_trial_metrics(
+        metric_calculators,
+        trial,
+        subject,
+        speed_threshold=speed_threshold,
+        consecutive_points=consecutive_points,
+        calculate_crosses=calculate_crosses,
+        target_radius_multiplier=target_radius_multiplier,
+        crosses_time_threshold=crosses_time_threshold,
+    )
+
+
+def get_non_cut_trial_metrics(calculate_crosses, consecutive_points, trial, speed_threshold, subject,
+                              target_radius_multiplier: float, crosses_time_threshold: float):
+    metric_calculators = get_non_cut_trial_metric_calculators()
+    return compute_trial_metrics(
+        metric_calculators,
+        trial,
+        subject,
+        speed_threshold=speed_threshold,
+        consecutive_points=consecutive_points,
+        calculate_crosses=calculate_crosses,
+        target_radius_multiplier=target_radius_multiplier,
+        crosses_time_threshold=crosses_time_threshold,
+    )
+
+
+def get_cut_trial_metric_calculators():
+    return [
+        ZigZagAmplitude(),
+        TotalDistanceCalculator(),
+        ReactionTimeCalculator(),
+        SpeedMetricsCalculator(),
+        SamplingPeriodCalculator(),
+        SegmentationMetricCalculator(),
+        TargetsTouchesCalculator(),
+        CrossesMetricCalculator(),
+        DifferenceFromIdealDistance(),
+        DifferenceFromIdealArea(),
+        TargetTime()
+    ]
+
+
+def get_non_cut_trial_metric_calculators():
+    prefix = "non_cut_"
+    return [
+        ZigZagAmplitude(prefix),
+        TotalDistanceCalculator(prefix),
+        ReactionTimeCalculator(prefix),
+        SpeedMetricsCalculator(prefix),
+        SamplingPeriodCalculator(prefix),
+        SegmentationMetricCalculator(prefix),
+        TargetsTouchesCalculator(prefix),
+        CrossesMetricCalculator(prefix),
+        DifferenceFromIdealDistance(prefix),
+        DifferenceFromIdealArea(prefix),
+        TargetTime(prefix)
+    ]
+
+
+def _attempt_cut_trial(
+        trial: Any,
+        correct_targets_minimum: int,
+        subject: TMTSubject,
+        subject_id: str,
+        cut_criteria: CutCriteria,
+        speed_threshold: float,
+        rows: List[Dict[str, Any]],
+        target_radius_multiplier: float
+) -> Optional[Any]:
+    """
+    Attempt to cut a trial using the specified criteria.
+
+    If cutting fails, the function logs a warning and appends an invalid trial row.
+
+    :return: The processed trial if successful, or None if an error occurred.
+    """
+    try:
+        return cut_trial(trial, correct_targets_minimum, subject, subject_id, cut_criteria, target_radius_multiplier)
+    except Exception as e:
+        logging.exception(f"Cut trial error for trial {trial.id} of subject {subject_id}: {e}")
+        rows.append(
+            create_invalid_trial_row(
+                subject, subject_id, trial, speed_threshold,
+                invalid_cause=InvalidCause.CUT_CRITERIA_ERROR,
+                error_msg=str(e)
+            )
+        )
+        return None
+
+
+def general_trial_info(speed_threshold, subject, subject_id, trial):
+
+    trial_row = {
+        "subject_id": subject_id,
+        "trial_id": trial.id,
+        "trial_type": trial.trial_type.name,
+        "is_valid": trial.is_valid(),
+        "trial_order_of_appearance": trial.order_of_appearance,
+        "speed_threshold": speed_threshold
+    }
+
+    session_data: Dict[str, str] = subject.session_data if subject.session_data else {}
+    trial_row.update(session_data)
+
+    return trial_row
+
+
+def create_invalid_trial_row(
+        subject: TMTSubject,
+        subject_id: str,
+        trial: TMTTrial,
+        speed_threshold: float,
+        invalid_cause: Optional[InvalidCause] = None,
+        error_msg: Optional[str] = None
+) -> Dict[str, Any]:
+    # Si no se pasó una causa, obtenerla del trial
+    if invalid_cause is None:
+        invalid_cause = trial.get_invalid_cause()
+
+    invalid_trial_row = {
+        "subject_id": subject_id,
+        "trial_id": trial.id,
+        "total_distance": 0,
+        "rt": trial.rt,
+        "is_valid": False,
+        "trial_type": trial.trial_type.name,
+        "trial_order_of_appearance": trial.order_of_appearance,
+        "correct_targets_touches": np.nan,
+        "wrong_targets_touches": np.nan,
+        "speed_threshold": speed_threshold,
+        "mean_speed": np.nan,
+        "std_speed": np.nan,
+        "peak_speed": np.nan,
+        "mean_acceleration": np.nan,
+        "std_acceleration": np.nan,
+        "peak_acceleration": np.nan,
+        "hesitation_distance": np.nan,
+        "hesitation_time": np.nan,
+        "mean_sampling_period": np.nan,
+        "median_sampling_period": np.nan,
+        "std_sampling_period": np.nan,
+        "min_sampling_period": np.nan,
+        "max_sampling_period": np.nan,
+        "sample_count": np.nan,
+        "valid_interval_count": np.nan,
+        "invalid_cause": invalid_cause.name
+    }
+
+    session_data: Dict[str, str] = subject.session_data if subject.session_data else {}
+    invalid_trial_row.update(session_data)
+
+    if error_msg:
+        invalid_trial_row["error_message"] = error_msg
+
+    return invalid_trial_row
+
+
+def compute_trial_metrics(
+        metric_calculators: List[BaseMetricCalculator],
+        trial: TMTTrial,
+        subject: TMTSubject,
+        speed_threshold,
+        consecutive_points,
+        calculate_crosses,
+        target_radius_multiplier: float,
+        crosses_time_threshold: float,
+) -> Dict[str, Any]:
+    """
+    Itera sobre cada calculador de métricas y va acumulando
+    sus resultados en un único dict.
+    """
+    trails_between_targets: list[tuple[TMTTarget, list[CursorInfo]]] = (
+        get_all_trails_between_targets(trial, subject.target_radius, target_radius_multiplier)
+    )
+    metrics: Dict[str, Any] = {}
+    for calculator in metric_calculators:
+        metrics = calculator.add_metrics(metrics, trial, subject, trails_between_targets, calculate_crosses,
+                                         speed_threshold, consecutive_points, target_radius_multiplier,
+                                         crosses_time_threshold)
+    return metrics
+
+
+def calculate_and_save_metrics(
+        experiment: TMTExperiment,
+        save_path: str,
+        correct_targets_minimum: int,
+        consecutive_points: int,
+        cut_criteria: CutCriteria,
+        calculate_crosses: bool,
+        target_radius_multiplier: float,
+        crosses_time_threshold: float
+) -> pd.DataFrame:
+    """
+    Calculate metrics for each subject in the experiment, save the results to a CSV file,
+    and return the aggregated DataFrame.
+
+    This function computes the speed threshold for each subject, then iterates over all subjects
+    to generate trial metric rows using `generate_rows_for_subject`. The resulting rows are aggregated
+    into a pandas DataFrame, saved as a CSV file to the specified path, and returned.
+
+    Args:
+        experiment (TMTExperiment): The experiment containing subjects and their trials.
+        save_path (str): The file path where the CSV should be saved.
+        correct_targets_minimum (int): The minimum number of correct target touches required.
+        consecutive_points (int): The number of consecutive points for segmentation metrics.
+        cut_criteria (CutCriteria): The criteria to use for cutting trials.
+        calculate_crosses (bool): Whether to calculate crosses.
+
+    Returns:
+        pd.DataFrame: DataFrame containing all computed metrics for the experiment.
+    """
+    rows: List[Dict[str, Any]] = []
+
+    # Compute speed thresholds for each subject.
+    speed_threshold_by_subject = calculate_speed_threshold_for_all_subjects(
+        experiment, target_radius_multiplier
+    )
+
+    for subject_id, subject in experiment.subjects.items():
+        try:
+            threshold = speed_threshold_by_subject.get(subject_id)
+            if threshold is None:
+                logging.warning(f"Speed threshold not found for subject {subject_id}. Skipping subject.")
+                continue
+
+            subject_rows = generate_rows_for_subject(
+                subject_id=subject_id,
+                subject=subject,
+                correct_targets_minimum=correct_targets_minimum,
+                speed_threshold=threshold,
+                consecutive_points=consecutive_points,
+                cut_criteria=cut_criteria,
+                calculate_crosses=calculate_crosses,
+                target_radius_multiplier=target_radius_multiplier,
+                crosses_time_threshold=crosses_time_threshold
+            )
+            rows.extend(subject_rows)
+        except Exception as e:
+            logging.exception(f"Error processing subject {subject_id}: {e}")
+            continue
+
+    df = pd.DataFrame(rows)
+
+    try:
+        df.to_csv(save_path, index=False)
+        logging.info(f"Metrics successfully saved to {save_path}.")
+    except Exception as e:
+        logging.exception(f"Error saving CSV to {save_path}: {e}")
+        raise
+
+    return df

neurotask/tmt/metrics/sampling_period.py

@@ -0,0 +1,89 @@
+from typing import Dict, Any, List
+
+import numpy as np
+
+from neurotask.tmt.metrics.base_metric import BaseMetricCalculator
+from neurotask.tmt.model.tmt_model import TMTTrial, TMTSubject, TMTTarget, CursorInfo
+
+
+class SamplingPeriodCalculator(BaseMetricCalculator):
+    """
+    Calculates sampling period (time between samples) metrics from the cursor trail.
+    """
+
+    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:
+        period_metrics = compute_sampling_period_metrics(trial)
+
+        for key, value in period_metrics.items():
+            metrics[self.get_metric_name(key)] = value
+
+        return metrics
+
+
+def compute_sampling_period_metrics(trial: TMTTrial) -> Dict[str, Any]:
+    """
+    Computes sampling period statistics based on cursor timestamps.
+
+    Timestamps are assumed to be in milliseconds. The sampling period is the
+    time interval between consecutive cursor samples.
+
+    Returns:
+        Dict with mean_sampling_period, median_sampling_period, std_sampling_period,
+        min_sampling_period, max_sampling_period, sample_count,
+        and valid_interval_count.
+    """
+    cursor_trail = trial.get_cursor_trail_from_start()
+
+    raw_sample_count = len(cursor_trail)
+
+    if raw_sample_count < 2:
+        return _empty_metrics(raw_sample_count)
+
+    time_intervals_ms = _calculate_time_intervals_ms(cursor_trail)
+
+    if not time_intervals_ms:
+        return _empty_metrics(raw_sample_count)
+
+    return {
+        "mean_sampling_period": np.mean(time_intervals_ms),
+        "median_sampling_period": np.median(time_intervals_ms),
+        "std_sampling_period": np.std(time_intervals_ms),
+        "min_sampling_period": np.min(time_intervals_ms),
+        "max_sampling_period": np.max(time_intervals_ms),
+        "sample_count": raw_sample_count,
+        "valid_interval_count": len(time_intervals_ms)
+    }
+
+
+def _calculate_time_intervals_ms(cursor_trail: List[CursorInfo]) -> List[float]:
+    """Calculates valid time intervals (in ms) between consecutive samples."""
+    intervals = []
+    for i in range(1, len(cursor_trail)):
+        dt = cursor_trail[i].time - cursor_trail[i - 1].time
+        if dt > 0:
+            intervals.append(dt)
+    return intervals
+
+
+def _empty_metrics(raw_sample_count: int, valid_count: int = 0) -> Dict[str, Any]:
+    """Returns empty metrics when calculation is not possible."""
+    return {
+        "mean_sampling_period": np.nan,
+        "median_sampling_period": np.nan,
+        "std_sampling_period": np.nan,
+        "min_sampling_period": np.nan,
+        "max_sampling_period": np.nan,
+        "sample_count": raw_sample_count,
+        "valid_interval_count": valid_count
+    }