Index

YouSleep common data types (enums, annotated primitives etc.).

See also the yousleep_common.models module for Pydantic models and data validation.

ORGANIZATION_NAME_MAX_LENGTH = 64 module-attribute

The longest an organization's display name may be, in characters.

A display name is a team label ("Sleep Lab Copenhagen"), not a full affiliation; a longer affiliation stays on the member's profile.

RECORDING_UPLOAD_FORMATS = (FileFormat.EDF,) module-attribute

The formats a recording may be uploaded in; the server refuses any other at registration. Served as ServerLimits.recording_formats, so a client filters its file picker and validates against the server's list instead of a copy.

AdminUserSort

Bases: str, Enum

Orderings the admin user list offers.

Each is a column the list can sort on directly; usage-derived orderings (storage, active analyses) are deliberately not offered here.

CREATED_AT = 'created_at' class-attribute instance-attribute

Newest accounts first.

EMAIL = 'email' class-attribute instance-attribute

Alphabetical by email address.

LAST_LOGIN_AT = 'last_login_at' class-attribute instance-attribute

Most recently signed-in first; accounts never signed into come last.

AnalysisStatus

Bases: str, Enum

Represents the status of an analysis.

CANCELLED = 'cancelled' class-attribute instance-attribute

An analysis that has been cancelled.

COMPLETED = 'completed' class-attribute instance-attribute

An analysis that has been completed.

DEPENDENCY = 'dependency' class-attribute instance-attribute

An analysis that is waiting for a dependency to be resolved.

ENQUEUED = 'enqueued' class-attribute instance-attribute

An analysis that is waiting to be executed.

FAILED = 'failed' class-attribute instance-attribute

An analysis that has failed.

PENDING = 'pending' class-attribute instance-attribute

An analysis that has not yet been started.

REJECTED = 'rejected' class-attribute instance-attribute

An analysis that has been rejected.

REVIEW = 'review' class-attribute instance-attribute

An analysis that is marked for review.

RUNNING = 'running' class-attribute instance-attribute

An analysis that is currently being executed.

SKIPPED = 'skipped' class-attribute instance-attribute

An analysis that was submitted but never executed — e.g. an upstream dependency failed, or it timed out waiting to run. Distinct from FAILED (which ran and errored): no compute ran, so no charge is applied and the reserved credits are released.

is_settled(status) classmethod

Check if the billing lifecycle has ended for status.

Parameters:

Name	Type	Description	Default
status	AnalysisStatus	The status of the analysis.	required

Returns:

Name	Type	Description
bool	bool	True if the status is settled (charged or released).

is_terminal(status) classmethod

Check if the analysis status is terminal (i.e., not pending, enqueued, or running).

Parameters:

Name	Type	Description	Default
status	AnalysisStatus | str	The status of the analysis (a member or its string value).	required

Returns:

Name	Type	Description
bool	bool	True if the status is terminal, False otherwise.

settled_states() classmethod

Return the states in which the billing lifecycle has ended.

A settled analysis has either been charged (COMPLETED) or released without charge (FAILED / CANCELLED / REJECTED / SKIPPED), and must never transition again. Any live analysis whose status is NOT settled constitutes an uncommitted credit hold.

Deliberately EXCLUDES REVIEW: although is_terminal counts REVIEW as terminal, a review analysis still holds its reservation and later moves to COMPLETED to settle. This is the single canonical definition of the billing end states — do not redeclare it.

Returns:

Type	Description
frozenset[AnalysisStatus]	frozenset[AnalysisStatus]: The settled (billing-final) states.

AnalysisType

Bases: str, Enum

Represents the type of an analysis.

AROUSALS = 'arousals' class-attribute instance-attribute

Represents an arousals analysis.

ARTIFACTS = 'artifacts' class-attribute instance-attribute

Represents an artifact detection analysis.

REM = 'rapid-eye-movements' class-attribute instance-attribute

Represents a rapid eye movements analysis.

STAGING = 'staging' class-attribute instance-attribute

Represents a sleep staging analysis.

AnalysisVisibility

Bases: str, Enum

Where an analysis is offered.

BucketCheckOutcome

Bases: str, Enum

How a check of an organisation's bucket went.

BucketCheckStep

Bases: str, Enum

One step of the check of an organisation's bucket.

CapabilityRequestStatus

Bases: str, Enum

Where a request for a capability stands. Pending until an administrator decides.

CapabilityState

Bases: str, Enum

Where an organisation stands with one capability.

ChannelType

Bases: str, Enum

Represents the type of a single signal (EDF+ labels) + types such as MASTOID and UNKNOWN.

References

See https://www.edfplus.info/specs/edftexts.html

infer_from_signal_name(signal_name, exact_edf_label_only=True) classmethod

Infer the ChannelType from a signal name.

In strict (default) mode, only the leading EDF+ label token is inspected (e.g. "EEG Fpz-Cz" → EEG, "Fpz-Cz" → UNKNOWN). With exact_edf_label_only=False, a regex-based classifier inspects the full name and handles the realistic set of PSG signal labels: EEG (standard 10-20 electrodes, referenced or not), EOG, EMG, ECG/EKG, respiratory (RIP, pressure flow/snore, airflow, etc.), SpO2/SaO2, temperature, light, and mastoid references.

Referenced montages like "E1:M2" (EOG referenced to a mastoid) are classified by falling back to the electrode before the colon when the full-name match is ambiguous.

Parameters:

Name	Type	Description	Default
signal_name	str	The signal name to infer the ChannelType from.	required
exact_edf_label_only	bool	If True, only match the leading EDF+ label token. If False, fall through to regex-based classification.	True

Returns:

Type	Description
ChannelType	The inferred ChannelType.

Examples:

>>> ChannelType.infer_from_signal_name("EEG Fpz-Cz")
<ChannelType.EEG: 'EEG'>
>>> ChannelType.infer_from_signal_name("E1:M2", exact_edf_label_only=False)
<ChannelType.EOG: 'EOG'>
>>> ChannelType.infer_from_signal_name("SpO2", exact_edf_label_only=False)
<ChannelType.SAO2: 'SAO2'>

ConsentDocument

Bases: str, Enum

A legal document whose acceptance is gated and audited.

Terms and privacy are required of every user. The licence documents are required per the user's usage_type: commercial (and clinical) users must accept the commercial licence, research users the non-commercial licence — the server derives which one is pending.

CreditBucket

Bases: str, Enum

Which balance a credit entry moves.

• grants: credits granted for research analyses. Every entry in it names the grant it belongs to; a grant may expire.
• purchased: credits bought. They pay for commercial analyses and for storage above an organization's free ceiling, and never expire.
• allowance and payg: retired balances (a recurring allowance and a balance mixing welcome, administrator and purchased credits). Kept so past entries still read; nothing is entered in them any more.

Grants never pay for commercial analyses or storage, and purchased credits never pay for research analyses.

CreditReason

Bases: str, Enum

Why a credit ledger entry was created.

CreditRequestDeclineReason

Bases: str, Enum

Why a grant or extension request was declined, in words the requester is sent.

A fixed list for the same reasons account requests use one: something is better than nothing, a hurried reason sent to a named person reads as a statement about them, and consistency cannot be kept by hand. The split that matters is whether a fresh request could succeed.

AMOUNT_NOT_SUPPORTED = 'amount_not_supported' class-attribute instance-attribute

The amount asked for is more than the plan supports. Fixable.

NOT_RESEARCH = 'not_research' class-attribute instance-attribute

The work described is not non-commercial research.

NO_CAPACITY = 'no_capacity' class-attribute instance-attribute

The platform cannot grant more credits at present.

PLAN_UNCLEAR = 'plan_unclear' class-attribute instance-attribute

The plan did not say enough to judge the amount. Fixable.

is_fixable property

Whether a fresh request could succeed.

CreditRequestKind

Bases: str, Enum

What an organization asks for.

CreditRequestStatus

Bases: str, Enum

Where a request stands. Pending until an administrator decides.

Currency

Bases: str, Enum

Supported currencies enum.

CREDITS = 'credits' class-attribute instance-attribute

Credits currency.

ErrorCode

Bases: str, Enum

Canonical machine-readable API error codes.

EventLabel

Bases: str, Enum

Labels of sleep events (EDF+ labels) + a small set of additional custom labels.

Custom labels

• REM: Rapid eye movements
• SIGNAL_ARTIFACT: Signal-level artifact detected by artifact analysis
• UNKNOWN: Unknown event

References

See https://www.edfplus.info/specs/edftexts.html

scope property

Return the scope of this event label.

Study-scoped labels (e.g. LIGHTS_OFF, LIGHTS_ON) describe environmental events shared across all recordings in a study. Recording-scoped labels describe signal-level events tied to a specific recording.

by_analysis_type(analysis_type) classmethod

Given an analysis type, return the list of event labels that are relevant to the analysis.

Parameters:

Name	Type	Description	Default
analysis_type	AnalysisType	The analysis type.	required

Returns:

Type	Description
list[EventLabel]	The list of relevant event labels.

Examples:

>>> from yousleep_common.types import AnalysisType
>>> EventLabel.by_analysis_type(AnalysisType.STAGING)
[<EventLabel.SLEEP_STAGE_W: 'Sleep stage W'>, ...]

from_string(event) classmethod

Return the EventType based on the string representation.

If the string does not match any EventLabel, returns EventLabel.UNKNOWN.

Parameters:

Name	Type	Description	Default
event	str	The event string representation.	required

Returns:

Type	Description
EventLabel	The EventLabel.

Examples:

>>> EventLabel.from_string("Sleep stage W")
<EventLabel.SLEEP_STAGE_W: 'Sleep stage W'>

FileFormat

Bases: str, Enum

Supported file formats.

from_file_name(fname) classmethod

Return the recording file type based on the file name.

If the file name does not have a recognized extension, raises ValueError.

Parameters:

Name	Type	Description	Default
fname	str | Path	The file name.	required

Returns:

Type	Description
FileFormat	The FileFormat.

Examples:

>>> FileFormat.from_file_name("recording.edf")
<FileFormat.EDF: 'edf'>

FileNames

Bases: str, Enum

Whether a project's recordings keep their file names.

CODED = 'coded' class-attribute instance-attribute

A code replaces the name. The portal makes the codes and a map the user downloads; the SDK takes the code from its caller. The platform keeps no map.

ORIGINAL = 'original' class-attribute instance-attribute

The file's own name reaches the platform.

FileType

Bases: str, Enum

Valid type of upload/input files.

ARCHIVES = 'archives' class-attribute instance-attribute

Archives file containing resampled or otherwise processed recording data.

EVENTS = 'events' class-attribute instance-attribute

Events file containing the event annotations and related information.

LOGS = 'logs' class-attribute instance-attribute

Logs file containing the logs of an analysis.

RECORDING = 'recording' class-attribute instance-attribute

Recording file containing the polysomnography data.

FileUploadState

Bases: str, Enum

State of a file upload.

FAILED = 'failed' class-attribute instance-attribute

The file upload has failed.

REGISTERED = 'registered' class-attribute instance-attribute

The file upload is registered but not yet started.

REJECTED = 'rejected' class-attribute instance-attribute

The file upload has been rejected, e.g., because the file format or content is invalid.

UPLOADED = 'uploaded' class-attribute instance-attribute

The file has been successfully uploaded.

GrantOrigin

Bases: str, Enum

How a grant came about.

HeartbeatAnswer

Bases: str, Enum

What a runner does next with a lease it reported.

InvitationStatus

Bases: str, Enum

Where an organisation invitation stands.

Only pending invitations can be accepted. An expired invitation is kept briefly so the inviter can see it lapsed; a revoked one is withdrawn by an organisation admin; an accepted one has become a membership.

JobEnd

Bases: str, Enum

How a leased job ended, as its runner reports it.

LeaseKind

Bases: str, Enum

What a lease asks a runner to do.

LeasePhase

Bases: str, Enum

Where a held lease is, as its runner reports it.

MatchModes

Bases: Enum

An enum for different filter match modes.

EXCLUDE = 'exclude' class-attribute instance-attribute

Exclude the events that matches the filter.

INCLUDE = 'include' class-attribute instance-attribute

Include the events that matches the filter.

MembershipRole

Bases: str, Enum

A member's role within an organization (intra-org RBAC).

MetadataType

Bases: str, Enum

Metadata types.

AGE = 'age' class-attribute instance-attribute

Age of the subject in years.

BMI = 'bmi' class-attribute instance-attribute

Body mass index of the subject.

SEX = 'sex' class-attribute instance-attribute

The sex of the subject.

Permission

Bases: str, Enum

A permission string, resource:action.

Two shapes, one rule — an account either holds a permission or it does not:

• Actions on a resource you operate on: create, read, update, delete, and all as the wildcard that implies the other four (project:read, recording:create). A resource may carry only the actions that mean something for it (api_key:create: listing and revoking your own keys is account management).
• A capability flag: a resource with the single action enabled (recording_download:enabled). Holding it grants the capability; not holding it is the only "off" there is. A stored "disabled" state would be a second source that the guard never reads.

action property

Get the action of the permission.

description property

Get the description of the permission.

resource property

Get the resource of the permission.

as_tuple()

Split the permission into resource and action.

with_action(action)

Return a new permission with the same resource but a different action.

PhysicalDimension

Bases: str, Enum

Represents the physical dimension of a signal (EDF+ labels).

References

See https://www.edfplus.info/specs/edftexts.html

infer_from_string(dimension_str, exact_edf_label_only=True) classmethod

Infer the PhysicalDimension from a string.

If the string does not match any known PhysicalDimensions, return PhysicalDimension.UNKNOWN.

Parameters:

Name	Type	Description	Default
dimension_str	str	The string to infer the PhysicalDimension from.	required
exact_edf_label_only	bool	If True, only use the EDF+ label to infer the PhysicalDimension. If False, uses a normalization map to infer the PhysicalDimension from the string.	True

Returns:

Type	Description
PhysicalDimension	The inferred PhysicalDimension.

Examples:

>>> PhysicalDimension.infer_from_string("uV")
<PhysicalDimension.MICROVOLT: 'uV'>

PlatformControlName

Bases: str, Enum

The operator controls an admin can override at runtime.

A control is a platform-wide switch whose configured value an operator can temporarily override — an incident response, never a permanent setting. Each member names one such switch.

API_KEYS = 'api_keys' class-attribute instance-attribute

Whether API keys authenticate requests and may be created.

REGISTRATION = 'registration' class-attribute instance-attribute

Whether self-registration is open.

SUBMISSIONS = 'submissions' class-attribute instance-attribute

Whether analyses may be submitted — single, batch and selector alike.

UPLOADS = 'uploads' class-attribute instance-attribute

Whether recordings may be registered for upload.

PlatformReach

Bases: str, Enum

Whether the platform could reach an organisation's bucket.

RecordingDates

Bases: str, Enum

Whether a project's recordings keep their start dates.

REAL = 'real' class-attribute instance-attribute

The start date stays, in the EDF header and on the platform.

REMOVED = 'removed' class-attribute instance-attribute

The start date becomes EDF+'s unknown date before a recording leaves the user's computer; the time of day stays. Calendar-axis longitudinal reports, sorting and grouping studies by date, and matching to clinic records by date are lost.

RegistrationRejectionReason

Bases: str, Enum

Why an access request was declined, in words the applicant is sent.

A fixed list rather than free text, for three reasons. An applicant who is told nothing writes to support, so saying something costs less than saying nothing. A reason written quickly to explain a decision to a colleague becomes an external statement about a named person the moment it is sent. And consistency is impossible to keep by hand across reviewers and over time.

The split that matters is whether the applicant can do anything about it. Three of these invite a fresh application; the rest do not, and say so rather than implying a route that is not there.

AFFILIATION_UNCLEAR = 'affiliation_unclear' class-attribute instance-attribute

We could not establish the applicant's institution. Fixable.

IDENTITY_UNVERIFIED = 'identity_unverified' class-attribute instance-attribute

The address could not be tied to the person or institution. Fixable.

NOT_ELIGIBLE = 'not_eligible' class-attribute instance-attribute

Declined, with no detail given.

For a request that should not be taught how to pass. Carries no explanation to the applicant by design, and the reviewer's own note stays in the audit record.

NO_CAPACITY = 'no_capacity' class-attribute instance-attribute

The platform cannot take more accounts at present.

PURPOSE_UNCLEAR = 'purpose_unclear' class-attribute instance-attribute

We could not tell what the account would be used for. Fixable.

USAGE_TYPE_NOT_AVAILABLE = 'usage_type_not_available' class-attribute instance-attribute

The usage the request describes is not one the platform offers yet.

is_fixable property

Whether a fresh application could succeed.

ResultDecision

Bases: str, Enum

The platform's answer to a posted result.

ReturnReason

Bases: str, Enum

Why a runner gave a lease back without a result.

counts_against_runner property

Whether the reason suggests a fault on the runner's host.

Role

Bases: str, Enum

A user's authorization role.

ADMIN = 'admin' class-attribute instance-attribute

Platform administrator.

USER = 'user' class-attribute instance-attribute

Regular user — the default.

RunPlace

Bases: str, Enum

Where an analysis runs.

RunnerState

Bases: str, Enum

Whether a runner may lease work.

Sex

Bases: StrEnum

Enum for sex.

SignalQualityScoreMethod

Bases: Enum

Signal quality score methods enum.

SIGNAL_QUALITY_SCORE = 'signal_quality_score' class-attribute instance-attribute

Signal quality score method.

SignalQualityScoreMode

Bases: Enum

Signal quality score modes enum.

GLOBAL = 'global' class-attribute instance-attribute

Global signal quality score mode.

PER_EPOCH = 'per_epoch' class-attribute instance-attribute

Per epoch signal quality score mode.

SignaturePurpose

Bases: str, Enum

What a URL signed for an organisation's bucket is for: the act it serves.

The act is what is recorded, never the URL; the purpose decides what the bucket may sign while its organisation's site storage is off.

SiteCapability

Bases: str, Enum

A capability an organisation may hold on its own hardware.

SleepStageGroup

Bases: str, Enum

The five clinical stage groups every scored staging label folds into.

Scientific semantics, defined once: the api-server's biomarker stage sets and hypnogram lanes, and any other consumer, derive from this map instead of re-encoding which raw label means N3 (the R&K "Sleep stage 3/4" folding lives here and nowhere else).

SpendClass

Bases: str, Enum

Which balance pays for an analysis, decided by the analysis's licence.

An analysis offered under a non-commercial licence is a research analysis and is paid from grants; one offered under the commercial licence is paid from purchased credits. Decided once when the analysis is submitted.

bucket property

The balance this class of analysis is paid from.

of_licence(licence_type) classmethod

Return the spend class of an analysis offered under licence_type.

StudyEventOrigin

Bases: str, Enum

Origin of a study-level event.

EDF_ANNOTATION = 'edf_annotation' class-attribute instance-attribute

Parsed from an EDF+ annotation signal.

MANUAL = 'manual' class-attribute instance-attribute

Created via the REST API by a user.

UsageType

Bases: str, Enum

The primary way a user intends to use the platform.

Captured at registration to help vet request-access applicants and to seed the user's licence: RESEARCH is non-commercial research, under the non-commercial licence; COMMERCIAL and CLINICAL fall under the commercial licence. CLINICAL is defined for forward compatibility but is not an allowed selection yet — the api-server rejects it and the frontend greys it out (no clinical licence exists). Which values are currently selectable is server policy, not part of this enum.

Visibility

Bases: str, Enum

Who can access a project (and the resources under it).

WindowFilterModes

Bases: Enum

An enum for different window filter match modes.

Modes:

• START: Match events that start after the window start time and before the window end time if provided. Does not enforce events to stop before the window end time. If no end time is provided, the window is considered open-ended (ending at time +infinity).

  For example: | ----------------- window ----------------- | | -- event -- || -- event -- | | -- event -- | | -- event -- | EXCL. INCL. INCL. EXCL.

• END: Match events that end before the window end time and after the window start time if provided. Does not enforce events to start after the window start time. If no start time is provided, the window is considered open-ended (starting at time 0).

  For example: | ----------------- window ----------------- | | -- event -- || -- event -- | | -- event -- | | -- event -- | INCL. INCL. EXCL. EXCL.

• CONTAIN: Match events that are fully contained within the [start, end] time window. If either start or end time is not provided, the window is considered open-ended in that direction (0/+infinity)

  For example: | ----------------- window ----------------- | | -- event -- || -- event -- | | -- event -- | | -- event -- | EXCL. INCL. EXCL. EXCL.

• CLIP: Match events overlapping the window at all, and return them truncated to the window. Unlike the other modes, which only select, this one also modifies the returned times: an event straddling a boundary comes back with the outside part removed, so reported durations sum to at most the window's width. Both start and end times are required.

  For example: | ----------------- window ----------------- | | -- event -- || -- event -- | | -- event -- | | -- event -- | INCL.(cut) INCL. INCL.(cut) EXCL.