Chart models: server-computed chart GEOMETRY.
The API computes all layout math (domains, tick positions, normalized
fractions) once; every renderer — the frontend's thin components, the export
pipeline's SVG emitters — draws from the same model. Raw values ride along
for tooltips and data-* attributes; colors are brand token NAMES resolved
by the consumer (CSS custom properties live, tokens.yaml literals in PDFs).
AxisTick
pydantic-model
Bases: BaseModel
One axis tick: value, normalized position, display label.
Fields:
clock_label = None
pydantic-field
Wall-clock display label (e.g. '23:00') for time axes whose producer knows the recording start. None on non-time axes or producers predating the field; consumers offer an Elapsed/Clock toggle when present.
fraction
pydantic-field
Position, 0 (left) … 1 (right).
label
pydantic-field
Display label for the tick.
value
pydantic-field
Tick value in the domain's unit.
BoxplotBoxValues
pydantic-model
Bases: BaseModel
Five-number summary — raw values or normalized fractions.
Fields:
-
min
(float)
-
q1
(float)
-
median
(float)
-
q3
(float)
-
max
(float)
BoxplotModel
pydantic-model
Bases: BaseModel
A horizontal box-and-whisker chart: shared axis + rows.
Fields:
decimals = 1
pydantic-field
Decimal places for 'decimal' formatting; ignored otherwise. Matches the tick precision the producer chose.
domain_max
pydantic-field
Axis maximum, in the axis unit.
domain_min
pydantic-field
Axis minimum, in the axis unit.
rows
pydantic-field
The rows, in display order.
svg = None
pydantic-field
Server-rendered inline SVG of this chart: the one renderer behind live pages and document exports. Colors are CSS custom-property references the page resolves; elements carry stable classes, native
tooltips and data-* attributes so consumers can layer interaction without geometry knowledge. None for producers predating the field — consumers fall back to drawing the geometry themselves.</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.BoxplotModel.ticks" class="doc doc-heading">
<code class="highlight language-python"><span class="n">ticks</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.BoxplotModel.ticks" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>Axis ticks at nice intervals.</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.BoxplotModel.unit_label" class="doc doc-heading">
<code class="highlight language-python"><span class="n">unit_label</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.BoxplotModel.unit_label" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>Axis caption including the unit, e.g. 'Total duration (h)'.</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.BoxplotModel.value_format" class="doc doc-heading">
<code class="highlight language-python"><span class="n">value_format</span> <span class="o">=</span> <span class="s1">'decimal'</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.BoxplotModel.value_format" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>How a consumer renders one of this chart's VALUES as text (tooltips, data labels). The axis ticks are already formatted in <code>ticks[].label</code>; this is the same rule for the numbers between them, so a tooltip cannot contradict the axis above it. 'duration-hours' means values are hours to be shown as a duration ('1h 30m'); 'decimal' means a plain number at <code>decimals</code> places. Defaults to 'decimal' so a producer predating the field is read literally rather than as hours.</p>
</div>
</div>
</div>
</div>
</div>
<div class="doc doc-object doc-class">
<h2 id="yousleep_common.models.charts.BoxplotPoint" class="doc doc-heading">
<code>BoxplotPoint</code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-model"><code>pydantic-model</code></small>
</span>
<a href="#yousleep_common.models.charts.BoxplotPoint" class="headerlink" title="Permanent link">¶</a></h2>
<div class="doc doc-contents ">
<p class="doc doc-class-bases">
Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
<p>One raw observation drawn as a dot, in the axis unit and on the 0…1 domain.</p>
<p>Fields:</p>
<ul>
<li>
<code><a class="autorefs autorefs-internal" title="value
pydantic-field
(yousleep_common.models.charts.BoxplotPoint.value)" href="#yousleep_common.models.charts.BoxplotPoint.value">value</a></code>
(<code><span title="float">float</span></code>)
</li>
<li>
<code><a class="autorefs autorefs-internal" title="fraction
pydantic-field
(yousleep_common.models.charts.BoxplotPoint.fraction)" href="#yousleep_common.models.charts.BoxplotPoint.fraction">fraction</a></code>
(<code><span title="float">float</span></code>)
</li>
<li>
<code><a class="autorefs autorefs-internal" title="label = None
pydantic-field
(yousleep_common.models.charts.BoxplotPoint.label)" href="#yousleep_common.models.charts.BoxplotPoint.label">label</a></code>
(<code><span title="str">str</span> | None</code>)
</li>
</ul>
<div class="doc doc-children">
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.BoxplotPoint.fraction" class="doc doc-heading">
<code class="highlight language-python"><span class="n">fraction</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.BoxplotPoint.fraction" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>The same value on the shared domain.</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.BoxplotPoint.label" class="doc doc-heading">
<code class="highlight language-python"><span class="n">label</span> <span class="o">=</span> <span class="kc">None</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.BoxplotPoint.label" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>Which observation the dot is, for its tooltip — the study, and the subject and visit it belongs to when those are declared. None when the source draws anonymous observations.</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.BoxplotPoint.value" class="doc doc-heading">
<code class="highlight language-python"><span class="n">value</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.BoxplotPoint.value" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>The observation, in the axis unit.</p>
</div>
</div>
</div>
</div>
</div>
<div class="doc doc-object doc-class">
<h2 id="yousleep_common.models.charts.BoxplotRow" class="doc doc-heading">
<code>BoxplotRow</code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-model"><code>pydantic-model</code></small>
</span>
<a href="#yousleep_common.models.charts.BoxplotRow" class="headerlink" title="Permanent link">¶</a></h2>
<div class="doc doc-contents ">
<p class="doc doc-class-bases">
Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
<p>One labelled box-and-whisker row on a shared axis.</p>
<p>Fields:</p>
<ul>
<li>
<code><a class="autorefs autorefs-internal" title="label
pydantic-field
(yousleep_common.models.charts.BoxplotRow.label)" href="#yousleep_common.models.charts.BoxplotRow.label">label</a></code>
(<code><span title="str">str</span></code>)
</li>
<li>
<code><a class="autorefs autorefs-internal" title="values
pydantic-field
(yousleep_common.models.charts.BoxplotRow.values)" href="#yousleep_common.models.charts.BoxplotRow.values">values</a></code>
(<code><a class="autorefs autorefs-internal" title="BoxplotBoxValues
pydantic-model
(yousleep_common.models.charts.BoxplotBoxValues)" href="#yousleep_common.models.charts.BoxplotBoxValues">BoxplotBoxValues</a></code>)
</li>
<li>
<code><a class="autorefs autorefs-internal" title="fractions
pydantic-field
(yousleep_common.models.charts.BoxplotRow.fractions)" href="#yousleep_common.models.charts.BoxplotRow.fractions">fractions</a></code>
(<code><a class="autorefs autorefs-internal" title="BoxplotBoxValues
pydantic-model
(yousleep_common.models.charts.BoxplotBoxValues)" href="#yousleep_common.models.charts.BoxplotBoxValues">BoxplotBoxValues</a></code>)
</li>
<li>
<code><a class="autorefs autorefs-internal" title="n = None
pydantic-field
(yousleep_common.models.charts.BoxplotRow.n)" href="#yousleep_common.models.charts.BoxplotRow.n">n</a></code>
(<code><span title="int">int</span> | None</code>)
</li>
<li>
<code><a class="autorefs autorefs-internal" title="subjects = None
pydantic-field
(yousleep_common.models.charts.BoxplotRow.subjects)" href="#yousleep_common.models.charts.BoxplotRow.subjects">subjects</a></code>
(<code><span title="int">int</span> | None</code>)
</li>
<li>
<code><a class="autorefs autorefs-internal" title="color_token = None
pydantic-field
(yousleep_common.models.charts.BoxplotRow.color_token)" href="#yousleep_common.models.charts.BoxplotRow.color_token">color_token</a></code>
(<code><span title="str">str</span> | None</code>)
</li>
<li>
<code><a class="autorefs autorefs-internal" title="series_key = None
pydantic-field
(yousleep_common.models.charts.BoxplotRow.series_key)" href="#yousleep_common.models.charts.BoxplotRow.series_key">series_key</a></code>
(<code><span title="str">str</span> | None</code>)
</li>
<li>
<code><a class="autorefs autorefs-internal" title="points = None
pydantic-field
(yousleep_common.models.charts.BoxplotRow.points)" href="#yousleep_common.models.charts.BoxplotRow.points">points</a></code>
(<code><span title="list">list</span>[<a class="autorefs autorefs-internal" title="BoxplotPoint
pydantic-model
(yousleep_common.models.charts.BoxplotPoint)" href="#yousleep_common.models.charts.BoxplotPoint">BoxplotPoint</a>] | None</code>)
</li>
</ul>
<p>Validators:</p>
<ul>
<li>
<code><a class="autorefs autorefs-internal" title="validate_fractions_bounded()
pydantic-validator
(yousleep_common.models.charts.BoxplotRow.validate_fractions_bounded)" href="#yousleep_common.models.charts.BoxplotRow.validate_fractions_bounded">validate_fractions_bounded</a></code>
</li>
</ul>
<div class="doc doc-children">
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.BoxplotRow.color_token" class="doc doc-heading">
<code class="highlight language-python"><span class="n">color_token</span> <span class="o">=</span> <span class="kc">None</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.BoxplotRow.color_token" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>Brand color token NAME (e.g. 'primary-600'); consumers resolve it (CSS variable live, tokens.yaml literal in PDFs).</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.BoxplotRow.fractions" class="doc doc-heading">
<code class="highlight language-python"><span class="n">fractions</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.BoxplotRow.fractions" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>The same box mapped to 0…1 on the shared domain.</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.BoxplotRow.label" class="doc doc-heading">
<code class="highlight language-python"><span class="n">label</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.BoxplotRow.label" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>Row label (e.g. an event type).</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.BoxplotRow.n" class="doc doc-heading">
<code class="highlight language-python"><span class="n">n</span> <span class="o">=</span> <span class="kc">None</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.BoxplotRow.n" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>Sample count behind the box.</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.BoxplotRow.points" class="doc doc-heading">
<code class="highlight language-python"><span class="n">points</span> <span class="o">=</span> <span class="kc">None</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.BoxplotRow.points" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>Set when the row has too few observations for a box to mean anything (below the producer's configured minimum): the raw observations, drawn as dots on the shared axis instead of the box. <code>values</code>/<code>fractions</code> still carry the five-number summary of the same observations, so a consumer that ignores this field draws a (degenerate) box rather than nothing.</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.BoxplotRow.series_key" class="doc doc-heading">
<code class="highlight language-python"><span class="n">series_key</span> <span class="o">=</span> <span class="kc">None</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.BoxplotRow.series_key" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>Stable series identifier stamped as a CSS class hook (e.g. group show/hide).</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.BoxplotRow.subjects" class="doc doc-heading">
<code class="highlight language-python"><span class="n">subjects</span> <span class="o">=</span> <span class="kc">None</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.BoxplotRow.subjects" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>Distinct subjects behind the same observations, when the producer knows them and they can differ from <code>n</code> — one person recorded twice in a calendar bin is two observations and one subject. None when subjects are unknown or not meaningful for the row.</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.BoxplotRow.values" class="doc doc-heading">
<code class="highlight language-python"><span class="n">values</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.BoxplotRow.values" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>Raw five-number summary, in the axis unit (tooltips/data-*).</p>
</div>
</div>
<div class="doc doc-object doc-function">
<h3 id="yousleep_common.models.charts.BoxplotRow.validate_fractions_bounded" class="doc doc-heading">
<code class="highlight language-python"><span class="n">validate_fractions_bounded</span><span class="p">()</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-validator"><code>pydantic-validator</code></small>
</span>
<a href="#yousleep_common.models.charts.BoxplotRow.validate_fractions_bounded" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>Fractions must lie on the shared 0…1 domain.</p>
<p><code>values</code> and <code>fractions</code> share a shape but not an invariant — the
bound lives here so a producer whose domain math drifts fails at the
contract, not in a renderer.</p>
</div>
</div>
</div>
</div>
</div>
<div class="doc doc-object doc-class">
<h2 id="yousleep_common.models.charts.HypnogramModel" class="doc doc-heading">
<code>HypnogramModel</code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-model"><code>pydantic-model</code></small>
</span>
<a href="#yousleep_common.models.charts.HypnogramModel" class="headerlink" title="Permanent link">¶</a></h2>
<div class="doc doc-contents ">
<p class="doc doc-class-bases">
Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
<p>A staging hypnogram: stage lanes + step segments over the recording.</p>
<p>Fields:</p>
<ul>
<li>
<code><a class="autorefs autorefs-internal" title="duration_ms
pydantic-field
(yousleep_common.models.charts.HypnogramModel.duration_ms)" href="#yousleep_common.models.charts.HypnogramModel.duration_ms">duration_ms</a></code>
(<code><span title="int">int</span></code>)
</li>
<li>
<code><a class="autorefs autorefs-internal" title="lanes
pydantic-field
(yousleep_common.models.charts.HypnogramModel.lanes)" href="#yousleep_common.models.charts.HypnogramModel.lanes">lanes</a></code>
(<code><span title="list">list</span>[<span title="str">str</span>]</code>)
</li>
<li>
<code><a class="autorefs autorefs-internal" title="segments
pydantic-field
(yousleep_common.models.charts.HypnogramModel.segments)" href="#yousleep_common.models.charts.HypnogramModel.segments">segments</a></code>
(<code><span title="list">list</span>[<a class="autorefs autorefs-internal" title="HypnogramSegment
pydantic-model
(yousleep_common.models.charts.HypnogramSegment)" href="#yousleep_common.models.charts.HypnogramSegment">HypnogramSegment</a>]</code>)
</li>
<li>
<code><a class="autorefs autorefs-internal" title="ticks
pydantic-field
(yousleep_common.models.charts.HypnogramModel.ticks)" href="#yousleep_common.models.charts.HypnogramModel.ticks">ticks</a></code>
(<code><span title="list">list</span>[<a class="autorefs autorefs-internal" title="AxisTick
pydantic-model
(yousleep_common.models.charts.AxisTick)" href="#yousleep_common.models.charts.AxisTick">AxisTick</a>]</code>)
</li>
<li>
<code><span title="yousleep_common.models.charts.HypnogramModel.lights_off_fraction">lights_off_fraction</span></code>
(<code><span title="float">float</span> | None</code>)
</li>
<li>
<code><span title="yousleep_common.models.charts.HypnogramModel.lights_on_fraction">lights_on_fraction</span></code>
(<code><span title="float">float</span> | None</code>)
</li>
<li>
<code><a class="autorefs autorefs-internal" title="svg = None
pydantic-field
(yousleep_common.models.charts.HypnogramModel.svg)" href="#yousleep_common.models.charts.HypnogramModel.svg">svg</a></code>
(<code><span title="str">str</span> | None</code>)
</li>
</ul>
<div class="doc doc-children">
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.HypnogramModel.duration_ms" class="doc doc-heading">
<code class="highlight language-python"><span class="n">duration_ms</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.HypnogramModel.duration_ms" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>Recording length the fractions map over.</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.HypnogramModel.lanes" class="doc doc-heading">
<code class="highlight language-python"><span class="n">lanes</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.HypnogramModel.lanes" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>Stage labels, top lane first.</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.HypnogramModel.segments" class="doc doc-heading">
<code class="highlight language-python"><span class="n">segments</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.HypnogramModel.segments" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>Runs in time order.</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.HypnogramModel.svg" class="doc doc-heading">
<code class="highlight language-python"><span class="n">svg</span> <span class="o">=</span> <span class="kc">None</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.HypnogramModel.svg" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>Server-rendered inline SVG of this hypnogram — same contract as BoxplotModel.svg: CSS-variable colors, stable classes, <title> tooltips, data-* attributes; None for producers predating the field.</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.HypnogramModel.ticks" class="doc doc-heading">
<code class="highlight language-python"><span class="n">ticks</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.HypnogramModel.ticks" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>Time-axis ticks (value in ms).</p>
</div>
</div>
</div>
</div>
</div>
<div class="doc doc-object doc-class">
<h2 id="yousleep_common.models.charts.HypnogramSegment" class="doc doc-heading">
<code>HypnogramSegment</code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-model"><code>pydantic-model</code></small>
</span>
<a href="#yousleep_common.models.charts.HypnogramSegment" class="headerlink" title="Permanent link">¶</a></h2>
<div class="doc doc-contents ">
<p class="doc doc-class-bases">
Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
<p>One constant-stage run of the hypnogram step curve.</p>
<p>Fields:</p>
<ul>
<li>
<code><a class="autorefs autorefs-internal" title="lane
pydantic-field
(yousleep_common.models.charts.HypnogramSegment.lane)" href="#yousleep_common.models.charts.HypnogramSegment.lane">lane</a></code>
(<code><span title="int">int</span></code>)
</li>
<li>
<code><a class="autorefs autorefs-internal" title="label
pydantic-field
(yousleep_common.models.charts.HypnogramSegment.label)" href="#yousleep_common.models.charts.HypnogramSegment.label">label</a></code>
(<code><span title="str">str</span></code>)
</li>
<li>
<code><a class="autorefs autorefs-internal" title="start_ms
pydantic-field
(yousleep_common.models.charts.HypnogramSegment.start_ms)" href="#yousleep_common.models.charts.HypnogramSegment.start_ms">start_ms</a></code>
(<code><span title="int">int</span></code>)
</li>
<li>
<code><a class="autorefs autorefs-internal" title="end_ms
pydantic-field
(yousleep_common.models.charts.HypnogramSegment.end_ms)" href="#yousleep_common.models.charts.HypnogramSegment.end_ms">end_ms</a></code>
(<code><span title="int">int</span></code>)
</li>
<li>
<code><span title="yousleep_common.models.charts.HypnogramSegment.start_fraction">start_fraction</span></code>
(<code><span title="float">float</span></code>)
</li>
<li>
<code><span title="yousleep_common.models.charts.HypnogramSegment.end_fraction">end_fraction</span></code>
(<code><span title="float">float</span></code>)
</li>
</ul>
<div class="doc doc-children">
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.HypnogramSegment.end_ms" class="doc doc-heading">
<code class="highlight language-python"><span class="n">end_ms</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.HypnogramSegment.end_ms" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>Run end, ms from recording start.</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.HypnogramSegment.label" class="doc doc-heading">
<code class="highlight language-python"><span class="n">label</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.HypnogramSegment.label" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>Event label of the run (e.g. 'Sleep stage N2').</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.HypnogramSegment.lane" class="doc doc-heading">
<code class="highlight language-python"><span class="n">lane</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.HypnogramSegment.lane" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>Row index into HypnogramModel.lanes.</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.HypnogramSegment.start_ms" class="doc doc-heading">
<code class="highlight language-python"><span class="n">start_ms</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.HypnogramSegment.start_ms" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>Run start, ms from recording start.</p>
</div>
</div>
</div>
</div>
</div>
<div class="doc doc-object doc-class">
<h2 id="yousleep_common.models.charts.LineChartModel" class="doc doc-heading">
<code>LineChartModel</code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-model"><code>pydantic-model</code></small>
</span>
<a href="#yousleep_common.models.charts.LineChartModel" class="headerlink" title="Permanent link">¶</a></h2>
<div class="doc doc-contents ">
<p class="doc doc-class-bases">
Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
<p>Lines over a shared value axis and a shared, ordered time axis.</p>
<p>Fields:</p>
<ul>
<li>
<code><a class="autorefs autorefs-internal" title="domain_min
pydantic-field
(yousleep_common.models.charts.LineChartModel.domain_min)" href="#yousleep_common.models.charts.LineChartModel.domain_min">domain_min</a></code>
(<code><span title="float">float</span></code>)
</li>
<li>
<code><a class="autorefs autorefs-internal" title="domain_max
pydantic-field
(yousleep_common.models.charts.LineChartModel.domain_max)" href="#yousleep_common.models.charts.LineChartModel.domain_max">domain_max</a></code>
(<code><span title="float">float</span></code>)
</li>
<li>
<code><a class="autorefs autorefs-internal" title="unit_label
pydantic-field
(yousleep_common.models.charts.LineChartModel.unit_label)" href="#yousleep_common.models.charts.LineChartModel.unit_label">unit_label</a></code>
(<code><span title="str">str</span></code>)
</li>
<li>
<code><a class="autorefs autorefs-internal" title="value_format = 'decimal'
pydantic-field
(yousleep_common.models.charts.LineChartModel.value_format)" href="#yousleep_common.models.charts.LineChartModel.value_format">value_format</a></code>
(<code><span title="typing.Literal">Literal</span>['duration-hours', 'decimal']</code>)
</li>
<li>
<code><a class="autorefs autorefs-internal" title="decimals = 1
pydantic-field
(yousleep_common.models.charts.LineChartModel.decimals)" href="#yousleep_common.models.charts.LineChartModel.decimals">decimals</a></code>
(<code><span title="int">int</span></code>)
</li>
<li>
<code><a class="autorefs autorefs-internal" title="ticks
pydantic-field
(yousleep_common.models.charts.LineChartModel.ticks)" href="#yousleep_common.models.charts.LineChartModel.ticks">ticks</a></code>
(<code><span title="list">list</span>[<a class="autorefs autorefs-internal" title="AxisTick
pydantic-model
(yousleep_common.models.charts.AxisTick)" href="#yousleep_common.models.charts.AxisTick">AxisTick</a>]</code>)
</li>
<li>
<code><a class="autorefs autorefs-internal" title="x_ticks
pydantic-field
(yousleep_common.models.charts.LineChartModel.x_ticks)" href="#yousleep_common.models.charts.LineChartModel.x_ticks">x_ticks</a></code>
(<code><span title="list">list</span>[<a class="autorefs autorefs-internal" title="AxisTick
pydantic-model
(yousleep_common.models.charts.AxisTick)" href="#yousleep_common.models.charts.AxisTick">AxisTick</a>]</code>)
</li>
<li>
<code><a class="autorefs autorefs-internal" title="series
pydantic-field
(yousleep_common.models.charts.LineChartModel.series)" href="#yousleep_common.models.charts.LineChartModel.series">series</a></code>
(<code><span title="list">list</span>[<a class="autorefs autorefs-internal" title="LineSeries
pydantic-model
(yousleep_common.models.charts.LineSeries)" href="#yousleep_common.models.charts.LineSeries">LineSeries</a>]</code>)
</li>
<li>
<code><a class="autorefs autorefs-internal" title="svg = None
pydantic-field
(yousleep_common.models.charts.LineChartModel.svg)" href="#yousleep_common.models.charts.LineChartModel.svg">svg</a></code>
(<code><span title="str">str</span> | None</code>)
</li>
</ul>
<div class="doc doc-children">
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.LineChartModel.decimals" class="doc doc-heading">
<code class="highlight language-python"><span class="n">decimals</span> <span class="o">=</span> <span class="mi">1</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.LineChartModel.decimals" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>Decimal places for 'decimal' formatting.</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.LineChartModel.domain_max" class="doc doc-heading">
<code class="highlight language-python"><span class="n">domain_max</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.LineChartModel.domain_max" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>Value-axis maximum, in the axis unit.</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.LineChartModel.domain_min" class="doc doc-heading">
<code class="highlight language-python"><span class="n">domain_min</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.LineChartModel.domain_min" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>Value-axis minimum, in the axis unit.</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.LineChartModel.series" class="doc doc-heading">
<code class="highlight language-python"><span class="n">series</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.LineChartModel.series" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>The lines, in legend order.</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.LineChartModel.svg" class="doc doc-heading">
<code class="highlight language-python"><span class="n">svg</span> <span class="o">=</span> <span class="kc">None</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.LineChartModel.svg" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>Server-rendered inline SVG of this chart, the same renderer behind live pages and document exports. None for producers predating the field.</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.LineChartModel.ticks" class="doc doc-heading">
<code class="highlight language-python"><span class="n">ticks</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.LineChartModel.ticks" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>Value-axis ticks at nice intervals.</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.LineChartModel.unit_label" class="doc doc-heading">
<code class="highlight language-python"><span class="n">unit_label</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.LineChartModel.unit_label" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>Value-axis caption including the unit, e.g. 'TST (min)'.</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.LineChartModel.value_format" class="doc doc-heading">
<code class="highlight language-python"><span class="n">value_format</span> <span class="o">=</span> <span class="s1">'decimal'</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.LineChartModel.value_format" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>How a consumer renders one of this chart's VALUES as text, the same rule the axis ticks already follow.</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.LineChartModel.x_ticks" class="doc doc-heading">
<code class="highlight language-python"><span class="n">x_ticks</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.LineChartModel.x_ticks" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>Time-axis ticks: one per bin, in order, labelled as the bins are. <code>value</code> is the bin's index.</p>
</div>
</div>
</div>
</div>
</div>
<div class="doc doc-object doc-class">
<h2 id="yousleep_common.models.charts.LinePoint" class="doc doc-heading">
<code>LinePoint</code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-model"><code>pydantic-model</code></small>
</span>
<a href="#yousleep_common.models.charts.LinePoint" class="headerlink" title="Permanent link">¶</a></h2>
<div class="doc doc-contents ">
<p class="doc doc-class-bases">
Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
<p>One observation on a line: where it sits on both axes.</p>
<p>Fields:</p>
<ul>
<li>
<code><a class="autorefs autorefs-internal" title="value
pydantic-field
(yousleep_common.models.charts.LinePoint.value)" href="#yousleep_common.models.charts.LinePoint.value">value</a></code>
(<code><span title="float">float</span></code>)
</li>
<li>
<code><a class="autorefs autorefs-internal" title="fraction
pydantic-field
(yousleep_common.models.charts.LinePoint.fraction)" href="#yousleep_common.models.charts.LinePoint.fraction">fraction</a></code>
(<code><span title="float">float</span></code>)
</li>
<li>
<code><a class="autorefs autorefs-internal" title="x_fraction
pydantic-field
(yousleep_common.models.charts.LinePoint.x_fraction)" href="#yousleep_common.models.charts.LinePoint.x_fraction">x_fraction</a></code>
(<code><span title="float">float</span></code>)
</li>
<li>
<code><a class="autorefs autorefs-internal" title="label
pydantic-field
(yousleep_common.models.charts.LinePoint.label)" href="#yousleep_common.models.charts.LinePoint.label">label</a></code>
(<code><span title="str">str</span></code>)
</li>
</ul>
<div class="doc doc-children">
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.LinePoint.fraction" class="doc doc-heading">
<code class="highlight language-python"><span class="n">fraction</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.LinePoint.fraction" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>The value on the shared value domain, 0…1.</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.LinePoint.label" class="doc doc-heading">
<code class="highlight language-python"><span class="n">label</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.LinePoint.label" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>The time bin it belongs to, as drawn.</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.LinePoint.value" class="doc doc-heading">
<code class="highlight language-python"><span class="n">value</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.LinePoint.value" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>The observation, in the axis unit.</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.LinePoint.x_fraction" class="doc doc-heading">
<code class="highlight language-python"><span class="n">x_fraction</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.LinePoint.x_fraction" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>Where along the time axis it sits, 0…1.</p>
</div>
</div>
</div>
</div>
</div>
<div class="doc doc-object doc-class">
<h2 id="yousleep_common.models.charts.LineSeries" class="doc doc-heading">
<code>LineSeries</code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-model"><code>pydantic-model</code></small>
</span>
<a href="#yousleep_common.models.charts.LineSeries" class="headerlink" title="Permanent link">¶</a></h2>
<div class="doc doc-contents ">
<p class="doc doc-class-bases">
Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
<p>One line: a subject's observations in time order.</p>
<p>Fields:</p>
<ul>
<li>
<code><a class="autorefs autorefs-internal" title="key
pydantic-field
(yousleep_common.models.charts.LineSeries.key)" href="#yousleep_common.models.charts.LineSeries.key">key</a></code>
(<code><span title="str">str</span></code>)
</li>
<li>
<code><a class="autorefs autorefs-internal" title="label
pydantic-field
(yousleep_common.models.charts.LineSeries.label)" href="#yousleep_common.models.charts.LineSeries.label">label</a></code>
(<code><span title="str">str</span></code>)
</li>
<li>
<code><a class="autorefs autorefs-internal" title="color_token = None
pydantic-field
(yousleep_common.models.charts.LineSeries.color_token)" href="#yousleep_common.models.charts.LineSeries.color_token">color_token</a></code>
(<code><span title="str">str</span> | None</code>)
</li>
<li>
<code><a class="autorefs autorefs-internal" title="dash = None
pydantic-field
(yousleep_common.models.charts.LineSeries.dash)" href="#yousleep_common.models.charts.LineSeries.dash">dash</a></code>
(<code><span title="str">str</span> | None</code>)
</li>
<li>
<code><a class="autorefs autorefs-internal" title="points
pydantic-field
(yousleep_common.models.charts.LineSeries.points)" href="#yousleep_common.models.charts.LineSeries.points">points</a></code>
(<code><span title="list">list</span>[<a class="autorefs autorefs-internal" title="LinePoint
pydantic-model
(yousleep_common.models.charts.LinePoint)" href="#yousleep_common.models.charts.LinePoint">LinePoint</a>]</code>)
</li>
</ul>
<div class="doc doc-children">
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.LineSeries.color_token" class="doc doc-heading">
<code class="highlight language-python"><span class="n">color_token</span> <span class="o">=</span> <span class="kc">None</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.LineSeries.color_token" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>Brand color token NAME the line uses; consumers resolve it (CSS variable live, tokens.yaml literal in PDFs).</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.LineSeries.dash" class="doc doc-heading">
<code class="highlight language-python"><span class="n">dash</span> <span class="o">=</span> <span class="kc">None</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.LineSeries.dash" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>SVG dash pattern, e.g. '5 3'. Set when lines share a colour because colour carries something else — a group, say — so the stroke still tells them apart on paper, where no tooltip can. None draws a solid line.</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.LineSeries.key" class="doc doc-heading">
<code class="highlight language-python"><span class="n">key</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.LineSeries.key" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>Stable series identity within the chart (a CSS class hook and a client selection key), not display text.</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.LineSeries.label" class="doc doc-heading">
<code class="highlight language-python"><span class="n">label</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.LineSeries.label" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>Legend text, e.g. the subject's key.</p>
</div>
</div>
<div class="doc doc-object doc-attribute">
<h3 id="yousleep_common.models.charts.LineSeries.points" class="doc doc-heading">
<code class="highlight language-python"><span class="n">points</span></code>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-pydantic-field"><code>pydantic-field</code></small>
</span>
<a href="#yousleep_common.models.charts.LineSeries.points" class="headerlink" title="Permanent link">¶</a></h3>
<div class="doc doc-contents ">
<p>The observations in time order. A bin the series has no study in carries no point, so the line breaks rather than interpolating a night that was never recorded.</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</article>
</div>
<script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script>
<script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script>
</div>
<button type="button" class="md-top md-icon" data-md-component="top" hidden>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg>
Back to top
</button>
</main>
<footer class="md-footer">
<div class="md-footer-meta md-typeset">
<div class="md-footer-meta__inner md-grid">
<div class="md-copyright">
Made with
<a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
Material for MkDocs
</a>
</div>
</div>
</div>
</footer>
</div>
<div class="md-dialog" data-md-component="dialog">
<div class="md-dialog__inner md-typeset"></div>
</div>
<div class="md-progress" data-md-component="progress" role="progressbar"></div>
<script id="__config" type="application/json">{"annotate": null, "base": "../../../..", "features": ["navigation.tabs", "navigation.tabs.sticky", "navigation.sections", "navigation.prune", "navigation.top", "navigation.indexes", "navigation.instant", "navigation.instant.progress", "toc.follow", "search.suggest", "search.highlight", "content.code.copy", "content.tabs.link"], "search": "../../../../assets/javascripts/workers/search.2c215733.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": null}</script>
<script src="../../../../assets/javascripts/bundle.d7400e89.min.js"></script>
</body>
</html> 