NEXUS CLASS LIBRARY home | classes | functions

Nexus Class Library (version 2.1)

by Paul O. Lewis and Mark T. Holder

For information on the v2.0 API see v2.0index.html. The documentation below reflects usage that will only work with version 2.1. Version 2.1 is stable.

Contents

What is the NCL?

The NEXUS Class Library (NCL) is an integrated collection of C++ classes designed to parse NEXUS-formatted data files. The library has recently been extended to support several simple file-formats (PHYLIP, relaxed PHYLIP, and FASTA). NCL does not diagnose the file format, but if you configure a parser to read several formats, then you will be able to parse multiple formats and extract the data from NCL's data structures using the same API.

This documentation is written for C++ programmers.

The NEXUS data file format was specified in the publication cited below (this is a link to pdf of that paper). Please read this paper for further information about the format specification itself; the documentation for the NCL does not attempt to explain the structure of a NEXUS data file.

Maddison, D. R., D. L. Swofford, and Wayne P. Maddison. 1997. NEXUS: an extensible file format for systematic information. Systematic Biology 46(4): 590-621.

Why is version 2.1 so different from version 2.0?

Version 2.1 extends the functionality significantly by allowing NCL to parse files that use extended forms of NEXUS. Both Mesquite and MrBayes rely on extensions to NEXUS. Particularly difficult to handle are Mesquite's support for multiple blocks of the same type within a file (accompanied by linking blocks by title).

Version 2.0 of NCL followed a model of creating a NxsReader object and adding NxsBlock objects which handle parsing of particular types of NEXUS content. Client code would typically inherit from base classes such as NxsCharactersBlock, or would extract the information when a block was completely read. The NxsBlock instance would be reset (by NxsBlock::Reset call) before it was asked to handle another block.

Unfortunately, not all NEXUS blocks are autonomous (for example commands in an ASSUMPTIONS block may rely on information in a CHARACTERS block). Combining inter-block dependencies with the need to store information from multiple blocks of the same type means that NCL's version 2.0 API can be quite cumbersome. To read a file with a single instance of a NxsCharactersBlock, the client code must carefully offload all of the information in a block before allowing parsing to proceed to the next block; later references between blocks have to be corrected so that blocks refer to the new location of the information (rather than the NxsBlock instance that originally held the data).

A more natural design pattern for processing files which may have multiple blocks of the same type is to use a factory method. Users of NCL v2.1 can register NxsBlock factories with a NxsReader, and parse an entire file before having to pull the parsed information from the blocks.

Backward compatibility

Despite several fundamental changes in the implementation of the library, we strive to keep NCL v2.1 backward compatible with version 2.0. A programmer that relied on version 2.0 should still work. If you discover that your client code works with version 2.0 of NCL, but not 2.1 please let us know.

Version 2.2

The svn branch for version 2.2 is very similar to 2.1. It only contains changes necessary to allow NCL to be callable from other languages via SWIG. Some of the changes needed to ensure this were not backward-compatible. So they were added to branch 2.2.

C++ programmers should probably use 2.1 (although their code will almost certainly work on v2.2 as well)

Obtaining the NCL?

The best link to use to get the latest (stable) version of NCL is from the sourceforge NCL project page.

Characteristics of the NCL

Portability

The NCL has been designed to be as portable as possible for a C++ class library. Please let us know if you find a (reasonably modern) compiler that does not accept NCL.

Cross-platform features

NCL does not rely on any external libraries. There are hooks (such as NxsToken::OutputComment) which all messages intended for the user to be displayed in the appropriate form for your application. Thus, it is possible to create an application that does not write to standard output or to write standard input/output applications with NCL.

Extensibility

The basic tools provided in the NCL allow you to create your own NEXUS blocks and use them in your program. This makes it easy to define a private block to contain commands that only your program recognizes, allowing your users to run your program in batch mode (see the section below entitled General Advice for more information on this topic).

Detailed v2.1 documentation

Mark Holder is currently documenting v2.1 (after he changed a lot of code without updating the comments).

The current API documentation is generated from doxygen, but also includes high level discussion about recommended usage patterns.

Future Of The NCL Project

NCL is stable and not expected to change API. We continue adding enhancements (more forgiving parsing, additional formats, and improved data storage). We welcome both suggestions for improvement as well as bug reports, of course.

Version 2.2 is now generated (by a script) from version 2.1. The two versions are not expected to diverge in functionality with the exception that version 2.2 enables SWIG bindings to non-C++ languages (while 2.1 preserves function signatures to avoid breaking client code written against 2.0 and 2.1).

Back to Table of Contents

Contact Information

Paul's and Mark's current mail and email addresses as well as my phone and fax numbers are given below:

Paul O. Lewis, Assoc. Professor
Department of Ecology and Evolutionary Biology
The University of Connecticut
75 North Eagleville Road, Unit 3043
Storrs, CT 06269-3043 U.S.A.

Email: paul.lewis@uconn.edu
URL:   http://www.eeb.uconn.edu/people/plewis/

Mark T. Holder, Assist. Professor
Department of Ecology and Evolutionary Biology
The University of Kansas
Lawrence, KS 66045 U.S.A.

Email: mtholder@ku.edu
URL:   http://phylo.bio.ku.edu/mark-holder