API reference

Every public name of tsdive, tsdive.eval and tsdive.switchback, grouped by task, with the first line of its docstring. Each name links to its own page.

The examples on those pages read the demo archives that tsdive demo data writes under data/.

Reading and ingest

Name	Summary
tsdive.ingest	Turn a CSV or parquet export into a tsdive archive.
tsdive.ingest_wide	Turn a wide export, one column per tag, into one archive per tag.
tsdive.ingest_long	Turn a long export, one row per tag and timestamp, into one archive per tag.
tsdive.init_meta	Write one metadata template per tag column of a wide export.
tsdive.init_long_meta	Write one metadata template per tag of a long export, one row per tag and timestamp.
tsdive.init_tag_meta	Write a metadata template for a single-tag export and return its path.
tsdive.read_meta_json	Load a TagMeta from a JSON file.
tsdive.write_tag	Create a single-tag parquet archive at path and return it.
tsdive.write_demo_data	Write the demo archives under directory and return their paths.

Analyses

Name	Summary
tsdive.profile	Profile one window of a single-tag archive.
tsdive.Profile	One archive window, its statistics, and an optional flatline verdict.
tsdive.segment	Segment one window of a single-tag archive into regimes.
tsdive.SegmentAnalysis	One window cut into piecewise-constant segments.
tsdive.screen	Screen one window of a single-tag archive against a baseline.
tsdive.ScreenAnalysis	One screen, whether it used one baseline or one per regime.
tsdive.spc	Chart one window of a single-tag archive against baseline limits.
tsdive.SpcAnalysis	An individuals chart: limits from the baseline, rule hits in the window.
tsdive.mspc	Detect multivariate departures over two or more single-tag archives.
tsdive.MspcAnalysis	PCA T2 and SPE over aligned tags: the model, and the window it graded.
tsdive.compare	Compare two periods over every single-tag archive of one unit.
tsdive.CompareAnalysis	What changed between two periods of one unit, with its report depth.

Switchback

Name	Summary
tsdive.switchback_plan	Plan a balanced random schedule of settings A and B over one window.
tsdive.SwitchbackPlan	A balanced random schedule of settings A and B over one window.
tsdive.switchback_analyze	The difference between settings A and B on target under a verified plan.
tsdive.SwitchbackAnalysis	The difference between settings A and B on one target, under a verified plan.
tsdive.SwitchbackEstimate	One analysis of the target: direct (no covariates) or adjusted.
tsdive.switchback.analyze	The B - A coefficient of y on [1, z] or [1, z, X], its p-value and interval.
tsdive.switchback.cut_blocks	Blocks of length from time 0, K = schedule_blocks(span, length).
tsdive.switchback.design_size	(balanced assignments, enumerated, smallest attainable two-sided p) of K blocks.
tsdive.switchback.lag_response	First-order lag response to the per-sample setting u, starting from 0.
tsdive.switchback.make_design	Observed assignment and reference set, deterministic in seed.
tsdive.switchback.make_plan	The balanced schedule seed draws over start to end.
tsdive.switchback.plan_digest	SHA-256 hex digest of the plan's canonical schedule.
tsdive.switchback.schedule_blocks	K = floor(span / length), less one when it is odd.
tsdive.switchback.setting	Per-sample setting: 1 in B blocks, 0 in A blocks and outside the schedule.
tsdive.switchback.verify_plan	The design the plan's seed draws, after checking the plan against it.
tsdive.switchback.Analysis	One randomization analysis of a target, or the reason it has none.
tsdive.switchback.Blocks	Block of each sample (-1 outside the schedule) and its offset from the block start.
tsdive.switchback.Design	The observed assignment of K blocks and the assignments its p-value reads.
tsdive.switchback.PlannedBlock	One block of the schedule: when it runs, its setting, and when its washout ends.
tsdive.switchback.PowerReadout	Detection rates of the plan's design over a history window where nothing changed.
tsdive.switchback.SwitchbackPlan	A balanced random schedule of settings A and B over one window.
tsdive.switchback.ALPHA	Level of the two-sided randomization test.
tsdive.switchback.COLLINEAR	Refusal reason: the observed assignment lies in the span of the covariates.
tsdive.switchback.EMPTY_BLOCK	Refusal reason: a block with no kept sample.
tsdive.switchback.MIN_ASSIGNMENTS	Fewest balanced assignments a design may have (DesignTooSmall below it).
tsdive.switchback.NO_SPREAD	Refusal reason: the kept target has MAD 0, or the covariates reproduce it.
tsdive.switchback.PERMUTATIONS	Largest reference set enumerated in full.
tsdive.switchback.POWER_DELTAS	Shifts the power readout adds to the B blocks, in sigma (1.4826 MAD of the history).
tsdive.switchback.POWER_DRAWS	Seeded schedules the power readout draws over the history window.
tsdive.switchback.REASONS	Every refusal reason analyze can put in Analysis.reason.
tsdive.switchback.TOO_FEW	Refusal reason: fewer than 30 kept samples.
tsdive.switchback.TOO_MANY_COVARIATES	Refusal reason: more than one covariate per 10 kept samples.

Evaluation

Name	Summary
tsdive.eval.clock_control	Score every window by how far into its own record it sits.
tsdive.eval.conformal_p_values	Conformal p-value of each stream score against its pool, in stream order.
tsdive.eval.far_floor	False-alarm rate of a score that reads nothing, at k baseline windows.
tsdive.eval.fires	True when score is strictly above threshold.
tsdive.eval.group_holdout	Assign whole groups to n_folds folds, balancing strata.
tsdive.eval.martingale_alarm	First index where the log martingale reaches log(1 / delta), else None.
tsdive.eval.mixture_martingale	Natural log of the mean over epsilons of the power martingales.
tsdive.eval.over_floor	How far a measured false-alarm rate sits above far_floor(k_baseline).
tsdive.eval.power_martingale	Natural log of the power martingale prod(epsilon * p ** (epsilon - 1)).
tsdive.eval.ranking_metrics	Score a fold: ROC-AUC, PR-AUC and precision at a recall floor.
tsdive.eval.worst_baseline_threshold	The alarm threshold: the largest score the tool gave a baseline window.
tsdive.eval.GroupLeakage	A holdout group was found on both sides of a split.
tsdive.eval.GroupSplit	A k-fold split in which every group sits entirely inside one fold.
tsdive.eval.RankingMetrics	Threshold-free metrics of a detector's scores against binary labels.

Archive, sampling contract and types

Name	Summary
tsdive.TagStore	Read-only view over root/<source_id>/<point_id>.parquet files.
tsdive.SingleFileStore	Read-only view over one explicit parquet file (no layout assumptions).
tsdive.Window	One tag's samples from start to end and the data physics of the read.
tsdive.Source	A read-only window provider over process time series.
tsdive.TagMeta	Static metadata for one tag.
tsdive.TagIdentity	Immutable archive coordinates of a tag.
tsdive.Role	Control-loop role of a tag. Nullable on TagMeta; populated when known.
tsdive.EngRange	Engineering range as zero/span (the historian's own representation).
tsdive.SamplingContract	Declares how a window's samples were produced.
tsdive.AggregateType	OPC UA Part 13 aggregate flavour, when the source is an aggregate.
tsdive.CalculationBasis	PI AF CalculationBasis values relevant to a window read.
tsdive.RetrievalMode	How raw samples were retrieved from the archive.

Errors

Name	Summary
tsdive.TSDiveError	Base class for every typed refusal raised by tsdive.
tsdive.DesignTooSmall	A switchback schedule has too few blocks for a randomization test.
tsdive.IncomparableSamplingError	Windows produced under different sampling contracts were mixed.
tsdive.IncomparableUnitsError	Two tags' units cannot be compared.
tsdive.InsufficientQuality	A requested statistic has too few GOOD samples to compute.
tsdive.MspcAlignmentError	Multivariate alignment could not be assembled.
tsdive.NarratorUnavailable	LLM narration was requested with no endpoint configured.
tsdive.NonMonotonicIndex	Timestamp index goes backwards.
tsdive.RegimeTooSparse	A regime has too few GOOD samples to support a baseline.
tsdive.ScheduleMismatch	A switchback plan's schedule differs from the one its fields produce.
tsdive.SchemaError	Input violates the mandatory schema.
tsdive.UnresolvedUnitError	A unit string could not be resolved and comparison was attempted.
tsdive.ZeroSpreadBaseline	A baseline whose GOOD values do not spread, so its scale is 0.

Package

Name	Summary
tsdive.__version__	__version__ = '0.10.0'