Prepare matrices for phylogenetic analysis

PrepareMatrix() constructs a processed morphological matrix and its derivatives for downstream phylogenetic analysis. It reads a raw character matrix and corresponding metadata spreadsheet from the directory specifed in .config$matrixDir (default: /matrices), applies standardization rules, re-codes characters according to the annotation patterns, and outputs curated NEXUS files for use in subsequent inference.

PrepareMatrix(pID, overwrite = FALSE)

Arguments

pID

Character giving the project identifier, e.g. "1210" for MorphoBank project 1210. Identifiers beginning with "072" refer to matrices from doi:10.1093/sysbio/syab072 , corresponding to files named syab<pID>.nex.

overwrite

Logical; whether to overwrite existing processed files. Defaults to FALSE.

Value

PrepareMatrix() invisibly returns TRUE if processing succeeds, or FALSE if matrix preparation cannot proceed (e.g., due to missing informative characters). The function is called primarily for its side-effect of producing standardized NEXUS matrix files in the appropriate output directory.

Details

Each character is categorized as neomorphic (presence/absence), transformational (multi-state), or ignored according to the pattern specified in the metadata file. Inapplicable tokens in neomorphic characters are converted to absences (0) following (Brazeau 2011) . Characters may also be translated according to custom mapping patterns defined in the spreadsheet.

The function creates four main output files at the path specified by MatrixFile(pID):

*.nex

Full processed matrix.

*-neo.nex

Subset containing informative neomorphic characters.

*-trans.nex

Subset containing informative transformational characters.

*-neo-rand.nex, *-trans-rand.nex

Matched random subsets for comparative analysis.

The function expects metadata spreadsheets formatted according to the matrix-processing vignette, containing at least the columns "Character Pattern" and "Unseen States". Character patterns define how tokens are grouped and interpreted; invalid or mismatched patterns will trigger diagnostic errors. Parsimony-uninformative characters (which define no non-trivial bipartitions) are excluded from subset matrices.

The function automatically sanitizes taxon names for NEXUS compatibility and ensures that neomorphic characters are strictly binary (0, 1). Multi-state characters are re-encoded so that their state tokens form a contiguous sequence starting from zero.

References

Brazeau MD (2011). “Problematic Character Coding Methods in Morphology and Their Effects.” Biological Journal of the Linnean Society, 104(3), 489–498. doi:10.1111/j.1095-8312.2011.01755.x .