tsdive.compare ¶

compare(
    archives: Sequence[str | Path],
    before: str,
    after: str,
    *,
    top: int = 10,
    rate_s: int | None = None,
) -> CompareAnalysis

Compare two periods over every single-tag archive of one unit.

Parameters:

Name	Type	Description	Default
`archives`	`Sequence[str \| Path]`	parquet archives carrying `tsdive.meta`.	required
`before`	`str`	`START/END` in ISO 8601 UTC for the earlier period.	required
`after`	`str`	`START/END` in ISO 8601 UTC for the later period.	required
`top`	`int`	rows each rendered table prints before it counts the rest.	`10`
`rate_s`	`int \| None`	grid rate in seconds. Omitted, the rate every archive declares.	`None`

A pair or joint table that cannot be built, for example because an archive declares no sample_rate_s and no rate_s is passed, holds its reason in pairs.reason and joint.reason. The report prints it under the headline, and to_dict()["refused_tables"] maps each refused table to its reason.

Raises:

Type	Description
`ValueError`	malformed periods, overlapping or swapped periods.
`TSDiveError`	any typed refusal that stops the whole comparison; a refusal on one archive stays a row in `tags`.

Examples:

>>> import tsdive
>>> c = tsdive.compare(["data/demo/fic101_demo.parquet", "data/demo/tic101_demo.parquet"],
...                    "2024-03-30T20:00:00Z/2024-03-30T23:00:00Z",  # before
...                    "2024-03-31T04:00:00Z/2024-03-31T06:00:00Z")  # after
>>> c.frame["tag"].tolist()
['demo:TIC101.PV', 'demo:FIC101.PV']
>>> c.frame["spread_ratio"].round(1).tolist()
[6.0, 0.5]
>>> c.to_dict()["refused_tables"]
{}