hyperstudy 0.3.0

Python SDK for the HyperStudy experiment platform API

hyperstudy

Python SDK for the HyperStudy experiment platform API. Designed for researchers working in Jupyter, marimo, or Python scripts.

Installation

pip install hyperstudy

For polars support:

pip install hyperstudy[polars]

Quick Start

import hyperstudy

hs = hyperstudy.HyperStudy(api_key="hst_live_...")
# Or set the HYPERSTUDY_API_KEY environment variable

# Fetch events as a pandas DataFrame
events = hs.get_events("your_experiment_id")

# Room-scoped data
events = hs.get_events("room_id", scope="room")

# Participant-scoped data
events = hs.get_events("participant_id", scope="participant", room_id="room_id")

Data Types

All data retrieval methods follow the same pattern:

events        = hs.get_events("exp_id")
recordings    = hs.get_recordings("exp_id")
chat          = hs.get_chat("exp_id")
videochat     = hs.get_videochat("exp_id")
sync          = hs.get_sync("exp_id")
ratings       = hs.get_ratings("exp_id", kind="continuous")
components    = hs.get_components("exp_id")
participants  = hs.get_participants("exp_id")
rooms         = hs.get_rooms("exp_id")

# Convenience methods for common event categories
questionnaire = hs.get_questionnaire("exp_id")
instructions  = hs.get_instructions("exp_id")
consent       = hs.get_consent("exp_id")

Output Formats

df_pandas = hs.get_events("exp_id")                      # pandas (default)
df_polars = hs.get_events("exp_id", output="polars")     # polars
raw       = hs.get_events("exp_id", output="dict")       # list[dict]

Filtering

events = hs.get_events(
    "exp_id",
    start_time="2024-01-01T10:00:00Z",
    end_time="2024-01-01T12:00:00Z",
    category="component",
    sort="onset",
    limit=100,
)

Auto-Pagination

When limit is not set, all pages are fetched automatically with a progress bar:

all_events = hs.get_events("exp_id")  # fetches all pages

Experiment Management

# List experiments
experiments = hs.list_experiments()

# Get details (with rich display in notebooks)
exp = hs.get_experiment("exp_id")

# Quick create / update / delete (kwargs form, backwards-compatible)
new_exp = hs.create_experiment(name="My Study", description="...")
hs.update_experiment("exp_id", name="Updated Name")
hs.delete_experiment("exp_id")

Building experiments programmatically (0.3.0+)

For full experiment definitions — states, components, roles — use the typed Experiment builder. Snake_case Python fields convert to the camelCase wire format automatically.

from hyperstudy import Experiment, State, Role, show_text, vas_rating

exp = Experiment(
    name="Two-person study",
    required_participants=2,
    states=[
        State(id="intro", focus_component=show_text("Welcome")),
        State(
            id="rate",
            focus_component=vas_rating("Rate the clip", output_variable="rating"),
        ),
    ],
    roles={"speaker": Role(name="Speaker", participant_count=1)},
)

# Dry-run validation against the backend.
print(hs.validate_experiment(exp))  # → {"valid": True, ...}

# Create.
info = hs.create_experiment(experiment=exp)

Component factories cover show_text, show_image, show_video, vas_rating, text_input, multiple_choice, waiting, likert_scale, ranking. For other component types, construct directly: FocusComponent(type=ComponentType.X, config={...}). See the Experiment Authoring guide for the full reference.

Deployments

# List deployments
deployments = hs.list_deployments()
deployments = hs.list_deployments(experiment_id="exp_id", status="active")

# Get deployment details
dep = hs.get_deployment("deployment_id")

# List sessions/rooms for a deployment
sessions = hs.get_deployment_sessions("deployment_id")

All Data for a Participant

data = hs.get_all_data("participant_id", room_id="room_id")
# Returns dict with keys: events, recordings, chat, videochat, sync,
# ratings_continuous, ratings_sparse, components, questionnaire,
# instructions, consent

API Key

Generate an API key from the HyperStudy dashboard under Settings. Keys follow the format hst_{environment}_{key} and are passed via the X-API-Key header.

Documentation

Full documentation: docs.hyperstudy.io/developers/python-sdk

Development

git clone https://github.com/hyperstudyio/hyperstudy-pythonsdk.git
cd hyperstudy-pythonsdk
pip install -e ".[dev,polars]"
pytest --cov=hyperstudy
ruff check src/

License

MIT