Identification of trait emergence and clustering of trait across the phylogeny using transition data

This function identifies episodes of trait emergence and loss across a phylogenetic tree.

Usage

asr_cluster_detection(
  df,
  tr,
  tip_name_variable,
  patient_id = NULL,
  parent_child_df,
  node_states = "joint",
  confidence = NULL,
  simplify_faux_clusters = FALSE,
  simplify_revertant = TRUE,
  collapse_cluster = TRUE
)

Arguments

df

Dataframe with tip name variable and phenotype

tr

Phylogenetic tree

tip_name_variable

Name of variable containing tip names in df

patient_id

Name of variable containing patient IDs, can be combined with faux_clusters option to factor into whether a cluster should have >1 patient. (Optional)

parent_child_df

Parent child dataframe from asr() object

node_states

Whether the reconstruction was "joint" or "marginal"

confidence

Whether to use 'high' (i.e., 0 -> 1) or 'low' (i.e., any transition) confidence transitions when determining clustering with marginal ancestral state reconstruction results. If the confidence_threshold value in asr() was > 0.5, set confidence as 'low'. Otherwise, set confidence as 'high'.

simplify_faux_clusters

Boolean (i.e., TRUE/FALSE), whether to collapse faux clusters (i.e., clusters where 1 patient contributes all isolates) as singletons without distinction (Optional)

simplify_revertant

Boolean (i.e., TRUE/FALSE). Whether to collapse revertant episodes as isolates without the trait in the cleaned text string

collapse_cluster

Boolean (i.e., TRUE/FALSE). Whether to create a variable that collapses cluster calls into one category

Value

A tip-only dataframe with inferences on the ancestral history of these strains. Can be merged with parent_child_df from asr() if desired

asr_cluster

Character string indicating cluster calls (cluster_[node]), singleton calls, traits without the feature (no feature), and revertant cases at the tip (revertant_tip) or clusters of revertants (revertant_cluster_[node]). If patient_id != NULL, additional calls may be provided where a cluster contains only one patient (cluster_[node]_1pt_only)

patient_id

Character string with the patient ID, if provided

asr_cluster_renamed

Character string where asr_cluster string was renamed as cluster [no. X], singletons, no feature. Clusters are ordered by presentation via ggtree. If simplify_revertant == TRUE, revertants are collapsed as 'No feature'

asr_cluster_collapsed

Character string where asr_cluster string was collapsed into cluster, singleton, no feature, and revertant. If simplify_revertant == TRUE, revertants are collapsed as 'No feature'