Starting a project

yousleep-init writes an analysis project that passes the conformance check as generated. The first change you make is to the method, not to the packaging.

pip install yousleep-common
yousleep-init my-analysis
cd my-analysis
make verify

In a terminal the command asks for each value, with a default that Enter accepts; the defaults come from the directory name and your git configuration where they can. Outside a terminal, or with --no-input, it takes the flags and the defaults, so it scripts. Every question has a flag.

What it writes

File	Purpose
analysis.py	A complete script: reads the manifest, selects the channels by index, writes an events document. It scores every window with a placeholder label; replace that loop with your method and keep the rest
Dockerfile, requirements.txt	Build the image. yousleep-common and mne are pinned to exact versions, so the image is reproducible, and imported once installed, so a missing system library fails the build rather than the first run; add each module you add to the import
<slug>.yaml	The configuration the platform reads, every block present and commented
Makefile	make verify, make run RECORDING=night.edf, make record, make check
conformance/	Where make record stores the expected output that later runs are compared with
README.md, .gitignore, .dockerignore	The usual. Recordings (*.edf) are kept out of git and out of the image's build context

The directory becomes a git repository unless --no-git is given or it is already inside one.

What it asks

Question	Flag	Default
Name of the analysis	--name	From the directory name
One-line description	--description	A placeholder
Analysis type	--analysis-type	staging
Developed by	--origin	third-party
Developer to credit	--developer	Your git user name
Where the source is published	--source-url	A placeholder URL (third-party only)
Its licence, as an SPDX identifier	--source-licence	MIT (third-party only)
Licence class it is offered under	--licence	non-commercial (or commercial)
Image name, without a tag	--image	ghcr.io/example/<slug>
Channel type it reads, how many, and the lowest sampling rate	--channel TYPE[:MIN-MAX][@HZ], repeatable; MIN 0 makes the type optional	EEG:1-8@100
Another channel type?	a further --channel	no

A flag answers its question without a prompt. Every value can be changed in the configuration afterwards; make check validates the file.

yousleep-init night-scorer --no-input \
    --name "Night Scorer" --analysis-type staging \
    --developer "Sleep Lab" --source-url https://github.com/sleep-lab/night-scorer \
    --image ghcr.io/sleep-lab/night-scorer --channel EEG:1-4 --channel EOG:2@50

A third-party project starts with data_rights: basis: pending, which lets you build, verify and use the analysis privately. Publishing it to every user needs the developer's signed Analysis Declaration on record, referenced as basis: declaration; the packaging guide shows the block.

What it does not ask

The command asks for what shapes the generated files. Everything else has a working default in the configuration, commented where it is, because editing a line there is quicker than answering a question and the answer is rarely known before the method exists:

• Resources. One core and 512 MiB. Once the method runs, set the base from the peak memory make verify reports. The terms that scale with recording length are measured with yousleep-verify --meter and set at registration.
• Output labels. One placeholder label from the analysis type's family, written by the generated script. Declare the labels your method produces under outputs.events; the labels check reports one the file does not declare.
• Parameters. One worked example, window-ms, read by the script. Add yours to parameters.custom and read them from manifest.parameters.
• Named channels, slots and derivations. --channel declares channel types with a count. A method that needs particular channels names them under channels instead; one that needs labelled positions declares slots. A derivation the file does not carry is prepared before upload; the platform never asks an analysis to derive a channel.

The Makefile targets

Target	What it does
make verify	Builds the image and runs yousleep-verify on it. When conformance/expected-events.json.gz exists, the output is compared with it
make run RECORDING=night.edf	Writes the manifest for a recording of yours with yousleep-manifest and runs the image on it, without network access, as the platform does. The events document lands in output-events.json.gz. The channels are the ones the platform would select; CHANNELS="EEG Fpz-Cz,EOG horizontal" chooses them by header label instead, and MANIFEST_ARGS="--age 40 --sex female" passes further yousleep-manifest flags
make record	Records the current output as the expected document. Re-run it when the analysis changes on purpose
make check	Validates the configuration without running anything

The targets run the tools the way yousleep-init itself was run, which the Makefile records at its top: uv run in a checkout, uvx pinned to the release, or the interpreter that has the package. In a clone on another machine they fall back to yousleep-verify on the PATH (a deliberate install, pipx or uv tool), to python3 or python with the package, then to uvx pinned to the version requirements.txt pins, which fetches it on demand. Every run says which one it uses and at which version, and notes when that differs from the pin, with the command that runs the pinned version. Override with make VERIFY="..." MANIFEST="..." verify.

What matters for a correct check is the version of the tools, not the environment: the check runs your image in docker, so the environment only decides which version of the checks and of the configuration model runs. The platform team registers with the current release; the version line and the note are there so that a difference is seen, not guessed.

Working on it

1. Run make verify once. It passes on the generated project.
2. Replace the loop that builds events in analysis.py with your method. Keep select_channels: it is what makes a wrong file fail before it is analysed.
3. Add your dependencies to requirements.txt, pinned. Anything the method downloads at run time, model weights in particular, goes into the image.
4. Adjust the configuration: the channels the method needs, the labels it produces, its parameters. make check reports what is wrong in the file's own terms.
5. make run on a recording of yours, then make record and commit the expected document.
6. When make verify passes on the final image, register it.

Converting an existing script

Run yousleep-init for the packaging and move the method in. The packaging guide lists the four things a working script changes: where paths come from, how channels are selected, how parameters arrive and what is written.

Why a standard layout

An analysis built this way arrives with the files registration needs, in the places the platform team expects them, checked by the same tool they run. That is quicker to review and register than a layout of its own. Nothing requires it: an image in any language that follows the contract is registered the same way.