Skip to content

study

Pydantic models related to studies.

StudyOrder = Literal['created', 'subject'] module-attribute

How a study listing is ordered.

created is the order the studies were created in — the default, and what pagination has always walked. subject puts a person's studies together and in series order: subjects in key order, within a subject the declared visit numbers first and unnumbered nights after them, and the studies that belong to no subject last. A paginated listing ordered this way can be read (and drawn) grouped by person.

SubjectKey = Annotated[str, StringConstraints(strip_whitespace=True, min_length=1, max_length=64)] module-attribute

A subject key as a client sends it: surrounding whitespace stripped, otherwise as typed. Grouping compares keys case- and whitespace-insensitively within a project, so P01, p01 and P 01 are one subject; what is stored and shown is the first spelling entered.

StudyCreate pydantic-model

Bases: NamedEntityCreate, StudyMetadata

Create payload for a study. name is required.

Fields:

StudyGroupSummary pydantic-model

Bases: BaseModel

A set of a project's studies: how many, and the first of them.

Fields:

count pydantic-field

How many studies the set holds.

studies pydantic-field

The first studies of the set in creation order, at most the summary's preview size.

StudyListResponse pydantic-model

Bases: PaginatedResponse

A page of a project's studies.

Fields:

StudyMetadata pydantic-model

Bases: BaseModel

A collection of optional metadata fields on a Study.

Fields:

age = None pydantic-field

Age of the subject in years

bmi = None pydantic-field

Body mass index of the subject

session_index = None pydantic-field

Declared position of this study in its subject's series, 1 = first. Set only by the user; never allocated by the server. Null means the position is derived from the order of recording starts within the subject; a study whose recording start is unknown cannot be placed that way and needs a declared index.

sex = None pydantic-field

Biological sex of the subject

subject_key = None pydantic-field

The person this study belongs to. Studies in one project sharing a key form that subject's series; the key is compared case- and whitespace-insensitively and is unique to nothing — it groups, it does not identify. Null for a study that stands alone, which is every study until a key is set.

StudyOut pydantic-model

Bases: StudyCreate

Study information available to user.

Fields:

analyses_count = 0 pydantic-field

Total number of analyses

analyzed_count = 0 pydantic-field

Recordings with >= 1 completed analysis

created_at pydantic-field

Creation timestamp of the study

first_recording_date = None pydantic-field

Earliest recording start across the study's recordings — when the night was recorded, as opposed to when it was uploaded (created_at). None when no recording carries a start time.

has_lights = None pydantic-field

Whether the study has lights off/on markers, i.e. its statistics will be lights-windowed. None when the producer did not compute it. Derivable from lights_off_ms/lights_on_ms where those are populated (kept for compatibility).

id pydantic-field

Unique identifier of the study

lights_off_ms = None pydantic-field

The lights-off marker, ms from the earliest recording start (first_recording_date is the clock frame). None = not set or not computed by the producer.

lights_on_ms = None pydantic-field

The lights-on marker, ms from the earliest recording start. None = not set or not computed by the producer.

owner_id = None pydantic-field

The member who added it. Only they, or the project's owner, may change or remove it; it passes to the project's owner when they leave the organization.

project_id = None pydantic-field

The project the study belongs to.

recording_count = 0 pydantic-field

Number of recordings

total_duration_ms = 0 pydantic-field

Total recording duration in ms

StudyRef pydantic-model

Bases: BaseModel

A study named in a summary: enough to show and link it.

Fields:

id pydantic-field

The study's id.

name pydantic-field

The study's name.

StudySummary pydantic-model

Bases: BaseModel

What a project's studies hold, without listing them.

Tag and subject vocabularies with their counts, and the first studies of each set, so a picker or a breakdown needs one small answer at any project size.

Fields:

excluded = None pydantic-field

The studies carrying none of the requested tags_any; absent when none were requested.

subjects pydantic-field

Every subject in the project, by normalised key.

tags pydantic-field

Every tag in the project, the most studies first, then by tag.

total pydantic-field

How many studies the project holds.

untagged pydantic-field

The studies carrying no tag.

StudyUpdate pydantic-model

Bases: NamedEntityUpdate, StudyMetadata

PATCH payload for a study — all fields are optional.

See NamedEntityUpdate for the universal PATCH semantics (omit-to-skip, include-to-set, null-to-clear).

Fields:

SubjectSummary pydantic-model

Bases: BaseModel

The studies of one subject.

Fields:

count pydantic-field

How many studies the subject has.

subject_key pydantic-field

The subject key as first entered. Keys that differ only in case or whitespace are one subject.

TagSummary pydantic-model

Bases: StudyGroupSummary

The studies carrying one tag.

Fields:

tag pydantic-field

The tag.