Type: Package
Title: Plotting Ultrasound Tongue Traces
Version: 0.2.1
Depends: R (≥ 4.1.0)
Imports: RColorBrewer, tibble, rjson, ggplot2, Cairo, purrr, plyr, tidyr, readr, stringr, ggsignif, ggpubr, car, rstatix, vegan
Description: Plots traced ultrasound tongue imaging data according to a polar coordinate system. There is currently support for plotting means and standard deviations of each category's trace; Smoothing Splines Analysis of Variance (SSANOVA) could be implemented as well. The origin of the polar coordinates may be defined manually or automatically determined based on different algorithms. Points for each category can be split into two groups (anterior and posterior) at the point of maximum curvature of each trace. User can specify rays to intersect various parts of the tongue; intersections along these rays serve as input for a pairwise t-test to measure significant contrasts between segments. Currently 'ultrapolaRplot' supports ultrasound tongue imaging trace data from 'UltraTrace' (https://github.com/SwatPhonLab/UltraTrace). 'UltraTrace' is capable of importing data from Articulate Instruments AAA. 'read_textgrid.R' is required for opening TextGrids to determine category and alignment information of ultrasound traces.
License: GPL-3
Encoding: UTF-8
NeedsCompilation: no
Packaged: 2026-04-24 03:08:02 UTC; yayaorigami
Author: Yana Outkin [aut, cre], Jonathan Washington [aut]
Maintainer: Yana Outkin <youtkin1@swarthmore.edu>
Repository: CRAN
Date/Publication: 2026-04-24 03:20:02 UTC

Processes metadata and TextGrids

Description

Processes layers, tiers, and categories within TextGrids. Extracts x and y coordinate data from metadata.

Usage

loadAllTracesMidPoint(directory_name)

Arguments

directory_name

a (readable binary-mode) connection or a character string giving the name of the folder containing metadata and textgrid files to load (when tilde expansion is done).

Value

Returns dataframe of filename, annotation number in file, segment, x-coordinate, y-coordinate, list of tiers, layer, segment text.

Plots ultrasound polar coordinate data

Description

Filters rawTraces by categories, tiers, and layers. Plots extracted segments with means and standard deviation bands calculated through use of polar coordinates. Compares significant constasts between segments along various parts of the tongue.

Usage

plotTraces(rawTraces, polarTraces = "", tiernameAll = c(NA), 
                 categoriesAll = list(c(NA)), layersAll = c(NA),
                 seg_filter = list(c(NA)), mergeCategories = c(FALSE), 
                 origin.algorithm = "BottomMiddle", origin.x = NA,
                 scaling.factor = 800/600,  interval = 1, mean.lines =
                 TRUE, points.display = FALSE, palette = c(),
                 bands.lines = FALSE, bands.fill = TRUE,
                 legend.position = "topleft", means.styles = c(),
                 standard.deviation.styles = "l", plot.ticks = FALSE,
                 plot.labels = FALSE, legend.size = 3, transparency =
                 0.37, pdf.filename = c(), bands.linewidth = 0.3,
                 png.filename = c(), legend.linewidth = 5,
                 means.linewidth = 3, tick.size = 2, maskCategories =
                 c(), rays = list(), bestFitRays = FALSE,
                 bestFitRays.show_elbows = FALSE,
                 bestFitRays.start_point_density = 1, 
                 bestFitRays.intersection_rays.negative = c(),
                 bestFitRays.intersection_rays.positive = c(),
                 angle_neg_rotate = c(), angle_pos_rotate = c(), 
                 ray_color = "darkgrey", elbow_color = "black", bubble = FALSE,
                 x_coor = 0, y_coor = 0, difference_plot = FALSE, 
                 angle_between_best_fit = FALSE, debug_intersections = FALSE)

Arguments

rawTraces

data frame returned from loadAllTracesMidPoint()

polarTraces

returned from makeTracesPolar(), optional, outdated

tiernameAll

respective tiers (if applicable) within layers. If none specified, all tiers are checked.

categoriesAll

respective categories of segments to extract within tiers.

layersAll

list of layers within metadata to extract x and y coodinate data from. Defaults to 'tongue' layer.

mergeCategories

boolean or boolean array, as to whether to merge respective categories.

seg_filter

respective segment_text for additional filtering

origin.algorithm

takes list of all extracted x-coordinates and sets

origin.x

override x coordinate of origin

scaling.factor

default 800/600

x_coor

x_coor of transducer (default = 0)

y_coor

y_coor of transducer (default = 0)

angle_between_best_fit

boolean, whether or not to display violin plot of angles between the bestfit lines per category

bands.fill

boolean, whether or not to show standard deviation bands

bands.lines

boolean, whether or not to show lines on edges of standard deviation bands

bands.linewidth

line thickness of standard deviation bands

bestFitRays

boolean, whether or not to display lines of best fit for tongue body and tongue root

bestFitRays.start_point_density

Number of intersecting traces per category needed to extend bestFitRays until (default = 1), 0 would be until farthest points, 2 would be until each segment has standard deviation

bestFitRays.intersection_rays.negative

List of percentages along bestfit ray on left side to intersect data

bestFitRays.intersection_rays.positive

List of percentages along bestfit ray on right side to intersect data

angle_neg_rotate

Corresponding angles to bestFitRays.intersection_rays.negative (default = 0) to rotate rays while still keeping the intersections with the bestfit line the same

angle_pos_rotate

Corresponding angles to bestFitRays.intersection_rays.positive (default = 0) to rotate rays while still keeping the intersections with the bestfit line the same

rays

list of arrays to specify (x,y), and angle of intersecting ray

bestFitRays.show_elbows

boolean, whether or not to show PMC along means

bubble

boolean, whether or not to display PMC cluster graph

difference_plot

boolean, whether or not to display difference_plot for the first two segments

debug_intersections

boolean, whether or not to print data frame of segments and their intersections with the perpedicular ray(s)

elbow_color

color of PMC along means (default = "black")

interval

sampling interval, in degrees, for finding intersections with existing traces (default = '1')

mean.lines

boolean, whether or not to display mean lines

means.styles

array to override default solid line (sequentially in order of categories)

means.linewidth

size of mean lines

standard.deviation.styles

line type for standard deviation upper and low bands, (default = "l")

transparency

transparency of standard deviation bands (default = 0.37)

palette

array to override default colour palette

pdf.filename

pdf file name, saves in current directory

png.filename

png file name, saves in current directory

plot.labels

boolean, whether or not to show labels

plot.ticks

boolean, whether or not to show tick marks

tick.size

size of label scaling on axises

points.display

boolean, whether or not to show original annotated points

ray_color

color of bestFitRays.intersection_rays.negative and bestFitRays.intersection_rays.positive (default = "darkgrey")

labels

array to override labels

legend.position

default "center", with an option of "topleft", "bottomright"

legend.size

size of legend (default = 0.6)

legend.linewidth

size of displayed legend lines

maskCategories

array to override current segment labels

Value

Returns a dataframe of filename, annotation number in file, segment, x-coordinate, y-coordinate, segment text; Displays and pairwise comparisons. User can export output to pdf or png.

ultrapolaRplot

Description

The ultrapolaRplot library for R is designed for plotting traced ultrasound tongue imaging data according to a polar coordinate system. There is currently support for plotting means and standard deviations of each category's trace; SSANOVA could be implemented as well. The origin of the polar coordinates may be defined manually or automatically determined based on different algorithms. Points for each category can be split into two groups (anterior and posterior) at the point of maximum curvature of each trace. User can specify rays to intersect various parts of the tongue; intersections along these rays serve as input for a pairwise t-test to measure significant contrasts between segments. Currently ultrapolaRplot supports ultrasound tongue imaging trace data from UltraTrace (<https://github.com/SwatPhonLab/UltraTrace>). UltraTrace is capable of importing data from Articulate Instruments AAA.

Examples

  ## Not run: 
  library(ultrapolaRplot)
  filepath <- system.file("extdata", package = "ultrapolaRplot")
  rawTraces <- loadAllTracesMidPoint(filepath)
  filteredTraces <- plotTraces(rawTraces, 
  categoriesAll = c("o", "i"), bestFitRays = TRUE,
  bestFitRays.intersection_rays.positive = c(0.5))
  
## End(Not run)