PoLaR-Praat-plugin: A Praat repository from ByronAhn

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…

Download the plugin_PoLaR.zip file

Get the zip file (plugin_PoLaR.zip) from GitHub by clicking here
Unzip the file, and you should find a new folder plugin_PoLaR
- We will move this folder shortly

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)
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, where finding this directory is described in a different way)

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/

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

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…

Download the plugin_PoLaR.zip file

Get the zip file (plugin_PoLaR.zip) from GitHub by clicking here
Unzip the file, and you should find a new folder plugin_PoLaR
- We will move this folder shortly

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)
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, where finding this directory is described in a different way)

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/

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/

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

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, 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
2. 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
2. 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
3. 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
4. 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
5. 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
1. 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
3. 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
  - 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
1. 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
2. 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
    - 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
- TextGrid with Momel-based labels
  - Corresponds to:
    - bullet 2.ii above
    - 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
    - There is a version of this that can run on entire directories as well; see the list of menu items below
Modify/Inspect PoLaR TextGrids
- Add Missing PoLaR Tiers
  - Corresponds to:
    - bullet 3.i above
    - 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
- Clear PoLaR tiers
  - Corresponds to:
    - bullet 3.ii above
    - 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
    - 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
    - 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
    - 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
Generate PoLaR Labels
- New Momel-based Points/Levels/Ranges
  - Corresponds to:
    - bullet 4.i above
    - 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
    - There is a version of this that can run on entire directories as well; see the list of menu items below
- New Momel-based Points/Levels/Ranges (More Settings)
  - Corresponds to:
    - bullet 4.i above
    - 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
- New Levels Labels
  - Corresponds to:
    - bullet 4.ii above
    - 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
- New Levels Labels (More Settings)
  - Corresponds to:
    - bullet 4.ii above
    - 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
    - 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
Assess PoLaR Turning Points
- Adjust Points audio/visually
  - Corresponds to:
    - bullet 5.i above
    - 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
      
      An Editor window with the original Sound/TextGrid, where you can listen to the original
      
      A Manipulation window, where you can: edit the pitch points time/f0 values & listen to resynthesis
      
      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
- Resynthesize Straight Line Approx.
  - Corresponds to:
    - bullet 5.ii above
    - 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
    - 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
    - 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
- Create picture (More Settings)
  - Corresponds to:
    - bullet 6 above
    - 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
    - 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
- Add Missing PoLaR Tiers to files in a directory
  - Corresponds to:
    - bullet 3.i above
    - 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
- Label the Levels tier for files in a directory
  - Corresponds to:
    - bullet 4.ii above
    - 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
- Label the Pseudo tier for files in a directory
  - Corresponds to:
    - bullet 4.iii above
    - 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
- New Momel-based labels for files in a directory
  - Corresponds to:
    - bullet 4.i above
    - 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
- Adjust Points audio/visually for files in a directory
  - Corresponds to:
    - bullet 5.i above
    - 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
      
      An Editor window with the original Sound/TextGrid, where you can listen to the original
      
      A Manipulation window, where you can: edit the pitch points time/f0 values & listen to resynthesis
      
      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
- Create pictures for files in a directory
  - Corresponds to:
    - bullet 6 above
    - 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
Additional convenient commands
- Objects window Save menu: Save as .wav (multiple selected objects)
  - Corresponds to:
    - 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
  - 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
  - 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
      
      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>

	* <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
      
      PoLaR-TextGrid-Add-Missing-from-TGE.praat
    - Effect:
      
      New blank TextGrid tiers appear in the open TextGrid
    - Additional notes:

		</details>

	* <details id=""><summary><code>Extract info from PoLaR tiers</code></summary>

		- _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

		</details>

- **`Assess PoLaR Turning Points:`**
	* <details id=""><summary><code>Adjust Points audio/visually</code></summary>

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

		</details>

	* <details id=""><summary><code>Resynthesize Straight Line Approximation</code></summary>

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

		</details>

- **`Generate PoLaR Labels:`**
	* <details id=""><summary><code>New Momel-Based Points/Levels/Ranges</code></summary>

		- _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_:

		</details>
		
	* <details id=""><summary><code>New Levels Labels</code></summary>

		- _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_:

		</details>

	* <details id=""><summary><code>New Pseudo Labels (Advanced labels req'd!)</code></summary>

		- _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_:

		</details>

File menu items (Sound Editors only)
- New PoLaR TextGrids:
  - Create Blank PoLaR TextGrid
    - Corresponds to:
      
      bullet 2.i above
      
      PoLaR-TextGrid-for-Sound-from-TGE.praat
    - Effect:
      
      asdfasdf
    - Additional notes:

		</details>

	* <details id=""><summary><code>Create PoLaR TextGrid with Momel-based labels</code></summary>

		- _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_:

		</details>

ByronAhn/PoLaR-Praat-plugin

PoLaR plugin for Praat

Installation of the plugin

Updating your plugin

What Can You Do with the PoLaR plugin

Buttons and Menu items for plugin functionalities