bead 0.1.0__py3-none-any.whl

bead/behavioral/extraction.py

@@ -0,0 +1,343 @@
+"""Behavioral data extraction from slopit sessions.
+
+This module provides functions for extracting per-judgment behavioral
+analytics from slopit session data, using slopit's IO loaders and
+analysis pipeline.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+from slopit import load_session, load_sessions
+from slopit.behavioral import (
+    Analyzer,
+    FocusAnalyzer,
+    KeystrokeAnalyzer,
+    PasteAnalyzer,
+    TimingAnalyzer,
+)
+from slopit.pipeline import AnalysisPipeline
+from slopit.schemas import AnalysisFlag, Severity, SlopitSession, SlopitTrial
+
+from bead.behavioral.analytics import AnalyticsCollection, JudgmentAnalytics
+
+if TYPE_CHECKING:
+    from bead.data.base import JsonValue
+
+
+def _get_max_severity(flags: list[AnalysisFlag]) -> Severity | None:
+    """Get maximum severity from a list of flags.
+
+    Parameters
+    ----------
+    flags : list[AnalysisFlag]
+        List of analysis flags.
+
+    Returns
+    -------
+    Severity | None
+        Maximum severity, or None if no flags.
+    """
+    if not flags:
+        return None
+
+    severity_order: dict[str, int] = {"info": 0, "low": 1, "medium": 2, "high": 3}
+    max_level = -1
+    max_severity: Severity | None = None
+
+    for flag in flags:
+        level = severity_order.get(flag.severity, 0)
+        if level > max_level:
+            max_level = level
+            max_severity = flag.severity
+
+    return max_severity
+
+
+def extract_from_trial(
+    trial: SlopitTrial,
+    session: SlopitSession,
+    item_id_key: str = "item_id",
+) -> JudgmentAnalytics | None:
+    """Extract behavioral analytics from a single slopit trial.
+
+    Parameters
+    ----------
+    trial : SlopitTrial
+        Slopit trial data.
+    session : SlopitSession
+        Parent session for participant context.
+    item_id_key : str
+        Key in platform_data containing the item UUID.
+
+    Returns
+    -------
+    JudgmentAnalytics | None
+        Analytics record, or None if item_id not found in trial.
+    """
+    # Extract item_id from platform_data
+    if trial.platform_data is None or item_id_key not in trial.platform_data:
+        return None
+
+    item_id_str = trial.platform_data[item_id_key]
+    if not isinstance(item_id_str, str):
+        return None
+
+    try:
+        item_id = UUID(item_id_str)
+    except (ValueError, TypeError):
+        return None
+
+    # Extract response value
+    response_value: JsonValue = None
+    if trial.response is not None:
+        response_value = trial.response.value
+
+    # Extract response time
+    response_time_ms = trial.rt if trial.rt is not None else 0
+
+    # Extract behavioral metrics
+    keystroke_metrics = None
+    focus_metrics = None
+    timing_metrics = None
+    paste_count = 0
+
+    if trial.behavioral is not None:
+        if trial.behavioral.metrics is not None:
+            keystroke_metrics = trial.behavioral.metrics.keystroke
+            focus_metrics = trial.behavioral.metrics.focus
+            timing_metrics = trial.behavioral.metrics.timing
+
+        if trial.behavioral.paste is not None:
+            paste_count = len(trial.behavioral.paste)
+
+    # Extract flags from capture_flags
+    flags: list[AnalysisFlag] = []
+    if trial.capture_flags is not None:
+        # Convert CaptureFlags to AnalysisFlags for consistency
+        for cf in trial.capture_flags:
+            flags.append(
+                AnalysisFlag(
+                    type=cf.type,
+                    analyzer="capture",
+                    severity=cf.severity,
+                    message=cf.message,
+                    evidence=cf.details,
+                    trial_ids=[trial.trial_id],
+                )
+            )
+
+    return JudgmentAnalytics(
+        item_id=item_id,
+        participant_id=session.participant_id or session.session_id,
+        trial_index=trial.trial_index,
+        session_id=session.session_id,
+        response_value=response_value,
+        response_time_ms=response_time_ms,
+        keystroke_metrics=keystroke_metrics,
+        focus_metrics=focus_metrics,
+        timing_metrics=timing_metrics,
+        paste_event_count=paste_count,
+        flags=flags,
+        max_severity=_get_max_severity(flags),
+    )
+
+
+def extract_from_session(
+    session: SlopitSession,
+    item_id_key: str = "item_id",
+) -> list[JudgmentAnalytics]:
+    """Extract behavioral analytics from all trials in a slopit session.
+
+    Parameters
+    ----------
+    session : SlopitSession
+        Slopit session containing trial data.
+    item_id_key : str
+        Key in platform_data containing the item UUID.
+
+    Returns
+    -------
+    list[JudgmentAnalytics]
+        Analytics records for trials with valid item_id.
+    """
+    analytics: list[JudgmentAnalytics] = []
+
+    for trial in session.trials:
+        result = extract_from_trial(trial, session, item_id_key)
+        if result is not None:
+            analytics.append(result)
+
+    return analytics
+
+
+def extract_from_file(
+    path: Path | str,
+    item_id_key: str = "item_id",
+) -> list[JudgmentAnalytics]:
+    """Extract behavioral analytics from a slopit session file.
+
+    Uses slopit's load_session() to automatically detect format.
+
+    Parameters
+    ----------
+    path : Path | str
+        Path to session file (JSON or JATOS format).
+    item_id_key : str
+        Key in platform_data containing the item UUID.
+
+    Returns
+    -------
+    list[JudgmentAnalytics]
+        Analytics records from the session.
+
+    Examples
+    --------
+    >>> analytics = extract_from_file("data/session_001.json")
+    >>> len(analytics)
+    50
+    """
+    session = load_session(path)
+    return extract_from_session(session, item_id_key)
+
+
+def extract_from_directory(
+    path: Path | str,
+    pattern: str = "*",
+    item_id_key: str = "item_id",
+    name: str | None = None,
+) -> AnalyticsCollection:
+    """Extract behavioral analytics from all session files in a directory.
+
+    Uses slopit's load_sessions() to load all files.
+
+    Parameters
+    ----------
+    path : Path | str
+        Directory containing session files.
+    pattern : str
+        Glob pattern for file matching (default: "*").
+    item_id_key : str
+        Key in platform_data containing the item UUID.
+    name : str | None
+        Name for the collection. Defaults to directory name.
+
+    Returns
+    -------
+    AnalyticsCollection
+        Collection of analytics from all sessions.
+
+    Examples
+    --------
+    >>> collection = extract_from_directory("data/jatos_export/")
+    >>> print(f"Extracted {len(collection)} analytics records")
+    """
+    path = Path(path)
+    sessions = load_sessions(path, pattern)
+
+    all_analytics: list[JudgmentAnalytics] = []
+    for session in sessions:
+        analytics = extract_from_session(session, item_id_key)
+        all_analytics.extend(analytics)
+
+    collection_name = name if name is not None else path.name
+    return AnalyticsCollection(name=collection_name, analytics=all_analytics)
+
+
+def analyze_sessions(
+    sessions: list[SlopitSession],
+    analyzers: list[Analyzer] | None = None,
+) -> list[SlopitSession]:
+    """Run slopit behavioral analyzers on sessions.
+
+    Uses slopit's AnalysisPipeline to process sessions with
+    the specified analyzers.
+
+    Parameters
+    ----------
+    sessions : list[SlopitSession]
+        Sessions to analyze.
+    analyzers : list[Analyzer] | None
+        Analyzers to run. If None, uses default set:
+        KeystrokeAnalyzer, FocusAnalyzer, PasteAnalyzer, TimingAnalyzer.
+
+    Returns
+    -------
+    list[SlopitSession]
+        Sessions with analysis flags added.
+
+    Examples
+    --------
+    >>> from slopit import load_sessions
+    >>> sessions = load_sessions("data/")
+    >>> analyzed = analyze_sessions(sessions)
+    >>> # Sessions now have analysis flags populated
+    """
+    if analyzers is None:
+        analyzers = [
+            KeystrokeAnalyzer(),
+            FocusAnalyzer(),
+            PasteAnalyzer(),
+            TimingAnalyzer(),
+        ]
+
+    pipeline = AnalysisPipeline(analyzers)
+    return pipeline.analyze(sessions)
+
+
+def extract_with_analysis(
+    path: Path | str,
+    pattern: str = "*",
+    item_id_key: str = "item_id",
+    analyzers: list[Analyzer] | None = None,
+    name: str | None = None,
+) -> AnalyticsCollection:
+    """Load sessions, run analysis, and extract analytics in one step.
+
+    Convenience function that combines loading, analysis, and extraction.
+
+    Parameters
+    ----------
+    path : Path | str
+        Path to session file or directory.
+    pattern : str
+        Glob pattern for directory (default: "*").
+    item_id_key : str
+        Key in platform_data containing the item UUID.
+    analyzers : list[Analyzer] | None
+        Analyzers to run. If None, uses default set.
+    name : str | None
+        Name for the collection.
+
+    Returns
+    -------
+    AnalyticsCollection
+        Collection with analyzed behavioral data.
+
+    Examples
+    --------
+    >>> collection = extract_with_analysis("data/jatos_export/")
+    >>> summaries = collection.get_participant_summaries()
+    >>> for s in summaries:
+    ...     if s.flag_rate > 0.1:
+    ...         print(f"Participant {s.participant_id}: {s.flag_rate:.1%} flagged")
+    """
+    path = Path(path)
+
+    # Load sessions
+    sessions = load_sessions(path, pattern)
+
+    # Run analysis
+    analyzed = analyze_sessions(sessions, analyzers)
+
+    # Extract analytics
+    all_analytics: list[JudgmentAnalytics] = []
+    for session in analyzed:
+        analytics = extract_from_session(session, item_id_key)
+        all_analytics.extend(analytics)
+
+    collection_name = name if name is not None else path.name
+    return AnalyticsCollection(name=collection_name, analytics=all_analytics)

bead/behavioral/merging.py

@@ -0,0 +1,343 @@
+"""Utilities for merging behavioral analytics with judgment data.
+
+This module provides functions for joining behavioral analytics with
+judgment DataFrames for analysis. All functions support both pandas
+and polars DataFrames, preserving the input type.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+import pandas as pd
+import polars as pl
+
+from bead.behavioral.analytics import AnalyticsCollection
+
+if TYPE_CHECKING:
+    from slopit.schemas import Severity
+
+    from bead.participants.collection import IDMappingCollection, ParticipantCollection
+
+# Type alias for supported DataFrame types
+DataFrame = pd.DataFrame | pl.DataFrame
+
+
+def merge_behavioral_analytics(
+    judgments_df: DataFrame,
+    analytics: AnalyticsCollection,
+    item_id_column: str = "item_id",
+    participant_id_column: str = "participant_id",
+    include_metrics: bool = True,
+    include_flags: bool = True,
+    how: str = "left",
+) -> DataFrame:
+    """Merge behavioral analytics into a judgments DataFrame.
+
+    Preserves input DataFrame type (pandas in -> pandas out,
+    polars in -> polars out).
+
+    Parameters
+    ----------
+    judgments_df : DataFrame
+        DataFrame containing judgment data.
+    analytics : AnalyticsCollection
+        Collection of behavioral analytics.
+    item_id_column : str
+        Column in judgments_df containing item IDs (default: "item_id").
+    participant_id_column : str
+        Column in judgments_df containing participant IDs.
+    include_metrics : bool
+        If True, include flattened behavioral metrics columns.
+    include_flags : bool
+        If True, include flag-related columns.
+    how : str
+        Merge type: "left", "inner", "outer" (default: "left").
+
+    Returns
+    -------
+    DataFrame
+        Merged DataFrame with behavioral analytics columns added.
+
+    Examples
+    --------
+    >>> import pandas as pd
+    >>> judgments = pd.DataFrame({
+    ...     "item_id": ["uuid1", "uuid2"],
+    ...     "participant_id": ["p1", "p1"],
+    ...     "response": [5, 3],
+    ... })
+    >>> # merged = merge_behavioral_analytics(judgments, analytics_collection)
+    """
+    is_polars = isinstance(judgments_df, pl.DataFrame)
+
+    # Convert analytics to DataFrame with same backend
+    backend: Literal["pandas", "polars"] = "polars" if is_polars else "pandas"
+    analytics_df = analytics.to_dataframe(
+        backend=backend,
+        include_metrics=include_metrics,
+        include_flags=include_flags,
+    )
+
+    if is_polars:
+        assert isinstance(judgments_df, pl.DataFrame)
+        assert isinstance(analytics_df, pl.DataFrame)
+
+        # Polars join on both item_id and participant_id
+        return judgments_df.join(
+            analytics_df,
+            left_on=[item_id_column, participant_id_column],
+            right_on=["item_id", "participant_id"],
+            how=how,  # type: ignore[arg-type]
+            suffix="_behavioral",
+        )
+    else:
+        assert isinstance(judgments_df, pd.DataFrame)
+        assert isinstance(analytics_df, pd.DataFrame)
+
+        # Pandas merge
+        merged = pd.merge(
+            judgments_df,
+            analytics_df,
+            left_on=[item_id_column, participant_id_column],
+            right_on=["item_id", "participant_id"],
+            how=how,  # type: ignore[arg-type]
+            suffixes=("", "_behavioral"),
+        )
+
+        # Remove duplicate columns if created
+        for col in ["item_id_behavioral", "participant_id_behavioral"]:
+            if col in merged.columns:
+                merged = merged.drop(columns=[col])
+
+        return merged
+
+
+def filter_flagged_judgments(
+    judgments_df: DataFrame,
+    analytics: AnalyticsCollection,
+    item_id_column: str = "item_id",
+    participant_id_column: str = "participant_id",
+    min_severity: Severity | None = None,
+    exclude_flagged: bool = True,
+) -> DataFrame:
+    """Filter judgments based on behavioral flags.
+
+    Preserves input DataFrame type.
+
+    Parameters
+    ----------
+    judgments_df : DataFrame
+        DataFrame containing judgment data.
+    analytics : AnalyticsCollection
+        Collection of behavioral analytics.
+    item_id_column : str
+        Column containing item IDs.
+    participant_id_column : str
+        Column containing participant IDs.
+    min_severity : Severity | None
+        Minimum severity level for filtering. If None, any flag counts.
+    exclude_flagged : bool
+        If True, exclude flagged judgments (default).
+        If False, keep only flagged judgments.
+
+    Returns
+    -------
+    DataFrame
+        Filtered DataFrame.
+
+    Examples
+    --------
+    >>> # Keep only unflagged judgments
+    >>> clean_df = filter_flagged_judgments(judgments, analytics, exclude_flagged=True)
+    >>> # Keep only high-severity flagged judgments for review
+    >>> flagged_df = filter_flagged_judgments(
+    ...     judgments, analytics, min_severity="high", exclude_flagged=False
+    ... )
+    """
+    is_polars = isinstance(judgments_df, pl.DataFrame)
+
+    # Get filtered analytics
+    filtered_analytics = analytics.filter_flagged(
+        min_severity=min_severity,
+        exclude_flagged=False,  # Get flagged records
+    )
+
+    # Build set of flagged (item_id, participant_id) pairs
+    flagged_pairs: set[tuple[str, str]] = {
+        (str(a.item_id), a.participant_id) for a in filtered_analytics.analytics
+    }
+
+    if is_polars:
+        assert isinstance(judgments_df, pl.DataFrame)
+
+        # Create mask column
+        df_with_flag = judgments_df.with_columns(
+            pl.struct([item_id_column, participant_id_column])
+            .map_elements(
+                lambda row: (
+                    (str(row[item_id_column]), str(row[participant_id_column]))
+                    in flagged_pairs
+                ),
+                return_dtype=pl.Boolean,
+            )
+            .alias("_is_flagged")
+        )
+
+        if exclude_flagged:
+            result = df_with_flag.filter(~pl.col("_is_flagged"))
+        else:
+            result = df_with_flag.filter(pl.col("_is_flagged"))
+
+        return result.drop("_is_flagged")
+
+    else:
+        assert isinstance(judgments_df, pd.DataFrame)
+
+        # Create mask
+        mask = judgments_df.apply(
+            lambda row: (
+                (str(row[item_id_column]), str(row[participant_id_column]))
+                in flagged_pairs
+            ),
+            axis=1,
+        )
+
+        if exclude_flagged:
+            return judgments_df[~mask].copy()
+        else:
+            return judgments_df[mask].copy()
+
+
+def create_analysis_dataframe_with_behavior(
+    judgments_df: DataFrame,
+    participants: ParticipantCollection,
+    analytics: AnalyticsCollection,
+    id_mappings: IDMappingCollection | None = None,
+    external_id_column: str | None = None,
+    participant_id_column: str = "participant_id",
+    item_id_column: str = "item_id",
+    metadata_columns: list[str] | None = None,
+    include_metrics: bool = True,
+    include_flags: bool = True,
+) -> DataFrame:
+    """Create analysis-ready DataFrame with metadata and behavioral analytics.
+
+    Combines both participant and behavioral merging in one step.
+    Preserves input DataFrame type.
+
+    Parameters
+    ----------
+    judgments_df : DataFrame
+        Raw judgment data.
+    participants : ParticipantCollection
+        Participant collection with metadata.
+    analytics : AnalyticsCollection
+        Behavioral analytics collection.
+    id_mappings : IDMappingCollection | None
+        ID mappings (required if external_id_column is provided).
+    external_id_column : str | None
+        Column with external IDs to resolve.
+    participant_id_column : str
+        Column with participant IDs (after resolution).
+    item_id_column : str
+        Column with item IDs.
+    metadata_columns : list[str] | None
+        Participant metadata columns to include.
+    include_metrics : bool
+        If True, include behavioral metrics columns.
+    include_flags : bool
+        If True, include flag columns.
+
+    Returns
+    -------
+    DataFrame
+        Analysis-ready DataFrame with both metadata and behavioral data.
+
+    Examples
+    --------
+    >>> analysis_df = create_analysis_dataframe_with_behavior(
+    ...     judgments,
+    ...     participants,
+    ...     analytics,
+    ...     id_mappings=mappings,
+    ...     external_id_column="PROLIFIC_PID",
+    ... )
+    """
+    # Import here to avoid circular imports
+    from bead.participants.merging import (  # noqa: PLC0415
+        merge_participant_metadata,
+        resolve_external_ids,
+    )
+
+    df = judgments_df
+
+    # Step 1: Resolve external IDs if needed
+    if external_id_column is not None and id_mappings is not None:
+        df = resolve_external_ids(
+            df,
+            id_mappings,
+            external_id_column=external_id_column,
+            output_column=participant_id_column,
+        )
+
+    # Step 2: Merge participant metadata
+    df = merge_participant_metadata(
+        df,
+        participants,
+        id_column=participant_id_column,
+        metadata_columns=metadata_columns,
+    )
+
+    # Step 3: Merge behavioral analytics
+    df = merge_behavioral_analytics(
+        df,
+        analytics,
+        item_id_column=item_id_column,
+        participant_id_column=participant_id_column,
+        include_metrics=include_metrics,
+        include_flags=include_flags,
+    )
+
+    return df
+
+
+def get_exclusion_list(
+    analytics: AnalyticsCollection,
+    min_flag_rate: float = 0.1,
+    min_severity: Severity | None = None,
+) -> list[str]:
+    """Get list of participant IDs that should be excluded based on flags.
+
+    Identifies participants with flag rates above the threshold.
+
+    Parameters
+    ----------
+    analytics : AnalyticsCollection
+        Behavioral analytics collection.
+    min_flag_rate : float
+        Minimum proportion of flagged judgments for exclusion (default: 0.1).
+    min_severity : Severity | None
+        Only count flags at or above this severity.
+
+    Returns
+    -------
+    list[str]
+        Participant IDs recommended for exclusion.
+
+    Examples
+    --------
+    >>> exclude = get_exclusion_list(analytics, min_flag_rate=0.2)
+    >>> clean_df = judgments_df[~judgments_df["participant_id"].isin(exclude)]
+    """
+    # Apply severity filter if specified
+    if min_severity is not None:
+        filtered = analytics.filter_flagged(
+            min_severity=min_severity, exclude_flagged=False
+        )
+    else:
+        filtered = analytics
+
+    summaries = filtered.get_participant_summaries()
+
+    return [s.participant_id for s in summaries if s.flag_rate >= min_flag_rate]

bead/cli/__init__.py

@@ -0,0 +1,11 @@
+"""Command-line interface.
+
+Provides commands for configuration management, project initialization,
+and pipeline execution.
+"""
+
+from __future__ import annotations
+
+from bead.cli.main import cli
+
+__all__ = ["cli"]