tsdive.switchback_analyze ¶

switchback_analyze(
    archives: Sequence[str | Path],
    plan: SwitchbackPlan | str | Path,
    *,
    target: str,
    covariates: Sequence[str] = (),
) -> SwitchbackAnalysis

The difference between settings A and B on target under a verified plan.

The plan is checked first: its digest against its blocks, the block times, the balance of the settings, and the settings against the ones its seed draws. The archives are read over the schedule under the sampling contract compare uses, and GOOD numeric samples at least the washout into their block are kept.

Parameters:

Name	Type	Description	Default
`archives`	`Sequence[str \| Path]`	single-tag parquet archives holding the target and every covariate; others are listed as unused.	required
`plan`	`SwitchbackPlan \| str \| Path`	a plan, or the path of a plan file.	required
`target`	`str`	the tag, as `source:point` or a point id that one archive carries.	required
`covariates`	`Sequence[str]`	tags declared before the analysis for the adjusted estimate. Each one's own B - A difference is tested with the same design, and `covariate_checks` flags one the setting moves (p < 0.05), whose adjustment can absorb the difference.	`()`

Raises:

Type	Description
`ScheduleMismatch`	the plan was edited or is not balanced.
`DesignTooSmall`	the plan holds too few blocks.
`ValueError`	a tag that matches no archive or is named twice.
`IncomparableSamplingError`	two reads under different sampling contracts.
`SchemaError`	a covariate repeats a timestamp among its valid samples.
`TSDiveError`	any typed refusal from the read path.

Examples:

>>> import tsdive
>>> plan = tsdive.switchback_plan("2024-06-03T00:00:00Z", "2024-06-04T00:00:00Z",
...                               block="PT1H", washout="PT15M", seed=7)
>>> archives = ["data/switchback_demo/ti201.parquet",
...             "data/switchback_demo/fi200.parquet",
...             "data/switchback_demo/tt001.parquet"]
>>> result = tsdive.switchback_analyze(archives, plan, target="TI201.PV",
...                                    covariates=["FI200.PV", "TT001.PV"])
>>> round(result.direct.estimate, 4), round(result.direct.p_value, 3)
(0.6024, 0.154)
>>> round(result.adjusted.estimate, 4), round(result.adjusted.p_value, 3)
(0.2847, 0.001)
>>> [(check.tag, check.moves) for check in result.covariate_checks]
[('demo:FI200.PV', False), ('demo:TT001.PV', False)]