yasa.SleepStatsAgreement.report#

SleepStatsAgreement.report(bias_method='auto', loa_method='auto', ci_method='auto', decimals=2, sleep_stats=None)[source]#

Return a human-readable DataFrame for reporting bias, limits of agreement, and statistical assumption results, following the reporting format proposed by Menghini et al. (2021).

Each row corresponds to one sleep statistic, labelled with its unit (e.g. "TST (min)"). Reference and observed scorer means (SD) are shown first, followed by bias and LoA, optionally merged with their confidence intervals (e.g. "2.34 [1.10, 3.58]"). An "Assumptions" column shows whether each statistical assumption was met ("✓") or not met ("✗"), which drives the automatic method selection.

Parameters:
bias_methodstr

If 'param' (parametric), bias is always the mean difference. If 'regr' (regression), bias is always a regression equation. If 'auto' (default), the method is chosen per statistic based on the proportional-bias assumption test.

loa_methodstr

Method used to compute limits of agreement. Options:

  • 'param' — constant LoA: bias ± 1.96 SD. Always uses this form regardless of assumptions or log_transform. When the bias is a regression line, the LoA run parallel to it at ± 1.96 SD of its residuals (Menghini et al. 2021, eq. 2) and are reported as "bias ± halfwidth".

  • 'regr' — regression LoA: bias ± 2.46 (c0 + c1 × ref), where c0 + c1 × ref models the absolute residuals of the bias. Always uses this form regardless of assumptions or log_transform.

  • 'log' — Euser LoA: bias ± slope × ref. Requires log_transform=True and no zero values; raises ValueError otherwise.

  • 'auto' (default) — uses 'log' for the log-transformed statistics (see log_transform). Otherwise, uses 'param' when the homoscedasticity assumption passes and 'regr' when it fails.

ci_methodstr or None

If 'param', parametric t-distribution CIs are used. If 'boot', bootstrap CIs are used (BCa by default, see bootstrap_kwargs). If 'auto' (default), the method is chosen per statistic based on the normality assumption test. If None, no confidence intervals are computed or shown (the columns are then named "Bias" and "LoA").

decimalsint

Number of decimal places. Default is 2.

sleep_statslist or None

List of sleep statistics to include, in the desired row order. Default (None) is to include all sleep statistics.

Added in version 0.8.0.

Returns:
reportpandas.DataFrame

A DataFrame indexed by "sleep_stat (unit)" with columns:

  • f"{ref_scorer} mean (SD)" — mean (SD) of the reference scorer values.

  • f"{obs_scorer} mean (SD)" — mean (SD) of the observed scorer values.

  • f"Bias [{pct}% CI]" (or "Bias") — mean bias or regression equation.

  • f"LoA [{pct}% CI]" (or "LoA") — lower–upper LoA, regression equation, or Euser proportional LoA.

  • "Assumptions" — pass/fail for the normal, constant bias and homoscedastic assumptions that drive the automatic method selection.

Examples

>>> import yasa
>>> ref_hyps = [yasa.simulate_hypnogram(tib=480, scorer="PSG", seed=i) for i in range(20)]
>>> obs_hyps = [h.simulate_similar(scorer="Device", seed=i) for i, h in enumerate(ref_hyps)]
>>> sstats = yasa.EpochByEpochAgreement(ref_hyps, obs_hyps).get_sleep_stats()
>>> ssa = yasa.SleepStatsAgreement(sstats)
>>> ssa.report(
...     sleep_stats=["TST", "WASO", "SE"],
...     bias_method="param",
...     loa_method="param",
...     ci_method=None,
...     decimals=1,
... ).drop(columns="Assumptions")
On this page