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

...

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

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

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", "normalizationMatrix.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,
  l = 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.path' attribute 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, createFulltext = TRUE, assignMedia = 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.fileformats.audio and options()$act.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

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,
  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"
)

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.fileformats.audio and options()$act.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 @history and . 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

Logical; if TRUE files with the same names will be skipped (only one of them will be loaded), if FALSE transcripts will be renamed to make the names unique.

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.

history

List; History of modifications made by any of the package functions to the corpus.

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

You can download the corresponding media files from

• www.oliverehmer.de in the section "Digital Humanities or

• from Github: https://github.com/oliverehmer/act_examplecorpus/. Alternatively you can use the download commands in the example section below.

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 th second transcripts in the corpus
examplecorpus@transcripts[[2]]

## Not run: 
# Download example corpus with media files
destinationpath <- 
temp <- tempfile()
download.file(options()$act.examplecorpusURL, temp)
unzip(zipfile=temp, exdir=destinationpath)

# Set the URL for the ZIP archive
url <- options()$act.examplecorpusURL

# Define output path
output_dir <- "/EXISTING_FOLDERON_YOUR_COMPUTER/examplecorpus"
output_path <- file.path(output_dir, "act_examplecorpus.zip")

# Download the ZIP file
download.file(url, output_path, mode = "wb")

# Unzip it to the output directory
unzip(output_path, exdir = output_dir)

# Rename the extracted folder
folder_old <- file.path(output_dir, "act_examplecorpus-main")
folder_new <- file.path(output_dir, "act_examplecorpus")
if (dir.exists(folder_new)) unlink(folder_new, recursive = TRUE)
file.rename(folder_old, folder_new)


## End(Not run)

Description

LAYOUT Using the layout object you may

• Adjust with, abbreviation of speakers, etc.

• set filters to include/exclude tiers matching regular expressions. – assign template files for .docx formatting using format templates

Usage

export_docx(
  t,
  l = NULL,
  pathOutput = NULL,
  filterTierNames = NULL,
  filterSectionStartsec = NULL,
  filterSectionEndsec = NULL,
  insertArrowAnnotationID = "",
  headerPreface = NULL,
  headerTitle = NULL,
  headerSubtitle = NULL,
  headerDescription = NULL,
  headerInsertSource = TRUE,
  layerNames = NULL
)

Arguments

Details

FORMATING

• adjust the the defaults format templates in the default .docx template.

• define further templates and add them to a styles matrix. The paths to both files need to be set in your l layout object. Please check the slots [email protected] and [email protected]. You can see the structure of the default styles matrix in each new layout object in l@ [email protected]. Use the [email protected]<-act:: export_docx_styles_load(...) to assign a custom styles matrix from a csv files. The default format templates are

• Header:

• header.preface (formats: s@results$header.description)

• header.title (formats: s@results$header.description)

• header.subtitle (formats: s@results$header.description)

• header.description (formats: s@results$header.description)

• Transcript body

• body.default (formats: any annotation in „t@annotations“

• LAYERS In addition to the original transcript content in transcript@annotations$content you can output further layers. The layers need to be assigned to the data.frame transcript@annotations as new columns. To output the layers, pass the name(s) of the repective column(s) as character vector in the parameter layerNames.

Value

Officer doc; transcript as object from library officer.

See Also

corpus_export, export_eaf, export_exb, export_rpraat, export_srt, export_textgrid

Examples

library(act)

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

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

# Display on screen
printtranscript

Description

This function is only for checking how the export styles matrix (as .csv) will be loaded internally.

Usage

export_docx_styles_load(path = NULL, encoding = "UTF-8", path_docx = NA)

Arguments

Value

Data.frame

Examples

library(act)

# An example replacement matrix comes with the package.
path <- system.file("extdata", "normalization", "normalizationMatrix.csv", package="act")

# Load the matrix
mymatrix <- act::matrix_load(path)

# Have a look at the matrix
colnames(mymatrix)
mymatrix

#the original path of the matrix is stored in the attributes
attr(mymatrix, 'path')

Description

Save styles matrix for .docx transcripts

Usage

export_docx_styles_save(exportStyles, path, encoding = "UTF-8")

Arguments

Value

nothing

Examples

library(act)

# An example replacement matrix comes with the package.
path <- system.file("extdata", "normalization", "normalizationMatrix.csv", package="act")

# Load the matrix
mymatrix <- act::matrix_load(path)

# ' # Create temporary file path
path <- tempfile(pattern = "mymatrix", tmpdir=tempdir(),  fileext = ".csv")

# 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",
                  "mymatrix.csv")

## End(Not run)

# Save the matrix
act::matrix_save(mymatrix, path=path)

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
)

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

If you want to modify the layout of the print transcripts, create a new layout object with mylayout <- methods::new("layout"), modify the settings and pass it as argument l. In the layout object you may also set additional filters to include/exclude tiers matching regular expressions.

Usage

export_txt(
  t,
  l = NULL,
  pathOutput = NULL,
  filterTierNames = NULL,
  filterSectionStartsec = NULL,
  filterSectionEndsec = NULL,
  insertArrowAnnotationID = "",
  headerPreface = NULL,
  headerTitle = NULL,
  headerSubtitle = NULL,
  headerDescription = NULL,
  headerInsertSource = TRUE,
  collapse = TRUE
)

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

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

Formats time as HH:MM:SS,mmm

Usage

helper_format_time(t, digits = 1, addHrsMinSec = FALSE, addSec = FALSE)

Arguments

Value

Character string.

Examples

library(act)


helper_format_time(12734.2322345)
helper_format_time(2734.2322345)
helper_format_time(34.2322345)
helper_format_time(0.2322345)

helper_format_time(12734.2322345, addHrsMinSec=TRUE)
helper_format_time(2734.2322345, addHrsMinSec=TRUE)
helper_format_time(34.2322345, addHrsMinSec=TRUE)
helper_format_time(0.2322345, addHrsMinSec=TRUE)

helper_format_time(12734.2322345, digits=3)
helper_format_time(2734.2322345, digits=3)
helper_format_time(34.2322345, digits=3)
helper_format_time(0.2322345, digits=3)

helper_format_time(12734.2322345, addHrsMinSec=TRUE, digits=3)
helper_format_time(2734.2322345, addHrsMinSec=TRUE, digits=3)
helper_format_time(34.2322345, addHrsMinSec=TRUE, digits=3)
helper_format_time(0.2322345, addHrsMinSec=TRUE, digits=3)

helper_format_time(12734.2322345, addHrsMinSec=TRUE, addSec=TRUE)
helper_format_time(2734.2322345, addHrsMinSec=TRUE, addSec=TRUE)
helper_format_time(34.2322345, addHrsMinSec=TRUE, addSec=TRUE)
helper_format_time(0.2322345, addHrsMinSec=TRUE, addSec=TRUE)

helper_format_time(12734.2322345, addHrsMinSec=TRUE, digits=3, addSec=TRUE)
helper_format_time(2734.2322345, addHrsMinSec=TRUE, digits=3, addSec=TRUE)
helper_format_time(34.2322345, addHrsMinSec=TRUE, digits=3, addSec=TRUE)
helper_format_time(0.2322345, addHrsMinSec=TRUE, digits=3, addSec=TRUE)

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()

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 tier name filter based on a vector of character strings and the values 'filterTierIncludeRegEx' and 'filterTierExcludeRegEx' in a layout object.

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 regular expression strings. 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 a element '\*' in 'sortVector' to define the position where they should be placed..

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

Description

Gets the names of all transcript objects in a corpus object based from the @name attribute of each transcript.

Usage

helper_transcript_names_get(x)

Arguments

Value

List

Examples

library(act)

act::helper_transcript_names_get(examplecorpus)

Description

Makes valid names for all transcript objects in a corpus object based on the names passed in 'transcriptNames' parameter. In particular, the functions also corrects names, which have to be non-empty and unique. The following options are performed in the mentioned order.

Usage

helper_transcript_names_make(
  transcriptNames,
  extractPatterns = NULL,
  searchPatterns = NULL,
  searchReplacements = NULL,
  toUpper = FALSE,
  toLower = FALSE,
  trim = FALSE,
  defaultEmpty = "no_name"
)

Arguments

Value

List

Examples

library(act)

# make some names with an empty value "" and a duplivate "d"
transcriptNames <- c("a", "b", "", "d", "d")
act::helper_transcript_names_make(transcriptNames)

Description

Sets the names of all transcript objects in a corpus object both in the names of the list x@transcripts and in the slot @name of each transcript.

Usage

helper_transcript_names_set(x, transcriptNames)

Arguments

Value

List

Examples

library(act)

# get current names of the transcripts
names.old <- act::helper_transcript_names_get(examplecorpus)

# rename giving numbers as names
names.test <- as.character(seq(1:length(names.old)))
test <-  act::helper_transcript_names_set(examplecorpus, names.test)
names(test@transcripts)

# create an error: empty name
## Not run: 
names.test <- names.old
names.test[2] <- " "
test <-  act::helper_transcript_names_set(examplecorpus, names.test)

## End(Not run)

# create an error: double names
## Not run: 
names.test <- names.old
names.test[2] <- names.test[1]
test <-  act::helper_transcript_names_set(examplecorpus, names.test)

## End(Not run)

Description

Advice: In most situations it is more convenient to use act::corpus_new, act::corpus_import for importing annotation files.

Usage

import(..., transcriptName = NULL)

Arguments

Details

Imports the contents of an annotation file and returns a transcript object.

The input to this function in the parameter '...' may either be (1) the path to an annotation file (Currently 'ELAN' .eaf, 'EXMARaLDA .exb, 'Praat' .TextGrid and 'Subrib title' .srt files), (2) the contents of an annotation file obtained from the @file.content or by reading the contents of the files directly with read.lines() or (3) a rPraat TextGrid object.

Only the first input to '...' will be processed

Value

Transcript object.

See Also

corpus_import, corpus_new, import_eaf, import_exb, import_rpraat, import_srt, import_textgrid

Examples

library(act)

# To import an annotation file of your choice:
## Not run: 
	path <- "PATH_TO_AN_EXISTING_FILE_ON_YOUR_COMPUTER"

## End(Not run)

# Path to a .TextGrid file that you want to read
filePath <- system.file("extdata", "examplecorpus", "GAT", 
						"ARG_I_PAR_Beto.TextGrid", package="act")
t <- act::import(filePath=filePath)
t

# Path to an .eaf file that you want to read
filePath <- system.file("extdata", "examplecorpus", "SYNC", 
						"SYNC_rotar_y_flexionar.eaf", package="act")
t <- act::import(filePath=filePath)
t

# Content of a .TextGrid file, e.g. as stored in \code{@file.content} 
# of a transcript object.
fileContent <- examplecorpus@transcripts[['ARG_I_CHI_Santi']]@file.content
t <- act::import(fileContent=fileContent)
t

# Content of an .eaf file, e.g. as stored in \code{@file.content} 
# of a transcript object.
fileContent <- examplecorpus@transcripts[['SYNC_rotar_y_flexionar']]@file.content
t <- act::import(fileContent=fileContent)
t

Description

Advice: In most situations it is more convenient to use act::corpus_new, act::corpus_import for importing annotation files.

Imports the contents of a 'ELAN' .eaf file and returns a transcript object. The input to this function is either the path to an .eaf file or the contents of a .eaf file obtained from the @file.content of an existing transcript object by readLines(). If you pass 'fileContent' you need to pass 'transcriptName' as parameter, too.

Usage

import_eaf(filePath = NULL, fileContent = NULL, transcriptName = NULL)

Arguments

Details

Please note:

• 'ELAN' offers a variety of tier types, some including dependencies from other tiers. Therefore not all annotations do actually have a time value. Missing values will be detected in the superordinate tier or will be interpolated. You will not be able to recognize interpolated values in the annotations.

• Please also note that dependencies between tiers in you .eaf file are not reflected in the transcript object within the act package.

Value

Transcript object.

See Also

corpus_import, corpus_new, import, import_exb, import_rpraat, import_textgrid

Examples

library(act)

# Path to an .eaf file that you want to read
path <- system.file("extdata", "examplecorpus", "SYNC", 
					"SYNC_rotar_y_flexionar.eaf", package="act")


# To import a .eaf file of your choice:
## Not run: 
path <- "PATH_TO_AN_EXISTING_EAF_ON_YOUR_COMPUTER"

## End(Not run)


t <- act::import_eaf(filePath=path)
t

# Content of an .eaf file (already read by \code{readLines}), 
# e.g. from an existing transcript object:
mycontent <- examplecorpus@transcripts[['SYNC_rotar_y_flexionar']]@file.content
t <- act::import_eaf(fileContent=mycontent, transcriptName="test")
t

Description

Advice: In most situations it is more convenient to use act::corpus_new, act::corpus_import for importing annotation files.

Usage

import_exb(filePath = NULL, fileContent = NULL, transcriptName = NULL)

Arguments

Details

Imports the contents of a 'EXMARaLDA' .exb file and returns a transcript object. The source is either the path to a .exb file or the contents of a .exb file obtained from the @file.content of an existing transcript object. If you pass 'fileContent' you need to pass 'transcriptName' as parameter, too.

Please note:

• 'EXMARaLDA' allows for empty time slots without a time values. Missing values will be interpolated during the import. You will not be able to recognize interpolated values in the data.

• Meta data for tiers (such as the display name etc.) will not be imported.

• Media files are referenced not by their path but only as file names in .exb files. The names will be imported but will not work as paths in act.

Value

Transcript object.

See Also

corpus_import, corpus_new, import, import_eaf, import_rpraat, import_textgrid

Examples

library(act)

## Not run: 
	# To import a .TextGrid file of your choice:
	filePath <- "PATH_TO_AN_EXISTING_TEXTGRID_ON_YOUR_COMPUTER"
	
	t <- act::import_exb(filePath=filePath)
	t

## End(Not run)

Description

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

Usage

import_rpraat(rpraatTextgrid, transcriptName = NULL)

Arguments

Details

Please note:

• Time values of annotations in TextGrids may be below 0 seconds. Negative time values will be recognized corretly in the first place. When exporting transcript object to other formats like 'ELAN' .eaf, 'EXMARaLDA' .exb ect. annotations that are completely before 0 sec will be deleted, annotations that start before but end after 0 sec will be truncated. Please see also the function act::transcripts_cure_single.

• TextGrids and contained tiers may start and end at different times. These times do not need to match each other. The act package does not support start and end times of TextGrids and tiers and will. The default start of a TextGrid will be 0 seconds or the lowest value in case that annotations start below 0 seconds.

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

Value

Transcript object.

See Also

corpus_import, corpus_new, import, import_eaf, import_exb, import_textgrid, export_rpraat

Examples

library(act)

# Path to the .TextGrid file that you want to read
path <- system.file("extdata", "examplecorpus", "GAT", 
					"ARG_I_PAR_Beto.TextGrid", package="act")

# To import a .TextGrid file of your choice:
## Not run: 
	path <- "PATH_TO_AN_EXISTING_TEXTGRID_ON_YOUR_COMPUTER"

## End(Not run)

# Make sure to have rPraat installed before you try the following
## Not run: 
	# Read TextGrid file with rPraat
	rPraat.tg <- rPraat::tg.read(path)

	# Convert to an act transcript
	t <- act::import_rpraat(rPraat.tg)
	
	# Change the name and add it to the examplecorpus
	t@name <-"rpraat"
	newcorpus <- act::transcripts_add(examplecorpus, t)
	
	# Have a look
	newcorpus@transcripts[["rpraat"]]
	
	# Alternatively, you can use the general import function
	t <- act::import(rPraat.tg)

## End(Not run)

Description

Advice: In most situations it is more convenient to use act::corpus_new, act::corpus_import for importing annotation files.

Usage

import_srt(filePath, transcriptName = NULL, tierName = "subtitle")

Arguments

Value

Transcript object.

See Also

corpus_import, corpus_new, import, import_eaf, import_exb, import_textgrid, import_rpraat

Examples

library(act)

# Path to the .TextGrid file that you want to read
path <- system.file("extdata", "examplecorpus", "GAT", 
					"ARG_I_PAR_Beto.TextGrid", package="act")

# To import a .TextGrid file of your choice:
## Not run: 
	path <- "PATH_TO_AN_EXISTING_TEXTGRID_ON_YOUR_COMPUTER"

## End(Not run)

# Make sure to have rPraat installed before you try the following
## Not run: 
	# Read TextGrid file with rPraat
	rPraat.tg <- rPraat::tg.read(path)

	# Convert to an act transcript
	t <- act::import_rpraat(rPraat.tg)
	
	# Change the name and add it to the examplecorpus
	t@name <-"rpraat"
	newcorpus <- act::transcripts_add(examplecorpus, t)
	
	# Have a look
	newcorpus@transcripts[["rpraat"]]
	
	# Alternatively, you can use the general import function
	t <- act::import(rPraat.tg)

## End(Not run)

Description

Advice: In most situations it is more convenient to use act::corpus_new, act::corpus_import for importing annotation files.

Usage

import_textgrid(filePath = NULL, fileContent = NULL, transcriptName = NULL)

Arguments

Details

Imports the contents of a 'Praat' .TextGrid file and returns a transcript object. The source is either the path to a .TextGrid file or the contents of a .TextGrid file obtained from the @file.content of an existing transcript object by readLines(). If you pass 'fileContent' you need to pass 'transcriptName' as parameter, too.

Please note:

• Time values of annotations in TextGrids may be below 0 seconds. Negative time values will be recognized corretly in the first place. When exporting transcript object to other formats like 'ELAN' .eaf, 'EXMARaLDA' .exb ect. annotations that are completely before 0 sec will be deleted, annotations that start before but end after 0 sec will be truncated. Please see also the function act::transcripts_cure_single.

• TextGrids and contained tiers may start and end at different times. These times do not need to match each other. The act package does not support start and end times of TextGrids and tiers and will. The default start of a TextGrid will be 0 seconds or the lowest value in case that annotations start below 0 seconds.

Value

Transcript object.

See Also

corpus_import, corpus_new, import, import_eaf, import_exb, import_rpraat

Examples

library(act)

# Path to the .TextGrid file that you want to read
path <- system.file("extdata", "examplecorpus", "GAT", 
					"ARG_I_PAR_Beto.TextGrid", package="act")

# To import a .TextGrid file of your choice:
## Not run: 
path <- "PATH_TO_AN_EXISTING_TEXTGRID_ON_YOUR_COMPUTER"

## End(Not run)


t <- act::import_textgrid(filePath=path)
t


# Content of a .TextGrid (already read by \code{readLines}), 
# e.g. from an existing transcript object:
mycontent <- examplecorpus@transcripts[[1]]@file.content
t <- act::import_textgrid(fileContent=mycontent, transcriptName="test")
t

Description

Gives detailed information about the contents of a corpus object or a transcript object that is passed as parameter to the function. In the case that you want to pass a transcript object form a corpus object, make sure that you access the transcript using double [[]] brackets.

Usage

info(...)

Arguments

Details

To get summarized information about the transcript and corpus objects use act::info_summarized.

Value

List.

See Also

info_summarized

Examples

library(act)

act::info(examplecorpus)

act::info(examplecorpus@transcripts[[1]])

Description

Gives summarized information about the contents of a corpus object or a transcript object that is passed as parameter to the function. In the case that you want to pass a transcript object form a corpus object, make sure that you access the transcript using double [[]] brackets.

Usage

info_summarized(...)

Arguments

Details

To get more detailed information about the tiers in a corpus object use act::info.

Value

List.

See Also

info

Examples

library(act)

act::info_summarized(examplecorpus)

act::info_summarized(examplecorpus@transcripts[[1]])

Description

You can create an new layout object with methods::new("layout"). This will give you a new layout object with the default settings uses by act. If you want to modify the layout of the print transcripts, create a new layout object with mylayout <- methods::new("layout"), modify the values in the @slots and pass it as argument l to the respective functions.

Slots

name

Character string; Name of the layout.

filter.tier.includeRegEx

Character string; as regular expression, tiers matching the expression will be included in the print transcript.

filter.tier.excludeRegEx

Character string; as regular expression, tiers matching the expression will be excluded from the print transcript.

transcript.width

Integer; width of transcript, -1 for no line wrapping.

speaker.regex

Character string; Regular expression to extract speaker abbreviation from tier name

speaker.width

Integer; maximum width of speaker abbreviation, -1 for full name without shortening.

speaker.ending

Character string; string that is added at the end of the speaker name.

spacesbefore

Integer; number of spaces inserted before line number.

brackets.align

Logical; if TRUE act will try to align brackets [] for parallel speaking (Attention: experimental function; results may not satisfy).

header.insert

Logical; if TRUE a transcript header is inserted.

arrow.insert

Logical; is only used when transcripts are made based on a search results; if TRUE an arrow will be inserted, highlighting the transcript line containing the search hit.

arrow.shape

Character string; shape of the arrow.

docx.template.path

Character string;

docx.styles

Data.frame; Matrix with mappings of act variables and the format templates in the .docx template files. To change the styles matrix use [email protected] <- act::export_docx_styles_load(path="...")

See Also

act::matrix_load

Description

This function is only for checking how the normalization matrix will be loaded internally.

Usage

matrix_load(path = NULL, encoding = "UTF-8")

Arguments

Value

Data.frame

Examples

library(act)

# An example replacement matrix comes with the package.
path <- system.file("extdata", "normalization", "normalizationMatrix.csv", package="act")

# Load the matrix
mymatrix <- act::matrix_load(path)

# Have a look at the matrix
colnames(mymatrix)
mymatrix

#the original path of the matrix is stored in the attributes
attr(mymatrix, 'path')

Description

Save replacement matrix

Usage

matrix_save(replacementMatrix, path, encoding = "UTF-8")

Arguments

Value

nothing

Examples

library(act)

# An example replacement matrix comes with the package.
path <- system.file("extdata", "normalization", "normalizationMatrix.csv", package="act")

# Load the matrix
mymatrix <- act::matrix_load(path)

# ' # Create temporary file path
path <- tempfile(pattern = "mymatrix", tmpdir=tempdir(),  fileext = ".csv")

# 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",
                  "mymatrix.csv")

## End(Not run)

# Save the matrix
act::matrix_save(mymatrix, path=path)

Description

Searches for media files in folders and assigns the links to transcript objects in a corpus. The function uses the name of the transcript to find the media files, e.g. the function assumes that the annotation files have the same name as the media files, except from the suffix/the file type.

Usage

media_assign(
  x,
  searchPaths = NULL,
  searchSubfolders = TRUE,
  filterFile = "",
  namesExtractPattern = "",
  transcriptNames = NULL,
  deleteExistingMedia = TRUE,
  onlyUniqueFiles = TRUE,
  audioAsFallback = TRUE
)

Arguments

Details

Only the the file types set in options()$act.fileformats.audio and options()$act.fileformats.video will be recognized. You can modify these options to recognize other media types.

Value

Corpus object.

See Also

media_delete, media_path_to_existing_file

Examples

library(act)

# Set the folder(s) where your media files are located in the corpus object
# Please be aware that that the example corpus that comes with the package
# does NOT contain media files. Please download the entire example corpus
# with media files if you want to use this function reasonably.
examplecorpus@paths.media.files <- c("", "")

examplecorpus <- act::media_assign(examplecorpus)

Description

Delete media files links from transcript objects

Usage

media_delete(x, transcriptNames = NULL)

Arguments

Value

Corpus object.

See Also

media_assign, media_path_to_existing_file

Examples

library(act)

examplecorpus <- act::media_delete(examplecorpus)

Description

Format the names attribute of the media paths. Relevant for media cuts with search_cuts. Names attribute can be used to differentiate multiple cuts with of the same media type (e.g. mp4 from different cameras).

Usage

media_format_names(
  x,
  recreateNames = TRUE,
  pattern,
  replacement = NULL,
  conditionalPreserve = FALSE
)

Arguments

Value

Corpus object.

See Also

media_assign, media_delete, search_cuts, \

Examples

library(act)

# Set the folder(s) where your media files are located in the corpus object
# Please be aware that that the example corpus that comes with the package
# does NOT contain media files. Please download the entire example corpus
# with media files if you want to use this function reasonably.
examplecorpus@paths.media.files <- c("", "")

examplecorpus <- act::media_assign(examplecorpus)

Description

Gets the path of a media file for a transcript

Usage

media_path_to_existing_file(
  t,
  filterMediaFile = c(".*\\.(mp4|mov)", ".*\\.(aiff|aif|wav)", ".*\\.mp3")
)

Arguments

Value

Character string; path to a media file, or NULL if no existing media file has been found.

See Also

media_assign, media_delete

Examples

library(act)

# Please be aware that that the example corpus that comes with the package
# does NOT contain media files. Please download the entire example corpus
# with media files if you want to use this function reasonably.

# You can access the media files linked to a transcript directly using
# the object properties.
examplecorpus@transcripts[["SYNC_rotar_y_flexionar"]]@media.path

# Get only media files of a certain type, e.g. a wav file, and return only the first match:
act::media_path_to_existing_file(examplecorpus@transcripts[["SYNC_rotar_y_flexionar"]],
 filterMediaFile=".*\\.wav")

Description

Loads all .docx files in a folder and merges them to a singe .docx file.

Usage

merge_docx(folderInput, pathTemplateInput, pathOutput = NULL, recursive = TRUE)

Arguments

Value

merged .docx in officeR format,

See Also

export_docx

Description

delete all options set by the package from R options

Usage

options_delete()

Examples

library(act)
act::options_delete()

Description

Reset options to default values

Usage

options_reset()

Examples

library(act)
act::options_reset()

Description

The package has numerous options that change the internal workings of the package.

Usage

options_show()

Details

There are several options that change the way the package works. They are set globally.

• Use options(name.of.option = value) to set an option.

• Use options()$name.of.option to get the current value of an option.

• Use act::options_reset to set all options to the default value.

• Use act::options_delete to clean up and delete all option settings.

The package uses the following options.

Program

• act.excamplecorpusURL character strings; where to download example media files.

• act.updateX Logical; If TRUE the original corpus object 'x' passed passed to the search functions search_new and search_run will also be updated, in case that during the search fulltexts are created or the normalization is performed.

• act.showprogress logical; if TRUE a progress bar will be shown during (possibly) time consuming operations.

Paths

• act.path.praat Character string; path to the 'Praat' executable on your computer. Only necessary if you use the functions to remote control Praat using Praat scripts.

• act.path.sendpraat Character string; path to the 'sendpraat' executable on your computer. Only necessary if you use the functions to remote control Praat using Praat scripts.

• act.path.elan Character string; path to the 'ELAN' executable on your computer. Only necessary if you want to open search results in ELAN.

File formats

• act.fileformats.video Vector of character strings; Suffixes of video files that will be identified; default is 'c("mp4", "mov")'.

• act.fileformats.audio Vector of character strings; Suffixes of audio files that will be identified; default is 'c("wav", "aif", "mp3")'.

FFMPEG commands and options

• act.ffmpeg.command.main Character string; 'FFmpeg' command that is used for cutting media files (audio & video).

• act.ffmpeg.command.main.fast Character string; 'FFmpeg' command that is used for cutting video files using the 'FFmpeg' option 'fast video positioning'. This is considerably faster when working with long video files.

• act.ffmpeg.command.audioAsMP3 Character string; 'FFmpeg' command that is used for cutting/generating compressed audio files as mp3 (for other audio, the main command is used).

• act.ffmpeg.command.images Character string; 'FFmpeg' command that is used for extracting still images.

• act.ffmpeg.command.images.fast Character string; 'FFmpeg' command that is used for extracting still images using the 'FFmpeg' option 'fast video positioning'. This is considerably faster when working with long video files.

• act.ffmpeg.exportchannels.fromColumnName Character string; Name of the column in the data frame s@results from information, which audio channel to export, will be taken.

Import annotation files

• act.import.readEmptyIntervals Logical; if TRUE empty intervals in you annotation files will be read, if FALSE empty intervals will be skipped.

• act.import.scanSubfolders Logical; if TRUE sub folders will also be scanned for annotation files; if FALSE only the main level of the folders specified in pathsAnnotationFiles of your corpus object will be scanned.

• act.import.storefileContentInTranscript if TRUE the contents of the original annotation file will be stored in [email protected]. Set to FALSE if you want to keep your corpus object small.

Export

• act.export.filename.fromColumnName Character string; Name of the column from which the file names for exported files will be taken.

• act.export.folder.grouping1.fromColumnName Character string; Name of sub folders that will be created in the folder of the search result, level 1.

• act.export.folder.grouping2.fromColumnName Character string; Name of sub folders that will be created in the folder of the search result, level 2.

Miscellaneous

• act.separator_between_intervals Character; Single character that is used for separating intervals when creating the full text.

• act.separator_between_tiers Character; Single character that is used for separating tiers when creating the full text.

• act.separator_between_words Character string; regular expression with alternatives that count as separators between words. Used for preparing the concordance.

• act.wordCountRegEx Character string; regular expression that is used to count words.

• act.pauseIdentifierGATRegEx Character string; regular expression that is used to identify pauses in GAT transcription

Value

Nothing.

Examples

library(act)
## Not run: 
act::options_show()

## End(Not run)

Description

Make concordance for search results

Usage

search_concordance(x, s, searchNormalized = TRUE)

Arguments

Value

Search object.

Examples

library(act)

# Search for the 1. Person Singular Pronoun in Spanish
# Search without creating the concordance immediately.
# This is for example useful if you are working with a large corpus, since
# making the concordance may take a while.
mysearch <- act::search_new(examplecorpus, pattern="yo", concordanceMake=FALSE)
mysearch@results[1,]


# The results do not contain the concordance, it is only 15 columns
ncol(mysearch@results)

# Make the concordance
mysearch.new <- act::search_concordance(x=examplecorpus, s=mysearch)
ncol(mysearch.new@results)

Description

This function will call the following functions:

• act_cuts_printtranscript to create print transcripts,

• act::cuts_media to create FFmpeg cutlist to make media snippets,

• act::search_cuts_srt() to create .srt subtitles, for all search results.

For a detailed description including examples please refer to the documentation of the indidival functions. They also offer some more parameters than this functions. If you want to use those, call the functions individually.

Usage

search_cuts(
  x,
  s,
  cutSpanBeforesec = NULL,
  cutSpanAftersec = NULL,
  l = NULL,
  folderOutput = NULL
)

Arguments

Value

Search object;

Examples

library(act)

# IMPORTANT: In the example corpus all transcripts are assigned media links.
# The actual media files are, however, not included in when installing the package 
# due to size limitations of CRAN.
# But you may download the media files separately.
# Please see the section 'examplecorpus' for instructions. 
# --> You will need the media files to execute the following example code.

## Not run: 
	# Search
	mysearch <- act::search_new(examplecorpus, pattern="yo")
	
	# Create print transcripts, media cutlists and .srt subtitles 
	# for all search results
	test <- act::search_cuts(x=examplecorpus, s=mysearch)
	
	# Display all print transcripts on screen from @cuts.printtranscripts
	cat(test@cuts.printtranscripts)
	
	# Display cutlist on screen from @cuts.cutlist.mac
	cat(test@cuts.cutlist.mac)
	
	# Display .srt subtitles
	cat(test@results[, mysearch@cuts.column.srt])

## End(Not run)

Description

This function creates FFmpeg commands to cut media files for each search results. If you want to execute the commands (and cut the media files) you need to have FFmpeg installed on you computer. To install FFmpeg you can follow the instructions given in the vignette 'installation-ffmpeg'. Show the vignette with vignette("installation-ffmpeg").

Usage

search_cuts_media(
  x,
  s,
  exportMedia = TRUE,
  exportStills = TRUE,
  exportThumbnail = TRUE,
  cutSpanBeforesec = NULL,
  cutSpanAftersec = NULL,
  folderOutput = NULL,
  filterMediaInclude = "",
  videoFastPositioning = TRUE,
  videoCodecCopy = FALSE,
  audioAsMP3 = FALSE,
  panning = NULL,
  outputOS = c("mac", "win"),
  outputFileName = "FFMPEG_cutlist"
)

Arguments

Details

Cut lists
The commands are collected in cut lists. The cut lists will be stored in different ways:

• A cut list for for ALL search results will be stored in [email protected] to be used on MacOS and [email protected] to be used on Windows.

• Individual cut lists for EACH search result will be stored in additional columns in the data frame s@results. The cut lists that can be executed in the Terminal (Apple) or the Command Line Interface (Windows).

Input media files
The function will use all files in corpus@transcripts[[ ]]@media.path. Therefore you will need to set the options filterMediaInclude filtering for which input media files you want to create the cuts. The filter is a regular expression, e.g. '\.(wav|aif)' for '.wav' and '.aif' audio files or '\.mp4' for '.mp4' video files.

Output file names
The file names of the cuts are taken from the resultID column in the search results table. To change this, modify the contents of this column or define a different column using options(act.export.filename.fromColumnName. By default, the name of the original media will be appended to the file name. The name of the media file will be taken from the names() attribute of each media file listed in the corpus@transcripts[]@media.path. To change this, modify the names()attribute.

Output format
The output format is predefined by in the options:

• act.ffmpeg.command.main: defines the basic FFmpeg command (used for audio & video)

• act.ffmpeg.command.main.fast: defines the FFmpeg command to be used with large video files.

• act.ffmpeg.command.audioAsMP3: defines the FFmpeg used for converting audio files to MP3

• act.ffmpeg.command.images. Defines the FFmpeg command used for extracting still images.

For video, the default is to generate mp4 cuts. You can also use the following commands to change the output format:

MP4 video cuts with original video quality:

• options(act.ffmpeg.command.main = 'ffmpeg -i "INFILEPATH" -ss TIMESTART -t TIMEDURATION OPTIONS -y "OUTFILEPATH.mp4" -hide_banner')

• options(act.ffmpeg.command.main.fast = 'ffmpeg -ss TIMESTARTMINUS10SECONDS -i "INFILEPATH" -ss 10.000 -t TIMEDURATION OPTIONS -y "OUTFILEPATH.mp4" -hide_banner')

MP4 video cuts with reduced video quality:

• options(act.ffmpeg.command.main = 'ffmpeg -i "INFILEPATH" -ss TIMESTART -t TIMEDURATION OPTIONS -vf scale=1920:-1 -b:v 1M -b:a 192k -y "OUTFILEPATH.mp4" -hide_banner')

• options(act.ffmpeg.command.main.fast = 'ffmpeg -ss TIMESTARTMINUS10SECONDS -i "INFILEPATH" -ss 10.000 -t TIMEDURATION OPTIONS -vf scale=1920:-1 -b:v 6M -b:a 192k -y "OUTFILEPATH.mp4" -hide_banner')

Extract stills
To extract stills the time information and the file names need to be stored in the search object in the results data frame, e.g. in s@results. The information needs to be contained in a vector. The elements of the vector are the time values in seconds, the name attribute will be used as file name, e.g. myStills <- c(still1=1.0, still2=2.0). The vector needs stored for each search result in the column called stills.values as a list, e.g code s@results$stills.values[[1]] <- myStills. Stills will be stored in a sub folder called stills by default, if not otherwise defined in the column stills.folder. Please see the section options_show to customize the behavior of the function.

Advanced options
You can adjust the FFmpeg commands according to your needs. The following options define the FFmpeg command that will be used by the package. The command needs to contain place holders which will be replaced by the actual values in the package. If you want to define your own ffmpeg command, please make sure to use the following placeholders:

• INfilePath path to the input media file.

• OUTFILEPATH path where the output media file will be saved

• OPTIONS FFmpeg options that will be applied additionally, in particular fast video positioning.

• TIMESTART time in seconds where to begin the cutting

• TIMESTARTMINUS10SECONDS time in seconds where to begin the cutting, in case that fast video positioning is being used.

• TIMEDURATION duration of cuts.

Value

Search object; cut lists will be stored in [email protected] and [email protected].

See Also

search_cuts_media,

Examples

library(act)

# IMPORTANT: In the example corpus all transcripts are assigned media links.
# The actual media files are, however, not included in when installing the package 
# due to size limitations of CRAN.
# But you may download the media files separately.
# Please see the section 'examplecorpus' for instructions. 
# --> You will need the media files to execute the following example code.

## Not run: 
	# Search
	mysearch <- act::search_new(examplecorpus, pattern="yo")
	
	# Create cut lists 
	mysearch <- act::search_cuts_media (x=examplecorpus, s=mysearch)
	
	# Check results for Mac:
	# Get entire cut list for Mac and display on screen, 
	# so you can copy&paste this into the Terminal
	mycutlist <- mysearch@cuts.cutlist.mac 
	cat(mycutlist)
	# Cut list for first search result
	mycutlist <- mysearch@results$cuts.cutlist.mac[[1]]
	cat(mycutlist)
	
	# Check results for Windows:
	# Get entire cut list for Mac and display on screen, 
	# so you can copy&paste this into the CLI
	mycutlist <- mysearch@cuts.cutlist.win 
	cat(mycutlist)
	# Cut list for first search result
	mycutlist <- mysearch@results$cuts.cutlist.win[[1]]
	cat(mycutlist)
	
	# It is, however, more convenient to specify the argument 'folderOutput' in order to get
	# the cut list as a (executable) file/batch list.

## End(Not run)

Description

Print transcripts in the style of conversation analysis will be created for each search result. The transcripts will be inserted into the column defined in [email protected]. All transcripts will be stored in [email protected].

Usage

search_cuts_printtranscript(
  x,
  s,
  l = NULL,
  exportTxt = TRUE,
  exportDocx = TRUE,
  headerInsertSource = TRUE,
  cutSpanBeforesec = 0,
  cutSpanAftersec = 0,
  folderOutput = NULL
)

Arguments

Details

If you want to modify the layout of the print transcripts, create a new layout object with mylayout <- methods::new("layout"), modify the settings and pass it as argument l.

Value

Search object;

Examples

library(act)

# Search
mysearch <- act::search_new(examplecorpus, pattern="yo")

# Create print transcripts for all search results
test <- act::search_cuts_printtranscript (x=examplecorpus, s=mysearch)

# Display all print transcripts on screen from @cuts.printtranscripts
cat(test@cuts.printtranscripts)

# Display all print transcripts from results data frame
cat(test@results[,mysearch@cuts.column.printtranscript])
cat(test@results[,mysearch@cuts.column.printtranscript])

# Only single print transcript from results data frame
cat(test@results[1,mysearch@cuts.column.printtranscript])

# Create print transcript snippets including 1 sec before and 5 sec after
mysearch@cuts.span.beforesec =1
mysearch@cuts.span.aftersec = 5
test <- act::search_cuts_printtranscript (x=examplecorpus,
s=mysearch)

# Display all transcript snippets on screen
cat(test@results[,mysearch@cuts.column.printtranscript])

Description

Subtitles in 'Subrib Title' .srt format will be created for each search result. The subtitles will be inserted into the column defined in [email protected].

Usage

search_cuts_srt(
  x,
  s,
  cutSpanBeforesec = NULL,
  cutSpanAftersec = NULL,
  folderOutput = NULL,
  speakerShow = TRUE,
  speakerWidth = 3,
  speakerEnding = ":"
)

Arguments

Details

Span
If you want to extend the cut before or after each search result, you can modify @cuts.span.beforesec and @cuts.span.aftersec in your search object. If you want to modify the layout of the print transcripts, create a new layout object with mylayout <- methods::new("layout"), modify the settings and pass it as argument l.

Value

Search object;

Examples

library(act)

# Search
mysearch <- act::search_new(examplecorpus, pattern="yo")

# Create srt subtitles for all search results
test <- act::search_cuts_srt (x=examplecorpus, s=mysearch)

# Display srt subtitle of first three results
cat(test@results[1:3, mysearch@cuts.column.srt])

# Create srt subtitle including 1 sec before and 5 sec after
mysearch@cuts.span.beforesec = 1
mysearch@cuts.span.aftersec = 5
test <- act::search_cuts_srt (x=examplecorpus,
								s=mysearch)

# Display srt subtitle of first  results
cat(test@results[1,mysearch@cuts.column.srt])

Description

Search a corpus object and return the names of all transcripts and tiers that match the given parameters. You can define parameters to include and/or exclude transcripts and tiers based on their names. All parameters passed to the function will be combined.

Usage

search_makefilter(
  x,
  filterTranscriptNames = NULL,
  filterTranscriptIncludeRegex = NULL,
  filterTranscriptExcludeRegex = NULL,
  filterTierNames = NULL,
  filterTierIncludeRegex = NULL,
  filterTierExcludeRegex = NULL
)

Arguments

Details

This functions is useful if you want to use functions of the package such as transcripts_update_normalization, transcripts_update_fulltexts, corpus_export and limit them to only some of the transcripts.

Value

List of character vectors. $filterTranscriptNames contains all transcript names in the corpus matching the expressions, $filterTierNames contains all tier names in the corpus matching the expressions.

See Also

search_new, search_run, search_sub

Examples

library(act)

# Search all transcripts that have "ARG" (ignoring case sensitivity) in their name
myfilter <- act::search_makefilter(x=examplecorpus, filterTranscriptIncludeRegex="(?i)arg")
myfilter$transcriptNames

# Search all transcripts that don't have "ARG" in their name
myfilter <- act::search_makefilter(x=examplecorpus, filterTranscriptExcludeRegex="ARG")
myfilter$transcriptNames

# Search all tiers that have an "A" or an "a" in their name
myfilter <- act::search_makefilter(x=examplecorpus, filterTierIncludeRegex="(?i)A")
myfilter$tierNames

# Search all tiers that have a capital "A" in their name
myfilter <- act::search_makefilter(x=examplecorpus, filterTierIncludeRegex="A")
myfilter$tierNames

# In which transcripts do these tiers occur?
myfilter$transcriptNames

# Let's check the first of the transcripts, if this is really the case...
examplecorpus@transcripts[[myfilter$transcriptNames[1]]]@tiers

Description

Creates a new search object and runs the search in a corpus object. Only 'x' and 'pattern' are obligatory. The other arguments can be left to their default values.

Usage

search_new(
  x,
  pattern,
  searchMode = c("content", "fulltext", "fulltext.byTime", "fulltext.byTier"),
  searchNormalized = TRUE,
  name = "mysearch",
  resultidPrefix = "result",
  resultidStart = 1,
  filterTranscriptNames = NULL,
  filterTranscriptIncludeRegex = NULL,
  filterTranscriptExcludeRegex = NULL,
  filterTierNames = NULL,
  filterTierIncludeRegex = NULL,
  filterTierExcludeRegex = NULL,
  filterSectionStartsec = NULL,
  filterSectionEndsec = NULL,
  concordanceMake = TRUE,
  concordanceWidth = NULL,
  cutSpanBeforesec = 0,
  cutSpanAftersec = 0,
  runSearch = TRUE
)

Arguments

Value

Search object.

See Also

search_run, search_makefilter, search_sub

Examples

library(act)

# Search for the 1. Person Singular Pronoun in Spanish.
mysearch <- act::search_new(examplecorpus, pattern= "yo")
mysearch
# Search in normalized content vs. original content
mysearch.norm  <- act::search_new(examplecorpus, pattern="yo", searchNormalized=TRUE)
mysearch.org   <- act::search_new(examplecorpus, pattern="yo", searchNormalized=FALSE)
mysearch.norm@results.nr
mysearch.org@results.nr

# The difference is because during normalization capital letters will be converted
# to small letters. 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

# Search in full text vs. original content.
# Full text search will find matches across annotations.
# Let's define a regular expression with a certain span.
# Search for the word "no" 'no' followed by a "pero" 'but'
# in a distance ranging from 1 to 20 characters.
myRegEx <- "\\bno\\b.{1,20}pero"
mysearch <- act::search_new(examplecorpus, pattern=myRegEx, searchMode="fulltext")
mysearch
mysearch@results$hit

Description

The function creates an temporary .eaf file and a .psfx file that locates the search hit. These files will then be opened in ELAN. To make this function work you need to have 'ELAN' installed on your computer and tell the act package where ELAN is located. Therefore you need to set the path to the ELAN executable in the option 'act.path.elan' using options(act.path.elan='PATHTOYOURELANEXECUTABLE').

Usage

search_openresult_inelan(x, s, resultid, openOriginal = FALSE)

Arguments

Details

WARNING: This function will overwrite existing .psfx files.

Credits: Thanks to Han Sloetjes for feedback on the structure of the temporary .pfsx files. He actually made the code work.

Examples

library(act)

mysearch <- act::search_new(x=examplecorpus, pattern = "yo")

# You can only use this function if you have installed ELAN on our computer.
## Not run: 
options(act.path.elan='PATHTOYOURELANEXECUTABLE')
act::search_openresult_inelan(x=examplecorpus, s=mysearch, resultid=1, TRUE)

## End(Not run)

Description

The function remote controls 'Praat' by using 'sendpraat' and a 'Praat' script. It opens a search result in the 'Praat' TextGrid Editor.

Usage

search_openresult_inpraat(
  x,
  s,
  resultid,
  play = TRUE,
  close = FALSE,
  filterMediaFile = c(".*\\.(aiff|aif|wav)", ".*\\.mp3"),
  delay = 0.5
)

Arguments

Details

To make this function work you need to do two things first:

• Install 'sendpraat' on your computer. To do so follow the instructions in the vignette 'installation-sendpraat'. Show the vignette with vignette("installation-sendpraat").

• Set the path to the 'sendpraat' executable correctly by using 'options(act.path.sendpraat = ...)'.

Examples

library(act)

mysearch <- act::search_new(x=examplecorpus, pattern = "pero")

# You can only use this functions if you have installed and 
# located the 'sendpraat' executable properly in the package options.
## Not run: 
act::search_openresult_inpraat(x=examplecorpus, s=mysearch, resultid=1, TRUE, TRUE)

## End(Not run)

Description

The function remote controls 'Quicktime' by using an Apple Script. It opens a search result in 'Quicktime' and plays it.

Usage

search_openresult_inquicktime(
  x,
  s,
  resultid,
  play = TRUE,
  close = FALSE,
  bringToFront = TRUE,
  filterFile = c(".*\\.(mp4|mov)", ".*\\.(aiff|aif|wav)", ".*\\.mp3")
)

Arguments

Details

Note: You need to be on a Mac to use this function.

Span
If you want to extend the cut before or after each search result, you can modify @cuts.span.beforesec and @cuts.span.aftersec in your search object.

Value

Logical; TRUE if media file has been played, or FALSE if not.

Examples

library(act)

mysearch <- act::search_new(x=examplecorpus, pattern = "pero")

# You can only use this function if you are on a Mac.
# In addition, you need to have downloaded the example media. 
## Not run: 

# Assign media files
examplecorpus@paths.media.files <- c("FOLDERWHEREMEDIAFILESARELOCATED")
examplecorpus <- act::media_assign(examplecorpus)
	
# Play the media for the first search result
act::search_openresult_inquicktime(x=examplecorpus, 
s=mysearch, 
resultid = 1,
play=TRUE,
close=TRUE)

# Play all search results after one another.
	for (i in 1:nrow(mysearch@results)) {
		print(mysearch@results$content[i])
		act::search_openresult_inquicktime(x=examplecorpus, 
s=mysearch, 
resultid = i, 
play=TRUE,
close=TRUE)
	}

## End(Not run)

Description

The function remote controls 'Quicktime' by using an Apple Script. It opens consecutively all search results in 'Quicktime' and plays them.

Usage

search_playresults_inquicktime(x, s, bringToFront = FALSE)

Arguments

Details

Note: You need to be on a Mac to use this function.

Value

No return value.

Examples

library(act)

mysearch <- act::search_new(x=examplecorpus, pattern = "pero")

# You can only use this function if you are on a Mac.
# In addition, you need to have downloaded the example media files. 
## Not run: 
	# Assign media files
	examplecorpus@paths.media.files <- c("FOLDERWHEREMEDIAFILESARELOCATED")
	examplecorpus <- act::media_assign(examplecorpus)
	
	# Create print transcripts. This is not necessary.
	# But its nice to see them when playing all results.
	mysearch <- act::search_cuts_printtranscript (x=examplecorpus, s=mysearch)
	
	# Play all search results
	act::search_playresults_inquicktime(x=examplecorpus, s=mysearch)

## End(Not run)

Description

Search results from a search object will be saved to a Excel-XLSX or a CSV (comma separated values) file. By default a XLSX file will be saved. If you want to save a CSV file, use saveAsCSV=TRUE. Please note:

• The function will '=' signs at the beginning of annotation by ".=". This is because the content would be interpreted as the beginning of a formula (leading to an error).

• In the case of writing to an excel file, line breaks will be replaced by "|". This is because line breaks will lead to an error.

Usage

search_results_export(
  s,
  path,
  sheetName = "data",
  saveAsCSV = FALSE,
  encoding = "UTF-8",
  separator = ";",
  overwrite = TRUE
)

Arguments

Examples

library(act)

# Search
mysearch <- act::search_new(examplecorpus, pattern="yo")
nrow(mysearch@results)

# Create temporary file path
path <- tempfile(pattern = "searchresults", tmpdir = tempdir(),
    			 fileext = ".xlsx")

# It makes more sense, however, to you define a destination folder
# that is easier to access on your computer:
## Not run: 
	path <- tempfile(pattern = "searchresults",
 					 tmpdir = "PATH_TO_AN_EXISTING_FOLDER_ON_YOUR_COMPUTER",
 					 fileext = ".xlsx")

## End(Not run)

# Save search results
act::search_results_export(s=mysearch, path=path)

# Do your coding of the search results somewhere outside of act
# ...

# Load search results
mysearch.import <- act::search_results_import(path=path)
nrow(mysearch.import@results)

Description

Search results will be imported from an Excel '.xlsx' file or a comma separated values '.csv' file into a search object.

Usage

search_results_import(
  path,
  revertReplacements = TRUE,
  sheetName = "data",
  encoding = "UTF-8",
  separator = ";"
)

Arguments

Value

Search object.

Examples

library(act)

# Search
mysearch <- act::search_new(examplecorpus, pattern="yo")
nrow(mysearch@results)

# Create temporary file path
path <- tempfile(pattern = "searchresults", tmpdir = tempdir(),
    			 fileext = ".xlsx")

# It makes more sense, however, to you define a destination folder
# that is easier to access on your computer:
## Not run: 
	path <- tempfile(pattern = "searchresults",
 					 tmpdir = "PATH_TO_AN_EXISTING_FOLDER_ON_YOUR_COMPUTER",
 					 fileext = ".xlsx")

## End(Not run)

# Save search results
act::search_results_export(s=mysearch, path=path)

# Do your coding of the search results somewhere outside of act
# ...

# Load search results
mysearch.import <- act::search_results_import(path=path)
nrow(mysearch.import@results)