PAMscapes (version 0.7.0)

plotPSD: Plot Power Spectral Density

Description

Plots the distribution of summarised sound levels across frequency, either as lines of quantile levels or a heatmap showing the full distribution. Multiple PSD sources can be combined and plotted as long as they have identical frequency levels.

Usage

plotPSD(
  x,
  style = c("quantile", "density"),
  scale = c("log", "linear"),
  q = 0.5,
  color = "black",
  freqRange = NULL,
  dbRange = NULL,
  dbInt = 1,
  densityRange = NULL,
  units = "dB re: 1uPa^2/Hz",
  cmap = viridis_pal()(25),
  by = NULL,
  title = NULL,
  returnData = FALSE,
  progress = TRUE
)
prepPSDData(
  x,
  freqRange = NULL,
  style = c("density", "quantile"),
  by = NULL,
  dbInt = 1,
  compression = 10000,
  progress = TRUE
)

Value

a ggplot object for plotPSD, see details for prepPSDData

Arguments

x

a dataframe or list of dataframes, or file path or vector of file paths, or the output from prepPSDData

style

character specifying plot style to create, either "quantile", "density", or a vector with both

scale

scale to use for frequency axis, one of "log" or "linear"

q

quantile to plot

color

color for quantile

freqRange

range of frequencies to plot

dbRange

range of dB values to plot

dbInt

bin interval size for density plot

densityRange

optional range of values for density color scale

units

units for dB axis of plot

cmap

color map to use for density plot

by

optional column to plot different quantile lines by, only affects style='quantile'. If x is a data.frame, by can also be one of 'hour', 'month', or 'year' and that column will be created automatically if not present.

title

optional title for plot

returnData

if TRUE then no plot will be generated, instead the dataframe that would normally be used to make the plot will be returned

progress

logical flag to show progress bar

compression

compression factor for tdigest, lower values are less accurate but will compute faster. Only relevant for style='quantile' when loading and combining multiple datasets

Author

Taiki Sakai

Details

prepPSDData is called by the plotting code, and does not necessarily need to be called separately from plotPSD. Loading PSD data can be time consuming, so it may be useful to load the data first, then it is easier to spend time adjusting plot settings.

The output of prepPSDData is a list with 5 elements:

frequency

- the frequency values of the input data

freqRange

- the value of the "freqRange" parameter if it was supplied

dbVals

- the dB values of breakpoints used for "density" plotting

quantileData

- the data used for quantile plots. These are stored as "tidgest" objects serialized using as.list.tdigest, from which quantiles can be computed

densityData

- the data used fro quantile plots. These are stored as a matrix of bin counts - each column corresponds to the "frequency" output, each row corresponds to bins defined using "dbVals" as boundaries

Examples

psd <- checkSoundscapeInput(system.file('extdata/PSDSmall.csv', package='PAMscapes'))
# Plotting only first 1000 columns for brevity
plotPSD(psd[1:1000], style='density')
plotPSD(psd[1:1000], style='quantile', q=.05)