tsdive.switchback_plan ¶

switchback_plan(
    start: str | Timestamp | datetime,
    end: str | Timestamp | datetime,
    block: str | int | float | timedelta,
    washout: str | int | float | timedelta,
    seed: int,
    *,
    history: str | Path | None = None,
    history_window: str
    | tuple[Timestamp, Timestamp]
    | None = None,
) -> SwitchbackPlan

Plan a balanced random schedule of settings A and B over one window.

The window from start is cut into K blocks of block (the last block is dropped when K is odd), and seed assigns exactly K/2 of them to B. The first washout of every block is left out of the analysis. The same arguments give the same plan and digest.

Parameters:

Name	Type	Description	Default
`start`	`str \| Timestamp \| datetime`	ISO 8601 UTC instant or an aware timestamp.	required
`end`	`str \| Timestamp \| datetime`	ISO 8601 UTC instant or an aware timestamp.	required
`block`	`str \| int \| float \| timedelta`	block length, an ISO 8601 duration such as `PT1H` or seconds; whole seconds only.	required
`washout`	`str \| int \| float \| timedelta`	time dropped at the start of every block, as `block`; 0 or more and shorter than a block.	required
`seed`	`int`	seed of the assignment, 0 or more.	required
`history`	`str \| Path \| None`	one archive of the target where nothing was switched; with `history_window` it adds a power readout.	`None`
`history_window`	`str \| tuple[Timestamp, Timestamp] \| None`	`START/END` in ISO 8601 UTC, or a pair of aware timestamps, at least as long as the schedule.	`None`

Raises:

Type	Description
`ValueError`	a malformed or naive bound, a block or washout out of range, or only one of `history` and `history_window`.
`DesignTooSmall`	the window holds too few blocks for a randomization test at the 5% level.

Examples:

>>> import tsdive
>>> plan = tsdive.switchback_plan("2024-06-03T00:00:00Z", "2024-06-04T00:00:00Z",
...                               block="PT1H", washout="PT15M", seed=7)
>>> plan.k, plan.digest[:12]
(24, '66da65ede04f')
>>> "".join(b.setting for b in plan.blocks)
'AAABBABAABBBBBBAAAAABBAB'
>>> plan.write_json("plan.json").name
'plan.json'