Draw a Spectrogram — draw_spectrogram • rtemis.draw

Renders an interactive time-frequency spectrogram as an ECharts heatmap widget. Accepts either a raw signal vector (STFT is computed internally via signal::specgram()) or a pre-computed spectrogram matrix (freq x time).

Usage

draw_spectrogram(
  x,
  sample_rate = NULL,
  time = NULL,
  frequency = NULL,
  n_fft = 256L,
  window = "hanning",
  overlap = NULL,
  power = TRUE,
  db = TRUE,
  db_range = 80,
  freq_scale = "linear",
  freq_range = NULL,
  freq_unit = "Hz",
  time_range = NULL,
  time_unit = "s",
  colormap = "magma",
  colormap_reverse = FALSE,
  n_colors = 256L,
  zlim = NULL,
  show_colorbar = TRUE,
  colorbar_title = NULL,
  title = NULL,
  xlab = NULL,
  ylab = NULL,
  theme = NULL,
  margins = NULL,
  width = NULL,
  height = NULL,
  element_id = NULL,
  filename = NULL,
  verbosity = 1L,
  legend_position = "right",
  legend_placement = "outside"
)

Arguments

x: Numeric matrix (freq x time) or numeric vector (raw signal). A matrix is used directly; time and frequency vectors supply axis values (defaults to sample indices when absent). A complex matrix (raw STFT output, e.g. from signal::specgram()$S) is also accepted. A vector triggers STFT computation via signal::specgram(); sample_rate is required.
sample_rate: Optional Numeric (0, Inf): Sampling frequency in Hz. Required when x is a raw signal vector.
time: Optional Numeric: Time axis values in seconds, length ncol(x). Only used when x is a matrix.
frequency: Optional Numeric: Frequency axis values in Hz, length nrow(x). Only used when x is a matrix.
n_fft: Integer [2, Inf): FFT window size in samples. Passed to signal::specgram() as n. Only used when x is a raw signal.
window: Character {"hanning", "hamming", "blackman", "bartlett", "rectangular"} or Numeric: Window function name or a pre-built window vector. Passed to signal::specgram(). Only used when x is a raw signal.
overlap: Optional Integer [0, n_fft): Overlap between consecutive frames in samples. Defaults to n_fft / 2. Only used when x is a raw signal.
power: Logical: Treat spectral values as power (TRUE) or amplitude (FALSE). When x is complex, controls whether the STFT magnitude is squared (|S|^2) or left as-is (|S|). When db = TRUE, also determines the dB scaling for real matrices: 10 * log10() for power, 20 * log10() for amplitude.
db: Logical: Convert to dB. For power: 10 * log10(); for amplitude: 20 * log10(). Set FALSE when passing a pre-computed dB matrix.
db_range: Numeric (0, Inf): Dynamic range to display in dB below the spectral peak. Values below peak - db_range are clipped to the floor.
freq_scale: Character {"linear", "log"}: Frequency axis scale. With "log" the DC component (0 Hz) is automatically dropped.
freq_range: Optional Numeric[2]: Frequency range to display in Hz, e.g. c(20, 8000). Applied after STFT computation.
freq_unit: Character {"Hz", "kHz"}: Unit for the frequency axis.
time_range: Optional Numeric[2]: Time range to display in seconds.
time_unit: Character {"s", "ms"}: Unit for the time axis.
colormap: Character: Color palette. Accepts a viridisLite colormap name ("magma" (default), "inferno", "plasma", "viridis", "cividis", "mako", "rocket", "turbo"), "diverging" for the rtemis teal-background-orange scale (suitable for signed data such as EEG/MEG amplitudes), or a character vector of >= 2 hex colors for a custom ramp.
colormap_reverse: Logical: Reverse the colormap direction.
n_colors: Integer [2, Inf): Number of discrete colors in the generated palette.
zlim: Optional Numeric[2]: Color-scale limits after all transformations (dB clipping, unit conversion). Defaults to the data range.
show_colorbar: Logical: Show the continuous visual-map colorbar.
colorbar_title: Optional Character: Colorbar label. Default: "dB", "Power", or "Amplitude" derived from db and power.
title: Optional Character: Chart title.
xlab: Optional Character: X-axis label. Default: "Time (s)" or "Time (ms)" depending on time_unit.
ylab: Optional Character: Y-axis label. Default: "Frequency (Hz)" or "Frequency (kHz)" depending on freq_unit.
theme: Optional Theme, list, or NA: Theme override passed to draw().
margins: Optional Named numeric or character vector / list: Plot margins in pixels. Valid names: "top", "right", "bottom", "left".
width: Optional Numeric or Character: Widget width.
height: Optional Numeric or Character: Widget height.
element_id: Optional Character: Explicit DOM element ID for the widget container. NULL lets htmlwidgets generate one.
filename: Optional Character: If provided, the widget is saved via save_drawing().
verbosity: Integer [0, Inf): Verbosity level. 0 silences the large-spectrogram performance advisory.
legend_position: Character {"top", "bottom", "left", "right", "top-left", "top-right", "bottom-left", "bottom-right"}: Legend anchor. Top/bottom anchors use horizontal rows; left/right anchors use a vertical column. Corner anchors align within the top or bottom row.
legend_placement: Character {"outside", "inside"}: Relation to the plotting area. Outside placement reserves space for the complete legend; inside placement overlays the data. Neither setting adds a missing legend.

Value

htmlwidget

Details

Corresponds to HeatmapSeriesOption in src/chart/heatmap/HeatmapSeries.ts. ECharts docs: https://echarts.apache.org/en/option.html#series-heatmap

Examples

if (requireNamespace("signal", quietly = TRUE)) {
  t_vec <- seq(0, 2, by = 1 / 8000)
  sig   <- signal::chirp(t_vec, 200, 2, 2000)
  draw_spectrogram(sig, sample_rate = 8000)
}