state_symbols2labels: Translates state symbols to labels in a character matrix

In xu-hong/rphenoscape: Semantically Rich Phenotypic Traits from the Phenoscape Knowledgebase

Translates state symbols to labels in a character matrix

Description

Translates a character matrix using symbols for states to one using labels instead. The character matrix must have been obtained from a nexml object, usually using get_char_matrix(), and the nexml object is required for the translation.

Usage

state_symbols2labels(nex, charmat, metacolumns = c(1, 2))

Arguments

nex	the nexml object from which the character matrix was obtained
charmat	the character matrix (as a data.frame, usually obtained using get_char_matrix())
metacolumns	the indexes of the columns in the matrix that contain metadata (such as taxa, identifiers, etc), not character states. If not all of these columns are before all character columns, then the returned matrix will move all of them to the front. The default is the first two columns.

Details

If state labels are missing for some characters, a warning will be issued. If the nexml object has no state labels at all, a warning will be issued and no translation will be attempted. If a symbol cannot be matched to a state definition in the nexml object, or if the matching state definition does not give a label for the state, the symbol will not be translated.

Value

A data.frame of the character matrix, with cells as state labels instead of symbols, and rows and columns in the same order as the input matrix (see parameter metacolumns for a possible exception). The data types of the columns may change as a result of translation, and even if no translation can take place (due to missing state labels) (although in the absence of translation a numeric type column should still have a numeric type).

Note

If the nexml object contains multiple character matrices, currently the character labels must be distinct between them.

Examples

# obtain a (synthetic) Ontotrace matrix:
nex <- get_ontotrace_data(taxon = c("Ictalurus", "Ameiurus"), entity = "fin spine")
m <- get_char_matrix(nex, otus_id = FALSE)
# by default it uses symbols
m
# translate symbols to labels without having to re-obtain the matrix
state_symbols2labels(nex, m)
# if we obtained the matrix with otus_id, then we have one more metadata column
m <- get_char_matrix(nex, otus_id = TRUE)
state_symbols2labels(nex, m, metacolumns = c(1,2,3))

xu-hong/rphenoscape documentation built on Jan. 28, 2024, 12:22 p.m.