praatio.data_classes.textgrid

  1"""
  2Functions for reading/writing/manipulating Textgrid classes
  3
  4This is the 'heart' of praatio.
  5"""
  6import io
  7import copy
  8from typing import Optional, Tuple, Sequence
  9from typing_extensions import Literal
 10from collections import OrderedDict
 11
 12
 13from praatio.utilities.constants import (
 14    TextgridFormats,
 15    MIN_INTERVAL_LENGTH,
 16    CropCollision,
 17)
 18
 19from praatio.data_classes import textgrid_tier
 20from praatio.data_classes import point_tier
 21from praatio.data_classes import interval_tier
 22from praatio.utilities import constants
 23from praatio.utilities import errors
 24from praatio.utilities import my_math
 25from praatio.utilities import textgrid_io
 26from praatio.utilities import utils
 27
 28
 29class Textgrid:
 30    """A container that stores and operates over interval and point tiers
 31
 32    Textgrids are used by the Praat software to group tiers.  Each tier
 33    contains different annotation information for an audio recording.
 34
 35    Attributes:
 36        tierNames(Tuple[str]): the list of tier names in the textgrid
 37        tiers(Tuple[TextgridTier]): the list of ordered tiers
 38        minTimestamp(float): the minimum allowable timestamp in the textgrid
 39        maxTimestamp(float): the maximum allowable timestamp in the textgrid
 40    """
 41
 42    def __init__(self, minTimestamp: float = None, maxTimestamp: float = None):
 43        """Constructor for Textgrids
 44
 45        Args:
 46            minTimestamp: the minimum allowable timestamp in the textgrid
 47            maxTimestamp: the maximum allowable timestamp in the textgrid
 48        """
 49
 50        self._tierDict: OrderedDict[str, textgrid_tier.TextgridTier] = OrderedDict()
 51
 52        # Timestamps are determined by the first tier added
 53        self.minTimestamp: float = minTimestamp  # type: ignore[assignment]
 54        self.maxTimestamp: float = maxTimestamp  # type: ignore[assignment]
 55
 56    def __len__(self):
 57        return len(self._tierDict)
 58
 59    def __iter__(self):
 60        for entry in self.tiers:
 61            yield entry
 62
 63    def __eq__(self, other):
 64        if not isinstance(other, Textgrid):
 65            return False
 66
 67        isEqual = True
 68        isEqual &= my_math.isclose(self.minTimestamp, other.minTimestamp)
 69        isEqual &= my_math.isclose(self.maxTimestamp, other.maxTimestamp)
 70
 71        isEqual &= self.tierNames == other.tierNames
 72        if isEqual:
 73            for tierName in self.tierNames:
 74                isEqual &= self.getTier(tierName) == other.getTier(tierName)
 75
 76        return isEqual
 77
 78    @property
 79    def tierNames(self) -> Tuple[str, ...]:
 80        return tuple(self._tierDict.keys())
 81
 82    @property
 83    def tiers(self) -> Tuple[textgrid_tier.TextgridTier, ...]:
 84        return tuple(self._tierDict.values())
 85
 86    def addTier(
 87        self,
 88        tier: textgrid_tier.TextgridTier,
 89        tierIndex: Optional[int] = None,
 90        reportingMode: Literal["silence", "warning", "error"] = "warning",
 91    ) -> None:
 92        """Add a tier to this textgrid.
 93
 94        Args:
 95            tier: The tier to add to the textgrid
 96            tierIndex: Insert the tier into the specified position;
 97                if None, the tier will appear after all existing tiers
 98            reportingMode: This flag determines the behavior if there is a size
 99                difference between the maxTimestamp in the tier and the current
100                textgrid.
101
102        Returns:
103            None
104
105        Raises:
106            TierNameExistsError: The textgrid already contains a tier with the same
107                name as the tier being added
108            TextgridStateAutoModified: The minimum or maximum timestamp was changed
109                when not permitted
110            IndexError: TierIndex is too large for the size of the existing tier list
111        """
112        utils.validateOption(
113            "reportingMode", reportingMode, constants.ErrorReportingMode
114        )
115        errorReporter = utils.getErrorReporter(reportingMode)
116
117        if tier.name in self.tierNames:
118            raise errors.TierNameExistsError("Tier name already in tier")
119
120        if tierIndex is None:
121            self._tierDict[tier.name] = tier
122        else:  # Need to recreate the tierDict with the new order
123            newOrderedTierNameList = list(self.tierNames)
124            newOrderedTierNameList.insert(tierIndex, tier.name)
125
126            newTierDict = OrderedDict()
127            self._tierDict[tier.name] = tier
128            for tmpName in newOrderedTierNameList:
129                newTierDict[tmpName] = self.getTier(tmpName)
130            self._tierDict = newTierDict
131
132        minV = tier.minTimestamp
133        if self.minTimestamp is not None and minV < self.minTimestamp:
134            errorReporter(
135                errors.TextgridStateAutoModified,
136                f"Minimum timestamp in Textgrid changed from ({self.minTimestamp}) to ({minV})",
137            )
138        if self.minTimestamp is None or minV < self.minTimestamp:
139            self.minTimestamp = minV
140
141        maxV = tier.maxTimestamp
142        if self.maxTimestamp is not None and maxV > self.maxTimestamp:
143            errorReporter(
144                errors.TextgridStateAutoModified,
145                f"Maximum timestamp in Textgrid changed from ({self.maxTimestamp}) to ({maxV})",
146            )
147        if self.maxTimestamp is None or maxV > self.maxTimestamp:
148            self.maxTimestamp = maxV
149
150    def appendTextgrid(self, tg: "Textgrid", onlyMatchingNames: bool) -> "Textgrid":
151        """Append one textgrid to the end of this one
152
153        Args:
154            tg: the textgrid to add to this one
155            onlyMatchingNames: if False, tiers that don't appear in both
156                textgrids will also appear
157
158        Returns:
159            the modified version of the current textgrid
160        """
161        minTime = self.minTimestamp
162        maxTime = self.maxTimestamp + tg.maxTimestamp
163        retTG = Textgrid(minTime, maxTime)
164
165        # Get all tier names.  Ordered first by this textgrid and
166        # then by the other textgrid.
167        combinedTierNames = list(self.tierNames)
168        for tierName in tg.tierNames:
169            if tierName not in combinedTierNames:
170                combinedTierNames.append(tierName)
171
172        # Determine the tier names that will be in the final textgrid
173        finalTierNames = []
174        if onlyMatchingNames is False:
175            finalTierNames = combinedTierNames
176        else:
177            for tierName in combinedTierNames:
178                if tierName in self.tierNames:
179                    if tierName in tg.tierNames:
180                        finalTierNames.append(tierName)
181
182        # Add tiers from this textgrid
183        for tierName in finalTierNames:
184            if tierName in self.tierNames:
185                tier = self.getTier(tierName)
186                retTG.addTier(tier)
187
188        # Add tiers from the given textgrid
189        for tierName in finalTierNames:
190            if tierName in tg.tierNames:
191                appendTier = tg.getTier(tierName)
192                appendTier = appendTier.new(minTimestamp=minTime, maxTimestamp=maxTime)
193
194                appendTier = appendTier.editTimestamps(self.maxTimestamp)
195
196                if tierName in retTG.tierNames:
197                    tier = retTG.getTier(tierName)
198                    newEntries = retTG.getTier(tierName).entries
199                    newEntries += appendTier.entries
200
201                    tier = tier.new(
202                        entries=newEntries,
203                        minTimestamp=minTime,
204                        maxTimestamp=maxTime,
205                    )
206                    retTG.replaceTier(tierName, tier)
207
208                else:
209                    tier = appendTier
210                    tier = tier.new(minTimestamp=minTime, maxTimestamp=maxTime)
211                    retTG.addTier(tier)
212
213        return retTG
214
215    def crop(
216        self,
217        cropStart: float,
218        cropEnd: float,
219        mode: Literal["strict", "lax", "truncated"],
220        rebaseToZero: bool,
221    ) -> "Textgrid":
222        """Creates a textgrid where all intervals fit within the crop region
223
224        Args:
225            cropStart: The start time of the crop interval
226            cropEnd: The stop time of the crop interval
227            mode: Determines the crop behavior
228                - 'strict', only intervals wholly contained by the crop
229                    interval will be kept
230                - 'lax', partially contained intervals will be kept
231                - 'truncated', partially contained intervals will be
232                    truncated to fit within the crop region.
233            rebaseToZero: if True, the cropped textgrid timestamps will be
234                subtracted by the cropStart; if False, timestamps will not
235                be changed
236
237        Returns:
238            the modified version of the current textgrid
239        """
240        utils.validateOption("mode", mode, CropCollision)
241
242        if cropStart >= cropEnd:
243            raise errors.ArgumentError(
244                f"Crop error: start time ({cropStart}) must occur before end time ({cropEnd})"
245            )
246
247        if rebaseToZero is True:
248            minT = 0.0
249            maxT = cropEnd - cropStart
250        else:
251            minT = cropStart
252            maxT = cropEnd
253        newTG = Textgrid(minT, maxT)
254
255        for tierName in self.tierNames:
256            tier = self.getTier(tierName)
257            newTier = tier.crop(cropStart, cropEnd, mode, rebaseToZero)
258
259            reportingMode: Literal[
260                "silence", "warning", "error"
261            ] = constants.ErrorReportingMode.WARNING
262            if mode == constants.CropCollision.LAX:
263                # We expect that there will be changes to the size
264                # of the textgrid when the mode is LAX
265                reportingMode = constants.ErrorReportingMode.SILENCE
266
267            newTG.addTier(newTier, reportingMode=reportingMode)
268
269        return newTG
270
271    def eraseRegion(self, start: float, end: float, doShrink: bool) -> "Textgrid":
272        """Makes a region in a tier blank (removes all contained entries)
273
274        Intervals that span the region to erase will be truncated.
275
276        Args:
277            start:
278            end:
279            doShrink: if True, all entries appearing after the
280                erased interval will be shifted to fill the void (ie
281                the duration of the textgrid will be reduced by
282                *start* - *end*)
283
284        Returns:
285            the modified version of the current textgrid
286
287        Raises:
288            ArgumentError
289        """
290        if start >= end:
291            raise errors.ArgumentError(
292                f"EraseRegion error: start time ({start}) must occur before end time ({end})"
293            )
294
295        diff = end - start
296
297        maxTimestamp = self.maxTimestamp
298        if doShrink is True:
299            maxTimestamp -= diff
300
301        newTG = Textgrid(self.minTimestamp, self.maxTimestamp)
302        for tier in self.tiers:
303            shrunkTier = tier.eraseRegion(
304                start, end, constants.EraseCollision.TRUNCATE, doShrink
305            )
306            newTG.addTier(shrunkTier)
307
308        newTG.maxTimestamp = maxTimestamp
309
310        return newTG
311
312    def editTimestamps(
313        self,
314        offset: float,
315        reportingMode: Literal["silence", "warning", "error"] = "warning",
316    ) -> "Textgrid":
317        """Modifies all timestamps by a constant amount
318
319        Args:
320            offset: the amount to offset in seconds
321            reportingMode: one of "silence", "warning", or "error". This flag
322                determines the behavior if there is a size difference between the
323                maxTimestamp in the tier and the current textgrid.
324
325        Returns:
326            Textgrid: the modified version of the current textgrid
327        """
328        utils.validateOption(
329            "reportingMode", reportingMode, constants.ErrorReportingMode
330        )
331
332        tg = Textgrid(self.minTimestamp, self.maxTimestamp)
333        for tier in self.tiers:
334            if len(tier.entries) > 0:
335                tier = tier.editTimestamps(offset, reportingMode)
336
337            tg.addTier(tier, reportingMode=reportingMode)
338
339        return tg
340
341    def getTier(self, tierName: str) -> textgrid_tier.TextgridTier:
342        """Get the tier with the specified name"""
343        return self._tierDict[tierName]
344
345    def insertSpace(
346        self,
347        start: float,
348        duration: float,
349        collisionMode: Literal["stretch", "split", "no_change", "error"] = "error",
350    ) -> "Textgrid":
351        """Inserts a blank region into a textgrid
352
353        Every item that occurs after *start* will be pushed back by
354        *duration* seconds
355
356        Args:
357            start:
358            duration:
359            collisionMode: Determines behavior in the event that an
360                interval stradles the starting point.
361                One of ['stretch', 'split', 'no change', None]
362                - 'stretch' stretches the interval by /duration/ amount
363                - 'split' splits the interval into two--everything to the
364                    right of 'start' will be advanced by 'duration' seconds
365                - 'no change' leaves the interval as is with no change
366                - None or any other value throws an AssertionError
367
368        Returns:
369            Textgrid: the modified version of the current textgrid
370        """
371        utils.validateOption(
372            "collisionMode", collisionMode, constants.WhitespaceCollision
373        )
374
375        newTG = Textgrid(self.minTimestamp, self.maxTimestamp)
376        newTG.minTimestamp = self.minTimestamp
377        newTG.maxTimestamp = self.maxTimestamp + duration
378
379        for tier in self.tiers:
380            newTier = tier.insertSpace(start, duration, collisionMode)
381            newTG.addTier(newTier)
382
383        return newTG
384
385    def mergeTiers(
386        self, tierNames: Optional[Sequence[str]] = None, preserveOtherTiers: bool = True
387    ) -> "Textgrid":
388        """Combine tiers
389
390        Args:
391            tierList: A list of tier names to combine. If none, combine
392                all tiers.
393            preserveOtherTiers: If false, uncombined tiers are not
394                included in the output.
395
396        Returns:
397            Textgrid: the modified version of the current textgrid
398        """
399        if tierNames is None:
400            tierNames = self.tierNames
401
402        # Determine the tiers to merge
403        intervalTierNames = []
404        pointTierNames = []
405        for tierName in tierNames:
406            tier = self.getTier(tierName)
407            if isinstance(tier, interval_tier.IntervalTier):
408                intervalTierNames.append(tierName)
409            elif isinstance(tier, point_tier.PointTier):
410                pointTierNames.append(tierName)
411
412        # Merge the interval tiers
413        intervalTier = None
414        if len(intervalTierNames) > 0:
415            intervalTier = self.getTier(intervalTierNames.pop(0))
416            for tierName in intervalTierNames:
417                intervalTier = intervalTier.union(self.getTier(tierName))
418
419        # Merge the point tiers
420        pointTier = None
421        if len(pointTierNames) > 0:
422            pointTier = self.getTier(pointTierNames.pop(0))
423            for tierName in pointTierNames:
424                pointTier = pointTier.union(self.getTier(tierName))
425
426        # Create the final textgrid to output
427        tg = Textgrid(self.minTimestamp, self.maxTimestamp)
428
429        if preserveOtherTiers:
430            for tier in self.tiers:
431                if tier.name not in tierNames:
432                    tg.addTier(tier)
433
434        if intervalTier is not None:
435            tg.addTier(intervalTier)
436
437        if pointTier is not None:
438            tg.addTier(pointTier)
439
440        return tg
441
442    def new(self) -> "Textgrid":
443        """Returns a copy of this Textgrid"""
444        return copy.deepcopy(self)
445
446    def save(
447        self,
448        fn: str,
449        format: Literal["short_textgrid", "long_textgrid", "json", "textgrid_json"],
450        includeBlankSpaces: bool,
451        minTimestamp: Optional[float] = None,
452        maxTimestamp: Optional[float] = None,
453        minimumIntervalLength: float = MIN_INTERVAL_LENGTH,
454        reportingMode: Literal["silence", "warning", "error"] = "warning",
455    ) -> None:
456        """Save the current textgrid to a file
457
458        Args:
459            fn: the fullpath filename of the output
460            format: one of ['short_textgrid', 'long_textgrid', 'json', 'textgrid_json']
461                'short_textgrid' and 'long_textgrid' are both used by praat
462                'json' and 'textgrid_json' are two json variants. 'json' cannot represent
463                tiers with different min and max timestamps than the textgrid.
464            includeBlankSpaces: if True, blank sections in interval
465                tiers will be filled in with an empty interval
466                (with a label of ""). If you are unsure, True is recommended
467                as Praat needs blanks to render textgrids properly.
468            minTimestamp: the minTimestamp of the saved Textgrid;
469                if None, use whatever is defined in the Textgrid object.
470                If minTimestamp is larger than timestamps in your textgrid,
471                an exception will be thrown.
472            maxTimestamp: the maxTimestamp of the saved Textgrid;
473                if None, use whatever is defined in the Textgrid object.
474                If maxTimestamp is smaller than timestamps in your textgrid,
475                an exception will be thrown.
476            minimumIntervalLength: any labeled intervals smaller
477                than this will be removed, useful for removing ultrashort
478                or fragmented intervals; if None, don't remove any.
479                Removed intervals are merged (without their label) into
480                adjacent entries.
481            reportingMode: one of "silence", "warning", or "error". This flag
482                determines the behavior if there is a size difference between the
483                maxTimestamp in the tier and the current textgrid.
484
485        Returns:
486            a string representation of the textgrid
487        """
488
489        utils.validateOption("format", format, TextgridFormats)
490        utils.validateOption(
491            "reportingMode", reportingMode, constants.ErrorReportingMode
492        )
493
494        self.validate(reportingMode)
495
496        tgAsDict = _tgToDictionary(self)
497
498        textgridStr = textgrid_io.getTextgridAsStr(
499            tgAsDict,
500            format,
501            includeBlankSpaces,
502            minTimestamp,
503            maxTimestamp,
504            minimumIntervalLength,
505        )
506
507        with io.open(fn, "w", encoding="utf-8") as fd:
508            fd.write(textgridStr)
509
510    def renameTier(self, oldName: str, newName: str) -> None:
511        oldTier = self.getTier(oldName)
512        tierIndex = self.tierNames.index(oldName)
513        self.removeTier(oldName)
514        self.addTier(oldTier.new(newName, oldTier.entries), tierIndex)
515
516    def removeTier(self, name: str) -> textgrid_tier.TextgridTier:
517        return self._tierDict.pop(name)
518
519    def replaceTier(
520        self,
521        name: str,
522        newTier: textgrid_tier.TextgridTier,
523        reportingMode: Literal["silence", "warning", "error"] = "warning",
524    ) -> None:
525        tierIndex = self.tierNames.index(name)
526        self.removeTier(name)
527        self.addTier(newTier, tierIndex, reportingMode)
528
529    def validate(
530        self, reportingMode: Literal["silence", "warning", "error"] = "warning"
531    ) -> bool:
532        """Validates this textgrid
533
534        Returns whether the textgrid is valid or not. If reportingMode is "warning"
535        or "error" this will also print on error or stop execution, respectively.
536
537        Args:
538            reportingMode: one of "silence", "warning", or "error". This flag
539                determines the behavior if there is a size difference between the
540                maxTimestamp in a tier and the current textgrid.
541
542        Returns:
543            True if this Textgrid is valid; False if not
544
545        Raises:
546            TierNameExistsError: Two tiers have the same name
547            TextgridStateError: A timestamp fall outside of the allowable range
548        """
549        utils.validateOption(
550            "reportingMode", reportingMode, constants.ErrorReportingMode
551        )
552        errorReporter = utils.getErrorReporter(reportingMode)
553
554        isValid = True
555        if len(self.tierNames) != len(set(self.tierNames)):
556            isValid = False
557            errorReporter(
558                errors.TierNameExistsError,
559                f"Tier names not unique: {self.tierNames}",
560            )
561
562        for tier in self.tiers:
563            if self.minTimestamp != tier.minTimestamp:
564                isValid = False
565                errorReporter(
566                    errors.TextgridStateError,
567                    f"Textgrid has a min timestamp of ({self.minTimestamp}) "
568                    f"but tier has ({tier.minTimestamp})",
569                )
570
571            if self.maxTimestamp != tier.maxTimestamp:
572                isValid = False
573                errorReporter(
574                    errors.TextgridStateError,
575                    f"Textgrid has a max timestamp of ({self.maxTimestamp}) "
576                    f"but tier has ({tier.maxTimestamp})",
577                )
578
579            isValid = isValid and tier.validate(reportingMode)
580
581        return isValid
582
583
584def _tgToDictionary(tg: Textgrid) -> dict:
585    tiers = []
586    for tier in tg.tiers:
587        tierAsDict = {
588            "class": tier.tierType,
589            "name": tier.name,
590            "xmin": tier.minTimestamp,
591            "xmax": tier.maxTimestamp,
592            "entries": tier.entries,
593        }
594        tiers.append(tierAsDict)
595
596    return {"xmin": tg.minTimestamp, "xmax": tg.maxTimestamp, "tiers": tiers}