Skip to content

CLI reference

tsdive switchback plan

Write a balanced random schedule and report it.

The guide walks a trial with it.

Usage

usage: tsdive switchback plan [-h] --window WINDOW --block BLOCK --washout
                              WASHOUT --seed SEED -o PLAN.json
                              [--history PARQUET]
                              [--history-window HISTORY_WINDOW] [--json]
                              [--no-color]

Options

Argument Value Default Description
--window WINDOW required ISO 8601 START/END the schedule runs over; bounds with a UTC offset are converted to UTC
--block BLOCK required block length as an ISO 8601 duration, like PT1H
--washout WASHOUT required time left out at the start of every block, like PT10M; PT0S for none
--seed SEED required seed of the assignment
-o, --out PLAN.json required file the plan is written to; an existing file is refused
--history PARQUET archive of the target where nothing was switched, for the power readout
--history-window HISTORY_WINDOW ISO 8601 START/END of the history, at least as long as the schedule; bounds with a UTC offset are converted to UTC
--json print one JSON object and nothing else
--no-color plain text, no ANSI colour (NO_COLOR does the same)

Example

$ tsdive switchback plan \
    --window "2024-06-03T00:00:00Z/2024-06-04T00:00:00Z" \
    --block PT1H --washout PT15M --seed 7 \
    --history data/switchback_demo/ti201.parquet \
    --history-window "2024-06-02T00:00:00Z/2024-06-03T00:00:00Z" \
    -o data/switchback_demo/plan.json
switchback plan   24 blocks of 1 h   A 12   B 12   digest 66da65ede04f

window    2024-06-03 00:00:00Z -> 2024-06-04 00:00:00Z   (1 d)
schedule  2024-06-03 00:00:00Z -> 2024-06-04 00:00:00Z   seed 7
washout   15 min at the start of every block
design    over 10^6 balanced assignments   1000 drawn   smallest p 0.000999
wrote     data/switchback_demo/plan.json

Schedule  (the plan file lists every block)
     0  2024-06-03 00:00:00Z  A
     1  2024-06-03 01:00:00Z  A
     2  2024-06-03 02:00:00Z  A
     3  2024-06-03 03:00:00Z  B
     4  2024-06-03 04:00:00Z  B
     5  2024-06-03 05:00:00Z  A
     6  2024-06-03 06:00:00Z  B
     7  2024-06-03 07:00:00Z  A
     8  2024-06-03 08:00:00Z  A
     9  2024-06-03 09:00:00Z  B
    10  2024-06-03 10:00:00Z  B
    11  2024-06-03 11:00:00Z  B
    12  2024-06-03 12:00:00Z  B
    13  2024-06-03 13:00:00Z  B
    14  2024-06-03 14:00:00Z  B
    15  2024-06-03 15:00:00Z  A
    16  2024-06-03 16:00:00Z  A
    17  2024-06-03 17:00:00Z  A
    18  2024-06-03 18:00:00Z  A
    19  2024-06-03 19:00:00Z  A
    20  2024-06-03 20:00:00Z  B
[10 more lines not shown]