praatpicture {praatpicture}

Make Praat Picture style plots of acoustic data

Description

Generate plots of acoustic data aligned with transcriptions similar to those made with Praat Picture. The default is to produce a plot with a relatively small waveform, somewhat larger spectrogram, and the first tier of a TextGrid.

Usage

praatpicture(
  sound,
  start = 0,
  end = 0,
  tfrom0 = TRUE,
  frames = c("sound", "spectrogram", "TextGrid"),
  proportion = c(30, 50, 20),
  mainTitle = "",
  start_end_only = TRUE,
  min_max_only = TRUE,
  wave_channels = "all",
  wave_channelNames = FALSE,
  wave_color = "black",
  tg_obj = NULL,
  tg_file = NULL,
  tg_tiers = "all",
  tg_focusTier = tg_tiers[1],
  tg_focusTierColor = "black",
  tg_focusTierLineType = "dotted",
  tg_tierNames = TRUE,
  tg_alignment = "central",
  tg_specialChar = FALSE,
  tg_color = "black",
  spec_channel = NULL,
  spec_freqRange = c(0, 5000),
  spec_windowLength = 0.005,
  spec_dynamicRange = 50,
  spec_timeStep = 1000,
  spec_windowShape = "Gaussian",
  spec_colors = c("white", "black"),
  spec_axisLabel = "Frequency (Hz)",
  pitch_timeStep = NULL,
  pitch_floor = 75,
  pitch_ceiling = 600,
  pitch_plotType = "draw",
  pitch_scale = "hz",
  pitch_freqRange = NULL,
  pitch_semitonesRe = 100,
  pitch_color = "black",
  pitch_plotOnSpec = FALSE,
  pitch_ssff = NULL,
  pitch_axisLabel = NULL,
  formant_timeStep = NULL,
  formant_maxN = 5,
  formant_windowLength = 0.025,
  formant_dynamicRange = 30,
  formant_freqRange = c(50, 5500),
  formant_plotType = "speckle",
  formant_color = "black",
  formant_plotOnSpec = FALSE,
  formant_ssff = NULL,
  formant_axisLabel = "Frequency (Hz)",
  intensity_timeStep = NULL,
  intensity_minPitch = 100,
  intensity_range = NULL,
  intensity_color = "black",
  intensity_plotOnSpec = FALSE,
  intensity_ssff = NULL,
  intensity_axisLabel = "Intensity (dB)",
  time_axisLabel = "Time (s)",
  draw_lines = list("formant", h = seq(0, 10000, by = 1000), lty = "dotted"),
  draw_rectangle = NULL,
  draw_arrow = NULL,
  annotate = NULL,
  gender = "u",
  ...
)

Arguments

sound

String giving the file name of a sound file with the .wav extension.

start

Start time (in seconds) of desired plotted area. Default is 0.

end

End time (in seconds) of desired plotted area. Default is 0 (= the entire file).

tfrom0

Logical; should time on the x-axis run from 0 or from the original time? Default is TRUE.

frames

String or vector of strings giving the frames that the plot should consist of. Default is sound, spectrogram, TextGrid. This requires a file with the extension .TextGrid and the same base name as the sound file. Other options are pitch, formant, and intensity. See details for more information.

proportion

Integer or vector of integers of the same size as frames giving the proportion in percents of the plotting area to be taken up by the individual frames. Default is c(30,50,20). If more or less than three frames are plotted and no proportions are given, frames will be of equal size.

mainTitle

String giving a title to print at the top left. The default is an empty string, i.e. no title.

start_end_only

Logical; should there only be ticks on the x-axis for start and end times? Default 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.

wave_channels

Vector of numbers or strings giving either numeric identifiers of audio channels to plot of the names of audio channels to plot. Also understands 'all', which plots all channels and is the default.

wave_channelNames

Should names of audio channels be printed on the y-axis? If TRUE, names will be grabbed from the audio metadata if available. Alternatively, if two channels are available, they will be named left and right. If more or less than two channels are available, channels are named Cn, where n is the number of the channel. Alternatvely, a vector of strings can be provided with channel names. Default is FALSE.

wave_color

String giving the name of the color to be used for plotting the waveform. Default is 'black'. Alternatively a vector of strings, if different colors should be used for different channels.

tg_obj

A TextGrid object returned by the make_TextGrid() function.

tg_file

Path of file to be used for plotting TextGrid. Default is NULL, in which case the function searches for a TextGrid sharing the same base name as sound with the .TextGrid extension.

tg_tiers

Vector of numbers or strings giving either numeric identifiers of TextGrid tiers to plot or the names of TextGrid tiers to plot. Also understands 'all', which plots all tiers and is the default.

tg_focusTier

For which tier(s) should lines be shown on all acoustic plots giving the locations of boundaries? Vector of number or strings giving either numeric identifiers of TextGrid tiers or the names of TextGrid tiers to plot. Default is tg_tiers[1], i.e. the first tier given in the tg_tiers argument. Additionally accepts the string none, in which case no lines are shown on acoustic plots, and all, in which case lines from all tiers are shown on acoustic plots.

tg_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'.

tg_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'.

tg_tierNames

Logical; should TextGrid tier names be printed along the y-axis? Default is TRUE.

tg_alignment

String giving the desired alignment of text in the TextGrids. Default is central; other options are left and right. Alternatively, a vector of strings if different alignments are needed.

tg_specialChar

Logical; should Praat typesetting for special font types such as italic, bold, and small caps be converted into corresponding R-readable special font types. Default is FALSE, since special characters can create unfortunate text alignment artefacts. See https://www.fon.hum.uva.nl/praat/manual/Text_styles.html.

tg_color

String or vector of strings giving the name of the color(s) to be used for the text in TextGrids. Default is 'black'. If a vector is provided, different colors are used for different tiers.

spec_channel

Numeric giving the channel that should be used to generate the spectrogram. Default is 1. Generating spectrograms from multiple channels is not currently possible with praatpicture.

spec_freqRange

Vector of two integers giving the frequency range to be used for plotting spectrograms. Default is c(0,5000).

spec_windowLength

Window length in seconds for generating spectrograms. Default is 0.005.

spec_dynamicRange

Dynamic range in dB for generating spectrograms. The maximum intensity minus spec_dynamicRange will all be printed in white. Default is 50.

spec_timeStep

How many time steps should be calculated for spectrograms? Default is 1000.

spec_windowShape

String giving the name of the window shape to be applied to the signal when generating spectrograms. Default is Gaussian; other options are square, Hamming, Bartlett, or Hanning.

spec_colors

Vector of strings giving the names of colors to be used for plotting the spectrogram; default is c('white', 'black'). The first value is used for plotting the lowest visible amplitude, and the last for plotting the highest visible amplitude. Vectors with more than two color names can be used for plotting values in between in different colors.

spec_axisLabel

String giving the name of the label to print along the y-axis when plotting a spectrogram. Default is Frequency (Hz).

pitch_timeStep

Measurement interval in seconds for tracking pitch. Default is NULL, in which case the measurement interval is equal to 0.75 / pitch_floor.

pitch_floor

Frequency in Hz; no pitch candidates considered below this frequency. Default is 75.

pitch_ceiling

Frequency in Hz; no pitch candidates considered above this frequency. Default is 600.

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_semitonesRe

Frequency in Hz giving the reference level for converting pitch frequency to semitones. Default is 100.

pitch_color

String giving the name of the color to be used for plotting pitch. Default is 'black'. If pitch_plotOnSpec=TRUE, axes will follow the same color scheme. Also if pitch_plotOnSpec=TRUE, a vector of two strings can be passed, in which case the second color is used for background highlighting.

pitch_plotOnSpec

Boolean; should pitch be plotted on top of spectrogram? Default is FALSE.

pitch_ssff

An object of class AsspDataObj containing a pitch track. Default is NULL.

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. If pitch_plotOnSpec=TRUE, this label will be printed on the right-hand y-axis label.

formant_timeStep

Measurement interval in seconds for tracking formants. Default is NULL, in which case the measurement interval is equal to formant_windowLength / 4.

formant_maxN

Integer giving the maximum number of formants to track. Default is 5.

formant_windowLength

The effective duration of the analysis window used for tracking formants in seconds; the actual duration of the analysis window is twice this value.

formant_dynamicRange

Dynamic range in dB for producing formant plots. When a formant plot of formant_plotType='speckle' is drawn, no formants are shown in frames with intensity level formant_dynamicRange below the maximum intensity. Default is 30. If set to 0, all formants are shown.

formant_freqRange

Vector of two integers giving the frequency range to be used for producing formant plots. Default is c(0,5500).

formant_plotType

String giving the type of formant plot to produce; default is speckle (a point plot), the only other option is draw (a line plot). Alternatively a vector c('draw','speckle') can be passed, in which case both are used.

formant_color

String or vector of strings giving the name(s) of colors to be used for plotting formants. If one color is provided, all formants will be plotted in this color. If multiple colors are provided, different formants will be shown in different colors. Default is 'black'. If formant_plotOnSpec=TRUE and the length of this vector twice the number of formants plotted, the first half of strings will be used for the formants' primary colors and the second half will be used for background highlighting. If the length of this vector is one more than the number of formants plotted, the last string will be used for background highlighting.

formant_plotOnSpec

Boolean; should formants be plotted on top of spectrogram? Default is FALSE.

formant_ssff

An object of class AsspDataObj containing formant tracks. Default is NULL.

formant_axisLabel

String giving the name of the label to print along the y-axis when plotting formants. Default is Frequency (Hz).

intensity_timeStep

Measurement interval in seconds for tracking intensity. Default is NULL, in which case the measurement interval is equal to 0.8 * intensity_minPitch.

intensity_minPitch

Lowest pitch in Hz used when calculating intensity; default is 100

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_color

String giving the name of the color to be used for plotting intensity. Default is 'black'. If intensity_plotOnSpec=TRUE, axes will follow the same color scheme. Also if intensity_plotOnSpec=TRUE, a vector of two strings can be passed, in which case the second color is used for background highlighting.

intensity_plotOnSpec

Boolean; should intensity be plotted on top of spectrogram? Default is FALSE.

intensity_ssff

An object of class AsspDataObj containing intensity tracks. Default is NULL.

intensity_axisLabel

String giving the name of the label to print along the y-axis when plotting intensity. Default is Intensity (dB). If intensity_plotOnSpec=TRUE, this label will be printed on the right-hand y-axis label.

time_axisLabel

String giving the name of the label to print along the x-axis. Default is Time (s).

draw_lines

Use for drawing straight lines on plot components. Takes an argument of type list which should contain a) a string giving the plot component to draw straight lines on, and b) arguments to pass on to graphics::abline. Should have a named argument h for horizontal lines, or v for vertical lines, or a,b for the intercept and slope of the line otherwise. Alternatively a nested list can be passed if more (sets of) lines should be drawn. If multiple audio channels are plotted and lines should be added to one of these, use the channel identifier instead of a string giving the frame to draw on. The default value is list('formant', h=seq(0,10000,by=1000), lty='dotted'). According to Praat defaults, this means that if formants are plotted in a separate frame, horizontal dotted lines (lty) are shown at 1000 Hz intervals. To override this behavior, simply pass draw_lines=NULL.

draw_rectangle

Use for drawing rectangles on plot components. A vector containing a) a string giving the plot component to draw a rectangle on, and b) arguments to pass on to graphics::rect. Alternatively a list of such vectors, if more rectangles should be drawn. If multiple audio channels are plotted and a rectangle should be added to one of these, use the channel identifier instead of a string giving the frame to draw on.

draw_arrow

Use for drawing arrows on plot components. A vector containing a) a string giving the plot component to draw an arrow on, and b) arguments to pass on to graphics::arrows. Alternatively a list of such vectors, if more arrows should be drawn. If multiple audio channels are plotted and an arrow should be added to one of these, use the channel identifier instead of a string giving the frame to draw on.

annotate

Use for annotating plot components. A vector containing a) a string giving the plot component to annotate, and b) arguments to pass on to graphics::text. Alternatively a list of such vectors, if more annotations should be made. If multiple audio channels are plotted and annotations should be added to one of these, use the channel identifier instead of a string giving the frame to draw on.

gender

String indicating the gender of the speaker; default is u for unknown, other legal values are m and f. Used to tweak pitch and formant tracking parameters.

...

Further global plotting arguments passed on to par().

Details

When available, pitch, formant, and intensity tracks are loaded from Praat files with the same base name as sound; i.e., if your sound file is called ⁠1.wav⁠ and there is a Praat file called ⁠1.Formant⁠ in the same directory, this file is used for plotting formants. Pitch files should have the PitchTier extension, and intensity files should have the IntensityTier extension.

If no such files are available, the signal processing tools in the wrassp package are used; pitch is tracked with the function wrassp::ksvF0, formants are tracked with wrassp::forest, and intensity is tracked with wrassp::rmsana. Parameters are set to mimic Praat as closely as possible, e.g. using a Gaussian-like window shape KAISER2_0, but results will differ from Praat simply because the tracking algorithms differ; as far as I know, the Burg algorithm used by Praat for tracking formants isn't implemented in R, nor is the autocorrelation method for tracking pitch.

Spectrograms are generated with the function phonTools::spectrogram. The code portion that actually adds the spectrogram to a plot is based on phonTools::plot.spectrogram but rewritten to use a bitmap raster for rendering the image if the graphics device allows for it, which significantly speeds up rendering the spectrogram.

Value

No return value, produces a figure.

Examples

datapath <- system.file('extdata', package='praatpicture')
soundFile <- paste0(datapath, '/1.wav')
praatpicture(soundFile)