What's CMAPLE library?

CMAPLE is a C++ reimplementation of MAPLE - a novel likelihood-based phylogenetic inference method for pandemic-scale epidemiological genomic data. CMAPLE is highly optimized for performance and scalability with many new features.

CMAPLE library provides a set of APIs, which allow users to integrate CMAPLE into existing phylogenetic inference methods.

How to use?

In the following, we give an instruction of how to include CMAPLE library into a project using CMake build system (instructions for other build systems will be updated soon). Here, we'll take IQ-TREE as an example.

Include CMAPLE as a submodule of your project

In your project directory, run

    git submodule add https://github.com/iqtree/cmaple.git

Update CMakeList to include CMAPLE

    project(iqtree)

    # Step 1: Add cmaple directory to the build
    add_subdirectory(cmaple)
    # add the main and other directories of your project
    add_subdirectory(main)

    # Step 2: Build two executables for DNA and protein data
    # build an executable for DNA data
    add_executable(iqtree2
        main.cpp main.h
    )
    # build another executable for protein data
    add_executable(iqtree2-aa
        main.cpp main.h
    )

    # Step 3: Add the binary tree to the search path for include files so that we can find cmaple/cmaple_config.h
    include_directories("${PROJECT_BINARY_DIR}/cmaple")

    # Step 4: Add linking libraries
    target_link_libraries(iqtree2 main maple)
    target_link_libraries(iqtree2-aa main maple-aa)

An example of APIs usage

    #include “cmaple.h”

    // Create an alignment from a file
    cmaple::Alignment aln("alignment.maple");

    // Check if the input alignment is suitable for using [C]Maple method
    if (cmaple::checkMapleSuitability(aln))
    {
        // Create a default model according to the data type from the alignment (i.e., GTR for DNA, and LG for protein data)
        cmaple::Model model(cmaple::ModelBase::DEFAULT, aln.getSeqType());

        // Create a tree, attach the alignment and model to the tree
        cmaple::Tree tree(&aln, &model);

        // Infer a phylogenetic tree from the alignment and the model using [C]Maple algorithm
        tree.autoProceedMAPLE();

        // Compute the branch supports for the inferred tree
        tree.computeBranchSupport();

        // Compute the likelihood of the tree
        cout << "- Tree log likelihood: " << tree.computeLh() << endl;

        // Export the tree (with branch supports) in NEWICK format
        cout << "- Tree: " << tree.exportNewick("cmaple::Tree::BIN_TREE, true) << endl;
    }
    else
    {
        // Execute existing methods (e.g., IQ-TREE, RAXML, PHYML) to analyse this alignment
    }

Tips for Debugging

CMAPLE outputs debugging messages to the standard output std::cout. One could control the amount of those messages via setting cmaple::verbose_mode to one of the following values.
- VB_QUIET: no messages except errors.
- VB_MED (default): common messages (showing the processing progress).
- VB_DEBUG: as many messages as possible (useful for debugging).

More APIs?

CMAPLE APIs are exposed in the following.
CMaple
Alignment
Model
Tree

How to cite CMAPLE?

To be updated...