Package 'act'

Description

The Aligned Corpus Toolkit (act) is designed for linguists that work with time aligned transcription data. It offers functions to import and export various annotation file formats ('ELAN' .eaf, 'EXMARaLDA .exb and 'Praat' .TextGrid files), create print transcripts in the style of conversation analysis, search transcripts (span searches across multiple annotations, search in normalized annotations, make concordances etc.), export and re-import search results (.csv and 'Excel' .xlsx format), create cuts for the search results (print transcripts, audio/video cuts using 'FFmpeg' and video sub titles in 'Subrib title' .srt format), modify the data in a corpus (search/replace, delete, filter etc.), interact with 'Praat' using 'Praat'-scripts, and exchange data with the 'rPraat' package. The package is itself written in R and may be expanded by other users.

act functions

...

Vignettes

• vignette("export_docx_styles", package = "act") – transcript profiles (format of the print transcripts)

• vignette("install_ffmpeg", package = "act") – Install FFmpeg

• vignette("praat_remote_control", package = "act") – Praat remote control

Package options

The package has numerous options that change the internal workings of the package. Please see act::options_show() and the information given there.

Examples

library(act)

# ========== Example data set
# There is an example data set consisting of annotation files and corresponding 
# media files. 
# While the annotation files are copied to your computer when installing 
# the media files are not.
# You can either download the full data set from GitHub or decide to work 
# only with the annotation files.

# The example data set (only annotation files) is stored at the following location:
path <- system.file("extdata", "examplecorpus", package="act")

# Since this folder is quite difficult to access, you might consider copying the 
# contents of this folder to a more convenient location.
# The following commands will create a new folder called 'examplecorpus' in the
# folder 'path'.
# You will find the data there.
## Not run: 
path <- "EXISTING_FOLDER_ON_YOUR_COMPUTER"
sourcepath <- system.file("extdata", "examplecorpus", package="act")
if (!dir.exists(path)) {dir.create(path)}
file.copy(sourcepath, dirname(path), recursive=TRUE)

## End(Not run)

# To download the full data set (including media files) from GitHub
# use the following code.
# In the first line specify an existing folder on your computer. 
# The following lines will then download the example data set from GitHub 
# and copy them to a sub folder called 'examplecorpus' in the folder 'path'.  
# You will find the data there.
## Not run: 
path <- "EXISTING_FOLDER_ON_YOUR_COMPUTER"
path <- "/Users/oliverehmer/Desktop"
sourceurl <- "https://github.com/oliverehmer/act_examplecorpus/archive/master.zip"
temp <- tempfile()
download.file(sourceurl, temp)
unzip(zipfile=temp, exdir=path)
path <- file.path(path, "act_examplecorpus-main")

## End(Not run)

# ========== Create a corpus object and load data
# Now that we have the example data accessible, we can create a corpus object.
# The corpus object is a structured collection of all the information that you can 
# work with using act.
# It will contain the information of each transcript, links to media files and further 
# meta data.

# --- Locate folder with annotation files
# When creating a corpus object you will need to specify where your annotation 
# files ('Praat' '.TextGrids' or 'ELAN' .eaf) are located.
# We will use the example data, that we have just located in 'path'.
path

# In case that you want to use your own data, you can set the path here:
## Not run: 
	path <- "EXISTING_FOLDER_ON_YOUR_COMPUTER"

## End(Not run)

# --- Create corpus object and load annotation files
# The following command will create a corpus object, with the name 'examplecorpus'.
examplecorpus <- act::corpus_new(
	pathsAnnotationFiles = path,
	pathsMediaFiles = path,
	name = "examplecorpus"
)

# The act package assumes, that annotation files and media files have the same base  
# name and differ only in the suffix (e.g. 'filename.TextGrid' and 'filename.wav'/
# 'filename.mp4').
# This allows act to automatically link media files to the transcripts.

# --- Information about your corpus
# The following command will give you a summary of the data contained in your corpus object.
examplecorpus
# More detailed information about the transcripts in your corpus object is available by 
# calling the function act::info()
act::info(examplecorpus)
# If you are working in R studio, a nice way of inspecting this information is the following:
## Not run: 
	View(act::info(examplecorpus)$transcripts)
	View(act::info(examplecorpus)$tiers)

## End(Not run)

# ========== all data
# You can also get all data that is in the loaded annotation files in a data frame:
all_annotations <- act::annotations_all(examplecorpus)
## Not run: 
	View(all_annotations)

## End(Not run)

# ========== Search
# Let's do some searches in the data.
# Search for the 1. Person Singular Pronoun in Spanish 'yo' in the examplecorpus
mysearch <- act::search_new(x=examplecorpus, 
							pattern= "yo")
# Have a look at the result:
mysearch

# Directly view all search results in the viewer
## Not run: 
	View(mysearch@results)

## End(Not run)

# --- Search original vs. normalized content
# You can either search in the original 'content' of the annotations,
# or you can search in a 'normalized' version of the annotations.
# Let's compare the two modes.
mysearch.norm  <- act::search_new(examplecorpus, pattern="yo", searchNormalized=TRUE)
mysearch.org   <- act::search_new(examplecorpus, pattern="yo", searchNormalized=FALSE)
# There is a difference in the number of results.
mysearch.norm@results.nr
mysearch.org@results.nr

# The difference is because during in the normalized version, for instance, capital letters 
# will be converted to small letters. 
# In our case, one annotation in the example corpus contains a "yO" with a
# capital letter:
mysearch <- act::search_new(examplecorpus, pattern="yO", searchNormalized=FALSE)
mysearch@results$hit

# During normalization a range of normalization procedures will be applied, using a 
# replacement matrix. This matrix searches and replaces certain patterns, that you want to 
# exclude from the normalized content.
# By default, normalization gets rid of all transcription conventions of GAT. 
# You may, in addition, also customize the replacement matrix to your own needs/transcription
# conventions.

# --- Search original content vs. full text
# There are two search modes.
# The 'fulltext' mode will will find matches across annotations.
# The 'content' mode will will respect the temporal boundaries of the original annotations.

# Let's define a search pattern with a certain span.
myRegEx <- "\\bno\\b.{1,20}pero"
# This regular expression matches the Spanish word "no" 'no' followed by a "pero" 'but'
# in a distance ranging from 1 to 20 characters.

# The 'content' search mode will not find any hit.
mysearch <- act::search_new(examplecorpus, pattern=myRegEx, searchMode="content")
mysearch@results.nr

# The 'fulltext' search mode will not find two hits that extend over several annotations.
mysearch <- act::search_new(examplecorpus, pattern=myRegEx, searchMode="fulltext")
mysearch@results.nr
cat(mysearch@results$hit[1])
cat(mysearch@results$hit[2])

Description

Adds a single annotation (interval or point) to a transcript object. Automatically checks for overlapping annotations and handles them based on the overwrite parameter. Always ensures no invalid overlaps exist.

Usage

annotations_add(
  x,
  tierName,
  startsec,
  endsec,
  content = "",
  content.norm = "",
  overwrite = FALSE
)

Arguments

Details

Overlap Handling

The function always checks for overlapping annotations in the specified tier:

When overwrite = FALSE (default):

• If overlap exists → Error with stop()

• If no overlap → Insert new annotation

When overwrite = TRUE:

• Existing overlapping annotations are trimmed/split:

  • Left remainder: [old_start, new_start] (if old_start < new_start)

  • Right remainder: [new_end, old_end] (if new_end < old_end)

  • Middle part is replaced by new annotation

• New annotation is inserted

Automatic Operations

• Assigns unique annotation ID

• Sets all char.* fields to NA (filled by fulltext operations)

• Maintains proper data.frame structure

• Updates modification time and history

Value

Transcript object with added annotation.

Examples

## Not run: 
library(act)

# Add annotation (error if overlap exists)
t <- annotations_add(
  x = examplecorpus@transcripts[[1]],
  tierName = "status",
  startsec = 10.5,
  endsec = 15.2,
  content = "o0.s0"
)

# Add annotation and overwrite overlaps
t <- annotations_add(
  x = examplecorpus@transcripts[[1]],
  tierName = "status",
  startsec = 10.5,
  endsec = 15.2,
  content = "new content",
  overwrite = TRUE
)

## End(Not run)

Description

Merges annotations from all transcripts in a corpus and returns a data frame.

Usage

annotations_all(x)

Arguments

Value

data frame

Examples

library(act)

#Get data frame with all annotations
allannotations <- act::annotations_all(examplecorpus)

#Have a look at the number of annotations
nrow(allannotations)

Description

Delete annotations in a corpus object. If only certain transcripts or tiers should be affected set the parameter filterTranscriptNames and filterTierNames. In case that you want to select transcripts and/or tiers by using regular expressions use the function act::search_makefilter first.

Usage

annotations_delete(
  x,
  pattern = "",
  filterTranscriptNames = NULL,
  filterTierNames = NULL
)

Arguments

Value

Corpus object.

Examples

library(act)

# Set the regular expression which annotations should be deleted.
# In this case: all annotations that contain the letter "a"
myRegEx <- "a"

# Have a look at all annotations in the first transcript
examplecorpus@transcripts[[1]]@annotations$content

# Some of them match to the regular expression
hits <- grep(pattern=myRegEx, x=examplecorpus@transcripts[[1]]@annotations$content)
examplecorpus@transcripts[[1]]@annotations$content[hits]
# Others don't match the regular expression
examplecorpus@transcripts[[1]]@annotations$content[-hits]

# Run the function and delete the annotations that match the regular expression
test <- act::annotations_delete (x=examplecorpus, pattern=myRegEx)

# Compare how many data rows are in the first transcript in 
# the example corpus and in the newly created test corpus:
nrow(examplecorpus@transcripts[[1]]@annotations)
nrow(test@transcripts[[1]]@annotations)

# Only the annotations are left, that did not match the regular expression:
test@transcripts[[1]]@annotations$content

Description

Delete empty annotations in a corpus object. If only certain transcripts or tiers should be affected set the parameter filterTranscriptNames and filterTierNames. In case that you want to select transcripts and/or tiers by using regular expressions use the function act::search_makefilter first.

Usage

annotations_delete_empty(
  x,
  trim = FALSE,
  filterTranscriptNames = NULL,
  filterTierNames = NULL
)

Arguments

Value

Corpus object.

Examples

library(act)

# In the example corpus are no empty annotations.
# Empty annotations are deleted by default when annotation files are loaded.
# So let's first make an empty annotation.

# Check the first annotation in the first transcript
examplecorpus@transcripts[[1]]@annotations$content[[1]]

# Empty the contents of this annotation
examplecorpus@transcripts[[1]]@annotations$content[[1]] <- ""

# Run the function
test <- act::annotations_delete_empty (x=examplecorpus)

# Compare how many data rows are in the first transcript in
# the example corpus and in the newly created test corpus:
nrow(examplecorpus@transcripts[[1]]@annotations)
nrow(test@transcripts[[1]]@annotations)

Description

Fills annotations in a specific tier and time range with content. By default, only fills empty annotations (does not overwrite existing content).

Usage

annotations_fill_tier_section(
  x,
  tier_pattern,
  content,
  startsec,
  endsec,
  overwrite = FALSE,
  create_if_missing = TRUE,
  perl = TRUE
)

Arguments

Value

Transcript object with modified annotations.

Examples

## Not run: 
library(act)

# Fill status tier with "o0.s0"
t <- annotations_fill_tier_section(
  x = examplecorpus@transcripts[[1]],
  tier_pattern = "(?i)status",
  content = "o0.s0",
  startsec = 10,
  endsec = 20
)

## End(Not run)

Description

The function will insert the results of a search as annotations into a specified destination tier. Results from different tiers will all be inserted into the same destination tier. It can be specified how overlapping search results or search results from the same annotation will be handled. Please note that hits with exactly the same start and end time will always be merged (e.g. they are not treated as overlapping).

Usage

annotations_insert_from_search_to_tier(
  x,
  s,
  destTier = "destinationTier",
  destTierAddMissing = TRUE,
  contentFromColname = "hit",
  interruptOverlap = FALSE,
  filterTranscriptNames = NULL,
  filterTierNames = NULL,
  collapseString = " | "
)

Arguments

Value

Corpus object.

Examples

library(act)

# Have a look at the first transcript in the example corpus:
printtranscript <- act::export_txt(examplecorpus@transcripts[[1]])
cat(printtranscript)
# In line 01 there is the word "UN".

# Replace this word by "XXX" in the entire corpus
test <- act::annotations_replace_copy(x=examplecorpus,
									  pattern="\\bUN\\b",
									  replacement="XXX")

# Have a look at the first transcript in the corpus object test:
printtranscript <- act::export_txt(test@transcripts[[1]])
cat(printtranscript)
# In line 01 there is now "XXX" instead of "UN"

# Insert a tier called "newTier" into all transcripts in the corpus:
for (t in examplecorpus@transcripts) {
	sortVector <- c(t@tiers$name, "newTier")
	examplecorpus <- act::tiers_sort(x=examplecorpus,
	sortVector=sortVector,
	filterTranscriptNames=t@name,
	tiersAddMissing=TRUE)
}
# Check that the first transcript now contains the newTier
examplecorpus@transcripts[[1]]@tiers

# Now replace "UN" by "YYY" in the entire corpus and
# copy the search hit to "newTier".
test <- act::annotations_replace_copy(x=examplecorpus,
									  pattern="\\bUN\\b",
									  replacement="YYY",
									  destTier = "newTier")

# Have a look again at the first transcript in the corpus object test.
printtranscript <- act::export_txt(test@transcripts[[1]])
cat(printtranscript)
# In line 01 you see that "UN" has been replaced by "YYY.
# In line 02 you see that it has been copied to the tier "newTier".

# If you only want to copy a search hit but not replace it in the original
# leave replacement="", which is the default
test <- act::annotations_replace_copy(x=examplecorpus,
									  pattern="\\bUN\\b",
									  destTier = "newTier")
printtranscript <- act::export_txt(test@transcripts[[1]])
cat(printtranscript)
# In line 01 you see that "UN" has been maintained.
# In line 02 you see that "UN" it has been copied to the tier "newTier".

Description

This functions performs a search and replace in the contents of an annotation. A simple matrix consisting of two columns will be used. The first column of the matrix needs to contain the search string, the second column the replacement string. The matrix needs to be in CSV format.

Usage

annotations_matrix(x, pathReplacementMatrix, filterTranscriptNames = NULL)

Arguments

Value

Corpus object.

See Also

matrix_load() for loading the matrix and matrix_save() for saving the matrix to a CSV file.

If only certain transcripts or tiers should be affected set the parameter filterTranscriptNames. In case that you want to select transcripts by using regular expressions use the function act::search_makefilter first.

media_delete, media_path_to_existing_file

Examples

library(act)

# An example replacement matrix comes with the package.
# It replaces most of the GAT conventions.
path <- system.file("extdata", "normalization", "normalization_matrix.csv", package="act")

# Have a look at the matrix
mymatrix <- act::matrix_load(path)
mymatrix

# Apply matrix to examplecorpus
test <- act::annotations_matrix(x=examplecorpus, pathReplacementMatrix=path)

# Compare some annotations in the original examplecorpus object and
# in the modified corpus object test
examplecorpus@transcripts[[1]]@annotations$content[[1]]
test@transcripts[[1]]@annotations$content[[1]]

examplecorpus@transcripts[[2]]@annotations$content[[3]]
test@transcripts[[2]]@annotations$content[[3]]

Description

The function searches within the contents of annotations and replaces the search hits. In addition the search hit may be copied to another tier. In case that there is NO overlapping annotation in the destination tier a new annotation will be created (based on the time values of the original annotation). In case that there is an overlapping annotation in the destination tier, the search result will be added at the end.

Usage

annotations_replace_copy(
  x,
  pattern,
  replacement = NULL,
  destTier = NULL,
  destTierAddMissing = TRUE,
  filterTranscriptNames = NULL,
  filterTierNames = NULL,
  collapseString = " | "
)

Arguments

Details

If only certain transcripts or tiers should be affected set the parameter filterTranscriptNames and filterTierNames. In case that you want to select transcripts and/or tiers by using regular expressions use the function act::search_makefilter first.

Value

Corpus object.

Examples

library(act)

# Have a look at the first transcript in the example corpus:
printtranscript <- act::export_txt(examplecorpus@transcripts[[1]])
cat(printtranscript)
# In line 01 there is the word "UN".

# Replace this word by "XXX" in the entire corpus
test <- act::annotations_replace_copy(x=examplecorpus,
									  pattern="\\bUN\\b",
									  replacement="XXX")

# Have a look at the first transcript in the corpus object test:
printtranscript <- act::export_txt(test@transcripts[[1]])
cat(printtranscript)
# In line 01 there is now "XXX" instead of "UN"

# Insert a tier called "newTier" into all transcripts in the corpus:
for (t in examplecorpus@transcripts) {
	sortVector <- c(t@tiers$name, "newTier")
	examplecorpus <- act::tiers_sort(x=examplecorpus,
	sortVector=sortVector,
	filterTranscriptNames=t@name,
	tiersAddMissing=TRUE)
}
# Check that the first transcript now contains the newTier
examplecorpus@transcripts[[1]]@tiers

# Now replace "UN" by "YYY" in the entire corpus and
# copy the search hit to "newTier".
test <- act::annotations_replace_copy(x=examplecorpus,
									  pattern="\\bUN\\b",
									  replacement="YYY",
									  destTier = "newTier")

# Have a look again at the first transcript in the corpus object test.
printtranscript <- act::export_txt(test@transcripts[[1]])
cat(printtranscript)
# In line 01 you see that "UN" has been replaced by "YYY.
# In line 02 you see that it has been copied to the tier "newTier".

# If you only want to copy a search hit but not replace it in the original
# leave replacement="", which is the default
test <- act::annotations_replace_copy(x=examplecorpus,
									  pattern="\\bUN\\b",
									  destTier = "newTier")
printtranscript <- act::export_txt(test@transcripts[[1]])
cat(printtranscript)
# In line 01 you see that "UN" has been maintained.
# In line 02 you see that "UN" it has been copied to the tier "newTier".

Description

Exports all (or some) transcript objects in a corpus object to different annotation file formats. If only some transcripts or tiers should be affected set the parameter filterTranscriptNames and filterTierNames. In case that you want to select transcripts and/or tiers by using regular expressions use the function act::search_makefilter first.

Usage

corpus_export(
  x,
  folderOutput,
  filterTranscriptNames = NULL,
  filterTierNames = NULL,
  formats = c("docx", "eaf", "exb", "edl", "srt", "textgrid", "txt"),
  createMediaLinks = TRUE,
  createFolderOutput = TRUE,
  style = NULL
)

Arguments

See Also

export_eaf, export_textgrid, export_exb, export_txt, export_docx, export_rpraat, export_srt

Examples

library(act)

# Set destination folder
folderOutput <- tempdir()

# It makes more sense, however, to you define a folder
# that is easier to access on your computer
## Not run: 
folderOutput <- "PATH_TO_AN_EMPTY_FOLDER_ON_YOUR_COMPUTER"

## End(Not run)

# Exports all transcript objects in all supported formats
act::corpus_export(x=examplecorpus,
							   folderOutput=folderOutput)

# Exports all transcript objects in 'Praat' .TextGrid format
act::corpus_export(x=examplecorpus,
                              folderOutput=folderOutput,
                              formats="textgrid")

# Exports all transcript objects in 'ELAN' .eaf format.
# By default WITH media links
act::corpus_export(x=examplecorpus,
						folderOutput=folderOutput,
						formats="eaf")


# Same same, but now WITHOUT media links.
# Only Media links are only exported that are in
# the '@media' table in the transcript object(s))
act::corpus_export(x=examplecorpus,
						folderOutput=folderOutput,
						formats="eaf",
						createMediaLinks=FALSE)

# Exports in 'ELAN' .eaf and Praat' .TextGrid format
act::corpus_export(x=examplecorpus,
                                 folderOutput=folderOutput,
                                 formats=c("eaf", "textgrid"))

Description

Scans all path specified in if [email protected] for annotation files. Supported file formats will be loaded as transcript objects into the corpus object. All previously loaded transcript objects will be deleted.

Usage

corpus_import(
  x,
  createNormalization = TRUE,
  createFulltext = TRUE,
  assignMedia = TRUE,
  cureTranscripts = TRUE,
  verbose = TRUE
)

Arguments

Details

If assignMedia=TRUE the paths defined in [email protected] will be scanned for media files. Based on their file names the media files and annotations files will be matched. Only the the file types set in options()$act.media.fileformats.audio and options()$act.media.fileformats.video will be recognized. You can modify these options to recognize other media types.

See @import.results of the corpus object to check the results of importing the files. To get a detailed overview of the corpus object use act::info(x), for a summary use act::info_summarized(x).

Value

Corpus object.

See Also

corpus_new, examplecorpus

Examples

library(act)

# The example files that come with the act library are located here:
path <- system.file("extdata", "examplecorpus", package="act")

# This is the examplecorpus object that comes with the library
examplecorpus

# Make sure that the input folder of the example corpus object is set correctly
examplecorpus@paths.annotation.files <- path
examplecorpus@paths.media.files <- path

# Load annotation files into the corpus object (again)
examplecorpus <- act::corpus_import(x=examplecorpus)

# Creating the full texts may take a long time.
# If you do NOT want to create the full texts immediately use the following command:
examplecorpus <- act::corpus_import(x=examplecorpus, createFulltext=FALSE )

Description

Combines one or several source corpora into a target corpus. The target corpus (x) is the winner for all configuration slots (normalization.matrix, import.*). Source transcripts are added to the target's transcript list.

Usage

corpus_merge(x, insert, conflictTranscripts = c("error", "skip", "overwrite"))

Arguments

Details

If a source corpus has a different normalization.matrix than the target, its transcripts get their normalization.signature and fulltext.signature invalidated, so that the next call to transcripts_update_normalization() and transcripts_update_fulltexts() will re-normalize and re-create the fulltexts using the target's matrix.

Value

Corpus object.

Description

Create a new corpus object and loads annotation files. Currently 'ELAN' .eaf, 'EXMARaLDA .exb and 'Praat' .TextGrid files are supported.

The parameter pathsAnnotationFiles defines where the annotation files are located. If skipDoubleFiles=TRUE duplicated files will be skipped, otherwise the will be renamed. If importFiles=TRUE the corpus object will be created but files will not be loaded. To load the files then call corpus_import.

Usage

corpus_new(
  pathsAnnotationFiles = NULL,
  pathsMediaFiles = NULL,
  name = "New Corpus",
  importFiles = TRUE,
  skipDoubleFiles = TRUE,
  skipDoubleFilesDatePattern = "",
  createNormalization = TRUE,
  createFulltext = TRUE,
  assignMedia = TRUE,
  pathNormalizationMatrix = NULL,
  namesInclude = character(),
  namesExclude = character(),
  namesExtractPatterns = character(),
  namesSearchPatterns = character(),
  namesSearchReplacements = character(),
  namesToUpper = FALSE,
  namesToLower = FALSE,
  namesTrim = TRUE,
  namesDefault = "no_name",
  cureTranscripts = TRUE,
  verbose = TRUE
)

Arguments

Details

The parameter pathsMediaFiles defines where the corresponding media files are located. If assignMedia=TRUE the paths defined in [email protected] will be scanned for media files and will be matched to the transcript object based on their names. Only the the file types set in options()$act.media.fileformats.audio and options()$act.media.fileformats.video will be recognized. You can modify these options to recognize other media types.

See @import.results of the corpus object to check the results of importing the files. To get a detailed overview of the corpus object use act::info(x), for a summary use act::info_summarized(x).

Value

Corpus object.

See Also

corpus_import, examplecorpus

Examples

library(act)

# The example files that come with the act library are located here:
path <- system.file("extdata", "examplecorpus", package="act")

# The example corpus comes without media files.
# It is recommended to download a full example corpus also including the media files.
# You can use the following commands.
## Not run: 
   path <- "EXISTING_FOLDER_ON_YOUR_COMPUTER/examplecorpus"
   temp <- tempfile()
   download.file(options()$act.examplecorpusURL, temp)
   unzip(zipfile=temp, exdir=path)

## End(Not run)

# The following command creates a new corpus object
mycorpus <- act::corpus_new(name = "mycorpus",
	pathsAnnotationFiles = path,
	pathsMediaFiles = path)

# Get a summary
mycorpus

Description

This is the main object the act package uses. It collects the annotations and meta data from loaded annotation files.

Details

Some of the slots are defined by the user. Some slots report results, such as @import.results and @media.assign.results. What the functions did to a transcript is recorded in the @history of that transcript object. Other slots are settings and are used when performing functions on the corpus object.

Slots

name

Character string; Name of the corpus.

transcripts

List of transcript objects; Each annotation file that has been load is stored in this list as a transcript object.

paths.annotation.files

Vector of character strings; Path(s) to one or several folders where your annotation files are located.

paths.media.files

Vector of character strings; Path(s) to one or several folders where your media files are located.

normalization.matrix

Data.frame; Replacement matrix used for normalizing the annotations. To change the normalization matrix use [email protected] <- act::matrix_load(path="...")

import.skip.double.files

Character string; controls handling of duplicate transcript names. "warn_keep_newest" keeps the newest file and warns. "warn_keep_first" keeps the first file and warns. "error" aborts on duplicates. "allow" allows duplicates without warning. For backward compatibility, logical values are accepted: TRUE is treated as "warn_keep_first", FALSE as "allow".

import.names.include

Vector of character strings; Only files matching this regular expression will be imported into the corpus.

import.names.exclude

Vector of character strings; Files matching this regular expression will be skipped and not imported into the corpus.

import.names.modify

List; Options how to modify the names of the transcript objects when they are added to the corpus. These options are useful, for instacne, if your annotation files contain character sequences that you do not want to include into the transcript name in the corpus (e.g. if you regularly add a date to the file name of your annotations files as 'myFile_2020-09-21.TextGrid').

import.results

Data.frame; information about the import of the annotation files.

media.assign.results

Data.frame; information about the media assignment.

Examples

library(act)

examplecorpus

Description

Example corpus with data loaded from the example annotations files that come with the package

Usage

data(examplecorpus)

Format

An object of class "corpus"

Details

The corpus comes without media files. To try it with its media (about 64 MB, downloaded once from GitHub, https://github.com/oliverehmer/act_examplecorpus/) use examplecorpus_media: x <- act::examplecorpus_media(). The paths in the corpus are relative to the example folder system.file("extdata", "examplecorpus", package = "act"). It is built by data-raw/examplecorpus_build.R of the package sources.

Source

• GAT: Ehmer, Oliver/Satti, Luis Ignacio/Martinez, Angelita/Pfaender, Stefan (2019): Un sistema para transcribir el habla en la interaccion: GAT 2.0 Gespraechsforschung - Online-Zeitschrift zur verbalen Interaktion (www.gespraechsforschung-ozs.de) 20, 64-114. http://www.gespraechsforschung-online.de/2019.html

• SYNC: Ehmer, Oliver (2020, in press): Synchronization in demonstrations. Multimodal practices for instructing body knowledge. Linguistics Vanguard. https://www.degruyter.com/view/journals/lingvan/lingvan-overview.xml

See Also

, corpus_new, corpus_import

Examples

library(act)

# Summary of the data in the corpus
examplecorpus

# Summary of the data in the second transcript in the corpus
examplecorpus@transcripts[[2]]

## Not run: 
# The example corpus with its media files (downloaded once, about 64 MB)
x <- act::examplecorpus_media()
x@transcripts[[1]]@media

## End(Not run)

Description

Returns the example corpus (examplecorpus) with its media files linked. The media (about 64 MB of wav and mp4 files) are not part of the package: at the first call they are downloaded from GitHub (option act.examplecorpusURL) into a folder of act on this computer (tools::R_user_dir("act", "data")); later calls use them from there without a download.

Usage

examplecorpus_media(folder = NULL, download = TRUE, verbose = TRUE)

Arguments

Value

Corpus object: the example corpus with its media files.

Examples

## Not run: 
library(act)
x <- act::examplecorpus_media()
x@transcripts[[1]]@media

## End(Not run)

Description

Creates a .pfsx preferences file next to an .eaf file. The .pfsx file makes 'ELAN' select and zoom to a time region when the .eaf file is opened. The .pfsx file is written to the same location as the .eaf file, with the extension replaced by .pfsx.

Usage

export_create_pfsx(
  path.out.eaf,
  startSec,
  endSec,
  tierName = NULL,
  overwrite = FALSE
)

Arguments

Value

Invisibly returns NULL. The function is called for its side effect of creating a .pfsx file.

Description

Writes a print transcript as a Word file. Everything about its look comes from a transcript profile (parameter style): mode (gat or score), width, line numbers, speaker acronyms, tier and character styles, the Word template and the advanced engine settings. Profiles are JSON files; the ones shipped with act are listed by helper_style_list(), and helper_style_read() reads one for inspection or modification.

Usage

export_docx(
  t,
  pathOutput = NULL,
  filterTierNames = NULL,
  filterSectionStartsec = NULL,
  filterSectionEndsec = NULL,
  insertArrowStartsec = NA_real_,
  insertArrowEndsec = NA_real_,
  insertArrowTierName = NA_character_,
  headerPreface = NULL,
  headerTitle = NULL,
  headerSubtitle = NULL,
  headerDescription = NULL,
  headerInsertSource = TRUE,
  layerOrder = NULL,
  report = FALSE,
  pathReport = NULL,
  mainTierNames = NULL,
  alignChars = NULL,
  alignModes = NULL,
  style = NULL
)

Arguments

Details

The Word styles of the profile are looked up in the template of the profile (word$file); with word$look = "profile" styles missing there are created from the profile.

Value

Officer doc; transcript as object from library officer.

See Also

corpus_export, export_eaf, export_exb, export_rpraat, export_srt, export_textgrid, vignette("export_docx_styles", package = "act")

Examples

library(act)

# Get a transcript
t <- examplecorpus@transcripts[[1]]

# Create print transcript
printtranscript <- act::export_docx (t=t)

# Display on screen
printtranscript

Description

Advice: In most situations it is more convenient to use act::corpus_export for exporting annotation files.

Usage

export_eaf(
  t,
  pathOutput = NULL,
  filterTierNames = NULL,
  filterSectionStartsec = NULL,
  filterSectionEndsec = NULL,
  createMediaLinks = TRUE,
  mediaMaxFiles = NULL,
  mediaWriteOffset = FALSE
)

Arguments

Details

The .eaf file will be written to the file specified in pathOutput. If pathOutput is left empty, the function will return the contents of the .eaf itself.

Value

Contents of the .eaf file (only if pathOutput is left empty)

See Also

corpus_export, export_exb, export_txt, export_rpraat, export_srt, export_textgrid, export_docx

Examples

library(act)

# Get the transcript you want to export
t <- examplecorpus@transcripts[[1]]

# Create temporary file path
path <- tempfile(pattern = t@name, tmpdir = tempdir(), fileext = ".eaf")

# It makes more sense, however, to you define a destination folder
# that is easier to access on your computer
## Not run: 
path <- file.path("PATH_TO_AN_EXISTING_FOLDER_ON_YOUR_COMPUTER",
                   paste(t@name, ".eaf", sep=""))

## End(Not run)

# Export WITH media links
act::export_eaf(t=t, pathOutput=path)

# Export WITHOUT media links
act::export_eaf(t=t, pathOutput=path, createMediaLinks = FALSE)

Description

Advice: In most situations it is more convenient to use act::corpus_export for exporting annotation files.

Usage

export_edl(
  t,
  pathOutput = NULL,
  filterTierNames = NULL,
  filterSectionStartsec = NULL,
  filterSectionEndsec = NULL,
  fps = 50
)

Arguments

Details

Creates a 'event list text' .edl file with definitions for Blackmagic DaVinci Resolve It will be written to the file specified in pathOutput. If pathOutput is left empty, the function will return the contents of the .edl itself.

Value

Contents of the .edl file (only if pathOutput is left empty)

See Also

corpus_export, export_eaf, export_exb, export_srt, export_txt, export_docx, export_rpraat, export_textgrid

Examples

library(act)

# Get the transcript you want to export
t <- examplecorpus@transcripts[[1]]

# Create temporary file path
path <- tempfile(pattern = t@name, tmpdir = tempdir(),
                 fileext = ".srt")

# It makes more sense, however, to you define a destination folder
# that is easier to access on your computer:
## Not run: 
path <- file.path("PATH_TO_AN_EXISTING_FOLDER_ON_YOUR_COMPUTER",
                    paste(t@name, ".srt", sep=""))

## End(Not run)

# Export
act::export_srt(t=t, pathOutput=path)

Description

Advice: In most situations it is more convenient to use act::corpus_export for exporting annotation files.

Usage

export_exb(
  t,
  pathOutput = NULL,
  filterTierNames = NULL,
  filterSectionStartsec = NULL,
  filterSectionEndsec = NULL,
  createMediaLinks = TRUE
)

Arguments

Details

The .exb file will be written to the file specified in pathOutput. If pathOutput is left empty, the function will return the contents of the .exb itself.

Value

Contents of the .exb file (only if pathOutput is left empty)

See Also

corpus_export, export_eaf, export_txt, export_docx, export_rpraat, export_srt, export_textgrid

Examples

library(act)

# Get the transcript you want to export
t <- examplecorpus@transcripts[[1]]

# Create temporary file path
path <- tempfile(pattern = t@name, tmpdir = tempdir(), fileext = ".exb")

# It makes more sense, however, to you define a destination folder
# that is easier to access on your computer
## Not run: 
path <- file.path("PATH_TO_AN_EXISTING_FOLDER_ON_YOUR_COMPUTER",
                   paste(t@name, ".exb", sep=""))

## End(Not run)

# Export WITH media links
act::export_exb(t=t, pathOutput=path)

# Export WITHOUT media links
act::export_exb(t=t, pathOutput=path, createMediaLinks = FALSE)

Description

Advice: In most situations it is more convenient to use act::corpus_export for exporting annotation files.

Usage

export_rpraat(
  t,
  filterTierNames = NULL,
  filterSectionStartsec = NULL,
  filterSectionEndsec = NULL
)

Arguments

Details

This function is to create compatibility with the rPraat package. It converts an act transcript to a rPraat TextGrid object.

Credits: Thanks to Tomáš Bořil, the author of the rPraat package, for commenting on the exchange functions.

Value

rPraat TextGrid object

See Also

import_rpraat, corpus_export, export_eaf, export_exb, export_txt, export_docx, export_srt, export_textgrid

Examples

library(act)

# Convert
rpraat.tg <- act::export_rpraat(t=examplecorpus@transcripts[[1]])

# Now you can use the object in the rPraat pachage.
# For instance you can plot the TextGrid
## Not run: 
	rPraat::tg.plot(rpraat.tg)

## End(Not run)

Description

Advice: In most situations it is more convenient to use act::corpus_export for exporting annotation files.

Usage

export_srt(
  t,
  pathOutput = NULL,
  filterTierNames = NULL,
  filterSectionStartsec = NULL,
  filterSectionEndsec = NULL,
  speakerShow = TRUE,
  speakerWidth = 3,
  speakerEnding = ":"
)

Arguments

Details

Creates a 'Subrip title' .srt subtitle file. It will be written to the file specified in pathOutput. If pathOutput is left empty, the function will return the contents of the .srt itself.

Value

Contents of the .srt file (only if pathOutput is left empty)

See Also

corpus_export, export_eaf, export_exb, export_txt, export_docx, export_rpraat, export_textgrid

Examples

library(act)

# Get the transcript you want to export
t <- examplecorpus@transcripts[[1]]

# Create temporary file path
path <- tempfile(pattern = t@name, tmpdir = tempdir(),
                 fileext = ".srt")

# It makes more sense, however, to you define a destination folder
# that is easier to access on your computer:
## Not run: 
path <- file.path("PATH_TO_AN_EXISTING_FOLDER_ON_YOUR_COMPUTER",
                    paste(t@name, ".srt", sep=""))

## End(Not run)

# Export
act::export_srt(t=t, pathOutput=path)

Description

Advice: In most situations it is more convenient to use act::corpus_export for exporting annotation files.

Usage

export_textgrid(
  t,
  pathOutput = NULL,
  filterTierNames = NULL,
  filterSectionStartsec = NULL,
  filterSectionEndsec = NULL
)

Arguments

Details

The .TextGrid file will be written to the file specified in pathOutput. If pathOutput is left empty, the function will return the contents of the .TextGrid itself.

Value

Contents of the .TextGrid file (only if pathOutput is left empty)

See Also

corpus_export, export_eaf, export_exb, export_txt, export_docx, export_rpraat, export_srt

Examples

library(act)

# Get the transcript you want to export
t <- examplecorpus@transcripts[[1]]

# Create temporary file path
path <- tempfile(pattern = t@name, tmpdir = tempdir(),
                 fileext = ".TextGrid")

# It makes more sense, however, to you define a destination folder
# that is easier to access on your computer:
## Not run: 
path <- file.path("PATH_TO_AN_EXISTING_FOLDER_ON_YOUR_COMPUTER",
                    paste(t@name, ".TextGrid", sep=""))

## End(Not run)

# Export
act::export_textgrid(t=t, pathOutput=path)

Description

Writes a print transcript as plain text. Its layout comes from a transcript profile (parameter style); see export_docx.

Usage

export_txt(
  t,
  pathOutput = NULL,
  filterTierNames = NULL,
  filterSectionStartsec = NULL,
  filterSectionEndsec = NULL,
  insertArrowStartsec = NA_real_,
  insertArrowEndsec = NA_real_,
  insertArrowTierName = NA_character_,
  headerPreface = NULL,
  headerTitle = NULL,
  headerSubtitle = NULL,
  headerDescription = NULL,
  headerInsertSource = TRUE,
  collapse = TRUE,
  layerOrder = NULL,
  report = FALSE,
  pathReport = NULL,
  mainTierNames = NULL,
  alignChars = NULL,
  alignModes = NULL,
  style = NULL
)

export_printtranscript(...)

Arguments

Value

Character string; transcript as text.

See Also

corpus_export, export_eaf, export_exb, export_rpraat, export_srt, export_textgrid, export_docx

export_txt

Examples

library(act)

# Get a transcript
t <- examplecorpus@transcripts[[1]]

# Create print transcript
printtranscript <- act::export_txt (t=t)

# Display on screen
cat(printtranscript)

Description

High-level reader that combines encoding detection with decoding, UTF-8 BOM stripping, optional XML declaration check (for EAF/EXB files), and optional header verification (e.g. TextGrid).

Usage

helper_annotationfile_read(
  filePath,
  expectedHeader = NULL,
  fileType = NULL,
  verbose = TRUE
)

Arguments

Details

The function reads the file with the detected encoding, removes a leading UTF-8 BOM character from line 1 if present, and (for XML files) extracts the declared encoding from the <?xml ... ?> header and compares it to the detected one. Mismatches are reported as a warning when verbose = TRUE but the file is still read with the detected encoding.

Value

A list with elements:

lines

Character vector with file contents, or NULL on error.

encoding_detected

Detected encoding (see helper_encoding_file_detect).

encoding_declared

Encoding declared in the XML header, or NA_character_.

encoding_match

Logical; whether declared and detected encoding belong to the same family, or NA if not applicable.

status

"ok" or "error".

message

Collected diagnostic messages, separated by "; ".

hash

Fingerprint of the bytes read (see helper_file_hash_compute), NA when nothing was read.

state

State of the file as it was read (see helper_file_state), an empty list when nothing was read.

See Also

helper_encoding_file_detect, helper_encoding_names_equivalent

Description

Ensures consistent column ordering: standard annotation columns first, then layer columns, then search/concordance columns (if present).

Usage

helper_annotations_columns_order(df)

Arguments

Value

Data.frame with reordered columns.

Description

Constructs the audio filter arguments for an FFmpeg command that optionally combines loudness normalization (loudnorm) and audio anonymization (silence, beep, or noise) over specified time ranges. The filters are built by helper_audio_filter_parts; the anonymization comes first, the normalization last. The beep and the noise are generated inside the filter graph.

Usage

helper_audio_filter_build(audio_normalize = FALSE, audio_anonymize = NULL)

Arguments

Details

Audio filter and beep frequency are read from options: act.ffmpeg.audio.anony_filter, act.ffmpeg.audio.anony_beep_freq, act.ffmpeg.audio.normalize.

Value

A named list with:

type

"none", "simple", or "filter_complex"

af_string

For "simple": the full -af "..." argument string. "" otherwise.

fc_parts

For "filter_complex": character vector of filter graph segments. character(0) otherwise.

out_label

For "filter_complex": the final audio stream label, e.g. "[aout]". "" otherwise.

map_a

For "filter_complex": the -map argument, e.g. "-map \"[aout]\"". "" otherwise.

Description

One builder for the sound filters of every export (viewer clips and sound files, act cuts): the channel selection, the loudness normalization and the anonymization of time ranges by beep, noise, mute or a voice distortion. The result is either a simple chain (af, for -af) or a filter graph (graph) that reads [0:a] and writes [aout]. The beep and the noise are generated inside the graph, so no further input is needed.

Usage

helper_audio_filter_parts(
  channel = "stereo",
  mono = FALSE,
  normalize = FALSE,
  ranges = NULL,
  mode = .audio_default_mode(),
  strength = 0.8,
  distort = NULL,
  beepFreq = getOption("act.ffmpeg.audio.anony_beep_freq", 800)
)

Arguments

Details

Order: channel first, then the anonymization, then the loudness (in front of the timed volume the loudness filter shifted its time base). The timed volume is evaluated in blocks of 64 samples (1.5 ms), so a range starts and ends where it is annotated. Beep and noise are mixed in the channel layout of the output (stereo, or mono with mono = TRUE).

Value

A list with af (character or NULL) and graph (character or NULL); at most one of them is set.

See Also

helper_ffmpeg_args_audio, helper_ffmpeg_args_clip

Examples

act::helper_audio_filter_parts(channel = "left",
                               ranges = data.frame(start = 1, end = 2.5))

Description

Exports only those transcripts from a corpus that were modified by transcripts_cure_single (either during import or via an explicit cure call). A transcript is considered cured if its most recent history entry of type transcripts_cure_single contains at least one non-zero correction counter.

Usage

helper_corpus_export_cured(x, folderOutput, formats = "textgrid")

Arguments

Details

All exported files are written flat into folderOutput, without sub-folders.

Value

Invisibly, a character vector with the names of the exported transcripts.

See Also

transcripts_cure_single, corpus_export

Description

One writer for every line of the render scripts that act and iclo save with helper_cutlist_save: ffmpeg and exiftool calls, folders, deletions, comments, messages and calls of other scripts. The caller collects the parts of each line (for ffmpeg the argument vector of helper_ffmpeg_args, helper_ffmpeg_args_clip or helper_ffmpeg_args_audio); this function quotes them for the shell of the target system. Arguments that need no quoting stay as they are.

Usage

helper_cutlist_lines(
  entries,
  os = c("mac", "win"),
  executable = getOption("act.cutlist.ffmpeg", "ffmpeg"),
  inputVariable = NULL,
  header = FALSE
)

Arguments

Details

Entry types (type) and their args:

• "ffmpeg": the ffmpeg arguments (without the executable).

• "exiftool": the exiftool arguments, as from helper_metadata_exif_argv; the call is skipped when exiftool is not installed.

• "mkdir": folders to create (with parents).

• "rm": files to delete (no error when missing).

• "comment": one text, written as a comment line.

• "echo": one text, printed when the script runs.

• "script": one script file to run.

• "blank": an empty line.

On Windows paths starting with / are written with backslashes and % is doubled.

Value

Character vector with the script lines.

See Also

helper_cutlist_save

Examples

act::helper_cutlist_lines(list(
  list(type = "comment", args = "==== clip 1 ===="),
  list(type = "mkdir", args = "/tmp/my clips"),
  list(type = "ffmpeg", args = c("-i", "/tmp/in.mp4", "-t", "2", "-y", "/tmp/my clips/out.mp4"))),
  os = "mac")

Description

Saves FFMPEG cut list fpr mac or windows For windows: simly saves to a .cmd file For mac: saves as a shell script and makes it executable (also adds "#!/bin/sh")

Usage

helper_cutlist_save(
  cutlistMac = NULL,
  cutlistWin = NULL,
  outFolder,
  outFilename
)

Arguments

Examples

library(act)

# --- Create two tier tables from scratch
tierTable1 <- act::helper_tiers_new_table(c("a","b","c","d"),
c("IntervalTier", "TextTier","IntervalTier","TextTier"))

tierTable2 <- act::helper_tiers_new_table(c("a","b","x","y"),
c("IntervalTier", "TextTier","IntervalTier","TextTier"))

tierTable3 <- act::helper_tiers_merge_tables(tierTable1,tierTable2)
tierTable3

Description

Determines the encoding of a text file deterministically using a four-step strategy:

Usage

helper_encoding_file_detect(filePath)

Arguments

Details

1. BOM detection in the first bytes: UTF-8 BOM (EF BB BF), UTF-16 LE BOM (FF FE), UTF-16 BE BOM (FE FF).

2. NULL-byte guard in the first 1000 bytes. Plain text files never contain 0x00; UTF-16 without BOM would be full of NULL bytes and would otherwise pass base::validUTF8() (because ASCII-range bytes are formally valid UTF-8).

3. UTF-8 validation via stringi::stri_enc_isutf8() on the whole file.

4. Fallback to LATIN1 (every byte sequence is valid LATIN1).

Value

A list with three elements:

encoding

One of "UTF-8", "UTF-8-BOM", "UTF-16LE", "UTF-16BE", "LATIN1", "UTF-16-no-BOM-likely", or NA_character_ on error.

confidence

One of "bom", "validated", "fallback", "unknown", or "error".

message

Human-readable explanation when the result is not "ok".

See Also

helper_annotationfile_read

Description

Normalizes encoding labels to a canonical family name by lowercasing, removing hyphens/underscores/whitespace, and mapping common aliases.

Usage

helper_encoding_name_normalize(x)

Arguments

Details

Examples:

• "UTF-8" -> "utf8"

• "utf-8-BOM" -> "utf8"

• "ISO-8859-1" -> "latin1"

• "UTF-16LE" -> "utf16"

Value

Character string with the canonical family name, or NA_character_.

See Also

helper_encoding_names_equivalent

Description

Compares two encoding labels after normalization via helper_encoding_name_normalize. Returns NA when either input is missing or empty.

Usage

helper_encoding_names_equivalent(a, b)

Arguments

Value

Logical or NA.

See Also

helper_encoding_name_normalize

Description

Builds the argument vector (without the program name) for one FFmpeg call that writes a single image (JPG or PNG). All image outputs of act and iclo are built here, so the rules for reading video sources apply in one place:

• The seek is done in two stages: a fast seek to one second before the target in front of the input, then an exact seek of the rest after it (-ss t-1 -i ... -ss 1). A single seek in front of the input (-ss t -i) can miss the frames that are displayed just before a keyframe but decoded after it (B-frames): it then delivers the keyframe instead. With a filter, the rest is cut by a trim at the start of the filter chain instead, so the filter only processes the target frame.

• The seek target is the time as players that honour the edit list of the file show it (ELAN with AVFoundation, browsers): the edit list offset of the video track is added, and the frame that is on screen at that moment is taken (not the next one). With the option act.media.timeline = "raw" (ELAN with VLC) the offset is not added. Camera files with B-frames carry an offset of their reorder delay (e.g. 2 frames), cuts made with stream copy may carry any offset.

• Video inputs (mp4, mov, m4a, m4v) get -ignore_editlist 1 -avoid_negative_ts make_zero in front of -i. Without these flags a file with an edit list delivers a black frame. Image inputs never get them (the image demuxer rejects the option).

• JPG outputs are written with -q:v derived from imageQuality.

Usage

helper_ffmpeg_args(
  output,
  input = NULL,
  startsec = NULL,
  duration = NULL,
  inputsExtra = NULL,
  videoFilter = NULL,
  filterComplex = NULL,
  filterMap = NULL,
  imageQuality = getOption("act.ffmpeg.image.quality", 100),
  maxHeight = NULL,
  videoOffset = NULL,
  videoFps = NULL
)

Arguments

Value

Character vector of FFmpeg arguments.

See Also

helper_ffmpeg_run, helper_ffmpeg_path

Examples

act::helper_ffmpeg_args(output = "still.jpg", input = "video.mp4", startsec = 12.5)

Description

Builds the argument vector (without the program name) for one FFmpeg call that writes a sound file (wav, mp3 or m4a) from a sound or video source. The sound of an MP4/MOV source is read with its edit list honoured, as ELAN plays it (with act.media.timeline = "raw" it is ignored, as VLC does). Without filter, a wav/aif from a source of the same format and an mp3 from an mp3 are copied as they are; otherwise a wav/aif is written with the bit depth and sample rate of the source, mp3 and m4a are encoded with act.ffmpeg.audio.bitrate. A source without sound track is refused with an error.

Usage

helper_ffmpeg_args_audio(
  output,
  input,
  startsec,
  duration,
  audioFilter = NULL,
  filterComplex = NULL,
  audioMap = "[aout]",
  audioBitrate = getOption("act.ffmpeg.audio.bitrate", "192k"),
  metadataArgs = NULL
)

Arguments

Value

Character vector of FFmpeg arguments.

See Also

helper_audio_filter_parts, helper_ffmpeg_args_clip, helper_ffmpeg_run

Examples

act::helper_ffmpeg_args_audio(output = "cut.wav", input = "sound.wav",
                              startsec = 12.5, duration = 4)

Description

Builds the argument vector (without the program name) for one FFmpeg call that writes a video clip (MP4). The rules of helper_ffmpeg_args apply to the picture: exact two-stage seek, edit list flags for video inputs, and the picture of a clip starts with the frame that players honouring the edit list (ELAN with AVFoundation) show at startsec. The sound is read from a second input of the same file (or audioInput) with its own seek: its edit list is honoured, so the encoder delay at the start of AAC tracks is skipped like ELAN does, and picture and sound are in sync as in ELAN. An AAC encoder shifts its output by 1024 samples, which no player compensates in a file without edit list; the first 1024 samples are therefore cut at the very end of the sound chain, so the clip plays at the right time. Filters (e.g. an anonymization in a graph) still see the time of the clip, so their ranges stay exact. The sound keeps the sample rate of the source (a loudness filter would otherwise raise it and shift that delay). In a filter graph the sound of the source is therefore addressed as [0:a] as usual - it is rewritten to the sound input.

Usage

helper_ffmpeg_args_clip(
  output,
  input,
  startsec,
  duration,
  inputsExtra = NULL,
  videoFilter = NULL,
  filterComplex = NULL,
  videoMap = NULL,
  audioMap = NULL,
  audioFilter = NULL,
  maxHeight = getOption("act.ffmpeg.video.max_height"),
  maxWidth = getOption("act.ffmpeg.video.max_width"),
  videoBitrate = getOption("act.ffmpeg.video.bitrate", "8M"),
  videoCrf = getOption("act.ffmpeg.video.crf"),
  keyframeInterval = getOption("act.ffmpeg.video.keyframe_interval", 25),
  audioCodecArgs = c("-c:a", "aac", "-b:a", getOption("act.ffmpeg.audio.bitrate",
    "192k")),
  metadataArgs = NULL,
  videoOffset = NULL,
  videoFps = NULL,
  audioInput = NULL,
  videoCodecCopy = FALSE,
  withAudio = TRUE,
  videoHardware = getOption("act.ffmpeg.video.hardware", TRUE),
  videoCodecCopyFail = getOption("act.ffmpeg.video.codec.copy.fail", "abort")
)

Arguments

Details

With the option act.ffmpeg.video.exact_timing (default TRUE) an encoded clip with sound is written with -avoid_negative_ts disabled: the AAC encoder starts the sound at a negative time, and without this flag the muxer shifts the picture from the second frame on by that amount (about 21 ms) behind the sound. Set the option to FALSE if PowerPoint has problems with such clips, e.g. when cropping the picture.

Every clip is written as H.264 with yuv420p (PowerPoint plays nothing else), with -use_editlist 0 -movflags +faststart, without B-frames (-bf 0): with B-frames the picture of a file without edit list starts two frames after the sound. The frame rate is set explicitly (-r): after the trim the encoder would otherwise assume the time base as frame rate and, with a bit rate, write grey frames at the start.

Value

Character vector of FFmpeg arguments.

See Also

helper_ffmpeg_args, helper_ffmpeg_run

Examples

act::helper_ffmpeg_args_clip(output = "cut.mp4", input = "video.mp4",
                             startsec = 12.5, duration = 4)

Description

Runs the executable resolved by helper_ffmpeg_path (or helper_ffprobe_path) with -version and reports whether it works. An executable can exist and still not run, e.g. an FFmpeg built for Intel processors on a Mac with Apple silicon that has no Rosetta. The result is remembered for the session.

Usage

helper_ffmpeg_check(executable = c("ffmpeg", "ffprobe"))

Arguments

Details

For FFmpeg the check also lists the filters act needs for burnt-in text that are missing: ass (subtitles, needs libass) and drawtext (timecode, needs freetype). FFmpeg still counts as working without them (clips, sound and stills without text are possible). On a Mac the plain Homebrew formula ffmpeg is built without both; install ffmpeg-full instead (see the README of act).

Value

TRUE or FALSE, with the attributes path (the executable that was tested), reason (why it does not run; NA when it runs) and filters_missing (character vector of the missing filters, empty when none is missing or when the executable is ffprobe or does not run) and hint (character vector: how to install FFmpeg with these filters on the running operating system; empty when nothing is missing).

See Also

helper_ffmpeg_path, helper_ffprobe_path

Examples

ok <- act::helper_ffmpeg_check()
if (!ok) print(attr(ok, "reason"))

Description

The demuxer flags that go directly before the -i of a source in an MP4/MOV container (mp4, m4a, m4v, mov) whose picture is read: -ignore_editlist 1 -avoid_negative_ts make_zero. Other files (images, wav, ...) get none - the image demuxer would abort on them.

Usage

helper_ffmpeg_input_flags(filePath)

Arguments

Value

Character vector of FFmpeg arguments (empty for other files).

Examples

act::helper_ffmpeg_input_flags("video.mp4")

Description

A video stream can only be copied (videoCodecCopy in helper_ffmpeg_args_clip) from a keyframe on. This function returns the time of the last keyframe at or before startsec, on the same timeline as startsec (the one players and ELAN show, see the option act.media.timeline). Only a short stretch before the start is read.

Usage

helper_ffmpeg_keyframe(input, startsec, videoOffset = NULL)

Arguments

Value

Numeric; the keyframe time in seconds, or startsec when the file is not a video or no keyframe was found. The attribute found tells the two apart: TRUE for a keyframe read from the file, FALSE when the lookup failed (not an MP4/MOV file, file missing, ffprobe missing, failed or timed out, no keyframe at or before startsec).

See Also

helper_ffmpeg_args_clip

Description

Returns the path to the FFmpeg executable using the following cascade:

1. Option act.path.ffmpeg, if it is set to a concrete path (any value other than the default "ffmpeg"). This path is returned as it is, without a test.

2. The first executable that runs and has the filters for burnt-in text (ass, drawtext), checked in this order: Sys.which("ffmpeg") (the PATH of the R session), then the known installation locations (/opt/homebrew/bin, /opt/homebrew/opt/ffmpeg-full/bin, /usr/local/bin, /usr/bin). So a Homebrew ffmpeg-full is found even when it is not linked and the plain formula ffmpeg is installed as well.

3. The first of these executables that runs, without these filters.

4. The first of these executables that exists, even if it does not run (helper_ffmpeg_check then reports why).

5. The literal "ffmpeg" as last resort (resolution is left to the shell).

Usage

helper_ffmpeg_path()

Details

Whether an executable runs is tested once per session (ffmpeg -version).

Value

Character string; path to the FFmpeg executable or "ffmpeg".

See Also

helper_ffprobe_path, helper_ffmpeg_check

Examples

act::helper_ffmpeg_path()

Description

Runs FFmpeg with an argument vector (as built by helper_ffmpeg_args) and checks the result at the file: FFmpeg ends with status 0 even when it wrote nothing (e.g. a seek behind the end of the file). A file of the same name is removed first, so an old file never counts as a new result.

Usage

helper_ffmpeg_run(args, output, what = "ffmpeg", quiet = FALSE)

Arguments

Value

Logical; TRUE if the file was written and is not empty.

See Also

helper_ffmpeg_args, helper_ffmpeg_path

Examples

## Not run: 
a <- act::helper_ffmpeg_args(output = "still.jpg", input = "video.mp4", startsec = 12.5)
act::helper_ffmpeg_run(a, output = "still.jpg")

## End(Not run)

Description

Returns the path to the ffprobe executable. ffprobe is installed together with FFmpeg and lives in the same directory. The cascade is:

1. ffprobe next to the FFmpeg executable resolved by helper_ffmpeg_path.

2. The first executable that runs: Sys.which("ffprobe"), then the known installation locations (/opt/homebrew/bin, /opt/homebrew/opt/ffmpeg-full/bin, /usr/local/bin, /usr/bin).

3. The first of these executables that exists, even if it does not run.

4. The literal "ffprobe" as last resort (resolution is left to the shell).

Usage

helper_ffprobe_path()

Value

Character string; path to the ffprobe executable or "ffprobe".

See Also

helper_ffmpeg_path, helper_ffmpeg_check

Examples

act::helper_ffprobe_path()

Description

Check whether an external application is available

Usage

helper_file_app_available(app = c("elan", "praat"))

Arguments

Value

Logical; TRUE if the option act.path.elan / act.path.praat points to an existing file.

Description

Builds a sortable key from the date (and optional version letter) in file names, e.g. 2026-10-04b. A plain date sorts before the same date with a version letter (no letter counts as version 0). Files without a date get an empty key, which sorts lowest.

Usage

helper_file_date_key_make(fileNames, datePattern)

Arguments

Value

Vector of character strings, one key per file name.

See Also

helper_file_newest_select

Examples

act::helper_file_date_key_make(c("a__2026-10-04.eaf", "a__2026-10-04b.eaf", "a.eaf"),
                               "__\\d{4}-\\d{2}-\\d{2}[a-z]?")

Description

Computes the fingerprint of the content of files as Git does (git hash-object): SHA-1 of "blob <size>\0" followed by the bytes of the file. Two files with the same fingerprint have the same content, byte for byte (a byte order mark and the line endings count).

Usage

helper_file_hash_compute(filePaths)

Arguments

Value

Vector of character strings, one fingerprint per file; NA for a file that does not exist or cannot be read.

Examples

library(act)
path <- system.file("extdata", "examplecorpus", "sync",
                    "SYNC_rotar_y_flexionar.eaf", package = "act")
helper_file_hash_compute(path)

Description

Chooses the newest of several files: by the date (and version letter) in the file name (see helper_file_date_key_make); when no file carries a date, by the modification time; when that is unknown too, the first file.

Usage

helper_file_newest_select(filePaths, datePattern)

Arguments

Value

Integer; index of the newest file (integer(0) for no files).

See Also

helper_file_date_key_make

Description

Starts the application with the file. The location of the application comes from the options act.path.elan and act.path.praat unless pathApp is given. ELAN opens .eaf files, Praat opens .TextGrid files; the format is not checked here.

Usage

helper_file_open_in(path, app = c("elan", "praat"), pathApp = NULL)

Arguments

Value

Logical; TRUE if the command was issued (invisibly). Aborts with a message if the file or the application is not found.

Examples

## Not run: 
helper_file_open_in("/path/to/file.eaf", app = "elan")
helper_file_open_in("/path/to/file.TextGrid", app = "praat")

## End(Not run)

Description

Opens the folder of the file and selects the file: Finder on macOS, Explorer on Windows. On Linux only the folder is opened (there is no common way to select a file).

Usage

helper_file_reveal(path)

Arguments

Value

Logical; TRUE if the command was issued, FALSE if the path does not exist (invisibly).

Examples

## Not run: 
helper_file_reveal("/path/to/file.eaf")

## End(Not run)

Description

The state a transcript keeps of the file it was read from or last written to (slot file.state of a transcript object): path, fingerprint, size, modification time and the time the state was taken. It is compared with the file on disk before the file is overwritten (helper_file_state_changed).

Usage

helper_file_state(filePath, hash = NULL)

Arguments

Value

A list with path, hash (see helper_file_hash_compute), size (bytes), mtime (POSIXct) and time (POSIXct, when the state was taken); an empty list when the file does not exist.

Examples

library(act)
path <- system.file("extdata", "examplecorpus", "sync",
                    "SYNC_rotar_y_flexionar.eaf", package = "act")
helper_file_state(path)

Description

Compares the file on disk with a state taken earlier (helper_file_state). The content decides: when size and modification time are the same, the file counts as unchanged without being read; otherwise its fingerprint is compared. A modification time that changed without a change of the content (e.g. by a sync service) therefore does not count as a change.

Usage

helper_file_state_changed(state, filePath = NULL)

Arguments

Value

FALSE unchanged, TRUE changed or no longer there, NA no state for this file.

Examples

library(act)
path <- system.file("extdata", "examplecorpus", "sync",
                    "SYNC_rotar_y_flexionar.eaf", package = "act")
state <- helper_file_state(path)
helper_file_state_changed(state)

Description

Reads the @history of a transcript (or of every transcript of a corpus) and reports whether entries were added after the last baseline entry. Baseline entries are the import entries written by the import functions (import_eaf, import_textgrid, ...; every entry whose modification starts with "import_") and the export marks written by helper_history_mark_export.

Usage

helper_history_changed(x)

Arguments

Value

Named logical vector, one element per transcript (TRUE = changed since the last import or export). For a single transcript the vector has length one.

See Also

helper_history_mark_export

Description

Appends an export entry to the @history of the given transcripts of a corpus. corpus_export does not change the corpus it is given; call this helper afterwards so that helper_history_changed knows that the current state has been written to disk.

Usage

helper_history_mark_export(
  x,
  transcriptNames = NULL,
  formats = NULL,
  folderOutput = NULL
)

Arguments

Value

Corpus object with the updated histories.

See Also

helper_history_changed, corpus_export

Description

Returns the anchor specification of every rendered row: which symbol of which layer row targets which column and line of its verbal source row. Intended for viewers that draw or edit aligned transcripts.

Usage

helper_layout_anchors(
  t,
  filterTierNames = NULL,
  filterSectionStartsec = NULL,
  filterSectionEndsec = NULL,
  layerOrder = NULL,
  mainTierNames = NULL,
  alignChars = NULL,
  alignModes = NULL,
  style = NULL
)

Arguments

Value

Data.frame with one row per anchored symbol (columns include row, tierName, char, occurrence, target_col, target_line, source_row, prefix_width, type, status, pair_id, source_occurrence). target_col counts from the text body of the source row - line number and speaker sigle are already subtracted; their width is reported in prefix_width. status explains an NA target_col: "placed", "flush_leading" (leading symbol flush with its segment start, no counterpart needed), "no_match" (no time-matched main symbol), "target_dropped" (matched symbol not present in the rendered line), "beyond_width" (target outside the wrap width). pair_id joins the two brackets of one overlap pair; source_occurrence is the bracket occurrence in the source row.

Description

Computes which opening and closing overlap brackets of the verbal tiers belong together, without rendering. Row indices refer to the engine frame returned in the ann element.

Usage

helper_layout_bracket_pairs(
  t,
  filterTierNames = NULL,
  filterSectionStartsec = NULL,
  filterSectionEndsec = NULL,
  mainTierNames = NULL,
  alignChars = NULL,
  alignModes = NULL,
  style = NULL
)

Arguments

Value

List with the engine frame ann and the data.frame pairs (columns i_row, i_occurrence, j_row, j_occurrence).

Description

Renders a single transcript into aligned print-transcript lines using the wrap-aware alignment engine. Layout, styles and the advanced engine settings (time tolerances, minimum description room, span limit, picture tiers, catch-all multimodal tiers) come from the transcript profile style; its mode decides between "gat" (one line per annotation) and "mondada" (score layout).

Usage

helper_layout_render(
  t,
  filterTierNames = NULL,
  filterSectionStartsec = NULL,
  filterSectionEndsec = NULL,
  layerOrder = NULL,
  mainTierNames = NULL,
  alignChars = NULL,
  alignModes = NULL,
  insertArrowStartsec = NA_real_,
  insertArrowEndsec = NA_real_,
  insertArrowTierName = NA_character_,
  style = NULL
)

Arguments

Value

List with the rendered lines, the line plan, the engine result frame (one row per annotation; its column line_number carries the printed line number of a numbered main annotation as a character string and NA otherwise - in the mondada mode, which numbers printed lines rather than annotations, it is always NA), the filtered transcript, the engineWidth, the layoutMode, and - computed from the same single rendering - the anchors table (as in helper_layout_anchors), the bracket pairs and the multimodal symbol matches.

Description

Matches every multimodal layer symbol to its verbal main symbol by time, without rendering. Row indices refer to the engine frame returned in the ann element.

Usage

helper_layout_symbol_matches(
  t,
  filterTierNames = NULL,
  filterSectionStartsec = NULL,
  filterSectionEndsec = NULL,
  mainTierNames = NULL,
  alignChars = NULL,
  alignModes = NULL,
  style = NULL
)

Arguments

Value

List with the engine frame ann and the data.frame matches (columns layer_row, char, layer_occurrence, main_row, main_occurrence).

Description

Asks ffprobe for the streams of a file (cached per file).

Usage

helper_media_audio_track_exists(filePath)

Arguments

Value

TRUE or FALSE; NA when the file does not exist or could not be read.

Description

Tells video from sound files by their extension, using the options act.media.fileformats.video and act.media.fileformats.audio. These two options are the only list of media formats in act and iclo.

Usage

helper_media_type(filePaths)

Arguments

Value

Vector of character strings: "video", "audio" or NA, one per path.

Examples

act::helper_media_type(c("rec.mp4", "rec.WAV", "still.png"))

Description

Reads the edit list offset of the video track and the frame duration of a video file (cached per file). Values passed in are used instead of reading the file. With the option act.media.timeline = "raw" the offset is 0.

Usage

helper_media_video_timing_read(filePath, videoOffset = NULL, videoFps = NULL)

Arguments

Value

List with offset (seconds) and frame_dur (seconds, NA when unknown).

Description

Returns the argument vector (without the program name) for ONE exiftool call that writes the EXIF UserComment of several JPG files, each with its own value (-execute between the files, -q and -overwrite_original as common arguments). Used for direct writing (helper_metadata_exif_write()) and for the exiftool line in cut list scripts.

Usage

helper_metadata_exif_argv(file, sourcePath, startsec, clipID)

Arguments

Value

Character vector of exiftool arguments.

See Also

helper_metadata_exif_write()

Description

Uses the bundled exiftool from the exifr package (which itself requires Perl on the system). When exifr is not installed or perl is not on the system path, the function silently returns without modifying the file. The single setup hint is emitted by iclo::config() (not by this helper, to keep it usable as a quiet library primitive).

Usage

helper_metadata_exif_write(file, sourcePath, startsec, clipID)

Arguments

Details

Uses -overwrite_original to avoid .jpg_original backup files. Several files are tagged in ONE exiftool call (see helper_metadata_exif_argv()).

Value

Invisibly NULL.

See Also

media_metadata_read(), helper_metadata_ffmpeg_args(), helper_metadata_exif_argv()

Description

Returns a string that can be appended to ffmpeg command lines to write ⁠act.*⁠ tags into the comment field of the output file. For video files (when fps is supplied) a native timecode track is added via the -timecode option.

Usage

helper_metadata_ffmpeg_args(sourcePath, startsec, clipID, fps = NULL)

Arguments

Details

Returns an empty string when option act.ffmpeg.write_metadata is FALSE, allowing callers to disable tagging globally without changing call sites.

Tag format: ⁠act.source=<path>;act.startsec=<sec_3nks>;act.clipID=<id>⁠.

Value

Character string with ⁠-metadata comment="..."⁠ and optionally ⁠-timecode "HH:MM:SS:FF"⁠. Returns "" if metadata writing is disabled.

See Also

media_metadata_read(), helper_metadata_exif_write()

Description

Same tags as helper_metadata_ffmpeg_args(), but returned UNQUOTED as a character vector, ready for system2() / an ffmpeg argument list. Callers that assemble commands as vectors must use this variant: the comment carries the source path, which may contain spaces, so splitting the quoted string from helper_metadata_ffmpeg_args() again is not safe.

Usage

helper_metadata_ffmpeg_argv(sourcePath, startsec, clipID, fps = NULL)

Arguments

Details

Returns character(0) when option act.ffmpeg.write_metadata is FALSE.

Value

Character vector of ffmpeg arguments, or character(0) if metadata writing is disabled.

See Also

helper_metadata_ffmpeg_args(), media_metadata_read()

Description

One ffprobe stream query instead of a full json read. Callers that write metadata need the frame rate for the timecode track, see helper_metadata_ffmpeg_argv().

Usage

helper_metadata_probe_fps(file_path)

Arguments

Value

Numeric frame rate, or NA_real_ when ffprobe fails or the file holds no video stream.

See Also

helper_metadata_ffmpeg_argv(), helper_metadata_ffmpeg_args()

Description

Fills the options act.path.praat and act.path.elan with the programs found at the usual installation places: on macOS /Applications and ~/Applications, on Windows the program folders, elsewhere /opt, the home folder and the search path. When several ELAN versions are installed side by side (ELAN_6.7, ELAN_7.1), the newest one is taken.

Usage

helper_program_paths_detect()

Details

An option that already points to an existing program is kept. An option that is empty or points nowhere (for example to an ELAN version removed after an update) is replaced by the program found. act calls the helper when it is loaded.

Value

Invisibly, a data frame with one row per option: option, before (value before the call), after (value after the call) and changed (logical).

Examples

act::helper_program_paths_detect()

Description

Helper: Get the progress callback

Usage

helper_progress_callback_get()

Value

The function set with helper_progress_callback_set, or NULL.

Description

Registers a function that every progress bar of act (and of packages that use helper_progress_set / helper_progress_tick) calls when it starts and at every step, also while the console bars are switched off (option act.showprogress). A graphical caller (a Shiny app) uses it to show the progress itself.

Usage

helper_progress_callback_set(fn)

Arguments

Value

The previous callback (or NULL), invisibly - pass it back to restore it.

Examples

old <- helper_progress_callback_set(function(title, current, total)
	message(title, ": ", current, " of ", total))
helper_progress_set("Counting", 3)
for (i in 1:3) helper_progress_tick()
helper_progress_callback_set(old)

Description

Formats the remaining time of a loop as a fixed-width tail " (%7s left)" (15 characters, fits "59m 20s"), estimated from the elapsed time per finished item. The progress bars of act and iclo use it.

Usage

helper_progress_eta_format(start, current, total)

Arguments

Value

Character string.

Description

Helper: Set progress bar

Usage

helper_progress_set(title, total)

Arguments

Examples

library(act)

# --- Create two tier tables from scratch
tierTable1 <- act::helper_tiers_new_table(c("a","b","c","d"),
c("IntervalTier", "TextTier","IntervalTier","TextTier"))

tierTable2 <- act::helper_tiers_new_table(c("a","b","x","y"),
c("IntervalTier", "TextTier","IntervalTier","TextTier"))

tierTable3 <- act::helper_tiers_merge_tables(tierTable1,tierTable2)
tierTable3

Description

Helper: Advance progress bar by one tick

Usage

helper_progress_tick(len = 1)

Arguments

Examples

library(act)

# --- Create two tier tables from scratch
tierTable1 <- act::helper_tiers_new_table(c("a","b","c","d"),
c("IntervalTier", "TextTier","IntervalTier","TextTier"))

tierTable2 <- act::helper_tiers_new_table(c("a","b","x","y"),
c("IntervalTier", "TextTier","IntervalTier","TextTier"))

tierTable3 <- act::helper_tiers_merge_tables(tierTable1,tierTable2)
tierTable3

Description

Builds the acronym of each tier name the way the print transcript does: case, search and replace, extract, width, ending - with the values of the tier style, and where it leaves one open, those of the profile.

Usage

helper_style_acronym(style, tierNames, ending = TRUE)

Arguments

Value

Vector of character strings; one acronym per tier name.

Description

Lists the styles of a profile with the appearance that finally holds for each: its own values, and for a value it does not set the one of the style it builds on (transcript lines on the default style, the default and the header styles on Normal). Character styles only have their own values.

Usage

helper_style_appearance(style)

Arguments

Value

Data.frame with one row per style: name, type, role, active, word, pattern, applies, and font, size, color, background, italic, bold (NA where nothing is set).

Description

Writes an empty Word file that carries the styles of a style profile: the file the profile names (or templatePath, or the template of the package) with the paragraph and character styles of the profile written into it. Use it as a template of your own, or to merge transcripts into.

Usage

helper_style_docx(
  style,
  pathOutput,
  templatePath = NULL,
  symbolChars = character(0)
)

Arguments

Value

Invisibly a list with the path and the names of the styles that were created (not in the Word file before).

Description

Helper: Style profiles that can be found

Usage

helper_style_list()

Value

Named vector of character strings; paths of the profile files, named by the profile names.

Description

A style profile is a JSON file that holds the whole format of a print transcript: line structure, acronyms, tier styles, character styles and the appearance in Word. A profile can build on another profile (extends) and then only states what differs.

Usage

helper_style_read(style)

Arguments

Details

The profile folders are the folders named in the option act.style.folders and the folder extdata/styles of the package. The profile is checked; all problems found are reported together.

Value

The profile as list of class act_style, with all values filled in.

Description

The subtitles of a video show the annotations of tiers as rows; the profile holds their look in the block video of the default style (text and box) and in the block video of each tier style (the values it changes for its tiers). This helper resolves the look the way the print transcript resolves the appearance: the tier style of a tier, and for every value it leaves open the default.

Usage

helper_style_video(style, tierNames)

Arguments

Value

List with text (font, size in percent of the video height, color, effect, effect.color, effect.width), box (background, opacity, padding in font sizes, overflow, lines) and rows: one entry per tier name with style (name of the tier style), row (a subtitle row by default), size (percent of the text size), color, effect, effect.color, effect.width, lines, bold, italic and acronym (the row carries the acronym of the speaker).

Description

Splits a character string into its user-perceived characters (grapheme clusters): a base letter with combining accents counts as one element. The layout engine measures and aligns text with this split.

Usage

helper_text_graphemes_split(text)

Arguments

Value

Character vector, one element per grapheme; empty for NA or an empty string.

Examples

act::helper_text_graphemes_split("ca\u0301fe")

Description

Creates a tier name filter based on a vector of character strings and the values 'filterTierIncludeRegEx' and 'filterTierExcludeRegEx' (in a transcript profile: functions$tiers.keep and functions$tiers.exclude). First, tiers matching 'filterTierExcludeRegEx' are removed. Then, tiers matching 'filterTierIncludeRegEx' are added back from the original tier list, ensuring they are always included regardless of the exclude filter. The original tier order is preserved.

Usage

helper_tiers_filter_create(
  tierNames,
  filterTierIncludeRegEx = "",
  filterTierExcludeRegEx = ""
)

Arguments

Value

Vector of character strings; names of tiers

Examples

library(act)

# --- Create a tier table from scratch
tierTable <- act::helper_tiers_new_table(c("a","b","c", "d"), 
c("IntervalTier", "TextTier","IntervalTier","TextTier"))
tierTable

Description

Merges several the tier tables into one tier table.

Usage

helper_tiers_merge_tables(...)

Arguments

Details

NOTE: To actually modify the tiers in a transcript object or a corpus object corpus use the functions of the package, e.g. act::transcripts_merge. This function is only a helper function and for people that like experiments. If tiers with the same name are of different types ('IntervalTier', 'TextTier') an error will be raised. In that case can use, for example, 'act::tier_convert()' to change the tier types.

Value

Data.frame

See Also

helper_tiers_sort_table, helper_tiers_merge_tables, tiers_convert, tiers_rename, tiers_sort, transcripts_merge

Examples

library(act)

# --- Create two tier tables from scratch
tierTable1 <- act::helper_tiers_new_table(c("a","b","c","d"),
c("IntervalTier", "TextTier","IntervalTier","TextTier"))

tierTable2 <- act::helper_tiers_new_table(c("a","b","x","y"),
c("IntervalTier", "TextTier","IntervalTier","TextTier"))

tierTable3 <- act::helper_tiers_merge_tables(tierTable1,tierTable2)
tierTable3

Description

Creates a new tier table as necessary in @tiers of a transcript object.

Usage

helper_tiers_new_table(tierNames, tierTypes = NULL, tierPositions = NULL)

Arguments

Details

NOTE: To actually modify the tiers in a transcript object or a corpus object corpus use the functions of the package. This function is only a helper function and for people that like experiments.

Value

Data.frame

See Also

helper_tiers_sort_table, helper_tiers_merge_tables, tiers_convert, tiers_rename, tiers_sort

Examples

library(act)

# --- Create a tier table from scratch
tierTable <- act::helper_tiers_new_table(c("a","b","c", "d"), 
c("IntervalTier", "TextTier","IntervalTier","TextTier"))
tierTable

Description

NOTE: To actually reorder the tiers in a transcript object or a corpus object corpus use act::tiers_sort. This function is only a helper function and for people that like experiments.

Usage

helper_tiers_sort_table(
  tierTable,
  sortVector,
  tiersAddMissing = TRUE,
  tiersDelete = FALSE
)

Arguments

Details

Sort a tier table by a predefined vector of tier names. The names are compared exactly (no regular expressions). Tiers that are missing in the table but are present in the sort vector may be inserted. Tiers that are present in the table but not in the sort vector may be deleted or inserted. These tiers will be inserted by default at the end of the table. You may also use an element "*" in 'sortVector' to define the position where they should be placed (the escaped form, a backslash followed by a star, is accepted as well).

Value

Data.frame

See Also

tiers_sort, helper_tiers_new_table, helper_tiers_merge_tables

Examples

# This function applies to the tier tables that are necessary in \code{@tiers} of a transcript.
# object. For clarity, we will create such a table from scratch.

library(act)

# --- Create a tier table from scratch
tierTable <- helper_tiers_new_table(c("a","b","c", "d"), 
c("IntervalTier", "TextTier","IntervalTier","TextTier"))

# --- Create a vector, defining the new order of the tiers.
sortVector <- c("c","a","d","b")

# Sort the table
tierTable.1 <- act::helper_tiers_sort_table(tierTable=tierTable, sortVector=sortVector)
tierTable.1

# --- Create a vector, in which the tier "c" is missing.
sortVector <- c("a","b","d")

# Sort the table, the missing tier will be inserted at the end.
tierTable.1 <- act::helper_tiers_sort_table(tierTable=tierTable, sortVector=sortVector)
tierTable.1

# --- Create a vector, in which the tier "c" is missing, 
# but define the place, where missing tiers will be inserted by "*"
sortVector <- c("a","\\*", "b","d")

# Sort the table. The missing tier "c" will be inserted in second place.
tierTable.2 <- act::helper_tiers_sort_table(tierTable=tierTable, sortVector=sortVector)
tierTable.2

# Sort the table, but delete tiers that are missing in the sort vector
# Note: If 'tiersDelete=TRUE' tiers that are missing in the
# will be deleted, even if the 'sortVector' contains a "\*".
tierTable.3 <- act::helper_tiers_sort_table(tierTable=tierTable, 
sortVector=sortVector, 
tiersDelete=TRUE)
tierTable.3

# --- Create a vector, which contains tier names that are not present in 'tierTable'.
sortVector <- c("c","a","x", "y", "d","b")
tierTable.4 <- act::helper_tiers_sort_table(tierTable=tierTable, sortVector=sortVector)
tierTable.4