Package 'oda'

Description

Build parent map and endpoint-index map for LORT nodes (internal helper used by lort_index_path and lort_path_table)

Usage

.lort_parent_maps(ort_nodes)

Arguments

Description

Converts the data.frame returned by cta_confusion_table (columns actual, predicted, n) to a 2x2 integer matrix suitable for novo_boot_ci.

Usage

as_confusion_matrix(df)

Arguments

Value

A 2x2 integer matrix with rows = actual class (0/1) and columns = predicted class (0/1), matching the training_confusion convention used throughout oda. Row and column names are "0" and "1".

See Also

cta_confusion_table, novo_boot_ci

Examples

# From raw data frame:
df <- data.frame(
  actual    = c(0L, 0L, 1L, 1L),
  predicted = c(0L, 1L, 0L, 1L),
  n         = c(146L, 40L, 36L, 33L)
)
m <- as_confusion_matrix(df)
novo_boot_ci(m, nboot = 200L, seed = 1L)

# From a fitted tree:

fit <- cta_fit(data.frame(x = seq_len(8L)),
               c(0L, 0L, 0L, 0L, 1L, 1L, 1L, 1L),
               mindenom = 2L, mc_iter = 100L, loo = "off")
ct <- cta_confusion_table(fit)
m  <- as_confusion_matrix(ct)
novo_boot_ci(m, nboot = 200L, seed = 42L)

Description

Returns X restricted to the columns identified by sda_selected_attributes(fit). Intended to produce the constrained candidate frame for cta_fit or cta_descendant_family.

Usage

as_cta_candidates(fit, X)

Arguments

Value

Data frame with columns matching sda_selected_attributes(fit), in SDA step order.

Description

Generic converter. Methods are provided for sda_fit and data.frame. Use sda_anchor for direct construction.

Usage

as_sda_anchor(x, ...)

## S3 method for class 'sda_fit'
as_sda_anchor(x, ...)

## S3 method for class 'data.frame'
as_sda_anchor(
  x,
  selected_attributes,
  candidate_universe = NULL,
  group_levels = NULL,
  canon_notes = c("Explicit / manual anchor - user-declared stage table",
    "Not derived from sda_fit", "This anchor is for future SORT / staged CTA workflows",
    "SORT is not implemented", "GORT is not implemented"),
  ...
)

Arguments

Value

Object of class c("sda_anchor", "list").

See Also

sda_anchor, validate_sda_anchor

Description

Validates and constructs a candidate set for sda_fit without fitting. Returns an auditable plan object that records which columns were accepted, which were excluded and why, and what settings would be passed to sda_fit().

Usage

auto_sda_plan(
  data,
  outcome,
  candidates = NULL,
  exclude = NULL,
  role_map = NULL,
  time_map = NULL,
  stage_map = NULL,
  attr_types = NULL,
  collinearity_threshold = 1,
  min_n = NULL,
  min_class_n = NULL,
  mode = c("unioda_max_ess", "novometric_min_d"),
  dry_run = TRUE
)

Arguments

Details

Agent principle: auto_sda_plan() proposes and validates. It does not silently decide causal validity, temporal ordering, exposure roles, or outcome roles. If temporal or causal structure is required, declare it via role_map, time_map, or stage_map.

Value

Object of class c("auto_sda_plan", "odacore_plan").

Description

Traverses the fitted cta_tree for each row of newdata and returns the terminal leaf reached, expressed as both its stored node identifier (endpoint_node_id) and its sequential endpoint index (endpoint_id) matching cta_endpoint_summary.

No endpoint membership is stored at fit time. This function performs the traversal on demand so the cta_tree object remains lean. The returned endpoint_id can be joined with the output of cta_propensity_weights to assign endpoint-level stabilized weights to individual observations.

Column order requirement: newdata must have the same attribute column order as the X matrix passed to oda_cta_fit. Traversal uses the stored integer column positions (attr_col) from the fit, not column names. If both names(newdata) and tree$attr_names are non-NULL, a warning is issued when they disagree at the split attribute positions.

Missingness:

"na" (default)

Canonical path-local behaviour: when a split attribute value is NA or a stored miss-code on the observation's actual traversal path, the row returns NA for both output columns. This matches the canonical missing_action = "na" semantics of predict.

"majority"

Routes the observation to the child subtree with the larger n_obs, then continues traversal to a terminal leaf. Ties are resolved by selecting the first child.

Usage

cta_assign_endpoints(tree, newdata, missing_action = c("na", "majority"))

Arguments

Details

Observation-level propensity weights (workflow sketch):

ep  <- cta_assign_endpoints(tree, X_train, missing_action = "na")
pw  <- cta_propensity_weights(tree, target_class = 1L, adjusted = TRUE)

# One row per classified training observation with its weight:
obs <- merge(
  data.frame(row_id = seq_len(nrow(X_train)),
             class  = as.character(y_train)),
  merge(ep, pw[, c("endpoint_id", "class", "adjusted_propensity_weight")],
        by = "endpoint_id"),
  by = c("row_id", "class")
)
# Rows with NA endpoint_id (missing root attribute) drop naturally.

Observation-level propensity weight expansion is intentionally left to the caller so that the cta_tree object stores no observation indices.

Value

A data.frame with one row per row of newdata and columns:

row_id

Integer; positional row index in newdata (1 to nrow(newdata)).

endpoint_node_id

Integer; node_id of the terminal leaf reached by traversal. NA_integer_ when the observation cannot be routed to a terminal leaf (missing split attribute with missing_action = "na", or no-tree fit).

endpoint_id

Integer; sequential endpoint index matching cta_endpoint_summary. NA_integer_ under the same conditions as endpoint_node_id.

For no-tree fits all rows have endpoint_node_id = NA_integer_ and endpoint_id = NA_integer_.

See Also

oda_cta_fit, cta_endpoint_summary, cta_propensity_weights, predict.cta_tree

Examples

data(mtcars)
X    <- mtcars[, c("cyl", "disp", "hp", "wt")]
y    <- as.integer(mtcars$am)
tree <- oda_cta_fit(X, y, mindenom = 5L, mc_iter = 500L, mc_seed = 42L)
ep   <- cta_assign_endpoints(tree, X)
head(ep)

Description

Builds one row per analysis scale (multivariate CTA) containing the observed full-tree ESS/WESS, a bootstrap confidence interval, and a chance interval. This is the multivariate analogue of oda_balance_effect_table: a single CTA ENUMERATE run per bootstrap or permutation iteration classifies all covariates jointly.

Usage

cta_balance_effect_summary(
  group,
  X,
  w = NULL,
  compare_weights = FALSE,
  mindenom = 1L,
  nboot = 200L,
  chance_iter = 200L,
  ci = 0.95,
  mc_seed = NULL,
  mc_iter = 5000L,
  ...
)

Arguments

Details

Three passes are run:

1. Observed: full cta_fit() with mc_iter – point estimate and tree metadata.

2. Bootstrap: nboot row-resamples, loo = "off" – ESS/WESS percentile CI. no_tree results contribute 0.

3. Chance: chance_iter group-label permutations – null percentile interval. no_tree results contribute 0.

no_tree convention: when CTA finds no admissible tree on a bootstrap or chance iteration, ESS = 0 (no discrimination above chance). The observed no_tree result is also recorded as estimate = 0.

Value

A list of class "cta_balance_effect_summary" with:

rows

Data frame; one row per analysis scale. Columns: analysis, metric, estimate, boot_lo, boot_hi, chance_lo, chance_hi, d_stat, n_endpoints, root_attribute, status, balance_interpretation.

meta

List: n_obs, has_weights, compare_weights, analyses, mindenom, nboot, chance_iter, ci, mc_iter, mc_seed.

References

Linden A, Yarnold PR (2016). Using machine learning to assess covariate balance in matching studies. Journal of Evaluation in Clinical Practice, 22(6), 861-867.

See Also

cta_balance_table, plot_cta_balance_effects

Examples

X <- data.frame(
  A = c(rep(0L, 20), rep(1L, 20), rep(1L, 20)),
  B = c(rep(0L, 20), rep(0L, 20), rep(1L, 20))
)
group <- c(rep(0L, 40), rep(1L, 20))
ces <- cta_balance_effect_summary(group, X, mindenom = 5L,
                                   mc_iter = 200L, mc_seed = 42L,
                                   nboot = 20L, chance_iter = 20L)
ces$rows[, c("analysis", "estimate", "boot_lo", "boot_hi",
             "chance_lo", "chance_hi", "status")]

Description

Transforms a cta_balance_table result into a renderer-independent data structure suitable for Graphics v3 plotting. For no_tree results, populates no_tree_message with the favorable-balance interpretation.

Usage

cta_balance_plot_data(cta_balance, target_class = 1L, digits = 1L)

Arguments

Details

This function does not fit any CTA models. It is a pure transformation of the pre-computed cta_balance_table result.

Value

A list of class "cta_balance_plot_data" with elements:

status

Character; "valid_tree", "stump", "no_tree", or "fit_error".

balance_interpretation

Character.

no_tree_message

Character; human-readable no-tree annotation for renderers; NA when status is not "no_tree".

cta_pd

List from cta_plot_data when a valid tree or stump was found; NULL for no_tree or fit_error.

ess_display

Numeric; full-tree ESS/WESS (%); NA for no_tree.

d_stat

Numeric; NA for no_tree.

has_weights

Logical.

ess_label

Character; "WESS" or "ESS".

See Also

cta_balance_table, cta_plot_data

Examples

X <- data.frame(
  A = c(rep(0L, 20), rep(1L, 20), rep(1L, 20)),
  B = c(rep(0L, 20), rep(0L, 20), rep(1L, 20))
)
group <- c(rep(0L, 40), rep(1L, 20))
ct  <- cta_balance_table(group, X, mindenom = 5L,
                          mc_iter = 200L, mc_seed = 42L)
cpd <- cta_balance_plot_data(ct)
cpd$status

Description

Fits a single cta_fit model with group as the class variable and all columns of X as candidate predictors. Returns a structured summary of the CTA balance result.

Usage

cta_balance_table(
  group,
  X,
  w = NULL,
  mindenom = 1L,
  alpha = 0.05,
  loo = "off",
  mc_iter = 5000L,
  mc_seed = NULL,
  ...
)

Arguments

Details

A status = "no_tree" result means no combination of baseline covariates in X predicted group membership at the declared significance level, LOO constraint, and minimum endpoint denominator. This is favorable evidence of multivariable covariate balance under the declared analytic constraints. It must not be interpreted as a model failure; in balance analysis, inability to discriminate groups is the goal.

group vs. outcome: group is the binary class variable. The scientific outcome is strictly out of scope.

Implementation constraint: this function calls cta_fit once; it does not reimplement ENUMERATE or node-growth logic.

Value

A list of class "cta_balance_table" with fields:

status

Character: "valid_tree", "stump", "no_tree", or "fit_error".

balance_interpretation

Character: "discriminating" or "no_discriminating_combinations" (when no_tree); NA on fit error.

root_attribute

Character; root split variable name; NA when no_tree.

n_endpoints

Integer; number of terminal endpoints; NA when no_tree.

overall_ess

Numeric; full-tree ESS (%) when weights not active; NA otherwise.

overall_wess

Numeric; full-tree WESS (%) when weights active; NA otherwise.

ess_display

Numeric; operative measure (overall_wess when weights active, else overall_ess); NA for no_tree.

d_stat

Numeric; parsimony-adjusted D statistic; NA for no_tree.

mindenom

Integer; MINDENOM used.

alpha

Numeric; significance threshold stored for downstream use.

has_weights

Logical; whether case weights were active.

tree

The raw cta_tree object; NULL on fit error.

endpoint_table

Data frame from cta_endpoint_table; zero-row for no_tree.

node_table

Data frame from cta_node_table.

fit_error

Logical; TRUE when cta_fit threw.

fit_reason

Character; error message when fit_error; NA otherwise.

References

Linden A, Yarnold PR (2016). Using machine learning to assess covariate balance in matching studies. Journal of Evaluation in Clinical Practice, 22(6), 861-867.

See Also

cta_balance_plot_data, oda_balance_table, cta_fit

Examples

X <- data.frame(
  A = c(rep(0L, 20), rep(1L, 20), rep(1L, 20)),
  B = c(rep(0L, 20), rep(0L, 20), rep(1L, 20))
)
group <- c(rep(0L, 40), rep(1L, 20))
ct <- cta_balance_table(group, X, mindenom = 5L,
                         mc_iter = 200L, mc_seed = 42L)
ct$status
ct$balance_interpretation

Description

Convenience wrapper: returns the 2x2 integer training confusion matrix for a binary oda_cta_fit result directly, without the intermediate tidy long-format step required by cta_confusion_table and as_confusion_matrix.

Usage

cta_confusion_matrix(tree)

Arguments

Details

Rows are actual class (0/1), columns are predicted class (0/1). Returns NULL invisibly when tree$no_tree is TRUE.

Value

A 2x2 integer matrix (actual x predicted) or NULL when no tree was found.

See Also

cta_confusion_table, as_confusion_matrix

Examples

data(mtcars)
X    <- mtcars[, c("cyl", "disp", "hp", "wt")]
y    <- as.integer(mtcars$am)
tree <- oda_cta_fit(X, y, mindenom = 5L, mc_iter = 500L, mc_seed = 42L)
if (!isTRUE(tree$no_tree)) cta_confusion_matrix(tree)

Description

Returns the stored full-tree training confusion matrix for the final selected CTA model in tidy long format (one row per actual x predicted class pair).

The confusion matrix is captured at fit time at the exact moment the winning candidate is selected, using the same scoring predictions. For the expanded ENUMERATE phase, predictions use majority-fallback for missing attributes. For the root-only stump phase, predictions are path-local (observations whose root attribute is missing are excluded).

This function does not report split-node local confusion. Split-node confusion reflects all observations at a node classified by that node's rule alone; it is not the same as full-tree confusion for trees with more than one split. The two coincide incidentally for stumps but the semantics here are always final-tree.

Usage

cta_confusion_table(tree)

Arguments

Value

A data.frame with columns:

actual

Integer actual class label.

predicted

Integer predicted class label.

n

Integer raw count of observations with this actual x predicted combination in the final selected tree.

Rows are sorted by actual then predicted. For a no-tree fit (or if training_confusion is absent), the returned data frame has zero rows but the correct column structure.

See Also

oda_cta_fit, summary.cta_tree, cta_endpoint_table, cta_node_table

Examples

data(mtcars)
X    <- mtcars[, c("cyl", "disp", "hp", "wt")]
y    <- as.integer(mtcars$am)
tree <- oda_cta_fit(X, y, mindenom = 5L, mc_iter = 500L, mc_seed = 42L)
cta_confusion_table(tree)

Description

Computes the parsimony-normalized classification criterion:

Usage

cta_d_stat(tree)

Arguments

Details

$D = \frac{100}{\text{ESS} / \text{strata}} - \text{strata}$

where strata is the number of terminal leaf endpoints and ESS is tree$overall_ess (WESS when case weights are active, ESS otherwise).

Returns NA_real_ when:

• tree$no_tree is TRUE;

• tree$overall_ess is missing, non-finite, or $\le 0$;

• strata < 2.

Value

Numeric scalar D, or NA_real_.

See Also

cta_strata, cta_min_terminal_denom

Description

A simulated data frame with 200 observations and 6 variables, designed to illustrate Classification Tree Analysis with cta_fit. This is the dataset used in the CTA.exe demonstration program.

Format

A data frame with 200 rows and 6 columns:

V1

Class label (integer; 1 or 2).

V2

Ordered attribute (root in MINDENOM = 1 solution).

V3

Ordered attribute.

V4

Binary attribute (0/1).

V5

Ordered attribute.

V6

Ordered attribute.

Details

The CTA.exe golden output for MINDENOM = 1 selects V2 as root (cut = 4.5, ESS = 52.63%). MINDENOM = 8 requires mc_iter = 25000 for parity.

Simulated dataset; no real subjects or PHI. Used as the primary introductory CTA example in the oda package vignettes and in the CTA.exe demonstration program (CTA_DEMO.pgm).

Description

Traces the MDSA descendant family by fitting CTA models starting at start_mindenom and stepping according to the novometric MDSA rule: next MINDENOM = minimum terminal endpoint denominator + 1. The family terminates when a no-tree fit is produced or max_steps is reached.

Usage

cta_descendant_family(
  X,
  y,
  w = NULL,
  ...,
  start_mindenom = 1L,
  max_steps = 20L
)

Arguments

Value

A list of class cta_family with fields:

members

List of new_cta_family_member objects in order, including the terminal no-tree member.

mindenoms

Integer vector of MINDENOM values tried.

summary

Data frame with one row per member: mindenom, status ("valid_tree", "stump", or "no_tree"), strata, min_terminal_denom, overall_ess, d, no_tree.

min_d_idx

Integer index of the feasible (non-no-tree) member with minimum D; NA_integer_ if no feasible member exists.

terminated

Logical; always TRUE.

termination_reason

Character: one of "no_tree", "max_steps", "no_next_mindenom".

See Also

oda_cta_fit, cta_d_stat, cta_min_terminal_denom, cta_strata

Description

Returns one row per terminal endpoint (leaf) per actual class, read directly from stored leaf node fields. No refitting, no prediction, and no recomputation from training data is performed.

Class counts are stored at fit time by oda_cta_fit on every terminal leaf. Row order within each endpoint follows the order of names(leaf$class_counts_raw), which is ascending by class label. Endpoints are ordered by node_id, matching cta_endpoint_summary.

Scope: This function exposes stored raw and weighted class counts only. It does not include target-class proportions, event rates, odds, or staging order. Staging-table and event-rate summaries are available via cta_staging_table.

If any terminal leaf is missing the stored class counts (i.e., the cta_tree was fitted by an earlier version of oda that did not store endpoint counts), the function stops with a clear error.

Usage

cta_endpoint_counts(tree)

Arguments

Value

A data.frame with one row per terminal endpoint per actual class and columns:

endpoint_id

Integer sequential endpoint index 1..n in node order, matching cta_endpoint_summary.

endpoint_node_id

Integer tree node identifier for this endpoint leaf.

path

Character; AND-joined branch labels from root to this leaf (e.g. "V14<=0.5 AND V15>0.5").

terminal_prediction

Integer class label assigned to this endpoint (stored leaf majority_class).

class

Character; actual class label for this row (e.g. "0", "1").

n_raw

Integer raw count of observations of this actual class reaching this endpoint.

n_weighted

Numeric weighted total for this actual class reaching this endpoint. Equals n_raw when case weights are not active.

For a no-tree fit the returned data frame has zero rows but the correct column structure and types.

See Also

oda_cta_fit, cta_endpoint_summary, cta_confusion_table, cta_endpoint_table, cta_staging_table, cta_propensity_weights

Examples

data(mtcars)
X    <- mtcars[, c("cyl", "disp", "hp", "wt")]
y    <- as.integer(mtcars$am)
tree <- oda_cta_fit(X, y, mindenom = 5L, mc_iter = 500L, mc_seed = 42L)
cta_endpoint_counts(tree)

Description

Returns the observation counts (n_obs) for each terminal leaf node, named by node ID. These are the raw row counts stored at fit time - they are not recomputed from training data or predictions.

Usage

cta_endpoint_denominators(tree)

Arguments

Details

Returns integer(0) for no-tree fits.

Value

Named integer vector of leaf n_obs values, named by node ID (as character); integer(0) for no-tree fits.

See Also

cta_strata, cta_min_terminal_denom

Description

Returns one row per terminal leaf (endpoint) with stable endpoint identifiers and stored node fields suitable for downstream reporting. All values are read directly from stored node fields; no refitting, no prediction, and no recomputation of tree metrics is performed.

Scope: This function reports structural endpoint fields only. It does not include endpoint class counts, target-class proportions, event rates, odds, or staging order. Per-endpoint class counts are available via cta_endpoint_counts. Staging-table and event-rate summaries are available via cta_staging_table.

Usage

cta_endpoint_summary(tree)

Arguments

Value

A data.frame with one row per terminal leaf and columns:

endpoint_id

Integer sequential index 1..n in node order.

endpoint_node_id

Integer tree node identifier for this leaf, corresponding to node_id in cta_endpoint_table.

path

Character; AND-joined branch labels from root to this leaf (e.g. "V14<=0.5 AND V15>0.5").

depth

Integer depth from root (root = 1).

terminal_prediction

Integer class label assigned to this endpoint (stored leaf majority_class).

n_obs

Integer raw observation count at this endpoint.

n_weighted

Numeric weighted observation count. Equals n_obs when case weights are not active (not NA).

denominator

Integer endpoint denominator (equal to n_obs); included to align with MPE/MDSA terminology.

For a no-tree fit the returned data frame has zero rows but the correct column structure and types.

See Also

oda_cta_fit, cta_endpoint_table, cta_strata, cta_endpoint_denominators, cta_endpoint_counts, cta_staging_table

Examples

data(mtcars)
X    <- mtcars[, c("cyl", "disp", "hp", "wt")]
y    <- as.integer(mtcars$am)
tree <- oda_cta_fit(X, y, mindenom = 5L, mc_iter = 500L, mc_seed = 42L)
cta_endpoint_summary(tree)

Description

Returns one row per terminal leaf (endpoint) of a cta_tree. All values are read directly from stored node fields; no refitting or prediction is performed. This is the canonical endpoint map for reporting, translation, ORT, and staged workflows.

Leaf class counts are stored on every terminal node at fit time (class_counts_raw, class_counts_weighted). target_n and target_prop are derived from the stored counts.

ESS, WESS, p, LOO status, LOO ESS/WESSL, and LOOp are canonical split-node report metrics (see cta_node_table). Terminal endpoints are connected to those metrics through their parent split-node lineage. The parent_split_* columns expose the immediate parent split's canonical metrics for auditability. They are not recomputed ESS at the leaf.

Usage

cta_endpoint_table(tree, target_class = NULL)

Arguments

Value

A data.frame with one row per terminal leaf and columns:

endpoint_id

Integer sequential endpoint index 1..n.

leaf_node_id

Integer tree node identifier for this leaf.

terminal_marker

Character "*" on every row.

terminal

Logical TRUE on every row.

depth

Integer depth from root (root = 1).

parent_split_node_id

Integer parent split node identifier.

path

Character; AND-joined branch labels from root to this leaf (e.g. "V14<=0.5 AND V15>0.5").

n

Integer raw observation count at this endpoint.

class_counts_raw

List column; each element is a named integer vector of raw per-class counts, or NULL.

class_counts_weighted

List column; each element is a named numeric vector of weighted per-class counts, or NULL.

predicted_class

Integer class label assigned to this endpoint (stored leaf majority class).

target_n

Integer count of target_class observations at this endpoint (NA when not resolvable).

target_prop

Numeric proportion target_n / n (NA when not resolvable).

parent_split_attribute

Attribute name of the parent split.

parent_split_ess

ESS of the parent split node.

parent_split_wess

WESS of the parent split node.

parent_split_loo_status

LOO status of the parent split node.

parent_split_loo_ess

LOO ESS/WESSL of the parent split node.

parent_split_p_mc

MC p-value of the parent split node.

For a no-tree fit the returned data frame has zero rows but the correct column structure and types.

See Also

oda_cta_fit, cta_node_table, summary.cta_tree, cta_strata, cta_endpoint_denominators, cta_endpoint_summary, cta_endpoint_counts

Examples

data(mtcars)
X    <- mtcars[, c("cyl", "disp", "hp", "wt")]
y    <- as.integer(mtcars$am)
tree <- oda_cta_fit(X, y, mindenom = 5L, mc_iter = 500L, mc_seed = 42L)
cta_endpoint_table(tree)

Description

Returns a data.frame with one row per family member, reading all values from the stored cta_family object. No refitting or recomputation is performed.

Usage

cta_family_table(family)

Arguments

Value

A data.frame with columns:

index

Integer position of the member in the chain.

mindenom

Integer MINDENOM used for this fit.

status

Character: "valid_tree", "stump", or "no_tree".

no_tree

Logical; TRUE for the terminal no-tree member.

strata

Integer number of terminal leaf endpoints; NA for no-tree members.

min_terminal_denom

Integer minimum leaf n_obs; NA for no-tree members.

next_mindenom

Integer MINDENOM for the next chain step (min_terminal_denom + 1); NA for no-tree members.

overall_ess

Numeric overall ESS or WESS stored at fit time; NA for no-tree members.

has_weights

Logical; TRUE when case weights were active for this fit.

d

Numeric D statistic (100 / (ESS / strata) - strata); NA for no-tree members.

selected_min_d

Logical; TRUE for the feasible member with minimum D (index family$min_d_idx). All FALSE when no feasible member exists.

See Also

cta_descendant_family, summary.cta_family

Examples

data(mtcars)
X <- mtcars[, c("cyl", "disp", "hp", "wt")]
y <- as.integer(mtcars$am)
fam <- suppressMessages(
  cta_descendant_family(X, y, start_mindenom = 1L, mc_iter = 200L,
                        mc_seed = 42L, loo = "off")
)
cta_family_table(fam)

Description

Public entry point for CTA. Currently supports binary (two-class) outcome variables only.

When recursive = FALSE (default), validates the class variable and delegates to oda_cta_fit. When recursive = TRUE, runs the Locally Optimal Recursive Tree (LORT) engine: at each endpoint a full MDSA family scan (cta_descendant_family) is performed, the min-D member is selected, and recursion continues until no further structure is found or a compute guard fires. Returns a dual-tagged cta_ort / cta_tree object.

Usage

cta_fit(X, y, verbose = FALSE,
        recursive        = FALSE,
        min_n            = 30L,
        max_depth        = 8L,
        max_nodes        = 31L,
        family_max_steps = 20L,
        ...)

Arguments

Value

Non-recursive: a cta_tree object.

Recursive: a dual-tagged cta_ort / cta_tree object. All existing cta_tree S3 methods (predict, print, summary, plot) operate on the root-level model. cta_ort-aware methods (predict.cta_ort, print.cta_ort, summary.cta_ort, plot.cta_ort) operate on the full composite tree. Use predict(obj, newdata, type="all") to retrieve stratum assignments.

Note

oda_cta_fit() is the internal engine name; cta_fit() is the preferred public entry point for non-recursive CTA. Both are exported and functionally equivalent for non-recursive use.

cta_fit(..., recursive = TRUE) is a legacy-compatible interface for the LORT workflow layer. Prefer lort_fit() for new code. SORT and GORT are reserved and not implemented.

See Also

oda_fit, cta_descendant_family, cta_node_table, cta_staging_table, plot.cta_tree, plot.cta_ort, ort_plot_data

Examples

# Small synthetic two-class example (non-recursive)
X <- data.frame(
  x1 = c(1, 2, 3, 4, 5, 6, 7, 8),
  x2 = c(0L, 0L, 1L, 0L, 1L, 1L, 0L, 1L)
)
y <- c(1L, 1L, 1L, 1L, 2L, 2L, 2L, 2L)

tree <- cta_fit(X, y,
  priors_on   = TRUE,
  mindenom    = 1L,
  mc_iter     = 500L,
  mc_seed     = 42L,
  loo         = "off",
  attr_names  = c("x1", "x2")
)
print(tree)

# Recursive ORT  -  two-level synthetic dataset
X2 <- data.frame(
  A = c(rep(0, 20), rep(1, 20), rep(1, 20)),
  B = c(rep(0, 20), rep(0, 20), rep(1, 20))
)
y2 <- c(rep(0L, 20), rep(0L, 20), rep(1L, 20))
ort <- cta_fit(X2, y2, recursive = TRUE,
               mc_iter = 100L, mc_seed = 42L, loo = "off",
               min_n = 5L)
print(ort)

Description

Returns the smallest leaf n_obs across all terminal endpoints. This value drives the next MINDENOM step in the MDSA descendant family: next_mindenom = cta_min_terminal_denom(tree) + 1L.

Usage

cta_min_terminal_denom(tree)

Arguments

Details

Returns NA_integer_ for no-tree fits.

Value

Minimum leaf n_obs as an integer, or NA_integer_ for no-tree fits.

See Also

cta_strata, cta_endpoint_denominators

Description

Returns a data frame with one row per node, mirroring the CTA.exe-style node report (ATTRIBUTE, NODE, LEV, OBS, p, ESS/WESS, LOO, WESSL/LOO ESS, LOOp, TYP, MODEL columns).

Split nodes carry canonical split metrics (ESS, WESS, p, LOO status, LOO ESS/WESSL, LOOp) and a MODEL field with branch strings and terminal-leaf * markers. Leaf rows have NA for all split metrics and MODEL.

Usage

cta_node_table(tree)

Arguments

Value

Data frame with columns:

node_id

Integer node identifier.

parent_id

Integer parent node identifier (0 for root).

level

Integer level from root (root = 1); alias for depth.

depth

Integer depth from root (root = 1).

leaf

Logical; TRUE for terminal leaf nodes.

attribute

Character attribute name (NA for leaves).

attr_type

Character attribute type (NA for leaves).

n_obs

Integer observation count at this node.

n_weighted

Numeric weighted observation count.

p_mc

Numeric Monte Carlo p-value (NA for leaves).

ess

Numeric ESS at this split (NA for leaves).

ess_weighted

Numeric WESS at this split (NA for leaves); equals ess when case weights are not active.

loo_status

Character LOO status, e.g. "STABLE" (NA for leaves).

loo_ess

Numeric LOO ESS/WESSL (NA for leaves).

loo_p

Numeric LOO p-value (NA for leaves).

model

Character CTA.exe-style branch string with terminal-leaf * markers, e.g. "<=0.5-->0,101/131,77.10%*; >0.5-->1,21/55,38.18%*". NA for leaf nodes.

See Also

oda_cta_fit, cta_endpoint_table, summary.cta_tree

Description

Convenience wrapper that calls cta_assign_endpoints and cta_propensity_weights and returns a joined observation-level data frame. The cta_tree object is not mutated; all computation is on demand.

Column order requirement: newdata must have the same attribute column order as the X matrix passed to oda_cta_fit. Traversal uses the stored integer column positions (attr_col) from the fit, not column names.

Unroutable observations: Observations with NA endpoint (missing root split attribute under missing_action = "na") or NA class label receive assigned = FALSE and NA for all weight columns. The output always contains nrow(newdata) rows.

Unmatched classified observations: When a non-NA endpoint observation's class is not present in the propensity weight table (e.g., a class unseen at fit time), a warning is issued and assigned = FALSE.

Usage

cta_observation_weights(tree, newdata, y, target_class = NULL,
                        adjusted = TRUE,
                        missing_action = c("na", "majority"))

Arguments

Details

No observation-level data are stored in the cta_tree object at fit time. This function performs traversal and weight lookup on demand.

No-tree fits: When the tree has no splits (leaf-only), all rows have endpoint_id = NA_integer_ and assigned = FALSE.

Join semantics: The join key is paste(endpoint_id, actual_class). Each observation is matched to the propensity weight row whose class equals its actual_class. The target_class parameter annotates all rows with the resolved design target class but does not affect which rows participate in the join.

Value

A data.frame with nrow(newdata) rows and columns:

row_id

Integer; positional row index (1 to nrow(newdata)).

actual_class

Character; class label from y, coerced to character.

endpoint_node_id

Integer; node ID of the terminal leaf reached by traversal, or NA_integer_ when unroutable.

endpoint_id

Integer; sequential endpoint index matching cta_endpoint_summary, or NA_integer_.

target_class

Integer; resolved design target class annotation from cta_propensity_weights, or NA_integer_ when unassigned.

propensity_weight

Numeric; unadjusted propensity weight for the observation's endpoint–class cell, or NA when unassigned.

adjusted_propensity_weight

Numeric; adjusted propensity weight (Yarnold-Linden correction for perfectly predicted endpoints), or NA when unassigned.

undefined_empirical

Logical; TRUE when the endpoint–class cell has zero observed frequency, or NA when unassigned.

perfectly_predicted_endpoint

Logical; TRUE when all observations at the endpoint belong to one class, or NA when unassigned.

adjusted

Logical; TRUE when the adjusted weight was applied at this endpoint, or NA when unassigned.

assigned

Logical; TRUE when a propensity weight was successfully matched for this observation.

See Also

cta_assign_endpoints, cta_propensity_weights, oda_cta_fit, cta_endpoint_summary

Examples

data(mtcars)
X    <- mtcars[, c("cyl", "disp", "hp", "wt")]
y    <- as.integer(mtcars$am)
tree <- oda_cta_fit(X, y, mindenom = 5L, mc_iter = 500L, mc_seed = 42L)
ow   <- cta_observation_weights(tree, X, y)
head(ow)

Description

Returns one row per LORT node from a cta_ort (LORT) object. Each row exposes the embedded CTA member selected at that node (MINDENOM, ESS, D, root attribute, split/leaf counts, endpoint count) plus the LORT method taxonomy metadata (method, selection_scope, global_optimization, sda_anchored).

Terminal nodes have NA for all selected-model columns. Non-terminal nodes have NA for stop_reason and non-empty child_ids.

Naming note: The function name cta_ort_node_table and the class cta_ort are legacy compatibility names for the implemented LORT method. They are retained for backward compatibility; new code and documentation should refer to the method as LORT.

Usage

cta_ort_node_table(object)

Arguments

Value

A data.frame with one row per ORT node and columns:

ort_node_id

Integer ORT node identifier.

parent_ort_node_id

Integer parent ORT node id; NA for root.

depth

Integer recursion depth (root = 0).

n

Integer observations at this ORT node.

class_counts

Character; named class counts, e.g. "0=60, 1=40".

terminal

Logical; TRUE for terminal leaf ORT nodes.

stop_reason

Character stop reason for terminal nodes; NA for non-terminal.

selected_mindenom

Integer MINDENOM of the embedded CTA member.

selected_ess

Numeric ESS of the embedded CTA member (%).

selected_d

Numeric D-statistic of the embedded CTA member.

selected_root_attribute

Character root attribute of the embedded CTA member.

selected_tree_nodes

Integer split-node count in the embedded CTA member.

selected_tree_leaves

Integer leaf count in the embedded CTA member.

selected_endpoint_count

Integer endpoint (terminal leaf) count of the embedded CTA member; equals number of ORT child nodes.

child_ids

Character comma-separated child ORT node ids; empty string for terminal nodes.

method

Character; always "lort" for current fits.

selection_scope

Character; always "local_node" for LORT.

global_optimization

Logical; always FALSE for LORT.

sda_anchored

Logical; always FALSE for LORT.

See Also

cta_fit, predict.cta_ort, summary.cta_ort

Examples

X <- data.frame(A = c(rep(0L, 20), rep(1L, 20), rep(1L, 20)),
                B = c(rep(0L, 20), rep(0L, 20), rep(1L, 20)))
y <- c(rep(0L, 20), rep(0L, 20), rep(1L, 20))
ort <- cta_fit(X, y, recursive = TRUE, mc_iter = 100L, mc_seed = 42L,
               loo = "off", min_n = 5L)
cta_ort_node_table(ort)

Description

Returns a pure-data list describing tree topology and layout coordinates. No graphics are produced. Use this as input to plot.cta_tree or to custom rendering code.

Layout algorithm: leaves receive sequential integer x-positions in depth-first (left-to-right) order; internal nodes are centred over their children. y = -depth so the root sits at the top.

Target-class enrichment: when target_class is supplied, each terminal leaf is joined to cta_staging_table and annotated with target-class counts, proportions, and a continuous display color derived from the endpoint's rank among all endpoints by ascending target-class proportion. Colors encode relative position within this tree's endpoint distribution and do not imply clinical thresholds or categories.

Usage

cta_plot_data(tree, target_class = NULL, class_labels = NULL,
              digits = 1, endpoint_palette = NULL)

Arguments

Value

When target_class = NULL: a list with elements nodes, edges, no_tree, has_weights.

When target_class is supplied: the same list plus endpoints (a staging data.frame with layout coordinates) and target_class_used (the integer target class used).

nodes

A data.frame with one row per node. Always-present columns: node_id (integer), parent_id (integer), depth (integer), x (numeric), y (numeric), leaf (logical), attribute (character; NA for leaves), n_obs (integer), majority_class (integer), ess (numeric; NA for leaves), label (character multi-line display text).

Additional columns present when target_class is supplied (values are NA on split nodes): endpoint_id (integer), stage (integer), target_class (integer), target_n (numeric), denominator (numeric), target_proportion (numeric; raw continuous proportion, not binned), target_rank (integer; ascending rank of proportion, ties broken by ties.method = "first"), endpoint_fill_color (character hex color assigned by rank within this tree - does not imply clinical thresholds or categories), predicted_label (character), target_label (character), endpoint_label (character multi-line display text).

edges

A data.frame with one row per parent-to-child edge and columns from_node_id (integer), to_node_id (integer), x0, y0, x1, y1 (numeric centre-to-centre coordinates), label (character branch condition, e.g. "V14<=0.5").

endpoints

(target_class only) A data.frame with one row per endpoint, ordered by ascending stage. Columns include all staging fields from cta_staging_table plus layout coordinates x, y, display columns predicted_label, target_label, endpoint_fill_color, and integer target_rank.

target_class_used

(target_class only) The integer target_class argument used for enrichment.

no_tree

Logical; TRUE for leaf-only fits.

has_weights

Logical; TRUE when case weights are active.

See Also

plot.cta_tree, cta_staging_table, oda_cta_fit

Examples

data(mtcars)
X    <- mtcars[, c("cyl", "disp", "hp", "wt")]
y    <- as.integer(mtcars$am)
tree <- suppressMessages(
  oda_cta_fit(X, y, mindenom = 5L, mc_iter = 500L, mc_seed = 42L,
              loo = "off")
)

# Structural layout only
pd <- cta_plot_data(tree)
head(pd$nodes)
pd$edges

# Target-class enrichment
pd2 <- cta_plot_data(tree, target_class = 1L,
                     class_labels = c("0" = "Manual", "1" = "Auto"))
pd2$endpoints[, c("stage", "target_proportion", "endpoint_fill_color")]

Description

Returns one row per terminal endpoint per actual class, containing the CTA-derived stabilized propensity-style weights described in Yarnold and Linden (2017). All values are computed on demand from the stored leaf class counts; no refitting, no prediction, and no training-data recomputation is performed.

Formula: For endpoint $s$ and actual class $z$,

$w_{s,z} = \frac{n_s \cdot \Pr(Z=z)}{n_{s,z}}$

where $n_s$ is the endpoint denominator, $n_{s,z}$ is the raw count of class $z$ observations at endpoint $s$, and $\Pr(Z=z)$ is the marginal class probability across the full classified analytic sample.

Perfect endpoints: When $n_{s,z} = 0$ for some class, the empirical weight is undefined (Inf). When adjusted = TRUE (default), one hypothetical misclassified observation is added to the absent class profile - and to the global marginal totals - so that all endpoint x class cells yield finite adjusted weights. This is the canon remedy from Yarnold and Linden (2017).

Scope: Raw observation counts (n_raw) are used exclusively. The function does not return observation-level weights; those require endpoint membership per training observation, which is not stored on the fitted tree.

Usage

cta_propensity_weights(tree, target_class = NULL, adjusted = TRUE)

Arguments

Value

A data.frame with one row per terminal endpoint per actual class, with columns:

endpoint_id

Integer sequential endpoint index.

endpoint_node_id

Integer tree node identifier.

path

Character; AND-joined branch labels from root.

terminal_prediction

Integer majority-class prediction.

class

Character; actual class label for this row.

target_class

Integer; design-annotation class label.

class_n

Integer; raw count of this class at this endpoint (empirical $n_{s,z}$).

endpoint_n

Integer; total raw observations at this endpoint (empirical $n_s$).

marginal_class_n

Integer; total raw observations of this class across all endpoints (empirical $N_z$).

marginal_total_n

Integer; total classified observations across all endpoints (empirical $N$).

marginal_class_probability

Numeric; empirical marginal class probability $\Pr(Z=z) = N_z / N$.

propensity_weight

Numeric; empirical stabilized weight $n_s \cdot \Pr(Z=z) / n_{s,z}$. Inf when class_n == 0.

undefined_empirical

Logical; TRUE when class_n == 0.

perfectly_predicted_endpoint

Logical; TRUE when any class has class_n == 0 at this endpoint.

adjusted

Logical; TRUE when the one-hypothetical-observation adjustment was applied to this row.

adjusted_class_n

Numeric; class_n + 1 where adjusted, otherwise class_n.

adjusted_endpoint_n

Numeric; endpoint denominator after adjustment.

adjusted_marginal_class_n

Numeric; global class count after all hypothetical additions.

adjusted_marginal_total_n

Numeric; global total after all hypothetical additions.

adjusted_marginal_class_probability

Numeric; adjusted marginal class probability.

adjusted_propensity_weight

Numeric; adjusted weight. Finite whenever adjusted_class_n > 0.

For a no-tree fit the returned data frame has zero rows but the correct column structure and types.

References

Yarnold PR, Linden A (2017). Computing propensity score weights for CTA models involving perfectly predicted endpoints. Optimal Data Analysis, 6, 43-46.

See Also

oda_cta_fit, cta_endpoint_counts, cta_staging_table

Examples

data(mtcars)
X    <- mtcars[, c("cyl", "disp", "hp", "wt")]
y    <- as.integer(mtcars$am)
tree <- oda_cta_fit(X, y, mindenom = 5L, mc_iter = 500L, mc_seed = 42L)
cta_propensity_weights(tree)

Description

Returns one row per terminal endpoint ordered by ascending target-class propensity (lowest to highest risk stratum). Empirical counts, proportions, and odds are computed from the stored leaf class counts. When an endpoint is perfectly predicted (100 percent one class), the empirical odds and proportion are undefined; the adjust_perfect option adds one hypothetical misclassified observation to the undefined profile so all endpoints can be ranked and compared - a canon remedy anchored in Yarnold and Linden (2017).

Scope: The two-class case is handled automatically when target_class = NULL (defaults to the numerically larger class label, typically 1). For trees with three or more classes target_class must be supplied explicitly.

Usage

cta_staging_table(tree, target_class = NULL, weighted = FALSE,
                   adjust_perfect = TRUE)

Arguments

Value

A data.frame with one row per terminal endpoint, ordered by ascending target-class propensity (lowest to highest risk stratum), with columns:

stage

Integer rank 1..n, ascending by target proportion.

endpoint_id

Integer sequential endpoint index, matching cta_endpoint_summary.

endpoint_node_id

Integer tree node identifier.

path

Character; AND-joined branch labels from root.

terminal_prediction

Integer majority-class prediction.

target_class

Integer; the target class used for this table.

target_n

Numeric; raw (or weighted) count of target-class observations at this endpoint.

denominator

Numeric; total raw (or weighted) observations at this endpoint.

target_proportion

Numeric; empirical target-class proportion (target_n / denominator).

non_target_n

Numeric; denominator minus target_n.

odds

Numeric; empirical odds (target_n / non_target_n); NA when perfectly_predicted is TRUE.

perfectly_predicted

Logical; TRUE when the endpoint is 100 percent one class (target_n == 0 or non_target_n == 0).

adjusted

Logical; TRUE when the one-hypothetical-misclassification adjustment has been applied. Always FALSE when adjust_perfect = FALSE.

adjusted_target_n

Numeric; target_n after adjustment. Equal to target_n when adjusted is FALSE.

adjusted_denominator

Numeric; denominator after adjustment.

adjusted_target_proportion

Numeric; adjusted proportion.

adjusted_non_target_n

Numeric; adjusted non-target count.

adjusted_odds

Numeric; adjusted odds.

weighted

Logical; the value of the weighted argument.

n_obs

Integer; raw observation count at this endpoint (from cta_endpoint_summary).

n_weighted

Numeric; weighted observation count.

For a no-tree fit the returned data frame has zero rows but the correct column structure and types.

References

Yarnold PR, Linden A (2017). Computing propensity score weights for CTA models involving perfectly predicted endpoints. Optimal Data Analysis, 6, 43-46.

See Also

oda_cta_fit, cta_endpoint_summary, cta_endpoint_counts, cta_propensity_weights

Examples

data(mtcars)
X    <- mtcars[, c("cyl", "disp", "hp", "wt")]
y    <- as.integer(mtcars$am)
tree <- oda_cta_fit(X, y, mindenom = 5L, mc_iter = 500L, mc_seed = 42L)
cta_staging_table(tree)

Description

Returns the count of terminal leaf nodes in a fitted cta_tree (an integer scalar, not a table). Returns NA_integer_ for no-tree fits (where tree$no_tree is TRUE).

Usage

cta_strata(tree)

Arguments

Details

To obtain endpoint details (node IDs, path labels, class counts, predicted class), use cta_endpoint_table.

Value

Integer scalar: number of terminal leaf nodes, or NA_integer_ for no-tree fits. This is a count, not a data frame - use cta_endpoint_table for per-endpoint rows.

See Also

cta_endpoint_table, cta_endpoint_denominators, cta_min_terminal_denom

Description

Preferred explicit entry point for the LORT workflow layer. LORT is a non-canonical workflow composition: at each recursive endpoint it runs a full MDSA family scan (cta_descendant_family), selects the min-D member, and recurses until no further structure is found or a compute guard fires. It uses canon CTA/MDSA components but is not itself a canon CTA.exe behavior.

Usage

lort_fit(
  X,
  y,
  w = NULL,
  mc_iter = 5000L,
  mc_seed = 42L,
  mc_stop = 99.9,
  mc_stopup = NA,
  alpha_split = 0.05,
  prune_alpha = 0.05,
  loo = "stable",
  min_n = 30L,
  max_depth = 8L,
  max_nodes = 31L,
  family_max_steps = 20L,
  verbose = FALSE
)

Arguments

Details

lort_fit() is functionally equivalent to cta_fit(..., recursive = TRUE). cta_fit(..., recursive = TRUE) is retained as a legacy-compatible alias and will continue to work; prefer lort_fit() for new code. SORT and GORT are reserved and not implemented.

Value

A dual-tagged cta_ort / cta_tree object. cta_ort-aware methods (predict.cta_ort, print.cta_ort, summary.cta_ort, plot.cta_ort, cta_ort_node_table) operate on the full composite tree. ort_settings$method is always "lort".

See Also

cta_fit, predict.cta_ort, cta_ort_node_table, ort_plot_data

Examples

X <- data.frame(
  A = c(rep(0L, 20), rep(1L, 20), rep(1L, 20)),
  B = c(rep(0L, 20), rep(0L, 20), rep(1L, 20))
)
y <- c(rep(0L, 20), rep(0L, 20), rep(1L, 20))
fit <- lort_fit(X, y, mc_iter = 100L, mc_seed = 42L, loo = "off", min_n = 5L)
print(fit)

Description

Returns a data frame tracing the LORT recursion path from the root node (index 1) to the requested node, one row per LORT node on the path.

Usage

lort_index_path(x, index)

Arguments

Value

A data frame with columns: lort_index, parent_lort_index, depth, n, stop_reason, is_terminal, incoming_endpoint_id (which endpoint of the parent led here), incoming_path_condition (condition string for that endpoint), incoming_path_label (human-readable label), local_status, local_ess, local_d, local_n_endpoints.

See Also

lort_local_tree, lort_path_table, plot_lort_path

Description

Returns the full cta_tree object selected at LORT node index. This is the complete CTA/MDSA family member fitted on the observations that reached that node – not a summary, not a stump approximation, not reconstructed from plot-data.

Usage

lort_local_tree(x, index)

Arguments

Details

Returns NULL when the node is terminal due to min_n, max_depth, max_nodes, or a pure-class guard (no fit was attempted). A no_tree result at a non-forced-terminal node yields a cta_tree with $no_tree = TRUE.

Value

A cta_tree object or NULL (with a message for forced-terminal nodes).

See Also

lort_index_path, plot_lort_path

Description

Prints and returns (invisibly) a summary of the LORT recursion path from the root node to the requested index. For each node on the path it shows the local CTA model's key metrics and the endpoint condition that led to the next recursive call.

Usage

lort_path_table(x, index)

Arguments

Value

Invisibly, the data frame from lort_index_path. Printed output goes to stdout().

See Also

lort_index_path, lort_local_tree, plot_lort_path

Description

Computes propensity weights from the terminal strata of a fitted LORT (Locally Optimal Recursive Tree) model. Uses stored class_counts per terminal node. Implements the Yarnold/Linden stratum-weight formula (same as cta_propensity_weights):

$w = n_s \times \Pr(Z=z) / n_{z,s}$

Usage

lort_propensity_weights(ort, target_class = NULL, adjusted = TRUE)

Arguments

Details

The fitted model must have been trained with the treatment/exposure/group membership as the class variable, not a clinical outcome. The user is responsible for this labeling decision.

Value

Data frame with one row per (stratum, class) combination. Columns: stratum_id (integer), path (character), depth (integer), stratum_n (integer), terminal_class (integer), class (character), class_n (integer), target_class (integer), marginal_class_n (integer), marginal_total_n (integer), marginal_class_probability (numeric), propensity_weight (numeric), undefined_empirical (logical), adjusted (logical), adjusted_propensity_weight (numeric), model_family ("lort"), global_optimization (FALSE), sda_anchored (FALSE).

See Also

cta_propensity_weights, oda_propensity_weights, lort_fit

Description

A data frame with 256 observations and 19 variables, formatted for use with cta_fit and oda_fit. Derived from the publicly available myeloma gene-expression dataset (GEO accession GSE4581), as distributed in the survminer package.

Format

A data frame with 256 rows and 19 columns:

V1

Survival event indicator (0 = censored, 1 = event). Used as the class variable y in CTA/ODA.

V2

Case weight (observation time in months). Use as w in cta_fit; rows with V2 == 0 should be excluded.

V3

CCND1 gene expression.

V4

CRIM1 gene expression.

V5

DEPDC1 gene expression.

V6

IRF4 gene expression.

V7

TP53 expression / mutation burden.

V8

WHSC1 gene expression.

V9

Molecular group: Cyclin D-1 (binary).

V10

Molecular group: Cyclin D-2 (binary).

V11

Molecular group: Hyperdiploid (binary).

V12

Molecular group: Low bone disease (binary).

V13

Molecular group: MAF (binary).

V14

Molecular group: MMSET (binary).

V15

Molecular group: Proliferation (binary).

V16

Chr1q21 status: 2 copies (binary).

V17

Chr1q21 status: 3 copies (binary).

V18

Chr1q21 status: 4+ copies (binary).

V19

Chr1q21 status: NA-coded (binary). Missing values are coded as -9 (miss_codes = -9).

Details

This dataset is used throughout the oda documentation and vignettes to illustrate weighted CTA, MINDENOM constraints, LOO STABLE validation, and missing-code handling. Reference CTA.exe golden outputs for MINDENOM = 1, 30, and 56 are used as regression anchors.

Use miss_codes = -9 and w = myeloma$V2 when calling cta_fit. With mindenom = 1, the enumerated CTA tree roots at V14 with a V15 child (OVERALL ESS = 26.32%, WEIGHTED ESS = 27.69%). With mindenom = 30, the selected tree is a V17 stump (WEIGHTED ESS = 16.51%). With mindenom = 56, no admissible tree exists.

Source

Derived from the myeloma dataset in the survminer package. Original data: NCBI GEO accession GSE4581. No PHI; no institutional data. See tests/testthat/fixtures/myeloma/README.md in the source tree.

Description

Estimates the precision of an observed binary classification effect by comparing model and chance distributions via permutation/resampling bootstrap. Based on the NOVOboot methodology (Yarnold 2020; Yarnold & Soltysik 2016).

Fixed-confusion bootstrap: This function samples from the observed confusion matrix structure. It does not refit ODA or CTA models and does not estimate model-selection variability. The model distribution is generated by resampling paired (actual, predicted) rows from the expanded confusion table; the chance distribution is generated by independently resampling actual and predicted labels, breaking their association. Novometric significance (Axiom 1) is declared when the 95% confidence intervals for model and chance ESS do not overlap.

Usage

novo_boot_ci(x, ...)

## Default S3 method:
novo_boot_ci(x,
             nboot       = 5000L,
             seed        = NULL,
             sample_frac = 0.5,
             probs       = c(0, .025, .05, .25, .5, .75, .95, .975, 1),
             alternative = c("two.sided", "greater", "less"),
             ...)

## S3 method for class 'oda_fit'
novo_boot_ci(x,
             nboot       = 5000L,
             seed        = NULL,
             sample_frac = 0.5,
             probs       = c(0, .025, .05, .25, .5, .75, .95, .975, 1),
             alternative = c("two.sided", "greater", "less"),
             ...)

## S3 method for class 'cta_tree'
novo_boot_ci(x,
             nboot       = 5000L,
             seed        = NULL,
             sample_frac = 0.5,
             probs       = c(0, .025, .05, .25, .5, .75, .95, .975, 1),
             alternative = c("two.sided", "greater", "less"),
             node_id     = NULL,
             weighted    = FALSE,
             ...)

## S3 method for class 'cta_ort'
novo_boot_ci(x,
             nboot       = 5000L,
             seed        = NULL,
             sample_frac = 0.5,
             probs       = c(0, .025, .05, .25, .5, .75, .95, .975, 1),
             alternative = c("two.sided", "greater", "less"),
             stratum_id  = NULL,
             weighted    = FALSE,
             ...)

## S3 method for class 'novo_boot_ci'
print(x, ...)

Arguments

Details

Model distribution: The input confusion matrix is expanded to n paired (actual, predicted) observation rows. For each replicate, k row indices are drawn with replacement, preserving the observed (actual, predicted) joint distribution. This mirrors the NOVOboot row-resampling approach.

Chance distribution: Actual and predicted labels are resampled independently for each replicate, breaking any association between them. This generates the null distribution against which the model effect is compared.

p-values: An exact 2x2 Fisher p-value is computed for every replicate confusion matrix for both model and chance distributions. These form precision distributions and complement the CI non-overlap criterion; they are not a substitute for it.

Novometric Axiom 1: A statistically significant effect exists when the exact discrete confidence intervals for model and chance performance do not overlap. significant = TRUE indicates the ESS model 95% CI lies entirely above the ESS chance 95% CI.

ESS formula: ESS(%) = 100 * (mean_PAC - 0.5) / 0.5, consistent with oda_ess_from_meanpac.

OR: Diagnostic odds ratio (TP * TN) / (FP * FN). NA when FP = 0 or FN = 0 in a replicate.

RR: Positive predictive value / false omission rate [TP / (TP+FP)] / [FN / (FN+TN)]. NA when undefined.

Value

An object of class novo_boot_ci, a list with:

call

The matched call.

confusion

Input confusion matrix (integer, 2x2).

n

Total observations (sum(x)).

k

Observations sampled per replicate (round(sample_frac * n)).

nboot, sample_frac, probs, alternative

Input parameters.

has_zero_cells

Logical; TRUE if any cell of x is zero. Does not stop computation; NA propagates for affected metrics in affected replicates.

observed

Data frame with one row per metric. Columns: metric, value. Reports the observed (not bootstrapped) sensitivity, specificity, mean_pac, ess, odds_ratio, and risk_ratio computed directly from the input confusion matrix.

model

Data frame (nboot rows). Per-replicate model bootstrap distributions: sensitivity, specificity, mean_pac, ess (all in %), odds_ratio, risk_ratio, p_value. NA for undefined OR/RR.

chance

Data frame (nboot rows). Same columns as model. Generated by independently resampling actual and predicted labels (null of no classification association).

quantiles

Data frame (length(probs) rows). Quantiles of each metric for model and chance across all replicates, including p_value_model and p_value_chance.

ci

Data frame (one row per metric). Fixed 95% CI bounds (2.5th and 97.5th percentiles) for model and chance. Columns: metric, model_lower, model_upper, chance_lower, chance_upper, overlap.

significant

Logical scalar. TRUE if the ESS model 95% CI lower bound exceeds the ESS chance 95% CI upper bound - novometric Axiom 1 CI non-overlap criterion.

source_type

Character. Evidence provenance tag: "matrix", "oda_fit", "cta_tree", "cta_tree_node", "cta_ort", or "cta_ort_stratum".

source_id

Integer or NA. Node or stratum id when evidence came from a specific sub-unit; NA for full-tree paths.

weighted

Logical or NA. TRUE when weighted class counts were used; FALSE for raw counts; NA for the default matrix path.

References

Yarnold PR (2020). Reformulating the First Axiom of Novometric Theory: Assessing Minimum Sample Size in Experimental Design. Optimal Data Analysis 9, 7–8.

Yarnold PR, Soltysik RC (2016). Maximizing Predictive Accuracy. ODA Books.

Examples

# Myeloma MINDENOM=1 confusion (actual x predicted, byrow = TRUE)
conf <- matrix(c(146, 40,
                  36, 33), nrow = 2, byrow = TRUE)
ci <- novo_boot_ci(conf, nboot = 200L, seed = 42L)
ci$significant
print(ci)

Description

Builds one row per covariate $\times$ analysis scale containing the observed ESS/WESS, a bootstrap confidence interval (model sampling variability), and a chance interval (null distribution from group-label permutation). The resulting table answers whether each covariate's model confidence interval clears the chance interval.

Usage

oda_balance_effect_table(
  group,
  X,
  w = NULL,
  compare_weights = FALSE,
  covariate_types = NULL,
  nboot = 2000L,
  chance_iter = 2000L,
  ci = 0.95,
  mc_seed = NULL,
  mc_iter = 1000L,
  ...
)

Arguments

Details

Three passes are run per covariate:

1. Observed: oda_fit(mcarlo = TRUE) – point estimate and Monte Carlo p-value.

2. Bootstrap: nboot resamples (rows with replacement), mcarlo = FALSE – percentile confidence interval.

3. Chance: chance_iter group-label permutations, mcarlo = FALSE – null percentile interval.

When compare_weights = TRUE and w is supplied, both an "unweighted" and a "weighted" row are produced per covariate. Multiplicity corrections (Sidak, Bonferroni) are applied within each analysis scale across covariates.

Interpretation:

• balanced_by_interval = TRUE: model bootstrap CI overlaps the chance interval (boot_lo <= chance_hi) – no evidence of residual imbalance for this covariate.

• residual_imbalance = TRUE: model CI clears chance (boot_lo > chance_hi) – residual imbalance detected.

Value

A list of class "oda_balance_effect_table" with:

rows

Data frame; one row per covariate $\times$ analysis scale. Columns: attribute, analysis, metric, estimate, boot_lo, boot_hi, chance_lo, chance_hi, p_mc, p_sidak, p_bonferroni, rule_summary, sensitivity, specificity, n_total, balanced_by_interval, residual_imbalance.

meta

List of metadata: n_covariates, n_obs, has_weights, compare_weights, analyses, nboot, chance_iter, ci, mc_iter, mc_seed.

References

Linden A, Yarnold PR (2016). Using machine learning to assess covariate balance in matching studies. Journal of Evaluation in Clinical Practice, 22(6), 861-867.

See Also

oda_balance_table, plot_oda_balance_effects

Examples

set.seed(1)
group <- c(rep(0L, 30), rep(1L, 30))
X <- data.frame(
  age   = c(rnorm(30, 45, 8), rnorm(30, 55, 8)),
  score = rnorm(60, 50, 10)
)
et <- oda_balance_effect_table(group, X,
                                nboot = 50L, chance_iter = 50L,
                                mc_iter = 200L, mc_seed = 1L)
et$rows[, c("attribute", "estimate", "boot_lo", "boot_hi",
            "chance_lo", "chance_hi", "balanced_by_interval")]

Description

Transforms an oda_balance_table result (and optionally an smd_balance_table result) into a renderer-independent data structure suitable for Graphics v3 plotting.

Usage

oda_balance_plot_data(
  balance_table,
  smd_table = NULL,
  p_col = c("p_mc", "p_sidak", "p_bonferroni"),
  rank_by = c("abs_ess", "p", "abs_smd")
)

Arguments

Details

This function does not fit any ODA models and does not accept group or X arguments. It is a pure transformation of pre-computed balance tables.

Value

A list of class "oda_balance_plot_data" with elements:

rows

Data frame; one row per covariate, sorted by rank_by. Columns: attribute, attr_type, ess_display, ess_display_bar (clipped to [0, 100]), p_plot (selected p column), significant, significance_label ("*" or ""), rule_summary, abs_smd, wsmd_available, abs_smd_display (weighted if active), fit_ok, rank.

has_weights

Logical.

ess_label

Character; "WESS" or "ESS".

p_col_used

Character; selected p column name.

alpha

Numeric; significance threshold from metadata.

n_covariates

Integer.

n_significant

Integer; covariates significant on p_col_used.

rank_by

Character.

See Also

oda_balance_table, smd_balance_table

Examples

set.seed(1)
group <- c(rep(0L, 30), rep(1L, 30))
X     <- data.frame(age   = c(rnorm(30, 45, 8), rnorm(30, 55, 8)),
                    score = rnorm(60, 50, 10))
bt  <- oda_balance_table(group, X, mcarlo = TRUE, mc_iter = 500L)
smd <- smd_balance_table(group, X)
pd  <- oda_balance_plot_data(bt, smd_table = smd)
pd$rows[, c("attribute", "ess_display", "p_plot", "significant", "abs_smd")]

Description

Fits a univariate ODA model for each covariate in X with group as the class variable. Returns one row per covariate summarizing ODA-based balance diagnostics: rule, sensitivity, specificity, Mean PAC, ESS/WESS, and permutation p-value with Sidak and Bonferroni multiplicity corrections.

Usage

oda_balance_table(
  group,
  X,
  w = NULL,
  covariate_types = NULL,
  loo = "off",
  mcarlo = TRUE,
  mc_iter = 1000L,
  alpha = 0.05,
  adjust = c("none", "sidak", "bonferroni"),
  ...
)

Arguments

Details

Balance asks whether group membership (treatment, exposure, or study arm) can be predicted from observed baseline covariates. When no covariate predicts group membership above chance, the groups are considered balanced on those covariates under the declared analytic constraints.

group vs. outcome: group is the binary class variable in every ODA call. The scientific outcome of interest is strictly out of scope; do not pass the outcome as group or as a column of X.

SMD: conventional standardized mean difference is a companion diagnostic, not the oda balance objective. Use smd_balance_table for the conventional companion table.

Value

A list of class "oda_balance_table" with elements:

rows

Data frame; one row per covariate. Key columns: attribute, attr_type, n_total, n_group_0, n_group_1, sensitivity, specificity, mean_pac, ess, wess, ess_display (operative measure), p_mc, p_sidak, p_bonferroni, significant_raw, significant_sidak, significant_bonferroni, significant (driven by adjust), rule_type, rule_summary, loo_status, ess_loo, has_weights, fit_ok, fit_reason.

meta

List of metadata: n_covariates, n_obs, has_weights, ess_label, alpha, adjust, k_valid (number of covariates with valid p_mc used for multiplicity correction), loo_mode, mcarlo, mc_iter.

References

Linden A, Yarnold PR (2016). Using machine learning to assess covariate balance in matching studies. Journal of Evaluation in Clinical Practice, 22(6), 861-867.

See Also

smd_balance_table, oda_balance_plot_data, oda_fit

Examples

set.seed(1)
n <- 60
group <- c(rep(0L, 30), rep(1L, 30))
X <- data.frame(
  age    = c(rnorm(30, 45, 8), rnorm(30, 55, 8)),   # imbalanced
  score  = rnorm(60, 50, 10)                         # balanced
)
bt <- oda_balance_table(group, X, mcarlo = TRUE, mc_iter = 500L)
bt$rows[, c("attribute", "ess_display", "p_mc", "significant_raw")]

Description

Select the best K-segment ordered partition by MegaODA spec: PRIMARY -> SECONDARY -> FIRST IDENTIFIED (enum order via tick()).

Usage

oda_best_ordered_multiclass_partition(
  x_rep,
  counts_obj,
  counts_raw,
  K,
  priors_on_eff = TRUE,
  degen = FALSE,
  primary = NULL,
  secondary = NULL,
  cut_value_mode = c("midpoint", "lower", "upper"),
  debug_return_ties = FALSE,
  debug_max_ties = 200L,
  direction = "off"
)

Arguments

Value

List with ok, cuts_idx, cut_values, seg_cls_idx, primary_obj, secondary_obj, best_enum_id, ties, classes.

Description

Replaces all values in miss_codes with replacement (default NA). Accepts a numeric vector or a data frame. Does not modify the class variable or weight vector — pass those separately if needed.

Usage

oda_clean_missing_codes(X, miss_codes, replacement = NA)

Arguments

Value

Object of the same class and dimensions as X with miss_codes values replaced.

Description

Retrieve a confusion matrix from a fitted ODA model

Usage

oda_confusion(fit, split = c("train", "loo"), weighted = FALSE)

Arguments

Value

The confusion object stored on the fit, or NULL.

Description

Compute a weighted binary confusion table from actual and predicted labels.

Usage

oda_confusion_binary(y, y_pred, w = NULL)

Arguments

Value

Named list with integer count fields TP, TN, FP, FN (weighted sums), and rate fields sensitivity, specificity (proportions in [0, 1]), and mean_pac (proportion in [0, 1]).

Note: With unit weights these are raw integer counts. With prior-odds weights (from oda_univariate_core with priors_on = TRUE) they are weighted counts, not raw integers.

Description

Compute a weighted multiclass confusion matrix with PAC and PV summaries.

Usage

oda_confusion_multiclass(y, y_pred, w = NULL)

Arguments

Value

Named list:

confusion

C x C numeric matrix of weighted counts. With unit weights these are raw integer observation counts. Rows are actual classes; columns are predicted classes.

correct

Total weighted count of correct classifications.

overall_acc

Overall accuracy as a proportion [0, 1].

pac_by_class

Per-class sensitivity as proportions [0, 1].

mean_pac

Mean sensitivity across classes, proportion [0,1].

pv_by_class

Per-class predictive value, proportions [0, 1].

mean_pv

Mean predictive value, proportion [0, 1].

Description

Internal CTA engine name retained for backward compatibility. Users should prefer cta_fit() as the public entry point.

Builds a classification tree by recursively applying ODA at each node. At each split, all attributes are evaluated and the attribute with the highest ESS passing the significance threshold is selected. Matches MegaODA CTA behaviour including MINDENOM, PRUNE, ENUMERATE, LOO STABLE, and WEIGHT parameters.

Usage

oda_cta_fit(X, y, w = NULL, priors_on = TRUE, miss_codes = NULL,
  alpha_split = 0.05, mindenom = 5L, prune_alpha = 1.0,
  max_depth = 10L, ess_min = 0,
  mc_iter = 25000L, mc_target = 0.05, mc_stop = 99.9, mc_stopup = NULL,
  mc_seed = NULL, loo = "off", attr_names = NULL, K_segments = NULL,
  verbose = FALSE, diag_env = NULL)

Arguments

Value

An object of class cta_tree containing:

nodes

Named list of node objects, each with fields: node_id, parent_id, depth, n_obs, n_weighted, attribute, rule, ess, p_mc, loo_status, loo_ess, confusion, child_ids, split_labels, majority_class, leaf.

root_id

Integer ID of the root node.

n_nodes

Total number of nodes grown.

Use predict.cta_tree to classify new data and cta_node_table to extract the node summary table.

See Also

predict.cta_tree, cta_node_table

Examples

## Binary CTA on mtcars
data(mtcars)
mt <- mtcars
X  <- mt[, c("cyl","disp","hp","wt")]
y  <- as.integer(mt$am)
tree <- oda_cta_fit(X, y, alpha_split = 0.05, mindenom = 5L,
                    mc_iter = 500L, mc_seed = 42L)
print(tree)
preds <- predict(tree, X)
mean(preds == y)   # training accuracy

Description

D measures the distance between a model's classification accuracy (ESS) and chance, expressed relative to the number of terminal prediction strata. Formula: $D = \frac{100}{ESS / strata} - strata$, where strata counts terminal prediction endpoints only.

Usage

oda_d_stat(fit)

Arguments

Details

Supported rule types and strata definitions:

• Binary (oda_fit_binary): strata = 2, ESS = fit$ess.

• Multiclass ordered (multiclass_ordered rule): strata = length(fit$rule$seg_classes), ESS = fit$ess.

• Multiclass nominal/categorical: returns NA_real_ (strata count is ambiguous without additional canon specification).

• Failed fit (ok = FALSE): returns NA_real_.

Value

A scalar numeric D value, or NA_real_ when the fit failed or the rule type does not have an unambiguous strata count.

Description

Compute Effect Strength for Sensitivity from mean PAC or mean PV for a problem with C classes.

Usage

oda_ess_from_mean(mean_metric, C)

Arguments

Value

ESS as a percentage [0, 100]. Chance baseline is 1/C.

Description

Compute ESS (Effect Strength for Sensitivity) in percent, scaled against a chance baseline.

Usage

oda_ess_from_meanpac(mean_pac, chance)

Arguments

Value

ESS as a percentage [0, 100].

Description

Unified entry point for Optimal Data Analysis. Dispatches to the binary-class engine when the outcome has exactly two distinct values, or the multiclass engine for three or more classes. This is the function CTA nodes call at each split candidate.

Usage

oda_fit(x, y, w = NULL,
        attr_type = c("auto","ordered","categorical","binary"),
        priors_on = TRUE, K_segments = NULL, degen = FALSE,
        miss_codes = NULL, missing_code = NULL,
        mcarlo = TRUE, mc_iter = 25000L, mc_target = 0.05,
        mc_stop = 99.9, mc_stopup = NA, mc_seed = NULL,
        loo = "off",
        boundary_mode = c("megaoda_halfopen","right_closed"),
        eval_order = c("mc_then_loo","loo_then_mc"),
        mindenom = 1L,
        direction = c("both","off","greater","less","ascending","descending"),
        direction_map = NULL)

Arguments

Value

A named list with components:

ok

Logical; TRUE if a valid model was found.

reason

Character reason string if ok = FALSE.

rule

The fitted rule (list; structure depends on attr_type and engine).

n_eff

Number of observations used (after missing removal).

ess

Effect Strength for Sensitivity (percent), scaled 0–100.

pac

Percentage Accuracy in Classification (training).

p_mc

Monte Carlo p-value, or NA if mcarlo = FALSE.

loo

LOO results list, or NULL if loo = "off".

engine

Character; "binary" or "multiclass".

confusion

Confusion table. For the binary engine this is a list with integer counts TP, TN, FP, FN plus sensitivity and specificity as proportions [0,1]. For the multiclass engine this is a numeric matrix of (possibly weighted) counts.

Examples

## Binary (C = 2)
x <- c(1,2,3,4,5,6,7,8)
y <- c(0L,0L,0L,0L,1L,1L,1L,1L)
fit <- oda_fit(x, y, mcarlo = FALSE)
fit$ok
fit$rule$cut_value

## Multiclass (C = 3)
x3 <- c(1,2,3,4,5,6,7,8,9)
y3 <- c(1L,1L,1L,2L,2L,2L,3L,3L,3L)
fit3 <- oda_fit(x3, y3, mcarlo = FALSE)
fit3$rule$cut_values
fit3$rule$seg_classes

Description

Uses the same type-inference logic as oda_fit() (“auto” mode) to report the likely ODA attribute type for each column.

Usage

oda_infer_attr_types(X, miss_codes = NULL)

Arguments

Value

Data frame with one row per column in X: attribute (character), inferred_type (one of "ordered", "categorical", "binary"), n_unique (integer, excluding miss_codes and NA), n_missing (integer, NA count), n_miss_code (integer, miss_code hit count).

See Also

oda_fit, oda_clean_missing_codes

Description

Leave-one-out cross-validation for ordered multiclass ODA.

Usage

oda_loo_multiclass_ordered(
  x,
  y,
  w0,
  priors_on_eff,
  degen,
  K_segments,
  miss_codes = NULL,
  cut_value_mode = c("midpoint", "lower", "upper"),
  grid_mode = c("fixed", "refit"),
  boundary_mode = c("megaoda_halfopen", "right_closed"),
  loo_use_samplerep = FALSE,
  loo_return_folds = FALSE,
  loo_priors_mode = c("fold", "global")
)

Arguments

Value

List with allowed, confusion_raw, confusion_weighted, y_pred, and optional fold_rule, fold_debug, fold_best_enum_id.

Description

Monte Carlo Fisher-randomization p-value with Clopper-Pearson early stopping.

Usage

oda_mc_p_value(
  x,
  y,
  w = NULL,
  attr_type,
  priors_on,
  primary,
  secondary,
  miss_codes = NULL,
  chance_model = c("class", "attribute"),
  mc_iter = 25000L,
  mc_target = 0.05,
  mc_stop = 99.9,
  mc_stopup = NA,
  mc_adjust = FALSE,
  seed = NULL,
  ess_obs = NULL,
  direction = c("both", "off", "greater", "less"),
  direction_map = NULL
)

Arguments

Value

List with p_mc, ge_count, iter_used, ess_obs.

Description

Compute mean Percentage Accuracy in Classification.

Usage

oda_mean_pac(sens, spec)

Arguments

Value

Mean PAC as a proportion [0, 1].

Description

Returns a list of scalar metrics present on the fit. No quantities are recomputed; absent fields appear as NA_real_. LOO p-value uses 2x2 Fisher exact when stored and available (p_status = "computed"); if the value is absent or NA the status is "not_computed" with an explicit reason. Multiclass/polychotomous LOO always returns p_status = "not_computed".