Translator Disclaimer
7 June 2013 A New R Package, Exsic, to Assist Taxonomists in Creating Indices
Author Affiliations +

A tedious part of preparing a taxonomic monograph is collating specimen data for (1) specimen citations and (2) indices to associate collectors and collector numbers to taxonomic identifications (exsiccatae). While preparing a taxonomic monograph of wild potatoes for northern South America, we designed tools to efficiently and accurately convert specimen data into the formats specified by Systematic Botany Monographs. One of the tools is a conversion tool to reformat tabulated records into specimen citations and the other for exsiccatae. It is a specific implementation of the reproducible research approach (Gentleman and Temple Lang, 2004). A version of our software tool is freely available for R (R Core Team, 2012) at  http://cran.r-project.org/web/packages/exsic/.

METHODS AND RESULTS

Overall design of the packageThe package was designed to facilitate very specific steps in the processing of tabular specimen data: the conversion from table-oriented to index-based or list-based formats. Other necessary steps, such as data cleansing or data conversions, are not part of the main functions as there are other tools available for that purpose. That is, date conversions or geographical coordinate transformations into the final desired format must be done separately by the user and before using the exsic function. The main function assumes, therefore, correct structure and content, but has been designed to be robust and to gracefully handle missing columns or content. In the case of essential columns (for sorting or filtering, e.g., "species", "country", "collcite", "number", "majorarea", "minorarea"), these will be added and filled with meaningful values for missing content (e.g., “Anonymous” for missing collector information). However, a few convenience functions have been added to handle specific transformations, and these are explained in more detail below.

Tabular data formatAs a starting point for preparing the specimen data, we used a format based on conventions defined by the BRAHMS (Botanical Research and Herbarium Management Software) package (Filer, 2001), as detailed in an online manual (Filer, 2010). The column names used by exsic are mostly the same as those used by BRAHMS, with a few modifications and additions to facilitate both the concurrent use of the BRAHMS conventions and this package (Table 1). One is the addition of the "colldate" field for the "date of collection". The content of this field should usually have the format “1 Jan 2013”; the corresponding BRAHMS field names are: "colldd", "collmm", and "collyy" for day, month, and year, respectively. Functions in the package "date" can be used to convert from these three columns to the desired format and stored in the column "colldate". The other addition is the column or field "collcite". The information on citing collectors is stored in two BRAHMS fields: "collector" and "addcoll". A custom function ("coll.cite") is provided that helps address most formatting issues, including whether or not to use initials, whether or not to use periods after initials, and whether to cite both names for collector pairs or cite only the first and add “et al.” when there are more than two. The variations can be set using "coll.cite" function parameters. Another convenience function is called "strip.last.dot"; this is meant to process the column "locnotes" for location notes because they are separated by a comma in most specimen citations. A last variation is the use of a separate column for "phenology", with expected content to be “fl” for flowering stage, “fr” for fruiting stage, or empty for neither stage.

Target formats for specimen citations of numbered collectionsWe researched format variations using a Google search and found three additional formats to that used in Systematic Botany Monographs. The four formats (Systematic Botany Monographs [format.SBMG], American Society of Plant Taxonomists [format.ASPT], New York Botanical Garden [format.NYBG], and PhytoKeys [format.PK]) are summarized in Table 2. The main differences between these specimen citation formats relate to the formatting of species and country information as well as to differences in formatting the collector information. New York Botanical Garden journals include phenology information after the date of observation. Numbered collections formats differed with respect to using index numbers to point to the species or directly using a species. Another difference is whether consecutive numbers of the same species for a collector citation are grouped or not. The report created by the command example (exsic) creates a Web page as shown in Fig. 1. The HTML page can then be further edited and formatted using a word processor. A user's guide showing the principal usage along with a precise description of the input format can be found in the package documentation ( http://cran.r-project.org/web/packages/exsic/exsic.pdf).

TABLE 1.

The data dictionary for the primary table of specimens. Field or column names correspond largely to BRAHMS standard; sample content data are invented.

t01_01.gif

Sorting and FilteringThe specimen citation records are, by default, not filtered from the given table, and species and countries are sorted alphabetically. However, a taxonomist may want to order species by taxonomic relationships, and countries may be ordered from north to south and west to east. Also, the same table may be used for checking subsets. Therefore, to allow both filtering and custom sorting “on-the-fly,” an additional table (an R data, frame) can be defined. It has two columns, "country" and "species", where the desired countries and species may be listed separated by semicolons without spaces. To list all countries or all species, the word “all” may be used. The table may be added to the exsic function as a parameter "sortfilter". If this parameter is omitted, default options apply. A helper function to check format compliance is available (is.sortfilter). A sample "sortfilter" table is also available (sort.specs).

TABLE 2.

A comparison of the four index formats detailing the fields used in the tables format.SBMG, format. ASPT, format.NYBG, and format.PK.

t02_01.gif

UsageThe package can be downloaded from the central R repository CRAN using standard procedures in R and activated using the command "library(exsic)". A user would typically start using the main exsic function and either provide an inmemory table or a file path. For example: a table may be read using the custom function "data <- read.exsic(filepath)". This function ensures that all obligatory fields (see Table 1) are present; if not, they will be created and prefilled with placeholder text (e.g., missing collector citation in "collcite" will be replaced with “Anonymous”; missing collection numbers with “s.n.”; missing dates with “s.d.”; and missing minor area or major area information with “Unknown major/minor area”). An example table with 1000 records of wild potato specimens is included in the package and can be accessed using "system.file("samples/exsic.csv", packages="exsic")". This may take a minute to process. For quicker testing, a subset can be constructed using "pt = potato[1:10,]" which will use only the first 10 records. A complete minimal example using the provided sample table is given here:

e01_01.gif

Fig. 1.

An example result for the exsic function using five records from a sample table.

f01_01.jpg

The resulting Web page will be in the same directory called "exsic.html" (this name can be changed via a parameter).

By default, the whole table passed to exsic will be used, sorted alphabetically by species and country, and formatted according to the conventions of Systematic Botany Monographs. To see an example, one may also type “example(exsic)” in the R console. The user may modify the defaults by combinations of the following five options: (a) choose of one of four formats, (b) select a subset of species and countries, and order nonalphabetically by species or country, (c) define additional formats, (d) set section titles and the output file name, and (e) selectively execute only some of the subroutines. These options are explained below.

  • A. Choice of formats: The main exsic function has an additional parameter, "formats", that accepts tabulated parameters. The table must have only four columns named exactly as "field", "style", "sept", "comments" (for example contents see Table 2). The four formats are listed in Table 2. The default format is "format.SBMG".

  • B. The "sortfilter" is a parameter in the form of a table that must have only two columns, named "country" and "species". Within each field, countries or species must be written exactly as in the primary table and must be separated by semicolons without spaces. Only those countries or species recognized will be used in the final indices and will be sorted according to the provided sequence.

  • C. Advanced users may define their own format conventions using one of the "format.XXXX" (where XXXX is either SBMG, ASPT, NTBG, or PK) examples as a starting point. The formats are defined in simple tables so that they can be edited using spreadsheet software. The available formats for text include: bold, italic, underline or underscore (no difference), capitals, uppercase, parentheses, or square brackets. These formats can be combined and are applied from left to right; several options must be separated by a semicolon without a space. Unrecognized formatting words are ignored. For example, the formatting "();italics" will result in italicized parentheses whereas "italics;()" will not. More details can be found in Table 3.

  • D. The parameter "header" can be used to set other section titles; the parameter "out.file" is used to set the output file name.

  • E. The building blocks of the main exsic function are also available individually along with some helper functions. Each index function can be executed separately. Output format is in an intermediate format called "markdown" format and needs to be converted. This can be achieved using the function "write.exsic". Headers can be provided by using "exsic.header" and a combination of string concatenating commands such as "paste". For example, a custom index could be achieved using:

e02_01.gif

TABLE 3.

A comparison of the four index formats showing examples of how to create the format using the exsic function.

t03_01.gif

For more details, see the package documentation.

Implementation and speedWe used R and two libraries: (1) stringr (Wickham, 2012) and (2) markdown package (Gruber and Swartz, 2004; Allaire et al., 2012) as a basis to implement the exsic package. The exsic package shows one application of R and reproducible research tools for taxonomists and botanists. The package is freely available under the open source GNU Public License (GPL) and for all platforms supported by R (currently Windows, Linux, and Mac OS). On a Dell T7400 precision PC with 4 GB of RAM, a 2.66-GHz Intel Xeon CPU E5430 processor, and running R 2.15.2 on top of Ubuntu 12.10, the sample table with 1000 records was processed in about 30 s. The function has also been tested on Windows XP and Mac OS Snow Leopard.

Important noteWhen working across operating systems with tables created in Excel, it is indispensable to make sure that data are saved not only in .csv format but also using the encoding standard UTF-8. This allows the use of accents or other alphabets in the indices. Excel does not use UTF-8 as a default, and this will result in formatting errors.

CONCLUSIONS

The tool primarily increases the speed of preparing specimen citations, numbered collections, and supporting indices. It also minimizes human errors in manual transcription from table to list formats as well as formatting errors. The possibility to quickly create indices in familiar formats also provides an opportunity to double check the consistency and completeness of the table before final publication, thereby increasing the final quality of the table and interpretation. We are not aware of a similar freely available tool except for the report module in the BRAHMS software version 7 that also facilitates the generation of these indices. While the BRAHMS software is Windows only, the exsic package works on Windows, Linux, and Mac OS.

LITERATURE CITED

  1. J. J. Allaire , J. Horner , V. Marti , and N. Porte 2012. Markdown: Markdown rendering for R. Website  http://cran.r-project.org/web/packages/markdown/ [accessed 24 May 2013]. Google Scholar

  2. D. L. Filer 2001. BRAHMS—Botanical research and herbarium management system. BioNET News 8: 6–7. Google Scholar

  3. D. L. Filer 2010. BRAHMS—Botanical Research and Management System: Training course guide. Website  http://herbaria.plants.ox.ac.uk/bol/Content/Groups/brahms/Resources/BRAHMS%202010%20training%20guide.pdf [accessed 24 May 2013]. Google Scholar

  4. R. Gentleman , and D. Temple Lang . 2004. Statistical analyses and reproducible research. Bioconductor Project Working Papers. Working Paper 2. Website  http://biostats.bepress.com/bioconductor/paper2 [accessed 24 May 2013]. Google Scholar

  5. J. Gruber , and A. Swartz . 2004. Markdown 1.0.1. Website  http://daringfireball.net/projects/markdown/ [accessed 24 May 2013], Google Scholar

  6. R Core Team. 2012. R: A language and environment for statistical computing. R Foundation for Statistical Computing, Vienna, Austria. Website  http://www.R-project.org/ [accessed 24 May 2013]. Google Scholar

  7. H. Wickham 2012. stringr: Make it easier to work with strings. Website  http://cran.r-project.org/web/packages/stringr/ [accessed 24 May 2013]. Google Scholar

Notes

[1] This research was supported by the National Science Foundation (DEB 0316614). The authors thank two anonymous reviewers for their feedback on earlier versions, which greatly helped to improve the scope and usability of the tool.

Reinhard Simon and David M. Spooner "A New R Package, Exsic, to Assist Taxonomists in Creating Indices," Applications in Plant Sciences 1(6), (7 June 2013). https://doi.org/10.3732/apps.1300024
Received: 28 March 2013; Accepted: 1 May 2013; Published: 7 June 2013
JOURNAL ARTICLE
PAGES


SHARE
ARTICLE IMPACT
Back to Top