`visualdynamics.plot.chance`¶

chance ¶

One channel of a comparison read as its miss from the target, line by line in decibels, beside what chance alone would put outside its bands.

The question this view answers is whether the lines outside a band are the test or the estimate: an averaged spectrum scatters about its true level by an amount its degrees of freedom set (core.chance), so a few lines outside a narrow band are expected on every average. The plot draws each judged line's (or group's) level over the target in dB, the target at zero, and the warning and abort edges about it. The lines outside are marked, and the legend and the title give each count beside the number chance alone puts there at the comparison's DOF, so a reader of a printed figure can tell the two apart without counting markers.

With lines combined, the groups are drawn over the single lines, which stand back in gray: the chance scatter shrinks in the groups, and an excursion that holds across neighbors survives.

Nothing here is carried by hue alone. The warning edges are dashed and the abort edges solid, each named in the legend. A line outside is marked with a triangle pointing the way it is out, down for under the band and up for over it: hollow outside the warning band, filled outside the abort band.

Functions:

Name	Description
`title_text`	The plot's title: the channel, the DOF it was judged at, and each
`build_chance`	Draw one channel's miss from its target against the bands, with the

Functions:¶

title_text ¶

title_text(result: dict[str, Any], channel: str) -> str

The plot's title: the channel, the DOF it was judged at, and each pair's count beside its expectation, as in '1Z+ at 120 DOF: 5 of 389 lines outside warning, 3.3 by chance; 0 outside abort, 0.00039 by chance'.

Source code in src/visualdynamics/plot/chance.py

def title_text(result: dict[str, Any], channel: str) -> str:
    """The plot's title: the channel, the DOF it was judged at, and each
    pair's count beside its expectation, as in '1Z+ at 120 DOF: 5 of
    389 lines outside warning, 3.3 by chance; 0 outside abort, 0.00039
    by chance'."""
    combine = result['combine']
    if combine == 1:
        head = f'{channel} at {result["dof"]:.4g} DOF'
        unit = 'lines'
    else:
        head = (f'{channel}, {combine} lines combined at '
                f'{result["judged_dof"]:.4g} DOF')
        unit = 'groups'
    parts = []
    for pair in PAIRS:
        if f'{pair}_lines' not in result:
            continue
        count = result[f'{pair}_lines']
        lead = (f'{count} of {result["lines"]} {unit} outside {pair}'
                if not parts else f'{count} outside {pair}')
        parts.append(f'{lead}, '
                     f'{expected_text(result[f"{pair}_expected"])} by chance')
    return f'{head}: ' + ('; '.join(parts) if parts else 'no bands to judge')

build_chance ¶

build_chance(layout: Any, specification: Any, measured: Any, *, channel: str | None = None, combine: int = 1, dof: float | None = None, scale_db: float | None = None, theme: Any = None) -> dict[str, Any]

Draw one channel's miss from its target against the bands, with the lines outside marked, and return the reading (core.chance.compare_chance).

channel is the DOF (or 'response/reference') to draw, the first the two have in common by default. combine, dof and scale_db are compare_chance's; the scale is resolved the way every comparison resolves it when omitted. A pair that cannot be read is refused with the reason as a ValueError, so nothing is drawn that would read as a count.