Tsibble interoperability

Ingesting a tsibble with ild_prepare()

Pass a tbl_ts to ild_prepare() in either of these ways:

1. Omit id and time — tidyILD infers the subject column from the tsibble key (exactly one key column) and the time column from the index.
2. Supply id and time — names must match the key and index columns; the input must still be a tbl_ts.

The tbl_ts class is not kept on the result: the prepared object is a tibble with ILD structure (.ild_* columns, etc.). Tsibble-specific information is copied into the tidyILD attribute before coercion.

suppressPackageStartupMessages({
  library(tidyILD)
  library(tsibble)
})
t <- seq.POSIXt(as.POSIXct("2020-01-01", tz = "UTC"), by = "hour", length.out = 4)
d <- tsibble(
  id = rep(1L, 4),
  t = t,
  y = 1:4,
  key = id,
  index = t
)
x <- ild_prepare(d)
class(x)
#> [1] "tidyild_df" "ild_tbl"    "tbl_df"     "tbl"        "data.frame"

What provenance is kept

When the source was a tbl_ts, metadata is stored under attr(x, "tidyILD")$tsibble. The exported reader is ild_tsibble_meta(), which returns NULL if the object was not prepared from a tsibble.

Typical fields include:

• key_vars, index_var — names of the subject and time columns.
• interval_format — human-readable summary of the declared tsibble::interval() (when available).
• is_regular — tsibble’s regularity flag at input time.
• index_type, tsibble_version, source_class — for reporting and reproducibility.

str(ild_tsibble_meta(x), max.level = 1)
#> List of 7
#>  $ source_class   : chr "tbl_ts"
#>  $ key_vars       : chr "id"
#>  $ index_var      : chr "t"
#>  $ interval_format: chr "1h"
#>  $ is_regular     : logi TRUE
#>  $ tsibble_version: chr "1.2.0"
#>  $ index_type     : chr "name"

ild_spacing() may include a tsibble sub-list that bridges the declared tsibble interval/regularity to empirical spacing computed from .ild_dt after ild_prepare() (sorting, duplicate handling, etc.). Declared and empirical summaries can diverge if rows change.

sp <- ild_spacing(x)
names(sp$tsibble)
#> NULL

How to inspect

• ild_tsibble_meta(x) — full tsibble provenance list (or NULL).
• ild_summary(x) — when tsibble metadata exists, the summary includes a tsibble element (same content as ild_tsibble_meta()).
• ild_spacing(x)$tsibble — declared vs empirical spacing bridge (when present).

names(ild_summary(x))
#> [1] "summary"    "n_units"    "n_obs"      "time_range" "spacing"   
#> [6] "n_gaps"     "pct_gap"    "tsibble"
ild_summary(x)$tsibble[c("key_vars", "index_var", "interval_format", "is_regular")]
#> $key_vars
#> [1] "id"
#> 
#> $index_var
#> [1] "t"
#> 
#> $interval_format
#> [1] "1h"
#> 
#> $is_regular
#> [1] TRUE

Round-trip with ild_as_tsibble()

ild_as_tsibble(x) builds a tbl_ts from the prepared tibble using ild_meta() for key and index column names. If ild_tsibble_meta(x) is not NULL, regular is set from the stored is_regular so tsibble::interval() often matches the original for data that was unchanged after ild_prepare().

d2 <- ild_as_tsibble(x)
tsibble::interval(d2)
#> <interval[1]>
#> [1] 1h
identical(tsibble::interval(d), tsibble::interval(d2))
#> [1] TRUE

You can pass extra arguments through to tsibble::as_tsibble() (e.g. override regular).

Limitations and policy

• One-key policy: ild_prepare() accepts a tbl_ts with exactly one key column (the subject id). Multiple keys (e.g. country + person) are not supported; reshape or aggregate first.
• Class is dropped: Output is not a tbl_ts; use ild_as_tsibble() when you need tsibble semantics again.
• Pre- vs post-prepare divergence: Declared interval and regularity describe the input tbl_ts. After ild_prepare(), empirical spacing (gaps, irregularity) comes from .ild_dt. Sorting, duplicate removal, or row drops can make ild_as_tsibble()’s reconstruction not regular even when the source was; in that case a warning may be emitted when reconstructed regularity disagrees with stored provenance.

For normative developer detail, see vignette("developer-contracts", package = "tidyILD") and inst/dev/DEVELOPER_CONTRACTS.md (tsibble section). Related: vignette("ild-decomposition-and-spacing", package = "tidyILD") for spacing tools.