Compute the per-tone mean f0 contour from long-format data

Aggregates a long-format f0 dataset into a per-tone mean contour suitable for plotting, comparison, or Chao numeral summarisation via contour_to_chao(). The function is used internally by the Summarise tab of the Shiny app when the user chooses the raw or normalised dataset as the input.

Usage

compute_mean_contour(
  data,
  token = "token",
  f0 = "f0",
  time = "time",
  tone = "tone",
  n_bins = 50,
  time_normalised = c("auto", "no", "yes")
)

Arguments

data

A long-format data frame with one row per f0 sample.

token, f0, time, tone

Column names.

n_bins

Number of evenly-spaced time bins across [0, 1]. Default 50. Larger values give a smoother contour at the cost of noisier per-bin estimates if some bins are sparsely populated.

time_normalised

One of "auto" (default: detect an already-normalised [0, 1] time column and use it as-is), "no" (always rescale to [0, 1] within each token), or "yes" (declare the column already normalised). See resolve_time_norm().

Value

A data frame with columns tone, time, f0_predicted, one row per (tone, time-bin).

Details

Internally:

1. Within each token, normalise the time axis to [0, 1] so tokens of different durations can be averaged across the same grid. A time column that is already normalised is detected with time_already_normalised() and used as-is (override with time_normalised), matching what fit_gca() and fit_gamm() do.

2. Round each sample's normalised time onto one of n_bins equally-spaced bins.

3. For each (tone, time-bin) cell, compute the mean of f0 across all tokens of that tone with samples in the bin.

4. Return the long-format mean contour with columns tone, time, f0_predicted (the column name f0_predicted matches the convention used by predict_gca() and predict_gamm() so the same downstream tools can consume either model predictions or raw mean contours).

References

Xu, C., & Zhang, C. (2024). A cross-linguistic review of citation tone production studies: Methodology and recommendations. The Journal of the Acoustical Society of America, 156(4), 2538–2565. doi:10.1121/10.0032356

See also

contour_to_chao() for converting mean contours to Chao numerals. predict_gca() and predict_gamm() for model-based alternatives that produce the same column structure.

Examples

data(sample_f0)
mc <- compute_mean_contour(sample_f0,
                           token = "token", f0 = "f0_Hz",
                           time  = "time",  tone = "tone")
head(mc)
#>   tone       time f0_predicted
#> 1    1 0.00000000     202.3695
#> 2    1 0.04081633     197.7551
#> 3    1 0.10204082     196.7470
#> 4    1 0.14285714     196.2067
#> 5    1 0.20408163     195.8127
#> 6    1 0.24489796     195.5778