--- title: "Praat Interpreter: Variables and Expressions" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Praat Interpreter: Variables and Expressions} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) ``` ```{r setup} library(pladdrr) ``` ## Introduction The `pladdrr` package provides complete access to Praat's interpreter system, enabling you to: - Evaluate Praat expressions directly from R - Manage persistent variables across expressions - Work with all 5 Praat variable types (numeric, string, vector, matrix, string array) - Query the global Praat object list This vignette demonstrates how to use the interpreter for computational tasks without requiring Praat scripts. ## Standalone Expression Evaluation The simplest way to use the interpreter is through standalone expression evaluation functions. These create temporary interpreters and return results immediately. ### Numeric Expressions ```{r numeric-expressions} # Basic arithmetic praat_eval_numeric("2 + 2") praat_eval_numeric("sqrt(16) + 2^3") # Trigonometric functions praat_eval_numeric("sin(pi/2)") praat_eval_numeric("cos(0)") # Complex calculations praat_eval_numeric("log10(1000)") ``` ### String Expressions ```{r string-expressions} # String concatenation praat_eval_string('"Hello" + " " + "World"') # String functions praat_eval_string('left$("testing", 4)') praat_eval_string("string$(42)") ``` ### Vector Expressions ```{r vector-expressions} # Create vectors vec <- praat_eval_vector("{ 1, 2, 3, 4, 5 }") vec # Vector with decimals vec2 <- praat_eval_vector("{ 1.1, 2.2, 3.3 }") vec2 ``` ### Matrix Expressions ```{r matrix-expressions} # Create 2x2 matrix mat <- praat_eval_matrix("{{ 1, 2 }, { 3, 4 }}") mat # Matrix dimensions are preserved dim(mat) ``` ### String Array Expressions ```{r string-array-expressions} # Create string arrays names <- praat_eval_string_array('{ "Alice", "Bob", "Charlie" }') names ``` ## Persistent Interpreter with State For more complex workflows, use the `PraatInterpreter` R6 class which maintains state between operations. ### Creating an Interpreter ```{r create-interpreter} # Create a persistent interpreter instance interp <- PraatInterpreter$new() ``` ### Setting Variables The interpreter automatically detects variable types and adds appropriate Praat suffixes: ```{r set-variables} # Numeric variables (no suffix) interp$set_variable("x", 42) interp$set_variable("pi_value", 3.14159) # String variables ($ suffix auto-added) interp$set_variable("name", "John") interp$set_variable("greeting", "Hello") # Vector variables (# suffix auto-added) interp$set_variable("data", c(1.5, 2.5, 3.5, 4.5)) # Matrix variables (## suffix auto-added) interp$set_variable("matrix", matrix(1:6, nrow = 2, ncol = 3)) # String array variables ($# suffix auto-added) interp$set_variable("names", c("alpha", "beta", "gamma")) ``` ### Getting Variables Retrieve variables using Praat suffix notation: ```{r get-variables} # Get numeric variable interp$get_variable("x") # Get string variable (must include $ suffix) interp$get_variable("name$") # Get vector (# suffix) interp$get_variable("data#") # Get matrix (## suffix) interp$get_variable("matrix##") # Get string array ($# suffix) interp$get_variable("names$#") ``` ### Using Variables in Expressions Variables can be used directly in expressions: ```{r variables-in-expressions} # Set some variables interp$set_variable("a", 10) interp$set_variable("b", 20) # Use in arithmetic result <- interp$eval("a + b") result result <- interp$eval("a * b") result # String operations with variables interp$set_variable("first", "hello") interp$set_variable("second", "world") result <- interp$eval('first$ + " " + second$') result ``` ### Vector and Matrix Operations ```{r vector-matrix-ops} # Create a vector interp$set_variable("vec", c(1, 2, 3, 4, 5)) # Get vector size size <- interp$eval("size(vec#)") size # Sum vector total <- interp$eval("sum(vec#)") total # Mean of vector mean_val <- interp$eval("mean(vec#)") mean_val # Create a matrix interp$set_variable("mat", matrix(1:4, nrow = 2, ncol = 2)) # Query matrix dimensions rows <- interp$eval("numberOfRows(mat##)") cols <- interp$eval("numberOfColumns(mat##)") c(rows = rows, cols = cols) ``` ## Praat Variable Type Reference Praat uses suffix notation to distinguish variable types: | R Type | Praat Suffix | Example Variable | Set | Get | |--------|--------------|------------------|-----|-----| | Numeric scalar | (none) | `x` | `set_variable("x", 42)` | `get_variable("x")` | | String | `$` | `name$` | `set_variable("name", "test")` | `get_variable("name$")` | | Numeric vector | `#` | `data#` | `set_variable("data", c(1,2,3))` | `get_variable("data#")` | | Numeric matrix | `##` | `mat##` | `set_variable("mat", matrix(...))` | `get_variable("mat##")` | | String array | `$#` | `names$#` | `set_variable("names", c("a","b"))` | `get_variable("names$#")` | **Key Points:** - When **setting** variables, omit the suffix - it's added automatically - When **getting** variables, include the appropriate suffix - Use variables **in expressions** with their full suffix notation ## Object Management Query Praat's global object list (useful when objects are created through other means): ```{r object-management} # Get count of objects count <- praat_object_count() count # List all objects (returns data frame) objects <- praat_list_objects() objects # Also available via R6 instance count2 <- interp$object_count() objects2 <- interp$list_objects() ``` **Note:** In library mode (without GUI), object creation commands like `Create Sound...` are not available. The object management functions are ready for use when GUI actions are enabled or when working with objects created through pladdrr's direct API (e.g., `sound_load()`, `pitch_create()`, etc.). ## Practical Example: Statistical Calculations ```{r practical-example} # Create an interpreter for a statistical workflow stats <- PraatInterpreter$new() # Set up data stats$set_variable("values", c(12.5, 15.3, 11.8, 14.2, 13.7, 16.1)) # Calculate statistics using Praat functions n <- stats$eval("size(values#)") mean_val <- stats$eval("mean(values#)") stdev <- stats$eval("stdev(values#)") # Results cat("Sample size:", n, "\n") cat("Mean:", mean_val, "\n") cat("Std Dev:", stdev, "\n") # Calculate z-scores manually stats$set_variable("mean", mean_val) stats$set_variable("sd", stdev) # For each value, could calculate (x - mean) / sd # This demonstrates variable persistence across multiple operations ``` ## Performance Considerations - **Standalone functions** (`praat_eval_*`) create temporary interpreters - use for one-off calculations - **Persistent interpreters** (`PraatInterpreter$new()`) reuse state - use for workflows with multiple related operations - **Variable overhead** is minimal - **Type conversion** between R and Praat is automatic and efficient ## Best Practices 1. **Use persistent interpreters for workflows**: When you need multiple related calculations, create one interpreter instance and reuse it 2. **Name variables clearly**: Since Praat and R variables are separate, use descriptive names to avoid confusion 3. **Remember suffix notation**: When getting variables or using them in expressions, always include the appropriate suffix 4. **Leverage type auto-detection**: Let `set_variable()` automatically determine the correct Praat type from your R object 5. **Check object types**: Use `class()`, `dim()`, etc. to verify R objects before setting as Praat variables ## Summary The Praat interpreter integration provides: - Access to Praat's expression evaluation - All 5 variable types (numeric, string, vector, matrix, string array) - Persistent state management via `PraatInterpreter` - Automatic type detection and conversion between R and Praat - Object list queries - R6 and standalone functional APIs The interpreter can be combined with pladdrr's other API functions for phonetic analysis workflows. ## See Also - `vignette("getting-started")` - Introduction to pladdrr - `vignette("formant-analysis")` - Formant extraction workflows - `?PraatInterpreter` - R6 class documentation - `?praat_eval_numeric` - Expression evaluation functions