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.
state_symbols2labels(nex, charmat, metacolumns = c(1, 2))the nexml object from which the character matrix was obtained
the character matrix (as a data.frame, usually obtained using get_char_matrix())
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.
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).
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.
If the nexml object contains multiple character matrices, currently the character labels must be distinct between them.
# 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
#> taxa otu anterior dentation of pectoral fin spine
#> 1 Ameiurus brunneus VTO_0036273 1
#> 2 Ameiurus catus VTO_0036275 1
#> 3 Ameiurus melas VTO_0036272 NA
#> 4 Ameiurus natalis VTO_0036274 NA
#> 5 Ameiurus nebulosus VTO_0036278 1
#> 6 Ameiurus platycephalus VTO_0036276 1
#> 7 Ameiurus serracanthus VTO_0036277 1
#> 8 Ictalurus australis VTO_0061495 1
#> 9 Ictalurus balsanus VTO_0036221 0
#> 10 Ictalurus dugesii VTO_0061497 NA
#> 11 Ictalurus furcatus VTO_0036223 0
#> 12 Ictalurus lupus VTO_0036220 1
#> 13 Ictalurus mexicanus VTO_0061498 NA
#> 14 Ictalurus pricei VTO_0036218 1
#> 15 Ictalurus punctatus VTO_0036225 1
#> anterior distal serration of pectoral fin spine
#> 1 1
#> 2 1
#> 3 0 and 1
#> 4 1
#> 5 1
#> 6 1
#> 7 1
#> 8 1
#> 9 0 and 1
#> 10 1
#> 11 1
#> 12 1
#> 13 1
#> 14 1
#> 15 1
# translate symbols to labels without having to re-obtain the matrix
state_symbols2labels(nex, m)
#> taxa otu anterior dentation of pectoral fin spine
#> 1 Ameiurus brunneus VTO_0036273 present
#> 2 Ameiurus catus VTO_0036275 present
#> 3 Ameiurus melas VTO_0036272 <NA>
#> 4 Ameiurus natalis VTO_0036274 <NA>
#> 5 Ameiurus nebulosus VTO_0036278 present
#> 6 Ameiurus platycephalus VTO_0036276 present
#> 7 Ameiurus serracanthus VTO_0036277 present
#> 8 Ictalurus australis VTO_0061495 present
#> 9 Ictalurus balsanus VTO_0036221 absent
#> 10 Ictalurus dugesii VTO_0061497 <NA>
#> 11 Ictalurus furcatus VTO_0036223 absent
#> 12 Ictalurus lupus VTO_0036220 present
#> 13 Ictalurus mexicanus VTO_0061498 <NA>
#> 14 Ictalurus pricei VTO_0036218 present
#> 15 Ictalurus punctatus VTO_0036225 present
#> anterior distal serration of pectoral fin spine
#> 1 present
#> 2 present
#> 3 present and absent
#> 4 present
#> 5 present
#> 6 present
#> 7 present
#> 8 present
#> 9 present and absent
#> 10 present
#> 11 present
#> 12 present
#> 13 present
#> 14 present
#> 15 present
# 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))
#> taxa otu otus
#> 1 Ameiurus brunneus VTO_0036273 tcb028860-571e-478a-9449-947a521946a1
#> 2 Ameiurus catus VTO_0036275 tcb028860-571e-478a-9449-947a521946a1
#> 3 Ameiurus melas VTO_0036272 tcb028860-571e-478a-9449-947a521946a1
#> 4 Ameiurus natalis VTO_0036274 tcb028860-571e-478a-9449-947a521946a1
#> 5 Ameiurus nebulosus VTO_0036278 tcb028860-571e-478a-9449-947a521946a1
#> 6 Ameiurus platycephalus VTO_0036276 tcb028860-571e-478a-9449-947a521946a1
#> 7 Ameiurus serracanthus VTO_0036277 tcb028860-571e-478a-9449-947a521946a1
#> 8 Ictalurus australis VTO_0061495 tcb028860-571e-478a-9449-947a521946a1
#> 9 Ictalurus balsanus VTO_0036221 tcb028860-571e-478a-9449-947a521946a1
#> 10 Ictalurus dugesii VTO_0061497 tcb028860-571e-478a-9449-947a521946a1
#> 11 Ictalurus furcatus VTO_0036223 tcb028860-571e-478a-9449-947a521946a1
#> 12 Ictalurus lupus VTO_0036220 tcb028860-571e-478a-9449-947a521946a1
#> 13 Ictalurus mexicanus VTO_0061498 tcb028860-571e-478a-9449-947a521946a1
#> 14 Ictalurus pricei VTO_0036218 tcb028860-571e-478a-9449-947a521946a1
#> 15 Ictalurus punctatus VTO_0036225 tcb028860-571e-478a-9449-947a521946a1
#> anterior dentation of pectoral fin spine
#> 1 present
#> 2 present
#> 3 <NA>
#> 4 <NA>
#> 5 present
#> 6 present
#> 7 present
#> 8 present
#> 9 absent
#> 10 <NA>
#> 11 absent
#> 12 present
#> 13 <NA>
#> 14 present
#> 15 present
#> anterior distal serration of pectoral fin spine
#> 1 present
#> 2 present
#> 3 present and absent
#> 4 present
#> 5 present
#> 6 present
#> 7 present
#> 8 present
#> 9 present and absent
#> 10 present
#> 11 present
#> 12 present
#> 13 present
#> 14 present
#> 15 present