ProsCanvas v8.12.4 — Concise User Manual

1. Purpose and scope

ProsCanvas is a speech-prosody explorer. It combines amplitude-envelope events and pauses, F0 contour analysis, low-frequency spectra and spectrograms, ridge/object trajectories, corpus comparison, clustering and exploratory classification.

Teaching and learning

Relate settings to visible waveform, ENV, F0, spectral and rhythm evidence.

Exploration

Inspect individual files, zoom, listen and adjust settings interactively.

Research comparison

Freeze one configuration, process a batch and retain reproducible outputs.

ProsCanvas is not a full segmental-phonetics or annotation system: it does not provide transcription tiers, forced alignment or formant measurement.

Validation distinction. Software checks establish that the agreed implementation behaves consistently. They do not establish that a variable, distance, cluster or classifier is scientifically appropriate for a particular research question.

2. Quick start

Select CONTINUE, then Choose WAV files.
Optionally choose filename-derived Categories and create a balanced random sample.
For controlled comparison, choose Parameter Setup, inspect one shared configuration, then choose Comparison Batch.
For individual work, choose Exploratory Flex.
Use the five left minitabs to set ENV, F0, spectrum, ridge and display controls.
After a completed batch, use SCATTER for scalar or vector comparison and export the final results.

3. Workspace and files

Top bar

File loading and sampling occupy the first row. Mode, navigation, export, Help and context-dependent actions occupy the second.

Main workspace

A collapsible analysis sidebar sits beside the time and frequency canvases. On narrow screens it becomes a drawer. SCATTER replaces this workspace with a full-width comparison area.

Control	Use
Choose WAV files	Load one or more recordings. Common RIFF/WAVE PCM and float material is accepted; multichannel files use the first channel and record a warning.
Categories · n/category · Seed	Choose filename-derived groups and configure reproducible balanced sampling. Defaults are 15 per category and seed 751.
SAMPLE / RESAMPLE / ALL FILES	Draw without replacement, increment the seed for a new draw, or restore the full loaded database. If a category is too small, all selected categories are reduced to the smallest available count.
Mode? · PREV · NEXT	Select the workflow and navigate files where navigation is permitted.
EXP · SCATTER · RESET · ?	Export, open comparison analysis, return to factory state, or open built-in Help.
ABORT	Stop a running Comparison Batch; interim batch results are discarded.

Filename categories: use <category>_<name>.wav or <category>-<name>.wav. Category codes are used in sampling and plot labels.

4. Modes and workflows

Parameter Setup

Adjust one shared configuration using the first file as an orientation preview. This enables Comparison Batch.

Comparison Batch

Confirm the complete F0 profile, freeze all settings, process every working-set file, export the batch and open SCATTER.

Exploratory Flex

Inspect files individually with per-file changes, zoom and playback. SCATTER is unavailable because settings are not frozen across the set.

Controlled comparison

Load/sample→Parameter Setup→Inspect ENV, F0 and frequency evidence→Comparison Batch→Automatic batch export→SCATTER→Export again

Exploratory inspection

Load files→Exploratory Flex→Adjust current file→Zoom/listen→ENV/F0 and Spectrum/Spectrogram→EXP

5. Analysis minitabs

Minitab	Main controls	Effect on results
Time: Env	Envelope Cutoff, peak Thresh and MinDist, Silence, Pause, IPUnPVI/GLOBnPVI.	Controls ENV smoothing, event landmarks, pauses/IPUs and Event Rhythm measures/vectors.
Time: F0	ENV/F0 source; Male, Female, Both and Custom shortcuts; F0 BP low/high; applied range; smoothing window; Advanced F0.	Controls F0 extraction and the contour supplied to downstream F0 spectrum, spectrogram and SCATTER variables. Female is the factory shortcut.
Freq: Spec	Range, smoothing, compact PWR, spectral peaks, DC removal, FFT, Tukey α, detrending and Spectrum/Spectrogram settings.	Controls low-frequency ENV or F0 evidence. ENV and F0 retain separate spectrum-setting records.
Freq: Ridge	TRACKS and object-analysis summary.	Builds spectrogram ridge/object trajectories for the active source. Set spectrogram settings before object analysis.
Disp: Show	WAV, ENV, PEAK, SPEC, LPF, PEAK, RFA, ZONE and CAND visibility.	Repaints displays only; numerical analysis is unchanged.

Time: F0 and Advanced F0 relationship

The compact controls and Advanced F0 edit one underlying working configuration. The compact BP limits and smoothing window are mirrored in Advanced F0. Profile shortcuts load complete persistent domains, not only the visible compact values.

Advanced F0 groups preprocessing and band-pass settings, FFT-YIN frame/window controls, the Primary CMND lag-selection threshold (CMND = cumulative mean normalised difference), preliminary and automatic F0 ranges, voicing/silence decisions, bridging and smoothing. Use Apply & calculate to commit field edits; closing discards unapplied edits. Profiles can be promoted, restored and transferred as JSON.

Freq: Spec essentials and defaults

Range: 1–6 Hz.
MOVWIN: MA, smoothing level 3, 7 bins.
Tukey α: 0.5; 0 = rectangular.
PWR: OFF; squared magnitude when enabled, not calibrated PSD.
Peak threshold 0.12; minimum distance 0.5 Hz; maximum 5.
DC removal 0.10 Hz; FFT 16384; FFT Tukey α 0.5.
ENV Det and Spec Det cycle detrending choices.
The action button reads Spec:gram while Spectrum is visible and Spectrum while Spectrogram is visible.
Spectrogram Window: 0.5 s, 1 s, then 2–20 s; default 4 s. Hops/win default 5.

A shorter window improves temporal localisation but reduces low-frequency resolution. If the requested window exceeds the available span, the setting is retained while the effective window is limited to the available signal.

6. Displays, zoom, playback and ridge analysis

Area/action	Behaviour
Upper canvas	ENV mode shows waveform, envelope, peaks and pause/IPU evidence. F0 mode shows a waveform hint and the final gap-preserving F0 contour; accepted bridges are distinguished from originally voiced material.
Click / drag	Click to start or stop playback. Drag to select a time interval; spectrogram time follows the active time range.
Lower canvas	Shows Spectrum or Spectrogram for the active ENV/F0 source. Spectrum supports frequency-range selection; spectrogram frequency follows the active range.
Zoom footer	Back, Forward, Zoom to selection, Full range and Clear operate on the active domain. Time, ENV-spectrum and F0-spectrum histories remain independent.
TRACKS	Detects elongated spectrogram bodies and centre trajectories, then opens aligned frequency and magnitude plots for up to three principal objects. T1–T3 visibility affects presentation, not the full set of significant objects used by object variables.

7. Event Rhythm outputs

Header	Meaning	Unit
`Dur`	First IPU start to final IPU end, including internal pauses.	s
`nPau` / `nIPU`	Qualifying internal pauses / interpausal units.	count
`nPk`	Detected ENV peaks inside Dur.	count
`mPau` / `mIPU`	Mean pause / IPU duration.	s
`GRate` / `IRate`	Peak rate over Dur / summed IPU time.	Hz
`GnPVI`	nPVI over all consecutive peak intervals, including pause-spanning intervals.	index
`InPVI`	Unweighted mean of eligible within-IPU nPVI values.	index
`elIPU`	IPUs with at least three peaks.	count
`P/I`	Mean pause duration divided by mean IPU duration.	ratio
`Pk/IPU`	Mean peaks per IPU.	count

Undefined values are shown as an em dash. Ineligible IPUs are excluded from InPVI; they do not contribute zero.

8. SCATTER: scalar and vector comparison

SCATTER becomes available after a completed Comparison Batch and uses the frozen batch feature records; changing its display choices does not rerun the acoustic batch.

Scalar variables

Select exactly three of 42 variables from seven empirical-source groups. They become A, B and C, producing A × B, A × C and B × C. The defaults are Duration, Global event rate and IPU nPVI.

Only recordings finite for all three selected variables appear, so every panel uses the same complete-case set.

Vector variables

Select one of 12 whole-representation vectors from ENV, F0 or Event Rhythm. Choose a distance and linkage to produce one hierarchical dendrogram, a distance matrix, nearest neighbours and exclusions.

Original vectors are retained; variable-length trajectories are proportionally aligned only for comparison.

SCATTER control	Use
Variable class / VARIABLES	Choose Scalar or Vector and open the searchable grouped picker. DESELECT ALL clears a scalar draft.
Regression	None, Linear, LOESS or both. LOESS bandwidth defaults to 0.75.
Analysis	Plain, K-Means, Linear SVM, Kernel SVM or DENDRO for scalar variables. Vector mode uses its own hierarchical comparison.
Distance / Linkage	Vector distances: Manhattan, Canberra, Chebyshev, Cosine, Euclidean and Pearson correlation. Linkages: Average/UPGMA, Complete, Median, Single and Ward; Median and Ward require Euclidean distance.
Chart font size	8–24 px, default 10. Main plots redraw immediately; k-means and Linear SVM popup canvases add 2 pt for display compensation.
RESULTS / Save PNGs / Save CSV / Export again	Inspect detailed tables, save current views, or regenerate the laboratory package after interactive analysis.

Vector eligibility. Spectral representations may be unavailable because suitable spectrum/spectrogram evidence is missing. Event Rhythm vectors use the canonical full-analysis ENV peak sequence, not zoom-dependent visible peaks. Eligibility messages are implementation diagnostics, not judgements about scientific adequacy.

9. Statistical and machine-learning workspaces

Plain, regression and DENDRO

Plain shows category-coloured observations. Linear and LOESS overlays are descriptive. DENDRO shows three one-variable horizontal dendrograms using the selected distance/linkage combination; in one dimension Manhattan and Euclidean both reduce to absolute difference.

k-means workflow

Select K-Means, open SETTINGS, then OPEN K-MEANS. The independent three-column workspace contains settings, a square plot and teaching diagnostics. Configure pair, k (2–6), initialisation, iterations and seed; run the analysis, inspect silhouette/variation and category correspondence, then APPLY TO SCATTER or cancel.

k-means is unsupervised. Known categories do not form the clusters, cluster numbers are arbitrary, and category correspondence does not independently validate the clustering.

Linear SVM workflow and evaluation

Select Linear SVM, open SETTINGS, then OPEN LINEAR SVM. Working settings remain separate until APPLY TO SCATTER. Choose plot pair, Category or k-means target, weighting, fixed or Auto C, and canonical or balanced-threshold boundary.

Evaluation choices are Training fit, leave-one-out and repeated stratified cross-validation. Repeated CV provides Auto/2/3/4/5/10 folds, 5/10/20/50 repeats (default 20) and a reproducible seed (default 751). Scaling, C selection and threshold selection are fitted within training data for held-out evaluation. Optional held-out error marks annotate plots.

The popup reports accuracy, balanced accuracy, category recalls, confusion matrices, case predictions and teaching interpretation. The plotted applied line is a full-data model; held-out metrics answer a different question.

Kernel SVM

Kernel SVM supplies an RBF boundary with Category or k-means target, C = 0.1/1/10 and γ = auto/0.1/0.5/1/2. Its displayed agreement is descriptive training fit; the evaluated cross-validation workflow belongs to Linear SVM with Category target.

10. Results and export

A completed batch produces a laboratory-log ZIP containing file/manifest data, frozen parameters, measurements, feature definitions and matrices, warnings, histories and available plots. Interactive SCATTER work can add:

scalar and vector selection/configuration;
regression, dendrogram and clustering results;
original and aligned vectors;
distance matrices and nearest neighbours;
k-means summary and case CSVs;
Linear SVM configuration, diagnostics and case predictions;
current plot PNGs and SCATTER CSV.

Use Export again after interactive SCATTER work. The automatic batch ZIP is created before later popup analyses; regenerating the export preserves the current applied state.

11. Interpretation and good practice

Inspect waveform, peaks, pauses, F0, spectrum and ridge evidence before accepting measurements.
Use one frozen configuration for controlled comparison.
Preserve recording/task/channel comparability and document exclusions.
Short spectrogram windows improve localisation but do not create additional true rhythm cycles.
Balanced accuracy and per-category recall are preferable to accuracy alone when categories are unequal.
Cross-validation is not a p-value and repeated folds do not add independent recordings.
Multiple recordings from one speaker/session may violate case independence; grouped CV is not implemented.
Trying many variable triples increases selection risk.
Cosine can exclude zero-norm vectors; Pearson can exclude zero-variance vectors.
Event Rhythm trajectories and their generic vector clustering are literature-informed exploratory representations, not established standard rhythm metrics.

12. Troubleshooting

Symptom	Action
Mode is disabled.	Load at least one WAV file.
Comparison Batch is unavailable.	Enter Parameter Setup first and establish the shared configuration.
SCATTER is unavailable.	Complete a Comparison Batch; SCATTER is not available in Exploratory Flex.
No or implausible ENV peaks/pauses.	Inspect Time: Env and adjust Cutoff, Thresh, MinDist, Silence and Pause.
No F0 contour.	Try the appropriate profile shortcut, inspect applied limits and use Advanced F0 when compact controls are insufficient.
No ridge/object analysis.	Switch to Spectrogram, set suitable Window/Hops and frequency limits, then use TRACKS.
Too few valid vectors.	Open Excluded recordings; inspect spectrogram evidence for ENV/F0 vectors or ENV peaks/intervals for Event Rhythm vectors.
Linear SVM held-out evaluation unavailable.	Use Category target with exactly two categories, sufficient cases and non-constant selected predictors.
Evaluation is stale.	Relevant variables or settings changed; evaluate again or restore a cached configuration.
Final ZIP lacks popup results.	Apply the working popup settings and use Export again.
Need a clean restart.	Select RESET; the factory F0 shortcut returns to Female.

13. Scalar-variable reference

The current picker contains 42 scalar variables. Expand only the groups needed.

Recording, pauses and IPUs (5)

Variable	Unit	Definition
Duration `duration`	s	Analysed duration from first IPU start to final IPU end.
Pause proportion `pauseProportion`	ratio	Internal-pause duration divided by analysed duration.
Mean pause duration `meanPauseDuration`	s	Mean duration of qualifying internal pauses.
Pause-duration IQR `pauseDurationIqr`	s	Interquartile range of qualifying internal pause durations; requires at least four pauses. literature-attested addition
Mean IPU duration `meanIpuDuration`	s	Mean duration of interpausal units.

Envelope events and p-centre proxies (6)

Variable	Unit	Definition
Global event rate `globRate`	Hz	ENV peak count divided by analysed duration.
IPU event rate `ipuRate`	Hz	ENV peak count divided by summed IPU duration.
Global nPVI `globNPVI`	index	nPVI over all consecutive ENV peak intervals.
IPU nPVI `ipuNPVI`	index	Mean eligible within-IPU nPVI.
Peak-interval CV `peakIntervalCv`	ratio	Coefficient of variation of consecutive ENV peak intervals.
P-centre interval slope `pcentreIntervalSlope`	ms/s	Median Theil–Sen slope of successive landmark intervals against interval midpoint time. literature-motivated addition

F0 contour (10)

Variable	Unit	Definition
Voiced proportion `voicedProportion`	ratio	Originally voiced F0 frames divided by all F0 frames.
Mean F0 `meanF0`	Hz	Arithmetic mean of finite final-contour F0 values. literature-attested addition
Median F0 `medianF0`	Hz	Median of finite final-contour F0 values. literature-attested addition
F0 variability `f0Variability`	ST	Standard deviation of finite F0 values in semitones.
F0 robust range `f0RobustRange`	ST	P80 minus P20 of finite F0 values in semitones.
F0 wiggliness `f0Wiggliness`	turns/s	Significant F0 direction changes per analysed second.
F0 spaciousness `f0Spaciousness`	ST	Mean of the two largest significant F0 excursions.
Median IPU F0 slope `medianIpuF0Slope`	ST/s	Median signed linear F0 slope across eligible IPUs.
IPU F0 slope IQR `ipuF0SlopeIqr`	ST/s	Interquartile range of eligible IPU F0 slopes.
F0 residual dispersion `f0ResidualDispersion`	ST	Median scaled residual MAD after removal of the IPU F0 trend. literature-motivated addition

ENV spectrum (7)

Variable	Unit	Definition
ENV NDP `envNdp`	count	Number of qualifying ENV spectrum peaks.
ENV MFDP `envMfdp`	Hz	Mean frequency of qualifying ENV spectrum peaks.
ENV VFDP `envVfdp`	Hz²	Variance of qualifying ENV spectrum peak frequencies.
ENV spectral spread `envSpectralSpread`	Hz	Magnitude-weighted spread of the ENV spectrum.
ENV spectral centroid `envSpectralCentroid`	Hz	Magnitude-weighted centre frequency of the ENV spectrum. literature-attested addition
ENV spectral entropy `envSpectralEntropy`	0–1	Normalised entropy of the selected ENV spectrum. literature-attested addition
ENV dominant-peak prominence `envDominantPeakProminence`	ratio	Relative topographic prominence of the strongest qualifying ENV spectrum peak. literature-attested addition

F0 spectrum (3)

Variable	Unit	Definition
F0 MFDP `f0Mfdp`	Hz	Mean frequency of qualifying F0 spectrum peaks.
F0 VFDP `f0Vfdp`	Hz²	Variance of qualifying F0 spectrum peak frequencies.
F0 spectral spread `f0SpectralSpread`	Hz	Magnitude-weighted spread of the F0 spectrum.

ENV spectrogram and objects (6)

Variable	Unit	Definition
ENV spectral flux `envSpectralFlux`	norm/s	Median time-normalised L2 change between consecutive unit-area ENV spectrogram slices. literature-attested addition
ENV frequency mobility `envObjectFrequencyMobility`	Hz²	Observed-duration-weighted within-object variance of ENV centre frequency.
ENV magnitude variability `envObjectMagnitudeVariability`	norm²	Observed-duration-weighted within-object variance of globally normalised ENV magnitude.
ENV prominence-crossover rate `envObjectCrossoverRate`	crossovers/s	ENV magnitude-dominance exchanges per second of valid overlap between significant objects.
ENV parallelism `envObjectParallelism`	objects/slice	Mean number of significant ENV objects present per valid spectrogram slice.
ENV mean object width `envObjectMeanWidth`	Hz	Observed-duration-weighted mean frequency width of significant ENV object bodies.

F0 spectrogram and objects (5)

Variable	Unit	Definition
F0 frequency mobility `f0ObjectFrequencyMobility`	Hz²	Observed-duration-weighted within-object variance of F0 centre frequency.
F0 magnitude variability `f0ObjectMagnitudeVariability`	norm²	Observed-duration-weighted within-object variance of globally normalised F0 magnitude.
F0 prominence-crossover rate `f0ObjectCrossoverRate`	crossovers/s	F0 magnitude-dominance exchanges per second of valid overlap between significant objects.
F0 parallelism `f0ObjectParallelism`	objects/slice	Mean number of significant F0 objects present per valid spectrogram slice.
F0 mean object width `f0ObjectMeanWidth`	Hz	Observed-duration-weighted mean frequency width of significant F0 object bodies.

14. Vector-representation reference

All 12 representations

Representation	Unit	Construction	Comparison dimension
Whole ENV spectrum ENV	distribution	Unit-sum ENV spectrum resampled to a fixed 128-bin frequency grid.	128
Whole ENV ridge-density field ENV	density	Unit-sum density of all significant ENV ridge bodies on a 24 × 32 proportional-time/frequency grid.	768
ENV highest-magnitude frequency trajectory ENV	modulation Hz	Frequency of the highest-magnitude point in each valid spectrogram slice, aligned by proportional time.	comparison-set maximum
ENV highest-magnitude magnitude trajectory ENV	relative magnitude	Magnitude at the highest-magnitude frequency in each valid slice, item-maximum normalised and aligned by proportional time.	comparison-set maximum
Whole F0 spectrum F0	distribution	Unit-sum F0 modulation spectrum resampled to a fixed 128-bin frequency grid.	128
Whole F0 ridge-density field F0	density	Unit-sum density of significant F0 ridge bodies on a 24 × 32 proportional-time/frequency grid.	768
F0 highest-magnitude frequency trajectory F0	modulation Hz	Frequency of the highest-magnitude point in each F0 spectrogram slice, aligned by proportional time.	comparison-set maximum
F0 highest-magnitude magnitude trajectory F0	relative magnitude	Magnitude at the highest-magnitude frequency in each F0 spectrogram slice, item-maximum normalised and aligned by proportional time.	comparison-set maximum
Proportional peak-time trajectory Event Rhythm	proportion	Detected ENV peak times expressed relative to the active analysis span and aligned by proportional event index.	comparison-set maximum
Normalised peak-magnitude trajectory Event Rhythm	relative magnitude	Ordered ENV peak magnitudes divided by the recording maximum and aligned by proportional event index.	comparison-set maximum
GLOB inter-peak-interval trajectory Event Rhythm	ms	Consecutive global ENV peak intervals in milliseconds, including intervals spanning internal pauses, aligned by proportional interval index.	comparison-set maximum
Mean-normalised GLOB inter-peak-interval trajectory Event Rhythm	ratio	Consecutive global ENV peak intervals divided by the recording mean interval and aligned by proportional interval index.	comparison-set maximum

Event Rhythm status. Peak-time and raw interval trajectories have the strongest conceptual grounding. Peak magnitude and mean-normalised interval trajectories are more exploratory. The mean-normalised interval trajectory is not nPVI.