R: Make Praat Picture style plots of acoustic data

praatpicture {praatpicture}

R Documentation

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_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 = 1,
  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_dottedLines = TRUE,
  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_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. The numbers should sum up to 100. 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'`.
`tg_obj`	A TextGrid object returned by the `make_TextGrid()` function.
`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).
`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.
`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).
`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'`.
`formant_dottedLines`	Logical; should dotted lines indicate the locations of frequency multiples of 1000 as in Praat? Default is `TRUE`.
`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.
`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_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)

[Package praatpicture version 1.0.0 Index]