bead 0.1.0__py3-none-any.whl

bead/data_collection/merger.py

@@ -0,0 +1,154 @@
+"""Data merger for JATOS and Prolific data.
+
+This module provides the DataMerger class for merging experimental results
+from JATOS with participant metadata from Prolific. The merger matches
+records based on participant IDs and handles unmatched records gracefully.
+"""
+
+from __future__ import annotations
+
+from bead.data.base import JsonValue
+
+
+class DataMerger:
+    """Merges JATOS results with Prolific metadata.
+
+    This class merges experimental data from JATOS with participant
+    demographics and metadata from Prolific based on participant IDs.
+
+    Parameters
+    ----------
+    merge_key : str
+        Key to merge on (e.g., "PROLIFIC_PID"). Default is "PROLIFIC_PID".
+
+    Attributes
+    ----------
+    merge_key : str
+        Key to merge on (e.g., "PROLIFIC_PID").
+
+    Examples
+    --------
+    Create a merger with custom key::
+
+        merger = DataMerger(merge_key="PROLIFIC_PID")
+        merged_data = merger.merge(jatos_results, prolific_submissions)
+    """
+
+    def __init__(self, merge_key: str = "PROLIFIC_PID") -> None:
+        self.merge_key = merge_key
+
+    def merge(
+        self,
+        jatos_results: list[dict[str, JsonValue]],
+        prolific_submissions: list[dict[str, JsonValue]],
+    ) -> list[dict[str, JsonValue]]:
+        """Merge JATOS and Prolific data.
+
+        Merges experimental results from JATOS with participant submissions
+        from Prolific by matching on participant IDs. Returns merged records
+        with both JATOS data and Prolific metadata.
+
+        Parameters
+        ----------
+        jatos_results : list[dict[str, Any]]
+            JATOS results from JATOSDataCollector.
+        prolific_submissions : list[dict[str, Any]]
+            Prolific submissions from ProlificDataCollector.
+
+        Returns
+        -------
+        list[dict[str, JsonValue]]
+            Merged data with structure:
+            {
+                "jatos_data": {...},
+                "prolific_metadata": {...} | None,
+                "merged": bool
+            }
+
+        Examples
+        --------
+        ::
+
+            jatos_results = [
+                {"data": {"PROLIFIC_PID": "abc123"}, "metadata": {}}
+            ]
+            prolific_submissions = [
+                {"participant_id": "abc123", "status": "APPROVED"}
+            ]
+            merged = merger.merge(jatos_results, prolific_submissions)
+            assert merged[0]["merged"] is True
+        """
+        # Create lookup by Prolific participant ID
+        prolific_lookup: dict[str, dict[str, JsonValue]] = {
+            sub["participant_id"]: sub for sub in prolific_submissions
+        }
+
+        merged: list[dict[str, JsonValue]] = []
+
+        for result in jatos_results:
+            # Extract Prolific PID from JATOS data
+            prolific_pid = self._extract_prolific_pid(result)
+
+            if prolific_pid and prolific_pid in prolific_lookup:
+                # Merge
+                merged_record: dict[str, JsonValue] = {
+                    "jatos_data": result,
+                    "prolific_metadata": prolific_lookup[prolific_pid],
+                    "merged": True,
+                }
+            else:
+                # No match
+                merged_record = {
+                    "jatos_data": result,
+                    "prolific_metadata": None,
+                    "merged": False,
+                }
+
+            merged.append(merged_record)
+
+        return merged
+
+    def _extract_prolific_pid(
+        self,
+        jatos_result: dict[str, JsonValue],
+    ) -> str | None:
+        """Extract Prolific PID from JATOS result.
+
+        Searches for the participant ID in both the data and metadata
+        fields of the JATOS result.
+
+        Parameters
+        ----------
+        jatos_result : dict[str, JsonValue]
+            JATOS result dictionary.
+
+        Returns
+        -------
+        str | None
+            Prolific PID if found, None otherwise.
+
+        Examples
+        --------
+        ::
+
+            result = {"data": {"PROLIFIC_PID": "abc123"}}
+            pid = merger._extract_prolific_pid(result)
+            assert pid == "abc123"
+        """
+        # Check in data field
+        data = jatos_result.get("data")
+        if isinstance(data, dict):
+            # Extract value from untyped JSON and verify type at runtime
+            value = data.get(self.merge_key)  # type: ignore[reportUnknownMemberType]
+            if isinstance(value, str):
+                return value
+
+        # Check in metadata field
+        metadata = jatos_result.get("metadata")
+        if isinstance(metadata, dict):
+            # Extract value from untyped JSON and verify type at runtime
+            value = metadata.get(self.merge_key)  # type: ignore[reportUnknownMemberType]
+            if isinstance(value, str):
+                return value
+
+        return None

bead/data_collection/prolific.py

@@ -0,0 +1,198 @@
+"""Prolific data collection for model training.
+
+This module provides the ProlificDataCollector class for downloading participant
+metadata and submissions from Prolific. It supports:
+- Downloading participant submissions with pagination
+- Filtering by submission status
+- Approving submissions
+- Getting study metadata
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import requests
+
+from bead.data.base import JsonValue
+from bead.data.timestamps import now_iso8601
+
+
+class ProlificDataCollector:
+    """Collects participant data from Prolific API.
+
+    This class interfaces with the Prolific API v1 to download participant
+    submissions, demographics, and metadata for model training.
+
+    Parameters
+    ----------
+    api_key : str
+        Prolific API key for authentication.
+    study_id : str
+        Prolific study ID to collect data from.
+
+    Attributes
+    ----------
+    api_key : str
+        Prolific API key for authentication.
+    study_id : str
+        Prolific study ID to collect data from.
+    base_url : str
+        Prolific API base URL.
+    session : requests.Session
+        HTTP session with authentication headers.
+
+    Examples
+    --------
+    Create a collector and download submissions::
+
+        collector = ProlificDataCollector(
+            api_key="my-api-key",
+            study_id="abc123"
+        )
+        submissions = collector.download_submissions(Path("submissions.json"))
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        study_id: str,
+    ) -> None:
+        self.api_key = api_key
+        self.study_id = study_id
+        self.base_url = "https://api.prolific.co/api/v1"
+
+        self.session = requests.Session()
+        self.session.headers.update({"Authorization": f"Token {api_key}"})
+
+    def download_submissions(
+        self,
+        output_path: Path,
+        status: str | None = None,
+    ) -> list[dict[str, JsonValue]]:
+        """Download participant submissions.
+
+        Downloads all submissions for the study, handling pagination automatically.
+        Each submission is enriched with a download timestamp.
+
+        Parameters
+        ----------
+        output_path : Path
+            Path to save submissions (JSON format).
+        status : str | None
+            Filter by status (e.g., "APPROVED", "AWAITING REVIEW").
+
+        Returns
+        -------
+        list[dict[str, JsonValue]]
+            Downloaded submissions with metadata.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the API request fails.
+
+        Examples
+        --------
+        Download all submissions::
+
+            submissions = collector.download_submissions(Path("submissions.json"))
+
+        Download with status filter::
+
+            submissions = collector.download_submissions(
+                Path("approved.json"),
+                status="APPROVED"
+            )
+        """
+        submissions: list[dict[str, JsonValue]] = []
+        page = 1
+
+        while True:
+            url = f"{self.base_url}/studies/{self.study_id}/submissions/"
+            params: dict[str, str | int] = {"page": page}
+
+            if status:
+                params["status"] = status
+
+            response = self.session.get(url, params=params)
+            response.raise_for_status()
+
+            data: dict[str, JsonValue] = response.json()
+            page_submissions: list[JsonValue] = (
+                data.get("results", []) if isinstance(data.get("results"), list) else []
+            )
+
+            if not page_submissions:
+                break
+
+            # Enrich with metadata
+            for sub in page_submissions:
+                if isinstance(sub, dict):
+                    sub["download_timestamp"] = now_iso8601().isoformat()
+                    submissions.append(sub)
+
+            page += 1
+
+        # Save to JSON file
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(output_path, "w") as f:
+            json.dump(submissions, f, indent=2)
+
+        return submissions
+
+    def get_study_info(self) -> dict[str, JsonValue]:
+        """Get study information.
+
+        Returns
+        -------
+        dict[str, JsonValue]
+            Study details dictionary.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the API request fails.
+
+        Examples
+        --------
+        ::
+
+            info = collector.get_study_info()
+            print(info["name"])
+        """
+        url = f"{self.base_url}/studies/{self.study_id}/"
+        response = self.session.get(url)
+        response.raise_for_status()
+        return response.json()
+
+    def approve_submissions(
+        self,
+        submission_ids: list[str],
+    ) -> None:
+        """Approve submissions.
+
+        Approves multiple submissions by transitioning their status to APPROVED.
+
+        Parameters
+        ----------
+        submission_ids : list[str]
+            Submission IDs to approve.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the API request fails.
+
+        Examples
+        --------
+        ::
+
+            collector.approve_submissions(["sub1", "sub2", "sub3"])
+        """
+        for submission_id in submission_ids:
+            url = f"{self.base_url}/submissions/{submission_id}/transition/"
+            data = {"action": "APPROVE"}
+            response = self.session.post(url, json=data)
+            response.raise_for_status()

bead/deployment/__init__.py

@@ -0,0 +1,5 @@
+"""Deployment module for generating experiments.
+
+Generates experiments for jsPsych/JATOS platforms with batch mode support
+and configurable list distribution strategies.
+"""