Skip to contents

Check whether traits and a tree are ready for pigauto

Source: R/check_pigauto.R
check_pigauto.Rd

Inspect declared inputs without constructing a phylogenetic graph or fitting a model. The check is intended to make input problems and likely compute scale visible before calling impute(). Its fingerprint identifies the declared input object for comparison within a workflow; it is not a security hash.

Usage

check_pigauto(
  traits,
  tree,
  species_col = NULL,
  trait_types = NULL,
  multi_proportion_groups = NULL,
  covariates = NULL,
  gnn = FALSE,
  ordinal_levels = NULL
)

Arguments

traits

A data.frame of traits, with row names or a species column.

tree

A phylo tree.

species_col

Optional name of the column in the traits data frame that contains species identities.

trait_types

Optional named type overrides passed to preprocess_traits().

multi_proportion_groups

Optional named composition groups passed to preprocess_traits().

covariates

Optional environmental covariates passed to preprocess_traits(). Non-finite values are an error.

gnn

Whether the planned imputation will use the graph neural network. The default FALSE skips the torch runtime probe, matching impute()'s default. Set TRUE to include the torch runtime in the preflight.

ordinal_levels

Optional named list giving the order of ordinal levels, applied before type detection so the report shows the same types the matching impute() call will use. Invalid declarations are reported as errors rather than thrown. See impute() / read_traits().

Value

A list of class pigauto_check containing a schema version, status, readiness flag, stable input fingerprint, input summaries, and structured messages.

Reading the result

Printing the result shows its status and, when present, up to three message/action pairs. Inspect check$messages for the complete table and follow its action column. The four status values mean:

  • "ready": the implemented checks found no errors or warnings.

  • "ready_with_warnings": review the warnings before deciding to fit.

  • "error": repair the reported problems before calling impute().

  • "not_needed": all matched target cells are observed, so no imputation is needed. Use cross_validate() to assess prediction instead.

check$ready is TRUE for "ready" and "ready_with_warnings": the current input checks found no errors, though warnings may remain. It is FALSE for "error" and "not_needed". Review any warnings and assess whether a model is scientifically suitable for your data separately. Inspect check$species and check$traits to confirm species matching and trait declarations.

Examples

tree <- ape::read.tree(text = "((a:1,b:1):1,c:2);")
traits <- data.frame(x = c(1, NA, 3), row.names = tree$tip.label)
check <- check_pigauto(traits, tree)
check
#> pigauto input check: ready 
check$ready
#> [1] TRUE
check$messages
#> [1] code     field    text     action   severity
#> <0 rows> (or 0-length row.names)

# An input error is returned as a report with a suggested action.
bad_tree <- tree
bad_tree$edge.length <- NULL
check_pigauto(traits, bad_tree)
#> pigauto input check: error 
#>   messages: 1 
#>   - Tree branch lengths are missing or have the wrong length.  Action: Supply one finite length per edge.