A quick guide to monographaR

collectorList

This function will generate a txt file with a collector list for all species in data. It requires a data.frame with five columns, ordered as species, collector name, collector number, herbarium acronym and herbarium number. Herbarium columns are only used if some collector number is missing (NA). Thus, if there is no missing value in collector number, then the herbarium columns might be empty.

Loading the example data

data(monographaR_examples)
monographaR_examples$collectorList -> data

This is how the table should be:

Now, to run the function just type the command below. It will print in the terminal the output. To export a txt, place a name in the filename argument (i.e., filename = “myoutput.txt”).

collectorList(data, filename = "", paragraphs = FALSE)

This is the output:

List of species

1. Smithia glabra. 2. Smithia lactescens. 3. Smithia pubescens.

Specimens examined

Berry, C. 372 (2); 874 (2); 1098 (2); 1303 (2). Clapton, E. 2986 (3); 4735 (3); 12011 (3). Hendrix, J. 5014 (1); 5017 (1); 5970 (1). Johnson, R. 13446 (2); 14302 (2). Page, J. 171 (3); 1101 (1); 12011 (33). Richards, K. 1098 (2). Vaughan, S.R. 48 (3); 57 (3); 152 (3); 181 (3); 209 (3); 228 (3); 875 (1); 2816 (1); 4352 (3). Young, A. 642 (1); 1503 (1).

Unknown collector and/or collector number

CEPEC 9429 (2). SPF 166044 (3).

examinedSpecimens

This function will generate a txt file with an examined specimens list. It requires a data.frame with eight columns, ordered as: species, collector name, collector number, herbarium acronym, herbarium number, country, state, and municipality.

Loading the example data

data(monographaR_examples)
monographaR_examples$examinedSpecimens -> data

This is how the table should be:

Now, to run the function just type the command below. It will print in the terminal the output. To export a txt, place a name in the filename argument (i.e., filename = “myoutput.txt”).

examinedSpecimens(data, filename = "")

This is the output:

Specimens Examined

Smithia glabra

BRAZIL. Bahia: Eunapolis, Vaughan, S.R. 875 (UPCB). Minas Gerais: Santa Barbara, Young, A. 1503 (CEPEC). Rio de Janeiro: Petropolis, Vaughan, S.R. 2816 (CEPEC). Santa Catarina: Unknown Municipality, Hendrix, J. 5014 (UPCB). Sao Paulo: Apiai, Young, A. 642 (RB, UPCB); Paranapiacaba, Hendrix, J. 5014 (SPF), Hendrix, J. 5970 (UPCB); Sao Jose do Barreiro, Page, J. 1101 (RB). Unknown State: Unknown Municipality, Hendrix, J. 5017 (UPCB).

Smithia lactescens

BRAZIL. Espirito Santo: Iuna, Berry, C. 1303 (RB, UPCB); Santa Teresa, Richards, K. 1098 (CEPEC). Rio de Janeiro: Itatiaia, Richards, K. 478 (CEPEC); Nova Friburgo, Johnson, R. 372 (NY); Rio de Janeiro, Johnson, R. 13446 (UPCB); Unknown Municipality, Johnson, R. 13446 (CEPEC). Sao Paulo: Sao Paulo, Berry, C. 1098 (RB), Berry, C. 874 (CEPEC). SRI LANKA. Kuma: Skatakum, Johnson, R. 14302 (NY).

Smithia pubescens

BRAZIL. Bahia: Barra do Choca, Clapton, E. 4352 (UPCB); Eunapolis, Vaughan, S.R. 152 (CEPEC); Itabuna, Vaughan, S.R. 48 (CEPEC); Itacare, Page, J. 12011 (NY). Espirito Santo: Venda Nova do Imigrante, Page, J. 12011 (RB). Parana: Campina Grande do Sul, Vaughan, S.R. 209 (CEPEC); Cerro Azul, Vaughan, S.R. 209 (CAS); Guaratuba, Vaughan, S.R. 181 (CEPEC). Santa Catarina: Orleans, Page, J. 171 (CEPEC). Sao Paulo: Cunha, Clapton, E. 2986 (CEPEC); Rio Claro, Page, J. 12011 (CEPEC); Sao Paulo, Clapton, E. 2986 (R), Vaughan, S.R. 228 (CEPEC), Vaughan, S.R. 57 (CEPEC); Unknown Municipality, Clapton, E. 4735 (CEPEC).

tableToDescription

This function will generate a txt file with species descriptions. It requires a data.frame where the first three columns are the character description, putative complement and the character to use as separator (i.e., words that will remain constant across descriptions). The character description and/or the complement might be empty. The remaining columns are the species with their respective character states, where each row is a character. The function accepts any number of species and/or characters.

Loading the example data

data(monographaR_examples)
monographaR_examples$tableToDescription -> data

This is how the table should be:

Now, to run the function just type the command below. The first column is just an identifier for the characters. We need to remove it before running the function. To export a txt, place a name in the filename argument (i.e., filename = “myoutput.txt”).

data[,-1] -> data  ## removing first column
tableToDescription(data, filename = "")

This is the output:

Species Descriptions

Smithia glabra

Shrubs 0.3-0.5 m tall. Indumentum absent. Leaves isophyllous or slightly anisophyllous in each pair (up to 6:9 ratio); petioles (0.7)1-2(3) cm long; blades 5.5-10 x 2.5-4.5 cm, ovate or elliptic, seldom lanceolate, apex acuminate, base rounded, seldom obtuse or slightly cuneate, margin crenulate or entire, ciliate (1.5 mm), membranaceous; 5 main nerves, plinerved, distant 4-12 mm above the base. Inflorescences terminal, 1 per node, 5-8 cm long, > 10 flowers per inflorescence; 4-8 x 2-4.5 mm, lanceolate, elliptic, or slightly obovate, uniformly covered by simple trichomes, persistent. Flowers 5(6) -merous, sessile. Hypanthium 3.8-4.2 x 1.7-2 mm, campanulate to tubular. Calyx tube 0.3-0.4 mm long; inner lobes 1.7-2.2 x ca. 1 mm, oblong with a rounded apex; external teeth 2.1-2.4 mm long. Petals white, 5.5-5.8 x 1.2-1.4 mm, linear to lanceolate, apex acuminate, glabrous. Stamens 10, opposite to the style; filaments 4.8-5.2 mm long; anthers pink, 4.3-4.5 mm long, linear-subulate, dorsally curved, pore 0.11-0.14 mm wide. Ovary 3 -celled, 2.8-3.2 x 1.7-1.9 mm, 30-40 % inferior. Style 10 mm long, sigmoid, stigma ca. 0.2 mm wide. Berries purple, 6-6.5 x 4-4.5 mm. Seeds ca. 1 x 0.6 mm, pyramidal.

Smithia lactescens

Trees 20-30 m tall. Indumentum present, branches, petioles, leaves, inflorescences, bracts and bracteoles covered by unbranched trichomes (0.8-1.5 mm), these sparser on leaf adaxial surfaces and denser on main nerves on leaf abaxial surface, petioles and inflorescences. Leaves isophyllous; petioles 1-5 cm long; blades 2.5-10 x 4.5-6.5 cm, lanceolate, apex obtuse, base rounded, margin entire, membranaceous; 3 main nerves, nerved. Inflorescences lateral, 2 per node, 5-15 cm long, 50 flowers per inflorescence; 4-8 x 2-4.5 mm, obovate, uniformly covered by simple trichomes, caducous. Flowers 5 -merous, sessile. Hypanthium 2-4.2 x 1.7-5 mm, campanulate to tubular. Calyx tube 0.3-0.4 mm long; inner lobes 1.5-2.5 x 1 mm, oblong with a rounded apex; external teeth 2.1-5 mm long. Petals white, 4.5-6.8 x 2.2-1.9 mm, ovate, apex acute, glabrous. Stamens 10, surrounding the style; filaments 4.8-5.2 mm long; anthers pink, 4.3-4.5 mm long, linear-subulate, dorsally curved, pore 0.12 mm wide. Ovary 3 -celled, 2-3 x 1.7-1.9 mm, 30-40 % inferior. Style 9 mm long, straight, stigma ca. 0.2 mm wide. Berries white, 4-6 x 4-4.5 mm. Seeds 1 x 1 mm, pyramidal.

Smithia pubescens

Shrubs 0.5-5 m tall. Indumentum absent. Leaves isophyllous or slightly anisophyllous in each pair (up to 6:9 ratio); petioles 2-10 cm long; blades 1.5-14 x 4.5-9.5 cm, ovate, apex acute, base decurrent, margin crenulate, membranaceous; 7 main nerves, plinerved, distant 5-15 mm above the base. Inflorescences lateral, 1 per node, 2-8 cm long, 5 flowers per inflorescence; 4-8 x 2-4.5 mm, ovate, uniformly covered by simple trichomes, persistent. Flowers 4 -merous, sessile. Hypanthium 3.8-7 x 2-4 mm, campanulate to tubular. Calyx tube 0.3-0.4 mm long; inner lobes 1-2.5 x ca. 1 mm, oblong with a rounded apex; external teeth 1-2 mm long. Petals white, 2.5-3 x 5-7 mm, ovate, apex acuminate, glabrous. Stamens 10, opposite to the style; filaments 4.8-5.2 mm long; anthers pink, 4.3-4.5 mm long, linear-subulate, dorsally curved, pore 0.14 mm wide. Ovary 3 -celled, 3-5 x 3-6 mm, 30-40 % inferior. Style 8 mm long, straight, stigma ca. 0.2 mm wide. Berries red, 4-6.5 x 3-4.5 mm. Seeds 1.5 x 0.9 mm, pyramidal.

buildMonograph

This function wraps around the previous three functions (tableToDescription, examinedSpecimens and collectorList) generating a monograph draft in MS-Word or html format. The resulting monograph skeleton will include the taxonomic heading, the description, comments and examined specimens list for all species found in the input tables, and it will append the collector list in the end of the file. It requires four tables as input. Three of them are the same tables used for “tableToDescription”, “collectorList” and “examinedSpecimens” functions. The additional input table should have three columns: species, taxonomic heading and comments. It uses functions of the rmarkdown package to export the output file.

Loading the example data

data(monographaR_examples)
monographaR_examples$taxonomic_headings -> taxonomic.headings
monographaR_examples$collectorList -> col.d
monographaR_examples$examinedSpecimens -> exam.d
monographaR_examples$tableToDescription -> desc.d
desc.d[,-1] -> desc.d

This is how the headings table should be:

Now, to run the function just type the command below. It will export a MS-Word file (if output=“Word”) or a html file (if output = “html”) to your working directory.

buildMonograph(headings=taxonomic.headings,collectorList.data = col.d, examinedSpecimens.data =
  exam.d, tableToDescription.data = desc.d, output = "Word", title="Monograph skeleton")

See the help of the function for options. Type:

• help(“buildMonograph”)

phenoHist

This wrapper function will generate circular histograms of phenology, using functions of the package circular. It requires a data.frame with three columns, ordered as: species, month and phenology. The month column should be numeric (month number), while the phenology column must have these values: “Flower”, “Fruit” and/or “Both”. If any of these are missing is possible to indicate in the “flower”, “fruit” and “both” arguments (both=“missing”). The function will plot the bars indicating flower observations in white, and fruits in gray by default (is possible to change it with the “flower.col”, “flower.border”, “fruit.col” and “fruit.border” arguments). The size of the bar corresponds to number of observations. The arguments “shrink”, “axis.cex” and “title.cex” control sizes, while the mfrow changes the number of histograms plotted at the same page (rows, columns).

Loading the example data

data(monographaR_examples)
monographaR_examples$phenoHist -> data

This is how the table should be:

Now, to run the function just type the command below. It will plot the histograms. To export a pdf, set “pdf=TRUE”.

phenoHist(data, shrink=1.1, axis.cex=0.8, title.cex=1, pdf=FALSE)

This is the output:

See the help of the function for customization options. Type:

• help(“phenoHist”)

mapPhenology

This wrapper function will generate heatmaps of phenology across a time range. The default is to produce 12 heatmaps plotted on a single plate. This can be changed with the argument time.range, where any numerical range can be provided (representing weeks for instance). The argument mfrow controls the plate layout. It requires a data.frame with four columns, ordered as: species, longitude, latitude and phenology. The phenology column should be numeric (i.e., the number of the month, week or day the specimen was collected with flower/fruit). It is possible to change the resolution of the resulting rasters. The function can produce presence/absence heatmaps (if binary = T) or abundance heatmaps (if binary = F). The abundance values are relative (divided by the maximum abundance observed across all rasters). The function returns a rasterStack that can be exported or used in customized plots. To export a pdf, set “pdf=TRUE”.

Loading the example data

data(monographaR_examples)
monographaR_examples$mapPhenology -> data

This is how the table should be:

Now, to run the function just type the command below. In this case it will plot 12 phenology heatmaps. To export a pdf, set “pdf=TRUE”.

mapPhenology(data, binary=F, by_species=F, legend=F)

This is the output:

## class      : RasterStack 
## dimensions : 48, 56, 2688, 12  (nrow, ncol, ncell, nlayers)
## resolution : 1, 1  (x, y)
## extent     : -94, -38, -30, 18  (xmin, xmax, ymin, ymax)
## crs        : +proj=longlat +datum=WGS84 
## names      :   Month_1,   Month_2,   Month_3,   Month_4,   Month_5,   Month_6,   Month_7,   Month_8,   Month_9,  Month_10,  Month_11,  Month_12 
## min values : 0.1111111, 0.1111111, 0.1111111, 0.1111111, 0.1111111, 0.1111111, 0.1111111, 0.1111111, 0.1111111, 0.1111111, 0.1111111, 0.1111111 
## max values : 0.7777778, 0.8888889, 0.8888889, 0.7777778, 0.7777778, 0.7777778, 1.0000000, 0.8888889, 0.8888889, 0.7777778, 0.7777778, 0.7777778

It is possible to create an animation (GIF) of the phenology across time. There are several options to do that. One possibility is to use the animation package.

require(animation)

saveGIF(
  {mapPhenology(data, binary=F, resolution=0.5, by_species=F, legend=F, mfrow=c(1,1))},
  movie.name="phenology.gif", interval=0.5, ani.width=600, ani.height=600
)

See the help of the function for customization options. Type:

• help(“mapPhenology”)

mapBatch

This wrapper function will export maps for all species in data. The function has two output options: a single pdf with all maps (export = “pdf”) or individual tiff files for each species (export = “tiff”). It requires a data.frame with three columns, ordered as: species, longitude and latitude. If zoom = TRUE, the function will set the limits of the plot using the distribution of each species plus the margin (relative value). If zoom = FALSE, the function will use the distribution of the whole data to set the limits (all maps will have the same limits). Colors can be changed with the arguments points.col, shape.col, shape.border, while the size of the points can be changed with points.cex. A raster layer can be provided (elevation for instance), and the colors of the raster are controlled by raster.col. Optionally, the user can provide a single or a list of shape files (type = “user”).

Loading the example data

data(monographaR_examples)
monographaR_examples$map_data -> data

This is how the table should be:

Now, to run the function just type the command below. It will export the maps as a pdf (export = “pdf”) or tiff images (export = “tiff”).

mapBatch(data , zoom=T, margin=2, points.col="black", points.border="white", shape.col="gray90", points.cex=1.5, shape.border = "gray90", export="pdf")

This is the output:

See the help of the function for customization options. Type:

• help(“mapBatch”)

mapDiversity

This function will generate a diversity heatmap using presence/absence of species on grid cells. It requires a data.frame with three columns, ordered as: species, longitude and latitude. The function will plot and return a raster object. The resolution of the grid can be changed by the argument “resolution” (in degrees). It uses functions of the package raster.

Loading the example data

data(monographaR_examples)
monographaR_examples$map_data -> data

This is how the table should be:

Now, to run the function just type the command below. It will plot the diversity map. Alternatively, you can export the resulting raster layer (set export = T). This layer can be visualized in a standard GIS program.

mapDiversity(data , resolution=1, plot=TRUE, plot.with.grid=TRUE, legend = T, export = F)

This is the plot:

## class      : RasterLayer 
## dimensions : 48, 56, 2688  (nrow, ncol, ncell)
## resolution : 1, 1  (x, y)
## extent     : -94, -38, -30, 18  (xmin, xmax, ymin, ymax)
## crs        : +proj=longlat +datum=WGS84 
## source     : memory
## names      : layer 
## values     : 1, 10  (min, max)

See the help of the function for customization options. Type:

• help(“mapDiversity”)

mapTable

This function will generate a presence/absence matrix based on a grid (if type=“grid”) or on countries (if type=“countries”). It requires a data.frame with three columns, ordered as: species, longitude and latitude. The resolution of the grid can be changed by the argument “resolution” (in degrees). It uses functions of the package raster.

Loading the example data

data(monographaR_examples)
monographaR_examples$map_data -> data

This is how the table should be:

Now, to run the function just type the command below. In this first case, we are running with the grid option (type = “grid”). It will generate a “list” object with a presence/absence matrix and the grid used. You can export the results (write.output = T). The output table can be visualized in a spreadsheet program and the grid in a standard GIS program.

map.table <- mapTable(data, type="grid", resolution=3, write.output=FALSE)
  
map.table$table

These are the outputs:

See the help of the function for customization options. Type:

• help(“mapTable”)