ByronAhn/PoLaR-Praat-plugin

PoLaR plugin for Praat

README last updated: 2023/11/20

In the documentation below, all text preceded by ⏵ can be clicked to reveal more text.

Installation of the plugin

Click for installation instructions…

1. **Download the plugin\_PoLaR.zip file** * Get the **zip file ([plugin_PoLaR.zip](https://github.com/ByronAhn/PoLaR-Praat-plugin/blob/main/plugin_PoLaR.zip?raw=true))** from GitHub by clicking [here](https://github.com/ByronAhn/PoLaR-Praat-plugin/blob/main/plugin_PoLaR.zip?raw=true) * Unzip the file, and you should find a new folder `plugin_PoLaR` - We will move this folder shortly 2. **Navigate to your “Praat preferences” directory** * On Windows, if your username is xxyyzz, your “Praat preferences” directory is: `C:\Users\xxyyzz\Praat\` * On Linux, your “Praat preferences” directory is in your home directory, namely at: `~/.praat-dir/` * On a Mac, your “Praat preferences” directory is in your user Library folder, more specifically at: `~/Library/Preferences/Praat Prefs/` - **NOTE:** On a Mac, this folder is in a hidden directory. To get there, use the “Go To Folder” functionality Finder by opening up a Finder window, and hitting `[SHIFT]+[CMD]+G`. - (_more details on [this page of the Apple support site](https://support.apple.com/en-gw/guide/mac-help/mchlp1236/mac)_) * In all cases, if you do not see your directory there, you may need to create it. - (_If you have trouble, navigate to [this page on the Praat manual](https://www.fon.hum.uva.nl/praat/manual/preferences_folder.html), where finding this directory is described in a different way_) 3. **Move the unzipped `plugin_PoLaR` to this directory** * Take the `plugin_PoLaR` folder that you unzipped and move it to Praat preferences directory * This `plugin_PoLaR` folder _**must**_ be found _**immediately**_ inside the “Praat preferences” directory - i.e., on Windows, `C:\Users\xxyyzz\Praat\plugin_PoLaR\` - i.e., on Linux, `~/.praat-dir/plugin_PoLaR/` - i.e., on a Mac, `~/Library/Preferences/Praat Prefs/plugin_PoLaR/` 4. **Double check location of files** * Importantly: the `setup.praat` file must be found just inside this `plugin_Praat` directory, **_WITHOUT_** any extra directories in between - And the `praatScripts` folder must be in the same directory as `setup.praat` * So for example the setup.praat file needs to be here: - on Windows, `C:\Users\xxyyzz\Praat\plugin_PoLaR\setup.praat` - on Linux, `~/.praat-dir/plugin_PoLaR/setup.praat` - on a Mac, `~/Library/Preferences/Praat Prefs/plugin_PoLaR/setup.praat` * If not already there, move the `setup.praat` file (and the `praatScripts` directory) to the right location 5. **If Praat is open, (save all your files and) quit the application and restart it** * After restarting, the plug-in is installed, and the new menu commands or buttons will be ready to use!

Updating your plugin

Click for updating instructions…

1. **Download the plugin\_PoLaR.zip file** * Get the **zip file ([plugin_PoLaR.zip](https://github.com/ByronAhn/PoLaR-Praat-plugin/blob/main/plugin_PoLaR.zip?raw=true))** from GitHub by clicking [here](https://github.com/ByronAhn/PoLaR-Praat-plugin/blob/main/plugin_PoLaR.zip?raw=true) * Unzip the file, and you should find a new folder `plugin_PoLaR` - We will move this folder shortly 2. **Navigate to your “Praat preferences” directory** * On Windows, if your username is xxyyzz, your “Praat preferences” directory is: `C:\Users\xxyyzz\Praat\` * On Linux, your “Praat preferences” directory is in your home directory, namely at: `~/.praat-dir/` * On a Mac, your “Praat preferences” directory is in your user Library folder, more specifically at: `~/Library/Preferences/Praat Prefs/` - **NOTE:** On a Mac, this folder is in a hidden directory. To get there, use the “Go To Folder” functionality Finder by opening up a Finder window, and hitting `[SHIFT]+[CMD]+G`. - (_more details on [this page of the Apple support site](https://support.apple.com/en-gw/guide/mac-help/mchlp1236/mac)_) * In all cases, if you do not see your directory there, you may need to create it. - (_If you have trouble, navigate to [this page on the Praat manual](https://www.fon.hum.uva.nl/praat/manual/preferences_folder.html), where finding this directory is described in a different way_) 3. **Delete the old `plugin_PoLaR` directory** * i.e., on Windows, `C:\Users\xxyyzz\Praat\plugin_PoLaR\` * i.e., on Linux, `~/.praat-dir/plugin_PoLaR/` * i.e., on a Mac, `~/Library/Preferences/Praat Prefs/plugin_PoLaR/` 4. **Move the new `plugin_PoLaR` (that you unzipped in step 1) to this directory** * Take the `plugin_PoLaR` folder that you unzipped and move it to Praat preferences directory * This `plugin_PoLaR` folder _**must**_ be found _**immediately**_ inside the “Praat preferences” directory - i.e., on Windows, `C:\Users\xxyyzz\Praat\plugin_PoLaR\` - i.e., on Linux, `~/.praat-dir/plugin_PoLaR/` - i.e., on a Mac, `~/Library/Preferences/Praat Prefs/plugin_PoLaR/` 5. **Double check location of files** * Importantly: the `setup.praat` file must be found just inside this `plugin_Praat` directory, **_WITHOUT_** any extra directories in between - And the `praatScripts` folder must be in the same directory as `setup.praat` * So for example the setup.praat file needs to be here: - on Windows, `C:\Users\xxyyzz\Praat\plugin_PoLaR\setup.praat` - on Linux, `~/.praat-dir/plugin_PoLaR/setup.praat` - on a Mac, `~/Library/Preferences/Praat Prefs/plugin_PoLaR/setup.praat` * If not already there, move the `setup.praat` file (and the `praatScripts` directory) to the right location 6. **If Praat is open, (save all your files and) quit the application and restart it** * After restarting, the plug-in is installed, and the new menu commands or buttons will be ready to use!

What Can You Do with the PoLaR plugin

[!IMPORTANT]

⚠️⚠️For **MAC USERS** using any of the Momel-based functionalities…⚠️⚠️
Because of how macOS security may try to prevent running "unknown" programs, you might need to try and run the Momel app first. (_Try this if you're experiencing an error when you try to run "New Momel-based Points/Levels/Ranges"._) Directions to locate/run the Momel app: * Navigate to the `momelFiles` directory in the `plugin_PoLaR` folder * Double click on `momel_osx_intel`, and you might get a message saying: "`"momel_osx_intel"` cannot be opened because it is from an unidentified developer." * If you do, click `OK` and then right-click (or control-click) on `momel_osx_intel` and select `Open`, and now you'll get a *new* message: "`"momel_osx_intel"` is a Unix app downloaded from the Internet. Are you sure you want to open it?" * Click `Open`; a Terminal window will open and show a few lines of text * After this is done, close the Terminal window and try to run the "New Momel-based Points/Levels/Ranges" functionality again from Praat

Adjust Pitch/Spectrogram viewing settings
*
Set the Spectrogram/Pitch view settings
* Sets a variety of pitch / spectrogram settings, so as to ensure uniform viewing across files / individuals * For pitch view settings, this either uses… - …a simple algorithm defined in [Daniel Hirst's Momel plugin](https://www.researchgate.net/publication/342039069_plugin_momel-intsint), or… - …the values in the Ranges tier (if present) * This function is _only_ available in an Editor window showing a Sound (and TextGrid)
Create New PoLaR TextGrid for Sound(s)
1.
New Blank PoLaR TextGrid for Sound
* This creates blank TextGrids with PolaR tiers, where the duration of the TextGrid matches the duration of the Sound
1. New TextGrid with Momel-based labels
  * This creates a TextGrids with PoLaR tiers * AND uses the Momel-based algorithms (described in bullet 4.i, below) to fill in the Points, Levels, and Ranges tiers * macOS users: see warning in bullet 4.i
Modify/Inspect PoLaR TextGrids
1.
Add missing PoLaR tiers
* Adds any PoLaR tiers that aren't yet present in the Textgrid * Can be run on… - any selected TextGrid(s) in the Objects window - an open TextGrid (and Sound) in an Editor window - every TextGrid in an entire directory
1. Clear PoLaR tiers
  * Removes any labels from the PoLaR tiers, and replaces them with blank tiers * Can be run on any selected TextGrid(s) in the Objects window
2. Clear PoLaR tiers and delete other (non-PoLaR) tiers
  * Removes any labels from the PoLaR tiers, and replaces them with blank tiers * **_ALSO_** deletes all other tiers (except Words and Phones tiers), leaving **_only_** blank PoLaR tiers * Can be run on any selected TextGrid(s) in the Objects window
3. Consensus Helper (beta)
  * Tries to automatically resolve any different advanced labels from two different .TextGrid files into consenus labels - Where it can't resolve labels automatically, a (large) TextGrid is created showing relevant labels from both TextGrid files, leaving the rest of the consenus work to the human labellers - For more details, see the separate guide in `PoLaR-Conensus-Helper.md` * Can be run when 1 Sound object *and* 2 TextGrid objects are selected in the Object window
4. Extract info from PoLaR tiers
  * Gather a large number of measures (timing, f0, etc.) of various aspects of a Sound, based on a corresponding PoLaR-labelled TextGrid - This will collect and organize PoLaR labels as well as some measures associated with them, which is output to the Praat Info window - That information is organized with a header and with elements separated by tabs, so it can be copy-pasted easily into a spreadsheet - Data in this format facilitates further analysis in spreadsheets / statistical software * Can be run on… - any selected TextGrid+Sound pair(s) in the Objects window - an open TextGrid+Sound pair in an Editor window - every TextGrid+Sound pair in an entire directory

Generate PoLaR labels for an existing TextGrid

New Points/Levels/Ranges based on Momel

* Generates labels on the Points / Levels / Ranges tiers, using the algorithms/code from the Momel-INTSINT Plugin - First: it estimates appropriate values for f0 min/max for evaluation - Next: using an algortihm described in Hirst 2011, the momel app identifies f0 turning points, and puts them in a PitchTier object - Last: the f0 values for the highest/lowest Points turning points are used to estimate a Ranges size, and Levels values are created * After this is done, the script will save the PitchTier and a TextGrid with these (new) Points/Levels/Ranges labels - when run from the Editor/Object window, they are saved in the Object window * and a backup of the original TextGrid, without these new labels, is also saved to the Object window - when run on a directory, these .TextGrid/.PitchTier files are saved in a sub-folder called `momel_Based_TextGrids/` * Can be run on… - any selected TextGrid+Sound(+PitchTier) combo(s) in the Objects window - an open TextGrid+Sound pair in an Editor window - every TextGrid+Sound(+PitchTier) combo in an entire directory 2.

New Levels Labels

* Generates labels on the Levels tier for a PoLaR TextGrid that has Points and Ranges labelled - Any existing Levels tier labels will be replaced. - If no Levels tier exists, one will be created. * The algorithm divides up the f0 min/max defined by Range labels into 5 equally-sized quintiles * This is based on Hz values by default, but running "New Levels Labels (More Settings)" you can choose to use Semitones values instead

New Pseudo Labels
* Generates "Pseudo-Categorical" labels, which resemble A-M style phonological labels - Some details about the algorithm are laid out in §5.1.3 of the monograph called "Embarking on PoLaR Explorations", which can be found on the [PoLaR OSF repository](https://osf.io/usbx5/) * Running this script requires that **_ALL_** PoLaR tiers are annotated, and that the Points tier contains **_ADVANCED_** PoLaR labels * Can be run on… - any selected TextGrid(s) in the Objects window - an open TextGrid (and Sound) in an Editor window - every TextGrid in an entire directory

Assess pitch turning points

Adjust Points audio/visually, in a Manipulation window

* Opens three windows - an Editor window with the original Sound+TextGrid pair - a Manipulation window for a Sound, where all pitch points are at the time,f0 coordinates from the PoLaR Points tier - a pop-up window with the button to press when editing is done * The user then moves the existing pitch points, add new ones, delete existing ones, etc. - while the Manipulation window is open, the user can select portions of the recording, and hear its straight-line approximation - this facilitates direct comparison with the original recording (which is also open) > [!NOTE] > To further facilitate direct comparison between the straight-line approximation and the original recording, ensure the "Group" checkbox in the bottom-right of the Manipulation and Editor windows is **ticked**. > When it is ticked, selecting a stretch of time in the Manipulation window automatically selects the _exact same_ stretch of time in the Editor window. * When the user is finished, they can select "Save Changes" in the pop-up window - This saves the pitch points in the Manipulation window to the TextGrid's Points tier * Can be run on… - any selected TextGrid+Sound(+PitchTier) combo(s) in the Objects window - an open TextGrid+Sound pair in an Editor window - every TextGrid+Sound(+PitchTier) combo in an entire directory

Resynthesize Straight Line Approximation
* Resynthesizes a Sound, with a straight-line approximation of the f0 contour, based on the PoLaR points tier and f0 measurements * Creates a new, save-able Sound object (named the same as the original, with "-resynth" tagged onto the end) - Two new Praat objects are added to the Objects window (but aren't saved): the resynthesized Sound object and a Manipulation object * Listening to this can be used to assess whether the Points yield an appropriate sounding straight line approximation * Can be run on… - any selected TextGrid+Sound pair in the Objects window - an open TextGrid+Sound pair in an Editor window - every TextGrid+Sound pair in an entire directory

Create PoLaR-styled Sound(+Textgrid) Drawings

Produce stylized Sound/TextGrid drawings

* Creates a drawing with the f0 track overlaid on top of a spectrogram for the Sound object - If there is a TextGrid as well, its labels are shown underneath - (This simulates the display for a View & Edit window) * If run with the menu item ending in "(More Settings)", a window opens with many more options and parameters that can be set

Buttons and Menu items for plugin functionalities

Objects Window: Buttons on the right-hand side…

> [!NOTE] > Which buttons are visible depends on what's selected * **`New PoLaR TextGrid for Sound(s)`** -

Blank PoLaR TextGrid(s)

* _Corresponds to_: - [bullet 2.i above](#create-textgrid-for-sounds) - [`PoLaR-TextGrid-for-Sound.praat`](praatScripts/PoLaR-TextGrid-for-Sound.praat) * _Operates on_: - 1+ Sounds * _Visible when selecting_: - 1+ Sounds * _Additional notes_: - The resultant TextGrid is an object in the Objects Window

- <details><summary><code>TextGrid with Momel-based labels</code></summary>

    * _Corresponds to_: 
        - [bullet 2.ii above](#momel-based-polar-for-sound)
        - [`PoLaR-momel-labels-Sound.praat`](praatScripts/PoLaR-momel-labels-Sound.praat)
    * _Operates on_:
        - 1+ Sounds
    * _Visible when selecting_:
        - 1+ Sounds
    * _Additional notes_: 
        - The resultant TextGrid is an object in the Objects Window
        - See information on the Momel-based Points/Levels/Ranges labels in [bullet 4.i above](#polar-based-on-momel)
        - There is a version of this that can run on entire directories as well; see [the list of menu items below](#objects-new-praat-menus)

    </details>

Modify/Inspect PoLaR TextGrids
- Add Missing PoLaR Tiers
  * _Corresponds to_: - [bullet 3.i above](#Add-missing-PoLaR-tiers) - [`PoLaR-TextGrid-Add-Missing.praat`](praatScripts/PoLaR-TextGrid-Add-Missing.praat) * _Operates on_: - 1+ TextGrids * _Visible when selecting_: - 1+ TextGrids (and 0+ Sounds and 0+ PitchTiers) * _Additional notes_: - There is a version of this that can run on entire directories as well; see [the list of menu items below](#objects-new-praat-menus)
- Clear PoLaR tiers
  * _Corresponds to_: - [bullet 3.ii above](#Clear-PoLaR-tiers) - [`PoLaR-TextGrid-Blank.praat`](praatScripts/PoLaR-TextGrid-Blank.praat) * _Operates on_: - 1+ TextGrids * _Visible when selecting_: - 1+ TextGrids (and 0+ Sounds and 0+ PitchTiers) * _Additional notes_: - Existing labels on PoLaR tiers **_WILL BE DELETED_**; use with caution
- Clear PoLaR tiers + Delete other tiers (CAUTION)
  * _Corresponds to_: - [bullet 3.iii above](#Clear-PoLaR-tiers-and-delete-others) - [`PoLaR-TextGrid-Blanker.praat`](praatScripts/PoLaR-TextGrid-Blanker.praat) * _Operates on_: - 1+ TextGrids * _Visible when selecting_: - 1+ TextGrids (and 0+ Sounds and 0+ PitchTiers) * _Additional notes_: - All labels and non-PoLaR tiers **_WILL BE DELETED_**; use with extreme caution
- Consensus Helper (beta)
  * _Corresponds to_: - [bullet 3.iv above](#Consensus-Helper) - [`PoLaR-Conensus-Helper.praat`](praatScripts/PoLaR-Conensus-Helper.praat) * _Operates on_: - 2 TextGrids for the same 1 Sound * _Visible when selecting_: - 2 TextGrids and 1 Sound * _Additional notes_: - This is intended to work with **_advanced_** PoLaR labels - Using this can be complex; see the separate guide in `PoLaR-Conensus-Helper.md`
- Extract info from PoLaR tiers
  * _Corresponds to_: - [bullet 3.v above](#Extract-info-from-PoLaR-tiers) - [`PoLaR-Extract-Info-to-TSV-Quick.praat`](praatScripts/PoLaR-Extract-Info-to-TSV-Quick.praat) * _Operates on_: - 1 TextGrid-Sound pair * _Visible when selecting_: - 1 TextGrid and 1 Sound (and 0+ PitchTiers) * _Additional notes_: - The extracted information is displayed in an Info window * All the information is tab-separated, so you can easily copy-paste it into spreadsheet software (e.g., Excel, Google Sheets, etc.) * Data in this format facilitates further analysis in spreadsheets / statistical software - There is a version of this that can run on entire directories as well; see [the list of menu items below](#objects-new-praat-menus)
Generate PoLaR Labels
- New Momel-based Points/Levels/Ranges
  * _Corresponds to_: - [bullet 4.i above](#polar-based-on-momel) - [`PoLaR-momel-labels-Quick.praat`](praatScripts/PoLaR-momel-labels-Quick.praat) * _Operates on_: - 1 TextGrid-Sound pair - 1 TextGrid-Sound-PitchTier combo * _Visible when selecting_: - 1 TextGrid and 1 Sound - 1 TextGrid and 1 Sound and 1 PitchTier * _Additional notes_: - The original (selected) TextGrid object is duplicated (as a backup of the original labels) in the Objects window * The new labels are added to the original (selected) TextGrid object - A new PitchTier object is also added to the Objects window, with pitch points corresponding to the Points tier labels * This PitchTier directly encodes the time,f0 coordinates of the Points tier labels, making future analysis (e.g., in R) easier - See information on the Momel-based Points/Levels/Ranges labels in [bullet 4.i above](#polar-based-on-momel) - There is a version of this that can run on entire directories as well; see [the list of menu items below](#objects-new-praat-menus)
- New Momel-based Points/Levels/Ranges (More Settings)
  * _Corresponds to_: - [bullet 4.i above](#polar-based-on-momel) - [`PoLaR-momel-labels.praat`](praatScripts/PoLaR-momel-labels.praat) * _Operates on_: - 1 TextGrid-Sound pair - 1 TextGrid-Sound-PitchTier combo * _Visible when selecting_: - 1 TextGrid and 1 Sound - 1 TextGrid and 1 Sound and 1 PitchTier * _Additional notes_: - The original (selected) TextGrid object is duplicated (as a backup of the original labels) in the Objects window * The new labels are added to the original (selected) TextGrid object - A new PitchTier object is also added to the Objects window, with pitch points corresponding to the Points tier labels * This PitchTier directly encodes the time,f0 coordinates of the Points tier labels, making future analysis (e.g., in R) easier - See information on the Momel-based Points/Levels/Ranges labels in [bullet 4.i above](#polar-based-on-momel)
- New Levels Labels
  * _Corresponds to_: - [bullet 4.ii above](#levels-labels) - [`PoLaR-Levels-labeller-Quick.praat`](praatScripts/PoLaR-Levels-labeller-Quick.praat) * _Operates on_: - 1 TextGrid-Sound pair * _Visible when selecting_: - 1 TextGrid and 1 Sound (0+ PitchTiers) * _Additional notes_: - The new Levels labels are added to the original (selected) TextGrid object - There is a version of this that can run on entire directories as well; see [the list of menu items below](#objects-new-praat-menus)
- New Levels Labels (More Settings)
  * _Corresponds to_: - [bullet 4.ii above](#levels-labels) - [`PoLaR-Levels-labeller-Advanced.praat`](praatScripts/PoLaR-Levels-labeller-Advanced.praat) * _Operates on_: - 1 TextGrid-Sound pair * _Visible when selecting_: - 1 TextGrid and 1 Sound (and 0+ PitchTiers) * _Additional notes_: - The new Levels labels are added to the original (selected) TextGrid object - One setting that's available here is one to allow the labeller to produce Levels labels on the basis of measurements of f0 in Semitones
- New Pseudo Labels (Adv. labels req'd!)
  * _Corresponds to_: - [bullet 4.iii above](#pseudo-labels) - [`PoLaR-to-pseudocategorical-Quick.praat`](praatScripts/PoLaR-to-pseudocategorical-Quick.praat) * _Operates on_: - 1+ TextGrids (with advanced PoLaR labels) * _Visible when selecting_: - 1+ TextGrids (and 0+ Sounds and 0+ PitchTiers) * _Additional notes_: - The new Pseudo labels are added to the original (selected) TextGrid object(s) - There is a version of this that can run on entire directories as well; see [the list of menu items below](#objects-new-praat-menus)
Assess PoLaR Turning Points
- Adjust Points audio/visually
  * _Corresponds to_: - [bullet 5.i above](#Adjust-Points-audio-visually) - [`PoLaR-Adjust-Points-in-Manipulation.praat`](praatScripts/PoLaR-Adjust-Points-in-Manipulation.praat) * _Operates on_: - 1 TextGrid-Sound pair - 1 TextGrid-Sound-PitchTier combo * _Visible when selecting_: - 1 TextGrid and 1 Sound (and 0+ PitchTiers) * _Additional notes_: - 3 windows will open 1. An Editor window with the original Sound/TextGrid, where you can listen to the original 2. A Manipulation window, where you can: edit the pitch points time/f0 values & listen to resynthesis 3. A pop-up window, which has the buttons to save (or not) changes in the Manipulation window - All changes in the Manipulation window are saved to the TextGrid object and to a new PitchTier object that is added to the Objects window - Make sure that the `Group` checkbox in the bottom-right corner of the Editor window is ticked * This allows selections in the original Editor window to also be selected in the Manipulation window (and vice-versa) - There is a version of this that can run on entire directories as well; see [the list of menu items below](#objects-new-praat-menus)
- Resynthesize Straight Line Approx.
  * _Corresponds to_: - [bullet 5.ii above](#Resynthesize-SLA) - [`PoLaR-resynthesize-SLA-Quick-Quiet.praat`](praatScripts/PoLaR-resynthesize-SLA-Quick-Quiet.praat) * _Operates on_: - 1 TextGrid-Sound pair * _Visible when selecting_: - 1 TextGrid and 1 Sound * _Additional notes_: - The resynthesized Sound is added as a new object to the Objects window - An Editor window also automatically opens up, with the resynthesized Sound and the original selected TextGrid - Make sure that the `Group` checkbox in the bottom-right corner of the Editor window is ticked * This allows selections in the original Editor window to also be selected in the Manipulation window (and vice-versa) - A Manipulation object is also added to the Objects window, with the pitch points used to resynthesize the Sound
- Resynthesize Straight Line Approx. (More Settings)
  * _Corresponds to_: - [bullet 5.ii above](#Resynthesize-SLA) - [`PoLaR-resynthesize-SLA-Advanced.praat`](praatScripts/PoLaR-resynthesize-SLA-Advanced.praat) * _Operates on_: - 1 TextGrid-Sound pair * _Visible when selecting_: - 1 TextGrid and 1 Sound * _Additional notes_: - The resynthesized Sound is added as a new object to the Objects window - An Editor window also automatically opens up, with the resynthesized Sound and the original selected TextGrid - Make sure that the `Group` checkbox in the bottom-right corner of the Editor window is ticked * This allows selections in the original Editor window to also be selected in the resynthesized Editor window (and vice-versa) - A Manipulation object is also added to the Objects window, with the pitch points used to resynthesize the Sound
Create Drawing for Sound(+TextGrid)
- Create picture
  * _Corresponds to_: - [bullet 6 above](#create-drawings) - [`PoLaR-Draw-Sound-and-TextGrid-Quick.praat`](praatScripts/PoLaR-Draw-Sound-and-TextGrid-Quick.praat) * _Operates on_: - 1 Sound - 1 TextGrid-Sound pair * _Visible when selecting_: - 1 Sound - 1 TextGrid and 1 Sound (and 0+ PitchTiers) * _Additional notes_: - The drawing uses Ranges labels, when available, to determine the endpoints of the y-axis of the f0 track - The resulting drawing is opened up on a Picture window, from which it can be saved - There is a version of this that can run on entire directories as well; see [the list of menu items below](#objects-new-praat-menus)
- Create picture (More Settings)
  * _Corresponds to_: - [bullet 6 above](#create-drawings) - [`PoLaR-Draw-Sound-and-TextGrid-Advanced.praat`](praatScripts/PoLaR-Draw-Sound-and-TextGrid-Advanced.praat) * _Operates on_: - 1 Sound - 1 TextGrid-Sound pair * _Visible when selecting_: - 1 Sound - 1 TextGrid and 1 Sound (and 0+ PitchTiers) * _Additional notes_: - The settings window that opens up provides many options, including: * time window * spectrogram frequency max * f0 min/max * drawing width * options for how the f0 draw range is determined * which TextGrid tiers to draw - The resulting drawing is opened up on a Picture window, from which it can be saved

Objects Window: "New"/"Praat"/"Save" menus…

* A `PoLaR plugin` menu is **added to *two* menus**: 1. The `New` menu, which is accessed through a button on the Objects window 2. The `Praat` menu, which is in different locations on a Mac vs. PC * On macOS, the `Praat` menu is up in the menubar that is permanently at the top of the screen * On Windows/Linux, the `Praat` menu is at the top of the Objects window (next to the `New` menu) * (_There are also some additional convenient commands added to the `Save` menu, which are also described further below_) * **`PoLaR plugin` menu** (_within `New` and `Praat` menus_) -

Extract PoLaR info from files in a directory

* _Corresponds to_: - [bullet 3.v above](#Extract-info-from-PoLaR-tiers) - [`PoLaR-Extract-Info-to-TSV-Dir.praat`](praatScripts/PoLaR-Extract-Info-to-TSV-Dir.praat) * _Operates on_: - all .TextGrid-.wav pairs in a given directory * _Output_: - a .tsv file for every .TextGrid-.wav pair, saved in the same directory * _Additional notes_: - After providing Praat with the directory, the script cycles through each .wav file and looks for a .Textgrid file of the same name - Such .tsv files can be easily imported into a spreadsheets or statistical software, for further analysis - There are versions of this that can run from [the Objects window](#) and from [the Editor window](#)

- <details><summary><code>Add Missing PoLaR Tiers to files in a directory</code></summary>

    * _Corresponds to_: 
        - [bullet 3.i above](#Add-missing-PoLaR-tiers)
        - [`PoLaR-TextGrid-Add-Missing-Dir.praat`](praatScripts/PoLaR-TextGrid-Add-Missing-Dir.praat)
    * _Operates on_:
        - all .TextGrid files in a given directory
    * _Output_:
        - each newly edited TextGrid is **saved over** the original .TextGrid file in the original directory
    * _Additional notes_:
        - There are versions of this that can run from [the Objects window](#) and from [the Editor window](#)

    </details>

- <details><summary><code>Label the Levels tier for files in a directory</code></summary>

    * _Corresponds to_: 
        - [bullet 4.ii above](#levels-labels)
        - [`PoLaR-Levels-labeller-Dir.praat`](praatScripts/PoLaR-Levels-labeller-Dir.praat)
    * _Operates on_:
        - all .TextGrid-.wav pairs in a given directory
    * _Output_:
        - each newly edited TextGrid is **saved over** the original .TextGrid file in the original directory
    * _Additional notes_:
        - After providing Praat with the directory, the script cycles through each .wav file and looks for a .Textgrid file of the same name
        - There are versions of this that can run from [the Objects window](#) and from [the Editor window](#)

    </details>

- <details><summary><code>Label the Pseudo tier for files in a directory</code></summary>

    * _Corresponds to_: 
        - [bullet 4.iii above](#pseudo-labels)
        - [`PoLaR-to-pseudocategorical-Dir.praat`](praatScripts/PoLaR-to-pseudocategorical-Dir.praat)
    * _Operates on_:
        - all .TextGrid files in a given directory
    * _Output_:
        - each newly edited TextGrid is **saved over** the original .TextGrid file in the original directory
    * _Additional notes_:
        - There are versions of this that can run from [the Objects window](#) and from [the Editor window](#)

    </details>

- <details><summary><code>New Momel-based labels for files in a directory</code></summary>

    * _Corresponds to_: 
        - [bullet 4.i above](#polar-based-on-momel)
        - [`PoLaR-momel-labels-Dir.praat`](praatScripts/PoLaR-momel-labels-Dir.praat)
    * _Operates on_:
        - all .TextGrid-.wav pairs in a given directory
        - all .TextGrid-.wav-.PitchTier combos in a given directory
    * _Output_:
        - each newly edited TextGrid is saved in a **sub-directory** called `momel_Based_TextGrids/`
            * (the original .TextGrid files are **not deleted**)
        - each PitchTier that is used is also saved to that same directory
    * _Additional notes_:
        - After providing Praat with the directory, the script cycles through each .wav file and looks for a .Textgrid file and a .PitchTier file of the same name
            * When there are .PitchTier files in the directory, those are used in Momel calculations
            * (otherwise new .PitchTier files are also created by the script, based on the .TextGrid/.wav)
        - After running this on a directory, it is **HIGHLY recommended** to run `Adjust Points audio/visually for files in a directory`
            * This is because the Momel-based turning points regularly need correction by a human labeller
        - There are versions of this that can run from [the Objects window](#) and from [the Editor window](#)

    </details>

- <details><summary><code>Adjust Points audio/visually for files in a directory</code></summary>

    * _Corresponds to_: 
        - [bullet 5.i above](#Adjust-Points-audio-visually)
        - [`PoLaR-Adjust-Points-in-Manipulation-Dir.praat`](praatScripts/PoLaR-Adjust-Points-in-Manipulation-Dir.praat)
    * _Operates on_:
        - all .TextGrid-.wav pairs in a given directory
        - all .TextGrid-.wav-.PitchTier combos in a given directory
    * _Output_:
        - each newly edited TextGrid is **saved over** the original .TextGrid file in the original directory
        - each new (or newly edited) PitchTier is **saved over** any pre-existing .PitchTier file in the original directory
    * _Additional notes_:
        - After providing Praat with the directory, the script cycles through each .wav file and looks for a .Textgrid file and a .PitchTier file of the same name
            * When there are .PitchTier files in the directory, those are used to create the pitch points in the Manipulation window
            * (otherwise new .PitchTier files are also created by the script, based on the .TextGrid/.wav)
        - 3 windows will open for each set of files
            1. An Editor window with the original Sound/TextGrid, where you can listen to the original
            2. A Manipulation window, where you can: edit the pitch points time/f0 values & listen to resynthesis
            3. A pop-up window, which has the buttons to save (or not) work to the TextGrid object and to a PitchTier object, when you're done
        - Make sure that the `Group` checkbox in the bottom-right corner of the Editor window is ticked
            * This allows selections in the original Editor window to also be selected in the resynthesized Editor window (and vice-versa)
        - There are versions of this that can run from [the Objects window](#) and from [the Editor window](#)

    </details>

- <details><summary><code>Create pictures for files in a directory</code></summary>

    * _Corresponds to_: 
        - [bullet 6 above](#create-drawings)
        - [`PoLaR-Draw-Sound-and-TextGrid-Dir.praat`](praatScripts/PoLaR-Draw-Sound-and-TextGrid-Dir.praat)
    * _Operates on_:
        - all .wav files in a given directory
        - all .TextGrid-.wav pairs in a given directory
    * _Output_:
        - Image files, in the format of your choice, to the same directory
    * _Additional notes_:
        - After providing Praat with the directory, the script cycles through each .wav file and looks for a .Textgrid file of the same name
        - There are versions of this that can run from [the Objects window](#) and from [the Editor window](#)

    </details>

Additional convenient commands
- Objects window Save menu: Save as .wav (multiple selected objects)
  * _Corresponds to_: - [`Save-multiple-Sounds-Textgrids.praat`](praatScripts/Save-multiple-Sounds-Textgrids.praat) * _Operates on_: - all selected Sound objects * _Output_: - .wav files saved to the directory of the user's choice * _Additional notes_: - Praat doesn't have a way to save multiple Sound objects at once; this serves that purpose - If there are pre-existing files with the same name in the directory that's chosen, the user is prompted for what to do
- Objects window Save menu: Save as .Textgrid (multiple selected objects)
  * _Corresponds to_: - [`Save-multiple-Sounds-Textgrids.praat`](praatScripts/Save-multiple-Sounds-Textgrids.praat) * _Operates on_: - all selected TextGrid objects * _Output_: - .TextGrid files saved to the directory of the user's choice * _Additional notes_: - Praat doesn't have a way to save multiple Sound objects at once; this serves that purpose - If there are pre-existing files with the same name in the directory that's chosen, the user is prompted for what to do
- Objects window Save menu: Save as .wav/.Textgrid (multiple selected objects)
  * _Corresponds to_: - [`Save-multiple-Sounds-Textgrids.praat`](praatScripts/Save-multiple-Sounds-Textgrids.praat) * _Operates on_: - all selected Sound and TextGrid objects * _Output_: - .wav and .Textgrid files saved to the directory of the user's choice * _Additional notes_: - Praat doesn't have a way to save multiple Sound objects at once; this serves that purpose - If there are pre-existing files with the same name in the directory that's chosen, the user is prompted for what to do

Editor Windows: Edit, Tier, and File menus…

> [!NOTE] > The menu items added to Editor menus are formatted best in **Praat version 6.3.18 onwards**. Make sure you have this version or newer for the best user experience. * Choosing `View` or `View & Edit` while a Sound and/or TextGrid object are selected causes an Editor window to open - If what was selected was just a Sound object, it a **Sound Editor** - If what was selected was a TextGrid object (or one TextGrid and one Sound), it a **TextGrid Editor** * Each type of Editor window has its own menu buttons, and this plugin adds commands to… * …the `Edit` menu (of TextGrid **and** Sound Editors) * …the `Tier` menu of TextGrid Editors * …the `File` menu of Sound Editors * **`Edit` menu items** - **`PoLaR-assisted View Settings:`** *

Standard view settings

- _Corresponds to_: - [bullet 1 above](#adjust-view) - [`PoLaR-Adjust-Editor-View-Standard.praat`](praatScripts/PoLaR-Adjust-Editor-View-Standard.praat) - _Effect_: - This adjusts the pitch and spectrogram settings - According to the values used throughout the PoLaR annotation guidelines - When there are Ranges tier labels already, these are used to set the Pitch min/max settings - _Additional notes_:

    * <details id=""><summary><code>Sensitive view settings</code></summary>

        - _Corresponds to_: 
            - [bullet 1 above](#adjust-view)
            - [`PoLaR-Adjust-Editor-View-Sensitive.praat`](praatScripts/PoLaR-Adjust-Editor-View-Sensitive.praat)
        - _Effect_:
            - This adjusts the pitch and spectrogram settings
            - According to slightly more sensitive (more error-prone) settings
            - When there are Ranges tier labels already, these are used to set the Pitch min/max settings
        - _Additional notes_:

        </details>

- **`Create PoLaR-styled Drawing:`**
    * <details id=""><summary><code>Create picture</code></summary>

        - _Corresponds to_: 
            - [bullet 6 above](#create-drawings)
            - [`PoLaR-Draw-Sound-and-TextGrid-from-TGE.praat`](praatScripts/PoLaR-Draw-Sound-and-TextGrid-from-TGE.praat)
        - _Effect_:
            - Puts the drawing in a Praat Picture window, from which it can be saved
        - _Additional notes_:
            - The drawing uses Ranges labels, when available, to determine the endpoints of the y-axis of the f0 track
            - The resulting drawing is opened up on a Picture window, from which it can be saved

        </details>

    * <details id=""><summary><code>Create picture (More Settings)</code></summary>

        - _Corresponds to_: 
            - [bullet 6 above](#create-drawings)
            - [`PoLaR-Draw-Sound-and-TextGrid-from-TGE-Adv.praat`](praatScripts/PoLaR-Draw-Sound-and-TextGrid-from-TGE-Adv.praat)
        - _Effect_:
            - Puts the drawing in a Praat Picture window, from which it can be saved
        - _Additional notes_:
            - The settings window that opens up provides many options, including:
                * time window
                * spectrogram frequency max
                * f0 min/max
                * drawing width
                * options for how the f0 draw range is determined
                * which TextGrid tiers to draw
            - The resulting drawing is opened up on a Picture window, from which it can be saved

        </details>

Tier menu items (TextGrid Editors only)
- Modify/Inspect PoLaR TextGrids:
  - Add missing PoLaR tiers
    - _Corresponds to_: - [bullet 3.i above](#Add-missing-PoLaR-tiers) - [`PoLaR-TextGrid-Add-Missing-from-TGE.praat`](praatScripts/PoLaR-TextGrid-Add-Missing-from-TGE.praat) - _Effect_: - New blank TextGrid tiers appear in the open TextGrid - _Additional notes_:
  - Extract info from PoLaR tiers
    - _Corresponds to_: - [bullet 3.v above](#Extract-info-from-PoLaR-tiers) - [`PoLaR-Extract-Info-to-TSV-from-TGE.praat`](praatScripts/PoLaR-Extract-Info-to-TSV-from-TGE.praat) - _Effect_: - The extracted information is displayed in an Info window - _Additional notes_: - All the information is tab-separated, so you can easily copy-paste it into spreadsheet software (e.g., Excel, Google Sheets, etc.) * Data in this format facilitates further analysis in spreadsheets / statistical software
- Assess PoLaR Turning Points:
  - Adjust Points audio/visually
    - _Corresponds to_: - [bullet 5.i above](#Adjust-Points-audio-visually) - [`PoLaR-Adjust-Points-in-Manipulation-from-TGE.praat`](praatScripts/PoLaR-Adjust-Points-in-Manipulation-from-TGE.praat) - _Effect_: - 3 windows will open 1. An Editor window with the original Sound/TextGrid, where you can listen to the original 2. A Manipulation window, where you can: edit the pitch points time/f0 values & listen to resynthesis 3. A pop-up window, which has the buttons to save (or not) changes in the Manipulation window - All changes in the Manipulation window are saved to the TextGrid object and to a new PitchTier object that is added to the Objects window - _Additional notes_: - Make sure that the `Group` checkbox in the bottom-right corner of the Editor window is ticked * This allows selections in the original Editor window to also be selected in the Manipulation window (and vice-versa)
  - Resynthesize Straight Line Approximation
    - _Corresponds to_: - [bullet 5.ii above](#Resynthesize-SLA) - [`PoLaR-resynthesize-SLA-from-TGE.praat`](praatScripts/PoLaR-resynthesize-SLA-from-TGE.praat) - _Effect_: - A Sound with a resynthesized f0 track (based on PoLaR points) will open in a new Editor window, with the original TextGrid - _Additional notes_: - Make sure that the `Group` checkbox in the bottom-right corner of the Editor window is ticked * This allows selections in the original Editor window to also be selected in the resynthesized Editor window (and vice-versa)
- Generate PoLaR Labels:
  - New Momel-Based Points/Levels/Ranges
    - _Corresponds to_: - [bullet 4.i above](#polar-based-on-momel) - [`PoLaR-momel-labels-from-TGE.praat`](praatScripts/PoLaR-momel-labels-from-TGE.praat) - _Effect_: - asdfasdf - _Additional notes_:
  - New Levels Labels
    - _Corresponds to_: - [bullet 4.ii above](#levels-labels) - [`PoLaR-Levels-labeller-from-TGE.praat`](praatScripts/PoLaR-Levels-labeller-from-TGE.praat) - _Effect_: - asdfasdf - _Additional notes_:
  - New Pseudo Labels (Advanced labels req'd!)
    - _Corresponds to_: - [bullet 4.iii above](#pseudo-labels) - [`PoLaR-to-pseudocategorical-from-TGE.praat`](praatScripts/PoLaR-to-pseudocategorical-from-TGE.praat) - _Effect_: - asdfasdf - _Additional notes_:
File menu items (Sound Editors only)
- New PoLaR TextGrids:
  - Create Blank PoLaR TextGrid
    - _Corresponds to_: - [bullet 2.i above](#blank-polar-for-sound) - [`PoLaR-TextGrid-for-Sound-from-TGE.praat`](praatScripts/PoLaR-TextGrid-for-Sound-from-TGE.praat) - _Effect_: - asdfasdf - _Additional notes_:
  - Create PoLaR TextGrid with Momel-based labels
    - _Corresponds to_: - [bullet 4.i above](#polar-based-on-momel) - [`PoLaR-momel-labels-from-TGE-Sound.praat`](praatScripts/PoLaR-momel-labels-from-TGE-Sound.praat) - _Effect_: - asdfasdf - _Additional notes_: