Package 'dynaSpec'

Title: Dynamic Spectrogram Visualizations
Description: Interactive and dynamic spectrogram visualizations (web pages and videos) built with a layered syntax.
Authors: Marcelo Araya-Salas [aut, cre] (ORCID: <https://orcid.org/0000-0003-3594-619X>), Matthew R. Wilkins [aut]
Maintainer: Marcelo Araya-Salas <[email protected]>
License: GPL (>= 2)
Version: 2.0.0.9000
Built: 2026-11-13 15:29:38 UTC
Source: https://github.com/maRce10/dynaSpec

Help Index


Add layers to dynamic spectrograms

Description

Add layers to dynamic spectrograms

Usage

## S3 method for class 'dynaspec'
e1 + e2

Arguments

e1

A dynaspec() object.

e2

A layer (e.g. ds_spectrogram(), ds_annotations() or ds_scrolling()).

Value

A dynaspec() object. Spectrogram, oscillogram, envelope, spectrum, overview, player and style layers replace previous ones of the same kind (arguments of spectrogram, theme and style layers are combined); annotations and captions are added.


Acoustic recording of Taraba major (great antshrike) songs

Description

Two songs of a great antshrike recorded by Julio E. Sánchez at Finca La Selva, Heredia, Costa Rica, on 20 June 1999 (9:47 am), at the edge of dense secondary growth (bird about 4 m away and 1.5 m high). Recorded on cassette with a Sony TC-D5 Pro-II recorder and a Telinga Pro II parabolic microphone, and digitized. Band-pass filtered between 0.4 and 5.25 kHz and downsampled to 11.025 kHz.

Usage

data(antshrike)

Format

A Wave object (tuneR::Wave): mono, 16.78 s, 11.025 kHz sampling rate, 16 bits.


Acoustic recordings of Hirundo rustica (barn swallow) songs

Description

Songs of a female and a male barn swallow recorded by Matthew R. Wilkins (the example sound files of dynaSpec 1.x).

Usage

data(female_barn_swallow)

male_barn_swallow

Format

Wave objects (tuneR::Wave): mono, 22.05 kHz sampling rate, 16 bits; female_barn_swallow lasts 1.93 s and male_barn_swallow 4.75 s.

An object of class Wave of length 104763.

Examples

data(female_barn_swallow)

x <- dynaspec(female_barn_swallow, flim = c(0, 10)) +
  ds_spectrogram(wl.ms = 14, collevels = seq(-50, 0, 1))

Annotation layer of dynamic spectrograms

Description

ds_annotations() highlights parts of the sound in a dynaspec() object with translucent boxes (e.g. calls, songs or the parts of a duet), optionally with borders and labels, or with horizontal lines above the sounds (e.g. to show which individual sings each part of a duet).

Usage

ds_annotations(
  X,
  col = NULL,
  alpha = 0.3,
  type = "box",
  border = NULL,
  lwd = 1,
  lty = 1,
  labels = NULL,
  cex = 1,
  freq = TRUE,
  sound.file = NULL,
  line.freq = NULL,
  contour = NULL,
  contour.col = NULL,
  contour.lwd = 2,
  contour.args = list()
)

Arguments

X

Data frame with the selections: columns 'start' and 'end' (in s) and, optionally, 'bottom.freq' and 'top.freq' (in kHz) to restrict boxes to a frequency range. Selection tables from 'warbleR' (or tables from 'ohun' or 'Rraven') can be used directly (see details). Extended selection tables are not supported.

col

Color of the boxes, or the name of a column of 'X' with the color of each box. Default is NULL: 'col.annotation' of ds_theme(), or "#E69F00".

alpha

Opacity of the boxes or lines (0-1). Default is 0.3 (1 for lines).

type

Character string: "box" (translucent boxes), "spectrogram" (the spectrogram is colored within each selection, with a gradient from the spectrogram background to the color of the selection, as warbleR::color_spectro(); only borders and labels are drawn on top) or "line" (a horizontal line from the start to the end of each selection at the frequency set by 'line.freq', drawn on spectrograms only; labels are shown above the lines). Default is "box".

border

Color of the box borders, or the name of a column of 'X' with the border color of each box. Default is NULL (no borders).

lwd

Width of the box borders, or of the lines when type = "line". Default is 1 (8 for lines).

lty

Line type of the box borders (or of the lines), as in graphics::par(): an integer (0-6) or a name ("solid", "dashed", "dotted", "dotdash", "longdash" or "twodash"). Default is 1 (solid).

labels

Name of a column of 'X' with labels to show at the top of each box (or above each line). Default is NULL (no labels).

cex

Size of the labels. Default is 1.

freq

Logical to control if the frequency range of selections is used (when 'X' has 'bottom.freq' and 'top.freq' columns). If FALSE boxes span the whole frequency range. Default is TRUE.

sound.file

Name of the sound file whose selections are shown, when 'X' has a 'sound.files' column with several sound files. Default is NULL: when the sound of dynaspec() is a file, the selections of that file are shown (matching the file name); otherwise 'X' must contain a single sound file.

line.freq

Frequency (in kHz) at which lines are drawn when type = "line", or the name of a column of 'X' with the frequency of each line (e.g. a different height for each individual of a duet). Default is NULL: near the top of the spectrogram (90% of the frequency range shown).

contour

Frequency contours to draw over the spectrogram within each selection. Default is NULL (no contours). It can be:

  • "dominant" or "fundamental": contours measured on the sound with seewave::dfreq() or seewave::fund(), within the frequency range of the selection ('bottom.freq' and 'top.freq' columns, if 'freq' is TRUE) or the frequency limits of dynaspec().

  • A list with one element per selection (NULL for no contour): a numeric vector of frequencies (in kHz) evenly spaced from the start to the end of the selection, or a data frame or matrix with the time (in s, as in 'start' and 'end') and frequency (in kHz) of each point, in that order or in columns named 'time' and 'freq'.

  • A data frame or matrix with one row per selection and the frequencies (in kHz) evenly spaced from its start to its end in numeric columns, as the output of warbleR::freq_ts() (columns 'sound.files' and 'selec' are ignored).

NA frequencies leave gaps in the contour.

contour.col

Color of the contours, or the name of a column of 'X' with the color of each contour. Default is NULL (the color of the selection, opaque).

contour.lwd

Width of the contours. Default is 2.

contour.args

List with the settings used to measure contours: 'wl.ms' (window length, in ms; takes precedence over 'wl') or 'wl' (in samples); default is the window of ds_spectrogram(), or 11.61 ms, 'ovlp' (percent overlap; default 90), 'threshold' (amplitude threshold, as a percentage, below which no frequency is measured; default 5) and 'smooth' (number of consecutive values of the running median and mean used to smooth contours; default 5, and 1 for no smoothing).

Details

Tables with a 'sound.files' column (e.g. 'warbleR' selection tables) can contain selections of several sound files; only those of the sound shown are used (see 'sound.file').

Contours are only drawn on spectrograms. To show contours without boxes use alpha = 0. Dominant frequency contours jump between frequencies when another frequency becomes the loudest one (e.g. fast trills), and fundamental frequency contours are coarse for high-pitched sounds at low sampling rates (they are measured in steps of the sampling period).

Value

A layer to be added to a dynaspec() object with +. Several annotation layers can be added.

See Also

dynaspec(), ds_captions()

Examples

data(scythebill)

# note types
st <- data.frame(start = c(0.34, 1.13, 1.44, 1.75), end = c(1.03, 1.36, 1.68, 2.28),
                 labels = c("A", "B", "B", "C"),
                 colors = c("#E69F00", "#56B4E9", "#56B4E9", "#009E73"))

x <- dynaspec(scythebill, flim = c(1.5, 5.5)) +
  ds_spectrogram(wl.ms = 18, collevels = seq(-50, 0, 1)) +
  ds_annotations(st, col = "colors", labels = "labels")

# dashed borders of the same color as the boxes
x <- x + ds_annotations(st, col = "colors", alpha = 0.1, border = "colors", lwd = 2, lty = "dashed")

# spectrogram colored within the selections
x <- dynaspec(scythebill, flim = c(1.5, 5.5)) +
  ds_spectrogram(wl.ms = 18, collevels = seq(-50, 0, 1)) +
  ds_annotations(st, col = "colors", type = "spectrogram")

# lines above the notes (one height per note type)
st$line.freq <- c(4.6, 4.9, 4.9, 5.2)
x <- dynaspec(scythebill, flim = c(1.5, 5.5)) +
  ds_spectrogram(wl.ms = 18, collevels = seq(-50, 0, 1)) +
  ds_annotations(st, col = "colors", type = "line", line.freq = "line.freq", labels = "labels")

# frequency contours
x <- dynaspec(scythebill, flim = c(1.5, 5.5)) +
  ds_spectrogram(wl.ms = 18, collevels = seq(-50, 0, 1)) +
  ds_annotations(st, col = "colors", labels = "labels", contour = "dominant",
                 contour.col = "#E69F00")

Caption layer of dynamic spectrograms

Description

ds_captions() adds text to a dynaspec() object at a fixed position of the figure, shown (fading in and out) during a time range of the sound, like subtitles. They are shown in the same way in all styles, in web pages and videos. To label parts of the spectrogram use the 'labels' argument of ds_annotations() instead.

Usage

ds_captions(
  labels,
  start,
  end,
  x = 0.5,
  y = 0.9,
  fading = 0,
  col = "black",
  cex = 1,
  font = 1
)

Arguments

labels

Character vector with the captions.

start, end

Numeric vectors with the start and end times (in s) of each caption.

x, y

Position of the center of the captions as proportions of the figure width and height (0-1, from the left and bottom). Defaults are 0.5 and 0.9.

fading

Duration (in s) of the fade-in and fade-out of captions. Default is 0.

col, cex, font

Color, size and font (1 = plain, 2 = bold, 3 = italic, 4 = bold italic) of the captions. Defaults are "black", 1 and 1.

Details

Each caption layer shows one caption at a time; when the time ranges of its captions overlap the most visible one is shown.

Value

A layer to be added to a dynaspec() object with +. Several caption layers can be added (e.g. at different positions).

See Also

dynaspec(), ds_annotations()

Examples

data(scythebill)

x <- dynaspec(scythebill, flim = c(1.5, 5.5)) +
  ds_spectrogram(wl.ms = 18, collevels = seq(-50, 0, 1)) +
  ds_captions(c("long note", "arched notes", "trill"), start = c(0.34, 1.13, 1.75),
              end = c(1.03, 1.68, 2.28), fading = 0.2)

Compare sounds with dynamic spectrograms

Description

ds_compare() shows two or more sounds one on top of the other and plays them in sequence, from top to bottom. Layers are added with +, as in dynaspec(), and are applied to all sounds.

Usage

ds_compare(..., flim = NULL, tlim = NULL, gap = 0.5, same.scale = TRUE)

Arguments

...

The sounds (at least two), in the order they are shown and played: objects of class 'Wave', paths to '.wav' or '.mp3' files, or dynaspec() objects, or a single list of them. Use dynaspec() objects for settings or layers of a single sound (e.g. its own ds_annotations(), ds_captions() or time range).

flim

Numeric vector of length 2 with the frequency limits (in kHz) of all sounds, as in dynaspec(). Default is NULL: the limits set in dynaspec() objects; limits set for only some sounds are used for all of them, if they are the same. Sounds with different sampling rates are shown up to the lowest Nyquist frequency, so all use the same frequency axis (unless they have different limits set in dynaspec() objects).

tlim

Numeric vector of length 1 or 2 with the time range (in s) of all sounds, as in dynaspec(). Default is NULL (the whole sounds, or the time range set in dynaspec() objects).

gap

Numeric vector of length 1 with the silence (in s) between consecutive sounds. Default is 0.5.

same.scale

Logical: use the same time scale for all sounds, so a second takes the same width in all of them? Static spectrograms leave empty room to the right of shorter sounds, and paged spectrograms without 't.display' use the duration of the longest sound as the duration of their pages (scrolling spectrograms and paged spectrograms with 't.display' always have the same scale). FALSE fits each sound to the width of the figure. Default is TRUE.

Details

All styles, panels, themes and output formats of dynaspec() objects can be used, and all sounds must use the same style:

  • Web pages have a single set of controls below the sounds. Speed, pitch, volume and zoom apply to all sounds, the time readout shows the number of the sound being played and its time, the seek bar spans all sounds, the loop button repeats the sequence and the download button saves all sounds (browsers may ask for permission to download several files). Clicking on a spectrogram plays that sound from that point, and then the following ones (the sequence ends after the last sound).

  • Videos ('.mp4', requires 'ffmpeg') stack the videos of the sounds: each sound keeps its first frame until it is played, and its last frame afterwards.

  • Still images ('.png') stack the images of the sounds (paged spectrograms: one image per page, stacking the pages with the same number).

Annotations and captions added to a comparison are applied to all sounds, with times referring to each sound. To add them to a single sound, add them to its dynaspec() object. Layers added to a comparison replace (or are combined with) those of the dynaspec() objects, as in any dynaspec() object.

Amplitudes are scaled within each sound (as in dynaspec()), so the colors of the spectrograms and the height of the oscillograms do not compare the amplitude of the sounds.

Value

An object of class 'dynaspec_compare' (also of class 'dynaspec'), which is shown and saved as any dynaspec() object, with layers added with +.

See Also

dynaspec(), save_dynaspec()

Examples

data(female_barn_swallow, male_barn_swallow)

x <- ds_compare(female_barn_swallow, male_barn_swallow, flim = c(0, 10)) +
  ds_spectrogram(wl.ms = 23, collevels = seq(-50, 0, 1))

save_dynaspec(x, file.path(tempdir(), "swallows.html"), play = FALSE)

## Not run: 
# show it
x

# other panels, styles and themes, as in dynaspec()
x + ds_oscillogram() + ds_theme_mako()
x + ds_scrolling(t.display = 1)
x + ds_paged(t.display = 1) + ds_player(buttons = c("progress", "time", "loop"))

# more than two sounds
data(scythebill)
ds_compare(female_barn_swallow, male_barn_swallow, scythebill) +
  ds_spectrogram(wl.ms = 23)

# video (requires ffmpeg)
save_dynaspec(x, file.path(tempdir(), "swallows.mp4"))

# layers of a single sound
st <- data.frame(start = 0.5, end = 1, labels = "A")
a <- dynaspec(female_barn_swallow) + ds_annotations(st, labels = "labels")
ds_compare(a, male_barn_swallow, flim = c(0, 10), gap = 1) + ds_spectrogram(wl.ms = 23)

## End(Not run)

Amplitude envelope layer of dynamic spectrograms

Description

ds_envelope() adds the amplitude envelope of the sound (absolute amplitude smoothed with a 5 ms moving window) to a dynaspec() object. Envelopes are shown by ds_static() (alone, or above or below the spectrogram, along with oscillograms) and ds_scrolling() (below the spectrogram, instead of the oscillogram) styles.

Usage

ds_envelope(position = "below", col = NULL, height = NULL)

Arguments

position

Character string: "below" or "above" the spectrogram (only for ds_static()). Default is "below".

col

Color of the envelope. Default is NULL: 'col.wave' of ds_theme(), or black (as oscillograms).

height

Numeric vector of length 1 with the height of the envelope panel relative to that of the spectrogram. Default is NULL (half the height of the spectrogram).

Value

A layer to be added to a dynaspec() object with +.

See Also

dynaspec(), ds_oscillogram()

Examples

data(scythebill)

x <- dynaspec(scythebill, flim = c(1.5, 5.5)) +
  ds_spectrogram(wl.ms = 18, collevels = seq(-50, 0, 1)) +
  ds_envelope(position = "above")

Frequency filter layer of dynamic spectrograms

Description

ds_filter() applies a bandpass filter to the sound of a dynaspec() object (also to the sound of video files), so the filtered sound is both what is shown and what is heard, in all styles and outputs (web pages, videos and images). Removing noise outside the frequency range of the sounds of interest (e.g. wind, traffic or insects) gives a cleaner spectrogram and also a cleaner sound to listen to. Adding it again replaces the previous filter.

Usage

ds_filter(bp)

Arguments

bp

Numeric vector of length 2 with the frequency limits (in kHz) of the bandpass filter (as 'bp' in 'warbleR' functions). Inf as upper limit makes a high-pass filter, and 0 as lower limit a low-pass filter. Upper limits at or above the Nyquist frequency of the sound (half its sampling rate) are not applied.

Details

The filter is applied to the whole sound before it is cut with 'tlim' (so its edges are not affected), with seewave::ffilter() (a filter in the frequency domain with windows of 11.61 ms, the default window length of spectrograms). Stereo sounds are filtered channel by channel. Frequency contours measured by ds_annotations() are measured on the filtered sound.

Value

A layer to be added to a dynaspec() object with +.

See Also

dynaspec(), ds_spectrogram()

Examples

data(antshrike)

# sound between 0.5 and 4 kHz (the low-frequency noise is removed)
x <- dynaspec(antshrike, flim = c(0, 5.5), tlim = c(0, 5)) +
  ds_spectrogram(wl.ms = 23, collevels = seq(-50, 0, 1)) +
  ds_filter(bp = c(0.5, 4))

# high-pass filter
x <- x + ds_filter(bp = c(1, Inf))

Oscillogram layer of dynamic spectrograms

Description

ds_oscillogram() adds an oscillogram (waveform) to a dynaspec() object. Oscillograms are shown by ds_static() (alone, or above or below the spectrogram) and ds_scrolling() (below the spectrogram) styles.

Usage

ds_oscillogram(position = "below", col = NULL, height = NULL)

Arguments

position

Character string: "below" or "above" the spectrogram (only for ds_static(); ds_scrolling() always shows it below). Default is "below".

col

Color of the oscillogram. Default is NULL: 'col.wave' of ds_theme(), or "black".

height

Numeric vector of length 1 with the height of the oscillogram relative to that of the spectrogram (e.g. 0.5 is half as high). Default is NULL (style default).

Value

A layer to be added to a dynaspec() object with +.

See Also

dynaspec()


Overview layer of scrolling spectrograms

Description

ds_overview() adds a lower panel to ds_scrolling() spectrograms with the spectrogram of the whole sound, in which the part being shown is highlighted.

Usage

ds_overview(height = NULL)

Arguments

height

Numeric vector of length 1 with the height of the overview panel relative to that of the scrolling spectrogram. Default is NULL (a fifth of it).

Details

Scrolling spectrograms show a single lower panel: an overview, an oscillogram or an envelope (the first one added). Other styles do not show overviews (static spectrograms show the whole sound already).

Value

A layer to be added to a dynaspec() object with +.

See Also

dynaspec(), ds_scrolling()

Examples

data(antshrike)

x <- dynaspec(antshrike, flim = c(0.5, 5.5)) +
  ds_spectrogram(wl.ms = 23, collevels = seq(-50, 0, 1)) +
  ds_overview() + ds_scrolling(t.display = 2)

Player settings of dynamic spectrogram web pages

Description

ds_player() sets the playback controls of web pages.

Usage

ds_player(
  speeds = c(1, 0.5, 0.25, 0.125),
  keep.pitch = FALSE,
  buttons = "time"
)

Arguments

speeds

Numeric vector with the playback speeds offered by the speed slider (between 0.0625 and 16). The slider snaps to these values, ordered from the slowest (left) to the fastest (right). The first value is the initial speed. Use a single value to hide the slider. Default is c(1, 0.5, 0.25, 0.125).

keep.pitch

Logical argument to control if the pitch is initially kept when playback speed changes. Listeners can switch this with the 'keep pitch' button. If FALSE slowing down a sound also lowers its pitch (as when slowing down a tape), which makes fast sound features (e.g. pulses) easier to hear. If TRUE the web browser time-stretches the sound to keep its pitch. Default is FALSE.

buttons

Character vector with the additional controls shown next to the play button:

  • "time": current time and duration of the sound

  • "loop": button to play the sound repeatedly

  • "volume": mute button and volume slider

  • "download": button to save the sound (as a '.wav' or '.mp3' file, as embedded in the web page)

  • "fullscreen": button to show the player in full screen (e.g. in presentations)

  • "progress": seek bar showing the part of the sound played (drag it to move to another time)

  • "zoom": slider (with - and + buttons) to stretch or shrink scrolling spectrograms, showing from 4 times less to 4 times more time than 't.display' (at most the whole sound). Only in scrolling spectrograms; the scrolling spectrogram is drawn at twice the resolution so zooming in stays sharp, which makes web pages larger

Use character() to show only the play button and speed slider. Default is "time" (c("progress", "time") with themes with bar.style = "rounded", e.g. ds_theme_xenocanto()). Buttons are only shown in web pages (not in videos).

Value

A layer to be added to a dynaspec() object with +.

See Also

dynaspec()

Examples

## Not run: 
data("scythebill")

dynaspec(scythebill, flim = c(1.5, 5.5)) +
  ds_spectrogram(wl.ms = 18, collevels = seq(-50, 0, 1)) +
  ds_player(buttons = c("time", "loop", "volume", "download", "fullscreen"))

## End(Not run)

Set the theme of all dynamic spectrograms

Description

ds_set_theme() sets a theme used by all dynaspec() objects created or shown afterwards in the R session (e.g. in all the code chunks of an R Markdown or Quarto document), as ggplot2::theme_set(). ds_get_theme() returns the current theme.

Usage

ds_set_theme(theme = NULL)

ds_get_theme()

Arguments

theme

A theme: ds_theme() or a preset theme (e.g. ds_theme_dark()). NULL removes the theme (the defaults of each style are used).

Details

Themes added to a dynaspec() object with + take precedence: ds_theme() changes some settings of the global theme, while preset themes (e.g. + ds_theme_paper()) are complete themes that replace it.

Value

ds_set_theme() returns the previous theme invisibly (so it can be restored); ds_get_theme() returns the current theme (NULL if none was set).

See Also

ds_theme()

Examples

data(scythebill)

old <- ds_set_theme(ds_theme_dark(cex.lab = 1.3))

# uses the dark theme
x <- dynaspec(scythebill, flim = c(1.5, 5.5)) +
  ds_spectrogram(wl.ms = 18, collevels = seq(-50, 0, 1)) + ds_oscillogram()

# dark theme with other axis titles
x <- x + ds_theme(xlab = "Time of the song (s)")

# restore the previous theme
ds_set_theme(old)

Spectrogram layer of dynamic spectrograms

Description

ds_spectrogram() adds a spectrogram to a dynaspec() object and sets how it is computed and drawn. Adding it again changes its settings.

Usage

ds_spectrogram(
  wl = NULL,
  wl.ms = NULL,
  ovlp = NULL,
  wn = NULL,
  pal = NULL,
  collevels = NULL,
  col.bg = NULL,
  amp.trans = 1,
  ...
)

Arguments

wl

Window length (in samples), as in seewave::spectro(). Used when 'wl.ms' is not supplied.

wl.ms

Window length in milliseconds (as 'Window length' in Praat). Takes precedence over 'wl'. When neither is supplied the window lasts 11.61 ms (512 samples at 44.1 kHz) in all styles. The window length in samples is computed from the sampling rate of the sound (for paged spectrograms, after resampling), so sounds with different sampling rates (e.g. in ds_compare()) get windows of the same duration and the same time resolution.

ovlp

Percent overlap between consecutive windows, as in seewave::spectro().

wn

Window function name, as in seewave::spectro() (e.g. "hanning" or "blackman").

pal

Color palette of the spectrogram, from low to high amplitude: a palette function (e.g. viridis::viridis() or seewave::reverse.gray.colors.1()), the name of a 'viridis' palette (e.g. "magma"), or two or more colors for a gradient (e.g. c("white", "black") or c("white", "gold", "red", "black")).

collevels

Numeric vector with the amplitude levels (in dB) of the colors, as in seewave::spectro() (e.g. seq(-40, 0, 1)).

col.bg

Background color of the spectrogram, shown where the amplitude is below the lowest level of 'collevels'. Default is the color of the lowest amplitude of the palette (e.g. white for seewave::reverse.gray.colors.1(), the default palette, or dark blue for viridis::mako()), so quiet parts and the background look the same.

amp.trans

Amplitude transformation to brighten paged spectrograms (values > 1 brighten quiet sounds; only used by ds_paged()).

...

Additional arguments passed to seewave::spectro().

Details

Only the arguments supplied are used. Arguments with default NULL take the defaults of each style (ds_static(), ds_scrolling() or ds_paged()):

  • 'wl.ms' (or 'wl'): 11.61 ms (512 samples at 44.1 kHz) in all styles.

  • 'ovlp': 70 (static and scrolling) and 90 (paged).

  • 'wn': "hanning" (static and scrolling) and "blackman" (paged).

  • 'pal': seewave::reverse.gray.colors.1() (static and scrolling) and "inferno" (paged).

  • 'collevels': seq(-40, 0, 1) (static), 30 levels from the lowest to the highest amplitude, as in seewave::spectro() (scrolling) and seq(-30, 0, 1) (paged).

  • 'col.bg': the color of the lowest amplitude of the palette.

Value

A layer to be added to a dynaspec() object with +.

See Also

dynaspec()

Examples

data(scythebill)

x <- dynaspec(scythebill, flim = c(1.5, 5.5)) +
  ds_spectrogram(wl.ms = 18, pal = viridis::mako, collevels = seq(-60, 0, 1))

# window length in milliseconds (the same duration for any sampling rate)
x <- dynaspec(scythebill, flim = c(1.5, 5.5)) +
  ds_spectrogram(wl.ms = 15, collevels = seq(-50, 0, 1))

Power spectrum layer of dynamic spectrograms

Description

ds_spectrum() adds the mean power spectrum of the sound next to the spectrogram of a dynaspec() object, sharing its frequency axis. Power spectra are shown by the ds_static() style (with several rows, each row shows the spectrum of its segment, on the same scale).

Usage

ds_spectrum(side = "right", col = NULL, width = 0.1)

Arguments

side

Character string: "right" or "left" of the spectrogram. Default is "right".

col

Color of the spectrum. Default is NULL: 'col.wave' of ds_theme(), or black (as oscillograms).

width

Width of the spectrum panel as a proportion of the figure width. Default is 0.1.

Value

A layer to be added to a dynaspec() object with +.

See Also

dynaspec(), ds_spectrogram()

Examples

data(scythebill)

x <- dynaspec(scythebill, flim = c(1.5, 5.5)) +
  ds_spectrogram(wl.ms = 18, collevels = seq(-50, 0, 1)) + ds_spectrum(side = "left")

Theme of dynamic spectrograms

Description

ds_theme() sets the look of a dynaspec() object (axes, text, panels, colors and player controls), in the same way for all styles. Adding it again changes the settings supplied (other settings are kept). Preset themes (e.g. ds_theme_dark()) set several settings at once.

Usage

ds_theme(
  xlab = NULL,
  ylab = NULL,
  cex.lab = NULL,
  cex.axis = NULL,
  font.lab = NULL,
  col.lab = NULL,
  col.axis = NULL,
  axis.type = NULL,
  bg = NULL,
  family = NULL,
  las = NULL,
  tick.length = NULL,
  box = NULL,
  col.box = NULL,
  grid = NULL,
  col.grid = NULL,
  col.panel = NULL,
  col.title = NULL,
  cex.title = NULL,
  pal = NULL,
  col.bg = NULL,
  col.wave = NULL,
  col.line = NULL,
  lty.line = NULL,
  lwd.line = NULL,
  col.highlight = NULL,
  col.annotation = NULL,
  col.bar = NULL,
  bg.bar = NULL,
  bar.style = NULL
)

ds_theme_dark(...)

ds_theme_presentation(...)

ds_theme_paper(...)

ds_theme_minimal(...)

ds_theme_transparent(...)

ds_theme_void(...)

ds_theme_macaulay(...)

ds_theme_xenocanto(...)

ds_theme_mako(...)

Arguments

xlab, ylab

Titles of the time and frequency axes. Defaults are "Time (s)" and "Frequency (kHz)".

cex.lab, cex.axis

Size of axis titles and axis labels, relative to the style default (e.g. 1.5 is 50% larger). Defaults are 1 (1.2 for axis titles of static spectrograms).

font.lab

Font of axis titles: 1 (plain), 2 (bold), 3 (italic) or 4 (bold italic). Defaults are 1 (static and scrolling) and 2 (paged).

col.lab

Color of axes, axis labels and titles. Default is black (paged spectrograms: picked to contrast with the background).

col.axis

Color of the axis labels (tick labels), when they should differ from the axis titles and lines. Default is 'col.lab'.

axis.type

Character string: "standard" (axes with labels and titles), "inside" (no axis titles; frequency labels inside the spectrogram, e.g. "8k", and time labels below the lowest panel, e.g. "2s"), "compact" (no axis titles; frequency labels below short ticks in a narrow column on the left, with the unit at the bottom, and time labels in minutes and seconds, e.g. "0:02", above the figure), "minimal" (1 s and 1 kHz scale bars; scrolling spectrograms only) or "none" (no axes). Defaults are "standard" (static and scrolling) and "none" (paged).

bg

Background color of the figure around the panels ("transparent" for a transparent background). Default is white. The backgrounds of the panels are set separately: 'col.bg' (spectrograms, see ds_spectrogram()) and 'col.panel' (other panels).

family

Font family of all text, including captions and annotation labels: "sans", "serif", "mono" or the name of a font installed in the system. Default is "sans".

las

Orientation of the axis labels (tick labels), as in graphics::par(): 0 (parallel to the axis), 1 (horizontal), 2 (perpendicular to the axis) or 3 (vertical). Applies to both axes (e.g. 2 makes time labels vertical and frequency labels horizontal) with standard axes ('axis.type'). Defaults are 1 (static and paged: horizontal labels) and 0 (scrolling: vertical frequency labels).

tick.length

Length of axis ticks, in lines of text (0 hides ticks). Defaults are 0.5 (static and scrolling) and 0.3 (paged).

box

Logical argument to control whether boxes are drawn around panels. Default is TRUE.

col.box

Color of the boxes around panels. Default is 'col.lab'.

grid

Logical argument to control whether horizontal grid lines are drawn at the frequency axis ticks of spectrograms. Default is FALSE.

col.grid

Color of grid lines. Default is a translucent gray.

col.panel

Background color of oscillogram, envelope and power spectrum panels. Default is 'bg' (the figure background shows through).

col.title, cex.title

Color and size of titles (the title of paged spectrograms and the 'Amp.' label of power spectra). Defaults are 'col.lab' and 1.

pal, col.bg

Color palette and background of spectrograms (see ds_spectrogram()). Used when not supplied in ds_spectrogram().

col.wave

Color of oscillograms, envelopes and power spectra. Used when not supplied in ds_oscillogram(), ds_envelope() or ds_spectrum().

col.line

Color of the play line (and of the cursor of paged spectrograms and the active player buttons). Defaults are "#07889B99" (scrolling), "white" (paged) and viridis::mako(10)[9] (static).

lty.line, lwd.line

Type and width of the play line of scrolling and static spectrograms, as in graphics::par(): 'lty.line' is an integer (0-6) or a name ("solid", "dashed", "dotted", "dotdash", "longdash", "twodash" or "blank"), and 'lwd.line' a width in which 1 is 1/96 inch (scaled with the resolution). Defaults are 2 and 2 (scrolling), and a solid line 2 pixels wide (static).

col.highlight

Color of the highlight box of paged spectrograms (default "#4B0C6BFF") and of the translucent boxes dimming the parts of the ds_overview() outside the window shown in scrolling spectrograms. Default is gray in overviews.

col.annotation

Color of the boxes of ds_annotations(). Used when 'col' is not supplied in ds_annotations().

col.bar, bg.bar

Color of the text and background of the player controls of web pages (play button, sliders, ...). Defaults are dark gray and transparent (the page background).

bar.style

Style of the player controls of web pages: "standard" (rectangular buttons), "rounded" (round play button, rounded controls, a seek bar and a frame with rounded corners around the figure; 'bg.bar' is used as the background of the whole player) or "square" (flat bar with a square play button and sliders in the color of the play line). With "rounded" ds_player() shows the seek bar and the time by default (buttons = c("progress", "time")), and with "square" the volume control and the time (buttons = c("volume", "time")). Default is "standard".

...

Settings of ds_theme() that replace those of the preset theme.

Details

Only the settings supplied are used: settings left as NULL take the defaults of each style (given for each setting above). Settings supplied in other layers (e.g. the palette in ds_spectrogram()) take precedence over those of the theme.

Preset themes are complete themes: adding one replaces previous themes (use ds_theme() afterwards to change some of its settings, or supply them in the preset):

  • ds_theme_dark(): black figure background, white text, 'mako' palette (the spectrogram background is its darkest color, as in all presets).

  • ds_theme_mako(): light theme with the 'mako' palette (dark blue background and light sounds) and 'mako' colors for panels, annotations, play line and player controls.

  • ds_theme_presentation(): large bold text for slides and projectors.

  • ds_theme_paper(): black and white with serif fonts, for printed figures.

  • ds_theme_minimal(): no boxes, light gray axes and short ticks.

  • ds_theme_transparent(): transparent background, to blend in slides or web pages of any color.

  • ds_theme_void(): no axes, titles or boxes (only the sound).

  • ds_theme_macaulay(): inspired by the player of the 'Macaulay Library': gray spectrogram, compact axes (time in minutes and seconds above the figure) and a black player bar with a square play button. Best with ds_scrolling() and an ds_overview() (e.g. ds_scrolling(t.display = 1.5, fix.time = FALSE)).

  • ds_theme_xenocanto(): inspired by the player of the 'Xeno-canto' web site: gray spectrogram, labels inside the figure, solid play line and rounded player controls with a seek bar. Best with ds_scrolling() and an ds_oscillogram() (e.g. ds_scrolling(t.display = 1.5, fix.time = FALSE)).

Value

A layer to be added to a dynaspec() object with +.

See Also

ds_set_theme() to set a theme for all spectrograms, dynaspec(), ds_spectrogram()

Examples

data(scythebill)

x <- dynaspec(scythebill, flim = c(1.5, 5.5)) +
  ds_spectrogram(wl.ms = 18, collevels = seq(-50, 0, 1)) +
  ds_theme(xlab = "Time (s)", ylab = "Frequency (kHz)", cex.lab = 1.4, font.lab = 2)

# preset theme with larger axis titles
x <- dynaspec(scythebill, flim = c(1.5, 5.5)) +
  ds_spectrogram(wl.ms = 18, collevels = seq(-50, 0, 1)) + ds_oscillogram() +
  ds_theme_dark(cex.lab = 1.4)

# Macaulay Library look
data(antshrike)
x <- dynaspec(antshrike, flim = c(0.5, 5.5)) +
  ds_spectrogram(wl.ms = 23, collevels = seq(-50, 0, 1)) +
  ds_overview() + ds_theme_macaulay() + ds_scrolling(t.display = 3, fix.time = FALSE)

# Xeno-canto look (and its color version)
x <- dynaspec(antshrike, flim = c(0.5, 5.5)) +
  ds_spectrogram(wl.ms = 23, collevels = seq(-50, 0, 1)) + ds_oscillogram(height = 0.15) +
  ds_theme_xenocanto() + ds_scrolling(t.display = 3, fix.time = FALSE)
x <- x + ds_theme_xenocanto(pal = viridis::inferno, col.bg = "black", bg = "black",
  col.panel = "black", col.wave = "white", col.lab = "white", col.line = "white")

Video layer of dynamic spectrograms

Description

ds_video() shows the video of a dynaspec() object made from a video file together with the spectrogram. The video plays in step with the sound, also when playback is slowed down, in web pages and videos ('.mp4') of all styles.

Usage

ds_video(position = "above", height = NULL)

Arguments

position

Where the video goes, relative to the spectrogram:

  • "above" (default): the video on top and the spectrogram right below it.

  • "below": the spectrogram on top and the video below it.

Other panels (e.g. oscillograms) stay with the spectrogram.

height

Height of the video relative to the height of the figure with the spectrogram (including its axes and other panels), as 'height' in ds_oscillogram(): e.g. 3 makes the video three times as high as the figure, and 0.5 half as high. The video always takes the width of the figure (with its own proportions), so 'height' sets the height of the figure: it replaces 'height' of the style (ds_static(), ds_scrolling() or ds_paged()), keeping its width. Default is NULL: the figure keeps the height of its style.

Details

The sound of the dynamic spectrogram is the sound of the video, so 'tlim' in dynaspec() also cuts the video.

Outputs of save_dynaspec():

  • Videos ('.mp4'): the video and the spectrogram are shown one on top of the other, with the sound of the video. In scrolling spectrograms the video also slows down with the sound ('speed' of ds_scrolling()), waits during the 'buffer' and is repeated when looping.

  • Web pages: a silent copy of the video (re-encoded at up to 960 pixels wide) is embedded in the page and follows the sound at any speed. Embedded videos make web pages larger (about 1 MB for each 10 s of video), so cut long videos with 'tlim'.

  • Still images ('.png'): the video is not shown.

Videos are read with 'ffmpeg', so most formats can be used (e.g. '.mp4', '.mov', '.mkv', '.webm' or '.avi', with H.264, H.265, VP9 or AV1 video, as supported by the installed 'ffmpeg'). Videos must have sound (the first sound track is used).

Value

A layer to be added to a dynaspec() object with +.

See Also

dynaspec(), save_dynaspec()

Examples

## Not run: 
# a video file with sound (requires ffmpeg)
x <- dynaspec("field_recording.mp4", flim = c(1, 8), tlim = c(0, 20)) +
  ds_spectrogram(wl.ms = 12) +
  ds_video()

# web page (video above the spectrogram)
x

# video below the spectrogram, as high as the figure
x + ds_video(position = "below", height = 1)

# video file of a scrolling spectrogram
save_dynaspec(x + ds_scrolling(t.display = 2), "field_recording_spectrogram.mp4")

## End(Not run)

Create dynamic spectrograms

Description

dynaspec() starts a dynamic spectrogram of a sound. Layers are added with +, as in 'ggplot2' graphs: ds_spectrogram() and ds_oscillogram() add the panels, ds_annotations() and ds_captions() highlight and label parts of the sound, and ds_scrolling(), ds_paged() or ds_static() set the style. Printing the object shows an interactive web page (embedded in R Markdown and Quarto documents when knitting), and save_dynaspec() saves it as a web page, a video or still images.

Usage

dynaspec(wave, flim = NULL, tlim = NULL)

Arguments

wave

The sound: an object of class 'Wave', the path to a '.wav' or '.mp3' file, or the path to a video file with sound (e.g. '.mp4', '.mov', '.mkv', '.webm' or '.avi'; requires 'ffmpeg'). The sound of videos is used as the sound, and ds_video() shows the video next to the spectrogram.

flim

Numeric vector of length 2 with the frequency limits (in kHz). Default is NULL (from 0 to the Nyquist frequency, or the style default). Inf as upper limit means the Nyquist frequency of the sound (half its sampling rate). Any other upper limit higher than the Nyquist frequency gives a warning, and spectrograms are shown up to the Nyquist frequency.

tlim

Numeric vector of length 1 or 2 with the time range (in s) of the sound to use: a single value takes the first seconds of the sound, and two values a time interval. Inf as upper limit means the end of the sound. Times of ds_annotations() and ds_captions() refer to the whole sound. Default is NULL (whole sound).

Details

Panels are added as layers, as in 'ggplot2': only the panels added are shown (ds_spectrogram(), ds_oscillogram(), ds_envelope() or several of them, and ds_spectrum() next to the spectrogram). dynaspec() alone shows an empty panel with a time axis and the play line (annotations and captions can be drawn on it). Scrolling and paged spectrograms need a spectrogram.

The three styles show the sound in different ways:

  • ds_scrolling(): the spectrogram scrolls past the play line (the line only moves at the start and the end of the sound).

  • ds_paged(): the spectrogram is split into pages, and a translucent box reveals the part of each page being played.

  • ds_static() (default): a play line moves over the whole figure (spectrogram, oscillogram or both), which can be split in several rows.

Web pages include buttons to slow down playback (see ds_player()), and clicking on the spectrogram plays the sound from that point. Figures and sounds are embedded in the HTML code, so web pages can be shared as single files or pasted into any web page. Note that embedding sounds makes web pages larger (about 1.4 times the size of the sound file), so cut or downsample long recordings before creating web pages.

Settings not supplied in layers take the defaults of each style (e.g. paged spectrograms use the 'inferno' color palette unless ds_spectrogram() sets another one).

Value

An object of class 'dynaspec'.

Author(s)

Marcelo Araya-Salas ([email protected])

References

Araya-Salas M & Wilkins M R. (2020). dynaSpec: dynamic spectrogram visualizations in R. R package version 1.0.0.

See Also

save_dynaspec(), ds_spectrogram(), ds_scrolling()

Examples

data(scythebill)

# empty panel with time axis (only the panels added as layers are shown)
dynaspec(scythebill)

# static spectrogram with oscillogram (printing shows it in the viewer or browser)
x <- dynaspec(scythebill, flim = c(1.5, 5.5)) +
  ds_spectrogram(wl.ms = 18, collevels = seq(-50, 0, 1)) +
  ds_oscillogram()

# save as a web page
save_dynaspec(x, file.path(tempdir(), "scythebill.html"), play = FALSE)

## Not run: 
# show it
x

# paged style
x + ds_paged(t.display = 1)

# scrolling style (a longer recording)
data(antshrike)
y <- dynaspec(antshrike, flim = c(0.5, 5.5)) +
  ds_spectrogram(wl.ms = 23, collevels = seq(-50, 0, 1))
y + ds_scrolling(t.display = 2)

# video (requires ffmpeg)
save_dynaspec(y + ds_scrolling(t.display = 2), "antshrike.mp4")

# highlight and label parts of the song
st <- data.frame(start = c(0.34, 1.13, 1.44, 1.75), end = c(1.03, 1.36, 1.68, 2.28),
                 labels = c("A", "B", "B", "C"))
x + ds_annotations(st, labels = "labels") +
  ds_captions("Brown-billed scythebill", start = 0, end = 3)

# only the oscillogram
dynaspec(scythebill) + ds_oscillogram()

## End(Not run)

Save dynamic spectrograms

Description

save_dynaspec() saves a dynaspec() object as an interactive web page, a video or still images.

Usage

save_dynaspec(x, file.name = NULL, play = TRUE, verbose = TRUE)

Arguments

x

A dynaspec() or ds_compare() object.

file.name

Character string with the name of the file. The extension sets the output:

  • '.html': interactive web page.

  • '.mp4': video (requires 'ffmpeg').

  • '.png': still image of static spectrograms, or one image per page of paged spectrograms (named after 'file.name', followed by the page number).

Default is NULL, which returns the HTML code of the web page without saving it.

play

Logical argument to control if the file is opened after it is saved (or the web page is shown in the viewer when 'file.name' is NULL, in interactive sessions). Default is TRUE.

verbose

Logical argument to control if progress messages are printed. Default is TRUE.

Details

Videos of scrolling spectrograms render every frame, which takes time (it can be sped up with the 'parallel' and 'fps' arguments of ds_scrolling()). Videos of paged and static spectrograms and all web pages are created in seconds.

Value

Invisibly returns the path to the file, or the HTML code of the web page (a character string of class 'dynaSpec_html') when 'file.name' is NULL or ends in '.html'. When knitting R Markdown or Quarto documents the web page is embedded in the document.

See Also

dynaspec()

Examples

data(scythebill)

x <- dynaspec(scythebill, flim = c(1.5, 5.5)) +
  ds_spectrogram(wl.ms = 18, collevels = seq(-50, 0, 1)) + ds_oscillogram()

save_dynaspec(x, file.path(tempdir(), "scythebill.html"), play = FALSE)
save_dynaspec(x, file.path(tempdir(), "scythebill.png"), play = FALSE)

## Not run: 
# videos (require ffmpeg)
save_dynaspec(x, file.path(tempdir(), "scythebill.mp4"))
data(antshrike)
y <- dynaspec(antshrike, flim = c(0.5, 5.5)) +
  ds_spectrogram(wl.ms = 23, collevels = seq(-50, 0, 1))
save_dynaspec(y + ds_scrolling(t.display = 2), file.path(tempdir(), "antshrike_scrolling.mp4"))

## End(Not run)

Acoustic recording of a Campylorhamphus pusillus (brown-billed scythebill) song

Description

Song of a brown-billed scythebill recorded by Julio E. Sánchez in Cartago, Costa Rica, on 10 September 1998 (5:24 am), at a forest edge (two individuals were responding to each other, about 10-12 m high). Recorded on cassette with a Marantz PMD-222 recorder and a Telinga Pro II parabolic microphone, and digitized. Downsampled to 11.025 kHz (low-pass filtered below 5.25 kHz).

Usage

data(scythebill)

Format

A Wave object (tuneR::Wave): mono, 3.05 s, 11.025 kHz sampling rate, 16 bits.


Styles of dynamic spectrograms

Description

Set the style of a dynaspec() object:

  • ds_scrolling(): the spectrogram scrolls from right to left past the play line, which stays at the center (it only moves at the start and the end, while the spectrogram is still, so the window shown is always full of sound; see 'still.ends').

  • ds_paged(): the spectrogram is split into pages, and a translucent box reveals the part of each page being played.

  • ds_static(): a play line moves over the whole spectrogram (and oscillogram), which can be split in several rows (default style).

Usage

ds_scrolling(
  t.display = 1.5,
  still.ends = TRUE,
  fix.time = TRUE,
  buffer = 0,
  loop = 1,
  speed = 1,
  width = 700,
  height = 400,
  res = 70,
  fps = 50,
  parallel = 1,
  ...
)

ds_paged(
  t.display = NULL,
  title = NULL,
  highlight.alpha = 0.6,
  legend = FALSE,
  width = 1350,
  height = 450,
  res = 150,
  fps = 30,
  parallel = 1,
  ...
)

ds_static(
  rows = 1,
  width = 1000,
  height = 500,
  res = 100,
  alt = NULL,
  fps = 30,
  play.line = TRUE,
  ...
)

Arguments

t.display

Time (in s) shown at once: the time window of scrolling spectrograms (default 1.5) or the duration of each page of paged spectrograms (default: the whole sound, up to 5 s).

still.ends

Logical: keep the window shown within the sound in scrolling spectrograms? With TRUE the spectrogram is still at the start, while the play line moves from the left edge to the center, then scrolls with the line at the center, and is still again at the end, while the line moves to the right edge (so the window never shows the empty room before the start or after the end of the sound). With FALSE the line stays at the center and the sound enters from the center and leaves at the center. Looping spectrograms (loop > 1) always scroll continuously. Default is TRUE.

fix.time

Logical: does the time axis stay fixed (TRUE, default) or move along with the scrolling spectrogram?

buffer

Time (in s) before the scrolling spectrogram starts moving. Default is 0.

loop

Number of times the sound is repeated in scrolling videos (web pages loop until paused when > 1). Default is 1.

speed

Playback speed of videos of scrolling spectrograms (e.g. 0.5 for half speed). Web pages start at the first speed of ds_player() ('speeds'), as in all styles. Default is 1.

width, height, res

Size (in pixels) and resolution of the figures: frames of scrolling spectrograms (defaults 700, 400 and 70), pages of paged spectrograms (defaults 1350, 450 and 150; web pages show them at a higher resolution), and each row of static spectrograms (defaults 1000, 500 and 100).

fps

Frames per second of videos. Defaults are 50 (scrolling) and 30 (paged and static).

parallel

Number of cores used to render videos of scrolling and paged spectrograms. Default is 1.

...

Other arguments of the style:

  • ds_static(): none.

  • ds_scrolling(): 'ggspectro' (use seewave::ggspectro(); default FALSE), 'derivative' (spectral derivatives; requires 'imager'; default FALSE) and 'spectro.call' (a call to a spectrogram function replacing the default one, made with base::call()).

  • ds_paged(): 'resample.rate' (sampling rate in Hz used for the spectrogram; default 15000), 'amp.thresh' (amplitude threshold, as a percentage; default 0), 'dest.path' (folder for temporary files) and 'delete.temp' (delete temporary files; default TRUE).

title

Title of paged spectrograms.

highlight.alpha

Opacity of the highlight box of paged spectrograms (default 0.6).

legend

Logical: show the amplitude color scale of paged spectrograms? Default is FALSE.

rows

Number of rows in which static spectrograms are split (each row shows a consecutive segment of the same duration). Default is 1.

alt

Alternative text of static spectrograms in web pages (for screen readers).

play.line

Logical: show the line moving along the sound in static spectrograms? With FALSE web pages show the figure without the moving line (clicking on it still plays the sound from that point) and videos show the figure with the sound. Default is TRUE.

Details

Only the arguments supplied are used; other settings take the defaults shown.

Only the arguments supplied are used: the defaults shown are those of each style, which apply when an argument is not supplied (adding the style again keeps the arguments supplied before and changes those supplied again).

The play line (its color, type and width) and the color of the highlight box of paged spectrograms are set with ds_theme() ('col.line', 'lty.line', 'lwd.line' and 'col.highlight'), for all styles.

Value

A layer to be added to a dynaspec() object with +.

See Also

dynaspec(), save_dynaspec(), ds_theme()

Examples

data(scythebill)

x <- dynaspec(scythebill, flim = c(1.5, 5.5)) +
  ds_spectrogram(wl.ms = 18, collevels = seq(-50, 0, 1))

## Not run: 
data(antshrike)
y <- dynaspec(antshrike, flim = c(0.5, 5.5)) +
  ds_spectrogram(wl.ms = 23, collevels = seq(-50, 0, 1))
y + ds_scrolling(t.display = 2, axis.type = "minimal")
x + ds_paged(t.display = 1, axis.type = "standard")
x + ds_oscillogram() + ds_static(rows = 2, height = 350)
x + ds_theme(col.line = "red", lty.line = "dashed", lwd.line = 3)

## End(Not run)