Skip to content

metadata

Analysis identification, purpose, and evidence metadata models.

AnalysisCredit pydantic-model

Bases: BaseModel

Who to credit for an analysis's results, and what to cite.

Derived from the configuration's provenance and evidence, so every place a result is shown or exported credits it the same way: the developer, with "packaged by youSleep" for an analysis developed elsewhere, and the publications to cite: by default those the developer wrote (Publication.cite). Other publications are evidence about the analysis, not what its users cite.

Config:

  • frozen: True

Fields:

citations pydantic-field

What to cite when using the analysis's results: by default the developer's own publications. Empty when there is none to cite.

developed_by pydantic-field

Who developed the analysis, as its results credit it: the developer, followed by '; packaged by youSleep' for an analysis developed elsewhere.

source_licence = None pydantic-field

That source's software licence, as an SPDX identifier.

source_url = None pydantic-field

Where an analysis developed elsewhere is published; null for youSleep's own.

of(provenance, evidence) classmethod

Return the credit a configuration's provenance and evidence give its results.

DataRights pydantic-model

Bases: BaseModel

On what basis an analysis may be offered under its licence class.

pending: the configuration validates, the conformance check runs, and the platform may offer the analysis privately to one organisation, but never publishes it. declaration names the signed Analysis Declaration that publication rests on.

Config:

  • frozen: True

Fields:

Validators:

basis pydantic-field

'pending' while developing; 'declaration' once the developer's signed Analysis Declaration is on record, referenced in 'declaration'.

declaration = None pydantic-field

The signed declaration's record and what it says. Required when the basis is 'declaration', absent otherwise.

declaration_goes_with_its_basis() pydantic-validator

Require the record with a declaration basis and refuse one with a pending basis.

Declaration pydantic-model

Bases: BaseModel

The signed Analysis Declaration a third-party analysis rests on.

The developer fills in and signs the platform's Analysis Declaration form (what the analysis is, what data it was developed on and under which terms, for which use it may be offered, how to credit it). The signed record is kept by youSleep in the records repository; this block says where, and restates the two facts the platform acts on so they can be checked against the configuration without reading the document.

Config:

  • frozen: True

Fields:

commit pydantic-field

The commit of that repository holding this version of the record.

offer pydantic-field

What the form's section 3 ticked: research and other non-commercial use only, or commercial use too. A commercial licence class needs 'commercial'.

record pydantic-field

Path of the signed declaration (a PDF) in the records repository.

repository = 'yousleep-ai/quality' pydantic-field

The repository that keeps the record.

sha256 pydantic-field

SHA-256 of the record file, so the reference cannot drift.

signatory pydantic-field

The name on the signed form.

signed_on pydantic-field

The date on the signed form.

Evidence pydantic-model

Bases: BaseModel

The published work a configuration cites for its analysis.

A citation list, not a census: it holds what the configuration chose to cite, and there may be further work that is not listed, not known here, or deliberately left out. Read a count off it as a floor — at least this many — never as a total, and present it that way.

Fields:

publications pydantic-field

What the analysis cites. Empty is allowed and is shown as such.

Identification pydantic-model

Bases: BaseModel

Analysis identification information.

Config:

  • frozen: True

Fields:

Validators:

  • _derive_id_from_name

family = None pydantic-field

The family the analysis belongs to: the versions and variants of one method share it (e.g. 'U-Sleep'), so clients can group and filter by it. Unset, the analysis is a family of its own, named by its name.

family_name property

The family to group the analysis under: its own name when it sets none.

id pydantic-field

The machine-readable identifier: one lineage of comparable results, never changed once registered. Derived from the name when omitted (lower case, spaces as hyphens); set it explicitly only to keep an existing id when the name changes.

Provenance pydantic-model

Bases: BaseModel

Who developed the analysis, and what youSleep claims about it.

A catalogue that lists what youSleep built beside what youSleep merely runs owes the reader the difference, and this is where it is stated rather than inferred from the absence of something else. Every field here is a fact about where the analysis came from; what is known about how it performs is evidence, and whether it carries a regulatory claim is neither.

For software developed elsewhere the upstream repository and its licence travel with the configuration. The attribution that licence requires is then rendered from the configuration that is actually deployed, and cannot drift from it.

Config:

  • frozen: True

Fields:

Validators:

data_rights = None pydantic-field

On what basis the analysis may be offered under the licence class in 'licence': 'pending' while developing, or the developer's signed Analysis Declaration once it is on record. Required for a third-party analysis; the platform publishes one only with a declaration.

developer pydantic-field

The name to credit as the developer — an organisation, or the authors of the upstream software.

origin pydantic-field

Who developed the analysis: 'yousleep' for an analysis youSleep developed, 'third-party' for software developed elsewhere that youSleep packages and operates.

source_licence = None pydantic-field

The licence the source is published under, as an SPDX identifier (e.g. 'BSD-3-Clause'). This is the licence of the software itself, which is not the licence the platform grants for running it on the platform — that is 'licence'. Required for a third-party analysis.

source_url = None pydantic-field

Where the analysis' source is published. Required for a third-party analysis: its licence is a licence on that source, and a reader cannot check either without the location.

source_version = None pydantic-field

The upstream version this analysis runs, as its developers name it, with the version of any trained model when that is separate (e.g. 'YASA 0.7.0, classifiers 0.5.0'). Shown on the analysis page. A change here within one analysis id must leave its results comparable; otherwise it is a new id.

third_party_names_its_source() pydantic-validator

Require a third-party analysis to name its source, its licence and its data rights.

Publication pydantic-model

Bases: BaseModel

Represents information on a publication.

The optional fields are left out of the dump when unset: a configuration's hash is that of its dump, and a field it does not use must not change it.

Fields:

by pydantic-field

Who produced this evidence, relative to the analysis' developer: 'developer' for work by the people who wrote the analysis, 'independent' for an evaluation by anyone else. This is a statement about authorship, not about quality — nothing here grades a study.

cite = None pydantic-field

Whether someone using the analysis should cite this publication. Unset, the developer's own publications are cited and independent ones are not; set it to false for the developer's own evaluation, which is evidence about the analysis rather than the work to cite, or to true for an independent publication that must be cited.

cited property

Whether a user of the analysis should cite this publication.

name pydantic-field

Short display name of the publication.

summary = None pydantic-field

One line on who or what was studied and what was found, as the publication reports it. A description, not an endorsement.

title pydantic-field

The title of the publication.

url pydantic-field

Persistent (e.g., doi) URL of the publication.

venue = None pydantic-field

Where it was published: the journal or proceedings.

year = None pydantic-field

The year of publication.

Purpose pydantic-model

Bases: BaseModel

Describes the analysis' type/outputs and purpose.

Fields:

analysis_types pydantic-field

The type(s) of analysis/anlyses (e.g., 'STAGING') that the analysis supports.

description pydantic-field

A brief description of the analysis.

tags pydantic-field

Optional free-form tags for categorising/sorting the analysis in clients (e.g. 'example' to mark demo configs, which clients sort last and badge).