| Title: | Mixed-Effects Conditional Inference Trees as Identification Keys |
|---|---|
| Description: | Fits decision trees to clustered data while a random effect absorbs the differences between clusters, so the tree splits only on variables that matter within clusters. Implements RE-EM trees with conditional inference trees (Fu and Simonoff 2015, <doi:10.1016/j.csda.2015.02.004>) and wraps the model-based version in 'glmertree' (Fokkema et al. 2018, <doi:10.3758/s13428-017-0971-x>). A fitted tree converts to a 'dimoose' dichotomous key, and expression data can be simulated on the human mitochondrial DNA phylogeny to test the method. A companion to the 'dimoose' package. |
| Authors: | Jeremy Leipzig [aut, cre] (ORCID: <https://orcid.org/0000-0001-7224-9620>) |
| Maintainer: | Jeremy Leipzig <[email protected]> |
| License: | GPL (>= 3) |
| Version: | 0.1.0 |
| Built: | 2026-11-21 04:27:28 UTC |
| Source: | https://github.com/leipzig/mecit |
Each split becomes a couplet and each terminal node a result, labelled
with its stratum level and size. Splits on 0/1 variables read as
"Carries 16311" / "Does not carry 16311". The leads carry machine-readable
tests on the split variables, so dimoose::classify() can place new samples given
their dimoose::haplotypeMatrix(), and dimoose::exportWizard() can draw the tree.
Splits on factor columns become text-only couplets ("tissue is liver or
lung"), which a person can follow but dimoose::classify() cannot; the function
warns when the key has any.
keyFromMecit(fit, desc = NULL, digits = 2)keyFromMecit(fit, desc = NULL, digits = 2)
fit |
A |
desc |
Title of the key. |
digits |
Decimal places for stratum levels. |
A dimoose::dimoose key.
sim <- simulateExpression(n = 600, genes = 6) fit <- mecit(sim$expr[, 1], sim$X, sim$samples$macro) key <- keyFromMecit(fit) head(dimoose::classify(key, sim$X))sim <- simulateExpression(n = 600, genes = 6) fit <- mecit(sim$expr[, 1], sim$X, sim$samples$macro) key <- keyFromMecit(fit) head(dimoose::classify(key, sim$X))
Fits a tree that partitions observations on candidate split variables (for
example which mutations each sample carries, from dimoose::haplotypeMatrix())
while a random effect absorbs differences between clusters (for example
macrohaplogroups, from dimoose::macroHaplogroup()). Without the random effect, a
tree also splits on variables that merely track the clusters, such as
clade-defining markers; with it, those differences are removed before the
tree looks for splits.
mecit( y, partition, cluster = NULL, method = c("ctree", "mob"), slope = NULL, alpha = 0.05, minbucket = 20L, maxdepth = Inf, ranefstart = TRUE, abstol = 0.001, maxit = 50L )mecit( y, partition, cluster = NULL, method = c("ctree", "mob"), slope = NULL, alpha = 0.05, minbucket = 20L, maxdepth = Inf, ranefstart = TRUE, abstol = 0.001, maxit = 50L )
y |
Numeric response, one value per observation. |
partition |
Matrix or data frame of candidate split variables, one row
per observation, with column names (which may be non-syntactic, like
|
cluster |
Cluster of each observation, or |
method |
|
slope |
Optional names of |
alpha |
Significance level for splitting (Bonferroni-adjusted over the candidate variables). |
minbucket |
Smallest allowed terminal node. |
maxdepth |
Maximum tree depth. |
ranefstart |
If |
abstol, maxit
|
Convergence tolerance and the maximum number of
iterations. For |
method = "ctree" (the default) is the RE-EM algorithm of Sela & Simonoff
(2012) with conditional inference trees, as proposed by Fu & Simonoff
(2015). It alternates between (1) a partykit::ctree() on the response
minus the current random-effect contribution and (2) a linear mixed model
(lme4::lmer()) with one fixed effect per terminal node plus the random
effects, until the random effects stop changing. method = "mob" uses
model-based partitioning through glmertree::lmertree() (Fokkema et al.
2018). In both, ranefstart = TRUE estimates the random effects from an
intercept-only mixed model before the first tree, which keeps that tree from
splitting on cluster-level variables.
With cluster = NULL the result is a plain conditional inference tree, the
baseline a mixed-effects tree is compared with.
An object of class mecit: tree (a partykit tree), lmer (the
final mixed model, or NULL), strata (data frame of node, mean
and n; mean is the stratum level net of random effects), node
(terminal node of each observation), ranef (random-effect
contribution of each observation), method, iterations and
converged.
Sela RJ, Simonoff JS (2012). RE-EM trees: a data mining approach for longitudinal and clustered data. Machine Learning 86, 169-207. doi:10.1007/s10994-011-5258-3
Fu W, Simonoff JS (2015). Unbiased regression trees for longitudinal and clustered data. Computational Statistics & Data Analysis 88, 53-74. doi:10.1016/j.csda.2015.02.004
Fokkema M, Smits N, Zeileis A, Hothorn T, Kelderman H (2018). Detecting treatment-subgroup interactions in clustered data with generalized linear mixed-effects model trees. Behavior Research Methods 50, 2016-2034. doi:10.3758/s13428-017-0971-x
splitVariables(), keyFromMecit(), simulateExpression()
sim <- simulateExpression(n = 600, genes = 6) fit <- mecit(sim$expr[, 1], sim$X, sim$samples$macro) fit splitVariables(fit) key <- keyFromMecit(fit) key$leads[, c("Statement", "Character", "Next", "Taxon")] ## Not run: dimoose::exportWizard(key, "mecit.html") ## End(Not run)sim <- simulateExpression(n = 600, genes = 6) fit <- mecit(sim$expr[, 1], sim$X, sim$samples$macro) fit splitVariables(fit) key <- keyFromMecit(fit) key$leads[, c("Statement", "Character", "Next", "Taxon")] ## Not run: dimoose::exportWizard(key, "mecit.html") ## End(Not run)
Simulates per-sample expression for a set of genes, where recurrent
mutations (variants that arise independently on many branches) shift
expression by fixed amounts on top of a baseline that differs between
macrohaplogroups. It is the ground truth for testing mecit(): a good
method finds the mutation effects as splits and does not split on clade
markers that only track the macrohaplogroup baselines.
simulateExpression( n = 1000, genes = 20, effectSites = c("16362", "150", "709", "16093"), propMutation = 0.4, propBaseline = 0.3, sitesPerGene = 1:2, effect = 1, macroSD = 1, slopeSD = 0, noise = 1, decoys = NULL, macroLevel = "letter", seed = 1 )simulateExpression( n = 1000, genes = 20, effectSites = c("16362", "150", "709", "16093"), propMutation = 0.4, propBaseline = 0.3, sitesPerGene = 1:2, effect = 1, macroSD = 1, slopeSD = 0, noise = 1, decoys = NULL, macroLevel = "letter", seed = 1 )
n |
Number of samples. |
genes |
Number of genes. |
effectSites |
Sites that can carry mutation effects. |
propMutation, propBaseline
|
Proportions of mutation and baseline genes; the rest are null. |
sitesPerGene |
Possible numbers of effect sites per mutation gene. |
effect |
Size of each mutation effect (its sign is random). |
macroSD |
Standard deviation of the macrohaplogroup baselines. |
slopeSD |
If positive, each mutation effect also varies between macrohaplogroups with this standard deviation (a random slope). |
noise |
Residual standard deviation. |
decoys |
Extra candidate split sites with no effect. By default the most recurrent other sites plus the markers of the four most common macrohaplogroups in the sample. |
macroLevel |
Passed to |
seed |
Random seed. |
Samples are drawn uniformly from the leaf haplogroups of dimoose::phylotree17, so their macrohaplogroups are as unbalanced as the tree itself (H is far more common than L5). For sample i and gene g:
expr[i, g] = b[g, macro(i)] + sum_s beta[g, s] * X[i, s] + slope + noise
Genes come in three kinds: "mutation" genes have a baseline and one or
more mutation effects, "baseline" genes have only the macrohaplogroup
baseline, and "null" genes are pure noise.
The default effect sites (16362, 150, 709, 16093) are highly recurrent but carried by a minority of lineages across many macrohaplogroups. The most-cited recurrent sites (152, 16311, 146, 16189) are poor effect sites in RSRS orientation: they are also on deep branches (16311 is an L3 marker), so most lineages carry them and carrying them largely tracks clade membership. They are included as decoys instead.
A list with expr (samples x genes), samples (data frame of
sample, haplogroup, macro), X (samples x sites, 0/1, from
dimoose::haplotypeMatrix()), truth (beta, genes x sites; b, genes x
macrohaplogroups; geneType; and slope when slopeSD > 0),
effectSites, markerSites and decoySites.
mecit(), dimoose::haplotypeMatrix()
sim <- simulateExpression(n = 300, genes = 10) table(sim$truth$geneType)sim <- simulateExpression(n = 300, genes = 10) table(sim$truth$geneType)
Variables a fitted tree splits on
splitVariables(fit)splitVariables(fit)
fit |
A |
The names (as given in partition) of the variables used in any
split, in the order they first appear; character(0) if the tree has no
splits.
sim <- simulateExpression(n = 600, genes = 6) splitVariables(mecit(sim$expr[, 1], sim$X, sim$samples$macro))sim <- simulateExpression(n = 600, genes = 6) splitVariables(mecit(sim$expr[, 1], sim$X, sim$samples$macro))