catalog: Create catalog of vocal signals

Description

catalog produces spectrograms of selections (signals) split into multiple rows and columns.

Usage

catalog(X, flim = c(0, 22), nrow = 4, ncol = 3, same.time.scale = TRUE, 
collev = seq(-40, 0, 1), ovlp = 50, parallel = 1, mar = 0.05, wl = 512, gr = FALSE, 
pal = reverse.gray.colors.2, it = "jpeg", path = NULL, pb = TRUE, fast.spec = FALSE, 
res = 100, orientation = "v", labels = c("sound.files", "selec"), height = NULL, 
width = NULL, tags = NULL, tag.pal = list(temp.colors, heat.colors), legend = 3, 
cex = 1, leg.wd = 1, img.suffix = NULL, tag.widths = c(1, 1), hatching = 0, 
breaks = c(5, 5))

Arguments

Data frame with columns for sound file name (sound.files), selection number (selec), and start and end time of signal (start and end). Default is NULL.

flim

A numeric vector of length 2 indicating the highest and lowest frequency limits (kHz) of the spectrogram, as in spectro. Default is c(0,22).

nrow

A numeric vector of length 1. Specifies number of rows. Default is 4.

ncol

A numeric vector of length 1. Specifies number of columns. Default is 3.

same.time.scale

Logical. Controls if all spectrograms are in the same time scale (i.e. have the same duration).

collev

A numeric vector of length 3. Specifies levels to partition the amplitude range of the spectrogram (in dB). The more levels the higher the resolution of the spectrogram. Default is seq(-40, 0, 1). seq(-115, 0, 1) will produces spectrograms similar to other acoustic analysis software packages.

ovlp

Numeric vector of length 1 specifying % of overlap between two consecutive windows, as in spectro. Default is 50. High values of ovlp slow down the function but produce more accurate selection limits (when X is provided).

parallel

Numeric. Controls whether parallel computing is applied. It specifies the number of cores to be used. Default is 1 (i.e. no parallel computing).

mar

Numeric vector of length 1. Specifies the margins adjacent to the start and end points of selections, dealineating spectrogram limits. Default is 0.05.

A numeric vector of length 1 specifying the window length of the spectrogram, default is 512.

Logical argument to add grid to spectrogram. Default is FALSE.

pal

Color palette function for spectrogram. Default is reverse.gray.colors.2. See spectro for more palettes. Palettes as gray.2 may work better when fast.spec = T.

A character vector of length 1 giving the image type to be used. Currently only "tiff" and "jpeg" are admitted. Default is "jpeg".

path

Character string containing the directory path where the sound files are located. If NULL (default) then the current working directory is used.

Logical argument to control progress bar. Default is TRUE. Note that progress bar is only used when parallel = 1.

fast.spec

Logical. If TRUE then image function is used internally to create spectrograms, which substantially increases performance (much faster), although some options become unavailable, as collevels, and sc (amplitude scale). This option is indicated for signals with high background noise levels. Palette colors gray.1, gray.2, gray.3, topo.1 and rainbow.1 (which should be imported from the package monitoR) seem to work better with 'fast.spec' spectograms. Palette colors gray.1, gray.2, gray.3 offer decreasing darkness levels. THIS IS STILL BEING TESTED.

res

Numeric argument of length 1. Controls image resolution. Default is 100 (faster) although 300 is recommended for publication/presentation quality. Note that high resolution produce significantly bigger image files. This could be problematic when creating pdf files using catalog.

orientation

String. Indicates whether a letter page size image is produced in vertical ('v' option) or horizontal orientation ('h' option). Note that width and height can also be specified.

labels

String vector. Provides the column names that will be used as labels above the corresponding spectrograms.

height

Numeric. Single value (in inches) indicating the height of the output image files. Default is 11 for vertical orientation.

width

Numeric. Single value (in inches) indicating the width of the output image files. Default is 8.5 for vertical orientation.

Value

Image files with spectrograms of whole sound files in the working directory. Multiple pages can be returned, depending on the length of each sound file.

Details

This functions aims to simplify the visual exploration of multiple vocalizations. The function plots a matrix of spectrograms from a selection table. Spectrograms can be labeled or color tagged to facilitate exploring variation related to a parameter of interest (e.g. location, song type). A legend will be added to help match colors with tag levels (if legend is > 0). Different color palettes can be used for each tag. Numeric tags are split in intervals (the number of intervals can be controlled with break argument). The width and height can also be adjusted to fit more column and/or rows. This files can be put together in a single pdf file with catalog2pdf. We recommend using low resolution (~60-100) and smaller dimensions (width & height < 10) if aiming to generate pdfs (otherwise pdfs could be pretty big).

Examples

Run this code

## Not run: ------------------------------------
# # Set temporary working directory
# setwd(tempdir())
# # save sound file examples
# data(list = c("Phae.long1", "Phae.long2","selec.table"))
# writeWave(Phae.long1,"Phae.long1.wav") 
# writeWave(Phae.long2,"Phae.long2.wav")
#  writeWave(Phae.long3,"Phae.long3.wav")
#  writeWave(Phae.long4,"Phae.long4.wav")
# 
# 
# catalog(X = selec.table, flim = c(1, 10), nrow = 4, ncol = 2, same.time.scale = T,
#  ovlp = 90, parallel = 1, mar = 0.01, wl = 200, gr = FALSE,
#  orientation = "v",  labels = c("sound.files", "selec"), legend = 0)
#  
#  #different time scales and tag palette
# catalog(X = selec.table, flim = c(1, 10), nrow = 4, ncol = 2, same.time.scale = F,
#  ovlp = 90, parallel = 1, mar = 0.01, wl = 200, 
#  orientation = "v",  labels = c("sound.files", "selec"), legend = 0, 
#  tag.pal = list(terrain.colors))
#  #'  
#  #adding tags and changing spectro palette
# catalog(X = selec.table, flim = c(1, 10), nrow = 4, ncol = 2, same.time.scale = F,
#  ovlp = 90, parallel = 1, mar = 0.01, wl = 200, pal = reverse.heat.colors,
#  orientation = "v",  labels = c("sound.files", "selec"), legend = 1, 
#  tag.pal = list(terrain.colors), tags = "sound.files")
# 
#  #create a bigger selection table
#  X <- rbind(selec.table, selec.table, selec.table, selec.table)
#  X <- rbind(X, X)
#  
#  #create some simulated labels
#  X$songtype <- sample(letters[1:3], nrow(X), replace = T)
#  X$indiv <- sample(letters[1:12], nrow(X), replace = T)
# 
# # 12 columns in 5 rows, 2 tags
# catalog(X = selec.table, flim = c(1, 10), nrow = 5, ncol = 12, same.time.scale = F,
#  ovlp = 90, parallel = 1, mar = 0.01, wl = 200, 
#  orientation = "v",  labels = c("sound.files", "selec"), legend = 3, 
#  collev = seq(-65, 0, 5), tag.pal = list(terrain.colors), tags = c("songtype", "indiv"))
# 
# 
# # with legend
# catalog(X = selec.table, flim = c(1, 10), nrow = 5, ncol = 12, same.time.scale = F,
#  ovlp = 90, parallel = 1, mar = 0.01, wl = 200, gr = FALSE,
#  orientation = "v",  labels = c("sound.files", "selec"), legend = 3, 
#  width = 20, collev = seq(-65, 0, 5), tag.pal = list(terrain.colors),
#   tags = c("songtype", "indiv"))
#   
#   #' horizontal orientation
# catalog(X = selec.table, flim = c(1, 10), nrow = 5, ncol = 12, same.time.scale = F,
#  ovlp = 90, parallel = 1, mar = 0.01, wl = 200, gr = FALSE,
#  orientation = "h",  labels = c("sound.files", "selec"), legend = 3, 
#  width = 20, collev = seq(-65, 0, 5), tag.pal = list(terrain.colors),
#   tags = c("songtype", "indiv"))
# check this floder
# getwd()
## ---------------------------------------------