studies

Study endpoint handlers.

StudiesEndpoint

Bases: BaseEndpoint

Handles study-related API endpoints.

Studies represent individual subjects or participants within a project.

count(project_id, *, tags_any=None, name_contains=None, subject_key=None, missing_metadata_any=None) async

Count the studies a filter resolves to, without fetching them.

This is the expected_count a live-set selector write must present (the server re-resolves with the SAME predicate).

create(project_id, study) async

Create a new study in a project.

Parameters:

Name	Type	Description	Default
project_id	UUID | str	UUID of the project	required
study	StudyCreate	Study data (name is required; description, tags, metadata optional)	required

Returns:

Type	Description
StudyOut	Created study information

Raises:

Type	Description
ValidationError	If study data is invalid
NotFoundError	If project doesn't exist
AuthenticationError	If not authenticated

Example

from yousleep_common.models import StudyCreate

study = StudyCreate(
    name="Subject 001",
    description="First participant",
    age=35,
    sex="male",
)
created = await client.studies.create(project_id, study)

create_events(study_id, request) async

Create study-level events (e.g. lights off/on).

Parameters:

Name	Type	Description	Default
study_id	UUID | str	UUID of the study	required
request	CreateStudyEventsRequest	Request containing list of study events to create	required

Returns:

Type	Description
list[StudyEvent]	List of created study events

Raises:

Type	Description
ValidationError	If event data is invalid
NotFoundError	If study doesn't exist
AuthenticationError	If not authenticated

delete(study_id) async

Delete a study.

Parameters:

Name	Type	Description	Default
study_id	UUID | str	UUID of the study to delete	required

Returns:

Type	Description
MessageResponse	Message confirming deletion

Raises:

Type	Description
NotFoundError	If study doesn't exist
AuthenticationError	If not authenticated

delete_event(study_id, event_id) async

Delete a study-level event.

Parameters:

Name	Type	Description	Default
study_id	UUID | str	UUID of the study	required
event_id	UUID | str	UUID of the study event to delete	required

Returns:

Type	Description
MessageResponse	Message confirming deletion

Raises:

Type	Description
NotFoundError	If event doesn't exist
AuthenticationError	If not authenticated

get(study_id) async

Get a specific study by ID.

Parameters:

Name	Type	Description	Default
study_id	UUID | str	UUID of the study	required

Returns:

Type	Description
StudyOut	Study information

Raises:

Type	Description
NotFoundError	If study doesn't exist
AuthenticationError	If not authenticated

get_report(study_id, include_biomarkers=False, soremp_threshold_min=15.0, statistics_window_start_ms=None, statistics_window_end_ms=None) async

Get a report for the study.

Returns event statistics for all completed analyses, optionally including biomarkers for staging analyses.

Parameters:

Name	Type	Description	Default
study_id	UUID | str	UUID of the study	required
include_biomarkers	bool	Whether to compute biomarkers for staging analyses	False
soremp_threshold_min	float	Max minutes from sleep onset to the first REM epoch for a SOREMP	15.0
statistics_window_start_ms	int | None	Optional window start override (ms)	None
statistics_window_end_ms	int | None	Optional window end override (ms)	None

Returns:

Type	Description
StudyReportResponse	StudyReportResponse with event stats, optional biomarkers, and window

Raises:

Type	Description
NotFoundError	If study doesn't exist
AuthenticationError	If not authenticated

list(project_id, *, skip=None, limit=None, tags_any=None, name_contains=None, subject_key=None, missing_metadata_any=None, order_by=None) async

List the (optionally filtered) studies in a project.

tags_any/name_contains/subject_key are the selector filter vocabulary — this filtered listing is the preview of what a batch selector write addresses (see the Bulk Operations with Selectors guide).

Parameters:

Name	Type	Description	Default
project_id	UUID | str	UUID of the project	required
skip	int | None	Pagination offset	None
limit	int | None	Maximum studies to return (1-10,000). Without it the whole list is read, a project of up to 10,000 studies in one request	None
tags_any	list[str] | None	Only studies carrying at least one of these tags	None
name_contains	str | None	Only studies whose name contains this text	None
subject_key	str | None	Only the studies of one subject — the key is compared case- and whitespace-insensitively	None
missing_metadata_any	list[MetadataType] | None	Only studies that do not record at least one of these subject values	None
order_by	StudyOrder | None	"created" (default) or "subject", which puts a person's studies together and in series order	None

Returns:

Type	Description
list[StudyOut]	List of matching studies in the project

Raises:

Type	Description
NotFoundError	If project doesn't exist
AuthenticationError	If not authenticated

list_events(study_id) async

List all study-level events.

Parameters:

Name	Type	Description	Default
study_id	UUID | str	UUID of the study	required

Returns:

Type	Description
list[StudyEvent]	List of study events

Raises:

Type	Description
NotFoundError	If study doesn't exist
AuthenticationError	If not authenticated

summary(project_id, *, tags_any=None, preview=None) async

Summarise a project's studies without listing them.

Every tag and every subject with its count, the studies carrying no tag, and the first studies of each set. One small answer at any project size, for pickers and breakdowns.

Parameters:

Name	Type	Description	Default
project_id	UUID | str	UUID of the project	required
tags_any	list[str] | None	The tags a selection keeps; the summary then also counts the studies carrying none of them (excluded)	None
preview	int | None	How many studies each set names (0-100, default 20)	None

Returns:

Type	Description
StudySummary	The project's study summary

Raises:

Type	Description
NotFoundError	If project doesn't exist
AuthenticationError	If not authenticated

update(study_id, study) async

Update an existing study (PATCH).

Universal field semantics:

• Omit a field to leave it unchanged.
• Include a field with a value to update it.
• Include a field with None to clear it (where nullable in storage — description, tags, age, bmi, sex).

name cannot be cleared; sending name=None raises a validation error. Omit name to leave it unchanged.

Parameters:

Name	Type	Description	Default
study_id	UUID | str	UUID of the study to update	required
study	StudyUpdate	Partial update (only included fields are modified)	required

Returns:

Type	Description
StudyOut	Updated study information

Raises:

Type	Description
NotFoundError	If study doesn't exist
ValidationError	If update data is invalid (e.g., name=None)
AuthenticationError	If not authenticated

Example

from yousleep_common.models import StudyUpdate

# Clear description and tags, leave everything else alone
study_update = StudyUpdate(description=None, tags=None)
updated = await client.studies.update(study_id, study_update)