waveplot: Plot waveform

In praatpicture: 'Praat Picture' Style Plots of Acoustic Data

Plot waveform

Description

Function for plotting waveforms called by praatpicture. Instead of using this function directly, just use praatpicture('my_sound_file', frames='sound').

Usage

waveplot(
  sig,
  bit,
  t,
  start,
  tfrom0 = TRUE,
  nchan = 1,
  energyRange = NULL,
  color = "black",
  pitch_plotOnWave = FALSE,
  pt = NULL,
  pitch_plotType = "draw",
  pitch_scale = "hz",
  pitch_freqRange = NULL,
  pitch_axisLabel = NULL,
  pitch_color = "black",
  pitch_highlight = NULL,
  intensity_plotOnWave = FALSE,
  it = NULL,
  intensity_range = NULL,
  intensity_axisLabel = "Intensity (dB)",
  intensity_color = "black",
  intensity_highlight = NULL,
  tgbool = FALSE,
  lines = NULL,
  focusTierColor = "black",
  focusTierLineType = "dotted",
  ind = NULL,
  line_comp = NULL,
  rect_comp = NULL,
  arr_comp = NULL,
  annot_comp = NULL,
  draw_lines = NULL,
  draw_rectangle = NULL,
  draw_arrow = NULL,
  annotate = NULL,
  channelNames = FALSE,
  axisDigits = 3,
  lineWidth = 1,
  cn = NULL,
  min_max_only = TRUE,
  highlight = NULL,
  drawSize = 1,
  speckleSize = 1
)

Arguments

sig	Numeric vector corresponding to a sound signal.
bit	Numeric; will generally be grabbed from a loaded WaveMC object.
t	Numeric vector giving times corresponding to the signal.
start	Start time (in seconds) of desired plotted area.
tfrom0	Logical; should time on the x-axis run from 0 or from the original time? Default is TRUE.
nchan	Numeric; how many channels will be plotted? Default is 1.
energyRange	Numeric vector giving the desired energy range (y-axis range) of waveform(s). Default is NULL, in which case the y-axis range is set to the lowest and highest value for each wave. If a vector of two values is passed for a multi-wave plot, these are recycled for each wave. Separate ranges can be set for each waveform by passing a vector of a length corresponding to twice the number of waves plotted.
color	String giving the name of the color to be used for plotting the waveform. Default is 'black'. Alternatively, a vector of colors, if different channels should be plotted with different colors.
pitch_plotOnWave	Boolean; should pitch be plotted on top of waveform? Default is FALSE.
pt	Pitch object loaded using rPraat::pt.read or similar object.
pitch_plotType	String giving the type of pitch plot to produce; default is draw (a line plot), the only other option is speckle (a point plot). Alternatively a vector c('draw','speckle') can be passed, in which case both are used.
pitch_scale	String giving the frequency scale to use when producing pitch plots. Default is hz; other options are logarithmic (also in Hz), semitones, erb, and mel.
pitch_freqRange	Vector of two integers giving the frequency range to be used for producing pitch plots. Default is NULL, in which case the pitch range is automatically reset to c(-12,30) for the semitones scale, c(0,10) for the erb scale, and c(50,500) for the Hz-based scales, following Praat defaults.
pitch_axisLabel	String giving the name of the label to print along the y-axis when printing a pitch track. Default is NULL, in which case the axis label will depend on the scale.
pitch_color	String or vector of strings giving the name of the color to be used for plotting pitch. Default is 'black'. If a vector of two strings is passed, the second color will be used for background highlighting.
pitch_highlight	Named list giving parameters for differential highlighting of pitch based on the time domain. This list should contain information about which parts of the plot to highlight, either done with the start and end arguments which must be numbers or numeric vectors, or using the tier and label arguments to highlight based on information in a plotted TextGrid. Further contains the optional arguments color (string or vector of strings, see pitch_color), drawSize or speckleSize (both numeric).
intensity_plotOnWave	Boolean; should intensity be plotted on top of waveform? Default is FALSE.
it	Intensity object loaded using rPraat::it.read or similar object.
intensity_range	Vector of two integers giving the intensity range to be used for producing intensity plots. Default is NULL, in which case the range is simply the minimum and maximum levels in the curve.
intensity_axisLabel	String giving the name of the label to print along the y-axis when plotting intensity. Default is Intensity (dB).
intensity_color	String or vector of strings giving the name of the color to be used for plotting intensity. Default is 'black'. If a vector of two strings is passed, the second color will be used for background highlighting.
intensity_highlight	Named list giving parameters for differential highlighting of the intensity contour based on the time domain. This list should contain information about which parts of the plot to highlight, either done with the start and end arguments which must be numbers or numeric vectors, or using the tier and label arguments to highlight based on information in a plotted TextGrid. Further contains the optional arguments color (string or vector of strings, see intensity_color) and drawSize (integer).
tgbool	Logical; should dotted lines be plotted corresponding to locations in a TextGrid? Default is FALSE.
lines	Numeric vector giving locations in seconds of locations from a TextGrid to be plotted with dotted lines. Default is NULL.
focusTierColor	String or vector of strings giving the color(s) to use for plotting focus tier lines. If multiple tiers are focused, a vector of the same length can be passed, and the nth tier will be plotted in the nth color. Default is 'black'.
focusTierLineType	String or vector of strings giving the line type(s) for plotting focus tier lines. If multiple tiers are focused, a vector of the same length can be passed, and the nth tier will be plotted in the nth line type. Default is 'dotted'.
ind	Integer indexing waveform relative to other plot components. Default is NULL.
line_comp	Vector of strings or numbers giving plot components to draw straight lines on. Default is NULL.
rect_comp	Vector of strings or numbers giving plot components to draw rectangles on. Default is NULL.
arr_comp	Vector of strings of numbers giving plot components to draw arrows on. Default is NULL.
annot_comp	Vector of strings of numbers giving plot components to annotate. Default is NULL.
draw_lines	List of arguments for drawing straight lines passed from praatpicture(). Default is NULL.
draw_rectangle	List of arguments for drawing rectangles passed from praatpicture(). Default is NULL.
draw_arrow	List of arguments for drawing arrows passed from praatpicture(). Default is NULL.
annotate	List of arguments for annotating passed from praatpicture(). Default is NULL.
channelNames	Logical; should names of audio channels be printed on the y-axis? Default is FALSE.
axisDigits	Numeric giving the number of digits to print for values along the y-axis of the waveform. Default is 3. If 0 is passed, the y-axis is suppressed. Note that this only applies when min_max_only = TRUE, as otherwise the look of the y-axis is determined entirely using grDevices::axisTicks().
lineWidth	Number giving the line width to use for plotting the waveform. Default is 1.
cn	Vector of strings with channel names to be printed on the y-axis if channelNames is TRUE.
min_max_only	Logical; should only minimum and maximum values be given on the y-axis? Default is TRUE. Can also be a logical vector if some but not all plot components should have minimum and maximum values on the y-axis. Ignored for TextGrid component.
highlight	Named list giving parameters for differential highlighting of the waveform based on the time domain. This list should contain information about which parts of the plot to highlight, either done with the start and end arguments which must be numbers or numeric vectors, or using the tier and label arguments to highlight based on information in a plotted TextGrid. Further contains the argument color (string, see color), and background (a string specifying a background color).
drawSize	Number indicating the line width of plot components where the ⁠_plotType⁠ is 'draw' (i.e., pitch, formants, or intensity rendered as line plots). Default is 1. Controls the lwd argument of graphics::lines.
speckleSize	Number indicating the point size of plot components where the ⁠_plotType⁠ is 'speckle' (i.e. pitch or formants rendered as point plots). Default is 1. Controls the cex arguments of graphics::points.

Value

No return values, called internally by praatpicture and sibling functions.

Examples

# Don't use directly
datapath <- system.file('extdata', package='praatpicture')
soundFile <- paste0(datapath, '/1.wav')
praatpicture(soundFile, frames='sound')

praatpicture documentation built on Dec. 9, 2025, 1:06 a.m.