Modified track related functionalities

Author: lxy2304

docs/source/acoustics_encoding.rst

@@ -231,38 +231,167 @@ a `window_max` of 30 means that it will look up to 30 milliseconds after the end
 Encoding other measures using a Praat script
 ============================================
 
-Other acoustic measures can be encoded by passing a Praat script to :code:`analyze_script`.
+You can encode additional acoustic measures by passing a Praat script to either 
+:code:`analyze_script` or :code:`analyze_track_script`. It is essential to follow the exact input and output format for 
+your Praat script to ensure compatibility with the system.
 
-The requirements for the Praat script are:
+- :code:`analyze_script`: Designed for single-point measurements. This function works for user-specific 
+  measurements that occur at exactly one point in time for any target annotation type 
+  (or a defined subset of that type) in the hierarchy, such as a predefined set of vowels within all phones.
 
-* exactly one input: the full path to the sound file containing (only) the phone. (Any other parameters can be set manually
-  within your script, and an existing script may need some other modifications in order to work on this type of input)
-* print the resulting acoustic measurements (or other properties) to the Praat Info window in the following format:
+- :code:`analyze_track_script`: Use this for continuous measurements or when measurements are required 
+  at multiple time points per annotation. This function allows you to configure your Praat script to 
+  output results for multiple time points. 
 
-  * The first line should be a space-separated list of column names. These are the names of the properties that will be
-    saved into the database.
-  * The second line should be a space-separated list containing one measurement for each property.
-  * (It is okay if there is some blank space before/after these two lines.)
+analyze_script
+--------------
 
-  An example of the Praat output::
+There are two input formats available for designing your Praat script:
+
+Format 1:
+~~~~~~~~~
+This is sufficient for most use cases and should be your default choice unless runtime efficiency is critical. 
+In this format, the system generates temporary sound files, each containing one instance of your chosen annotation type. 
+
+**Input Requirements:**
+
+- One required input: the full path to the sound file. This input will be automatically filled by the system. You can define additional attributes as needed.
+
+Example input section for a Praat script using Format 1::
+
+    form Variables
+        sentence filename
+        # add more arguments here 
+    endform
+
+    Read from file... 'filename$'
+
+Format 2 (for optimized analysis):
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This format is more efficient as it reuses the same discourse sound file for all annotations in the same discourse, avoiding the creation of extra files.
+
+**Input Requirements:**
+
+- Five required inputs: 
+    - Full path to the **long** sound file
+    - `begin` time
+    - `end` time
+    - `channel`
+    - `padding`
+
+Do not assign values to these five fields; the system will populate them during processing. You may include additional 
+attributes beyond these five, but ensure that values are passed as an array via the API.
+
+Example Praat script for Format 2::
+
+    form Variables
+        sentence filename 
+        real begin 
+        real end
+        integer channel
+        real padding
+        # add more arguments here
+    endform
+
+    Open long sound file... 'filename$'
+
+    seg_begin = begin - padding
+    if seg_begin < 0
+        seg_begin = 0
+    endif
+
+    seg_end = end + padding
+    if seg_end > duration
+        seg_end = duration
+    endif
+
+    Extract part... seg_begin seg_end 1
+    channel = channel + 1
+    Extract one channel... channel
+
+**Key Notes:**
+
+- Always use :code:`Open long sound file` to ensure compatibility with the system.
+- The `padding` field allows flexibility by extending the actual start and end times of the segment (default is 0.1s).
+- Channel indexing starts at 0 in the system, so increment by 1 for use in Praat (Praat uses 1-based indexing).
+
+**Output Requirements:**
+
+- Print results to the Praat Info window in this format:
+    - The first line contains space-separated column names (property names to be saved in the database).
+    - The second line contains space-separated measurements for each property.
+
+An example of the Praat output::
 
     peak slope cog spread
     5540.7376 24.3507 6744.0670 1562.1936
 
-  Output format if you are only taking one measure::
+Output format if you are only taking one measure::
 
     cog
     6013.9
 
-To run :code:`analyze_script`, do the following: 
+To run :code:`analyze_script`, follow these steps:
+
+    1. (Optional) Encode a subset for the annotation type you want to analyze.
+    2. Call :code:`analyze_script` with the annotation type, the subset name and the path to your script.
+
+.. code-block:: python
+
+    with CorpusContext(config) as c:
+        c.encode_type_subset('phone', ['S', 'Z', 'SH', 'ZH'], 'sibilant')
+        c.analyze_script(subset='sibilant', annotation_type="phone", script_path='path/to/script/sibilant.praat')
+
+
+analyze_track_script
+--------------------
+
+This function shares the same input formats and functionality as :code:`analyze_script`. However, 
+:code:`analyze_track_script` is specifically designed for continuous measurements.
+Before using this functionality, you must add utterance encoding. When calling the API, you will 
+need to specify an annotation type (e.g., phone, syllable, or word) to perform the analysis. 
+The script will then run separately for each instance of the selected annotation type in a multiprocessing manner.
 
-1. encode a phone class for the subset of phones you would like to analyze
-2. call :code:`analyze_script` on that phone class, with the path to your script
+**Output Requirements:**
 
-For example, to run a script which takes measures for sibilants:
+- Print results to the Praat Info window in the following format:
+    - The first line begins with time, followed by space-separated column names.
+    - Subsequent lines contain timestamps and measurements for each property.
+
+Example output::
+
+    time    f1  f2  f3  f4
+    0.000   502 1497    2502    3498
+    0.050   518 1483    2475    3452
+    0.100   537 1471    2462    3441
 
 .. code-block:: python
 
     with CorpusContext(config) as c:
-        c.encode_class(['S', 'Z', 'SH', 'ZH'], 'sibilant')
-        c.analyze_script('sibilant', 'path/to/script/sibilant.praat')
+        script_path = 'voice_quality.praat'
+        c.config.praat_path = '/path/to/your/praat/executable'
+        props = [('H1_H2', float), ('H1_A1',float), ('H1_A2',float), ('H1_A3',float)]
+        c.analyze_track_script('voice_quality', props, script_path, annotation_type='phone')
+
+
+Encoding acoustic track statistics
+==================================
+
+After encoding an acoustic track measurement—either through the built-in algorithms or custom Praat scripts—
+you can perform statistical aggregation on these data tracks. The supported statistical measures are: mean, median, 
+standard deviation (stddev), sum, mode, and count. 
+Aggregation can be performed on a specified annotation type, such as phones, words, or syllables 
+(if syllable encoding is available). The aggregation is conducted for all annotations with the same label.
+Aggregation can be performed by speaker, in which case the results will be grouped by speaker, 
+and each (annotation_label, speaker) pair will have its corresponding statistical measure computed.
+Once encoded, the computed statistics are stored and can be queried later.
+
+.. code-block:: python
+
+    with CorpusContext(config) as c:        
+        # Encode a statistic for an acoustic measure
+        c.encode_acoustic_statistic('formants', 'mean', by_annotation='phone', by_speaker=True)
+        
+        # Alternatively, call the get function directly; it will encode the statistic if not already available
+        results = c.get_acoustic_statistic('formants', 'mean', by_annotation='phone', by_speaker=True)
+

docs/source/developer_influxdb_implementation.rst

@@ -42,16 +42,16 @@ along with the ``time`` in seconds will always give a unique acoustic time point
 
 
 In addition to these tags, there are several queryable fields which are always present in addition to the measurement fields.
-First, the ``phone`` for the time point is saved to allow for efficient aggregation across phones.  Second, the ``utterance_id``
-for the time point is also saved.  The ``utterance_id`` is used for general querying, where each utterance's track for the
+First, the ``phone``, ``word``, ``syllable``(if syllable encoding has been performed for the corpus) for the time point are saved to allow for efficient aggregation across annotations.  
+Second, the ``utterance_id``for the time point is also saved.  The ``utterance_id`` is used for general querying, where each utterance's track for the
 requested acoustic property is queried once and then cached for any further results to use without needing to query the
 InfluxDB again.  For instance, a query on phone formant tracks might return 2000 phones.  Without the ``utterance_id``, there
 would be 2000 look ups for formant tracks (each InfluxDB query would take about 0.15 seconds), but using the utterance-based caching,
 the number of hits to the InfluxDB database would be a fraction (though the queries themselves would take a little bit longer).
 
 .. note::
 
-   For performance reasons internal to InfluxDB, ``phone`` and ``utterance_id`` are ``fields`` rather than ``tags``, because
+   For performance reasons internal to InfluxDB, ``phone``, ``syllable``, ``word``, and ``utterance_id`` are ``fields`` rather than ``tags``, because
    the cross of them with ``speaker``, ``discourse``, and ``channel`` would lead to an extremely large cross of possible tag
    combinations.  This mix of tags and fields has been found to be the most performant.
 

docs/source/queries_annotations.rst

@@ -179,7 +179,7 @@ contains.
 
    with CorpusContext(config) as c:
        q = c.query_graph(c.word)
-       q = q.columns(c.word.phone.label.column('phones'))
+       q = q.columns(c.word.phone.label.column_name('phones'))
        results = q.all()
        print(results)
 
@@ -210,8 +210,8 @@ The keyword ``count`` will return the number of elements.
 
    with CorpusContext(config) as c:
        q = c.query_graph(c.word)
-       q = q.columns(c.word.phone.rate.column('phones_per_second'))
-       q = q.columns(c.word.phone.count.column('num_phones'))
+       q = q.columns(c.word.phone.rate.column_name('phones_per_second'))
+       q = q.columns(c.word.phone.count.column_name('num_phones'))
        results = q.all()
        print(results)
 
@@ -221,9 +221,9 @@ These keywords can also leverage subsets, as above:
 
    with CorpusContext(config) as c:
        q = c.query_graph(c.word)
-       q = q.columns(c.word.phone.rate.column('phones_per_second'))
-       q = q.columns(c.word.phone.filter_by_subset('+syllabic').count.column('num_syllabic_phones'))
-       q = q.columns(c.word.phone.count.column('num_phones'))
+       q = q.columns(c.word.phone.rate.column_name('phones_per_second'))
+       q = q.columns(c.word.phone.filter_by_subset('+syllabic').count.column_name('num_syllabic_phones'))
+       q = q.columns(c.word.phone.count.column_name('num_phones'))
        results = q.all()
        print(results)
 

polyglotdb/acoustics/other.py

@@ -34,9 +34,8 @@ def generate_praat_script_function(praat_path, script_path, arguments=None):
 
 
 def analyze_script(corpus_context,
-                   phone_class=None,
+                   annotation_type='phone',
                    subset=None,
-                   annotation_type=None,
                    script_path=None,
                    duration_threshold=0.01,
                    arguments=None,
@@ -58,8 +57,6 @@ def analyze_script(corpus_context,
     ----------
     corpus_context : :class:`~polyglot.corpus.context.CorpusContext`
         corpus context to use
-    phone_class : str
-        DEPRECATED, the name of an already encoded subset of phones on which the analysis will be run
     subset : str, optional
         the name of an already encoded subset of an annotation type, on which the analysis will be run
     annotation_type : str
@@ -81,12 +78,13 @@ def analyze_script(corpus_context,
     """
     if file_type not in ['consonant', 'vowel', 'low_freq']:
         raise ValueError('File type must be one of: consonant, vowel, or low_freq')
-
-    if phone_class is not None:
-        raise DeprecationWarning("The phone_class parameter has now been deprecated, please use annotation_type='phone' and subset='{}'".format(phone_class))
-        annotation_type = corpus_context.phone_name
-        subset = phone_class
-
+    
+    if not annotation_type in corpus_context.hierarchy.annotation_types:
+        raise ValueError('Annotation type does not exists')
+    
+    if script_path is None: 
+        raise ValueError('Please specify script path')
+    
     if call_back is not None:
         call_back('Analyzing {}...'.format(annotation_type))
     time_section = time.time()
@@ -111,25 +109,35 @@ def analyze_script(corpus_context,
 def analyze_track_script(corpus_context,
                          acoustic_name,
                          properties,
-                         script_path,
+                         script_path=None,
+                         subset=None,
+                         annotation_type='phone',
                          duration_threshold=0.01,
-                         phone_class=None,
                          arguments=None,
                          call_back=None,
                          file_type='consonant',
                          stop_check=None, multiprocessing=True):
+    
     if file_type not in ['consonant', 'vowel', 'low_freq']:
         raise ValueError('File type must be one of: consonant, vowel, or low_freq')
+
+    if not annotation_type in corpus_context.hierarchy.annotation_types:
+        raise ValueError('Annotation type does not exists')
+    
+    if script_path is None: 
+        raise ValueError('Please specify script path')
+    
     if acoustic_name not in corpus_context.hierarchy.acoustics:
         corpus_context.hierarchy.add_acoustic_properties(corpus_context, acoustic_name, properties)
         corpus_context.encode_hierarchy()
+    else: 
+        raise ValueError('Acoustic measure already exists')
+
     if call_back is not None:
-        call_back('Analyzing phones...')
-    if phone_class is None:
-        segment_mapping = generate_utterance_segments(corpus_context, padding=PADDING)
-    else:
-        segment_mapping = generate_segments(corpus_context, corpus_context.phone_name, phone_class, file_type=file_type,
-                                            padding=PADDING, duration_threshold=duration_threshold)
+        call_back('Analyzing track...')
+
+    segment_mapping = generate_segments(corpus_context, annotation_type, subset, file_type=file_type,
+                                        padding=PADDING, duration_threshold=duration_threshold)
 
     segment_mapping = segment_mapping.grouped_mapping('speaker')
     praat_path = corpus_context.config.praat_path