praatio.data_classes.textgrid_tier

  1"""
  2The abstract class used by all textgrid tiers
  3"""
  4import re
  5import copy
  6import math
  7from typing import (
  8    List,
  9    Optional,
 10    Type,
 11    TypeVar,
 12    Union,
 13)
 14from abc import ABC, abstractmethod
 15
 16from typing_extensions import Literal
 17
 18
 19from praatio.utilities import constants
 20from praatio.utilities import errors
 21from praatio.utilities import utils
 22
 23T = TypeVar("T", bound="TextgridTier")
 24
 25
 26class TextgridTier(ABC):
 27    tierType: str
 28    entryType: Union[Type[constants.Point], Type[constants.Interval]]
 29
 30    def __init__(
 31        self,
 32        name: str,
 33        entries: List,
 34        minT: float,
 35        maxT: float,
 36        errorMode: Literal["silence", "warning", "error"] = "warning",
 37    ):
 38        "A container that stores and operates over interval and point tiers"
 39        utils.validateOption("errorMode", errorMode, constants.ErrorReportingMode)
 40
 41        """See PointTier or IntervalTier"""
 42        entries.sort()
 43
 44        self.name = name
 45        self._entries = entries
 46        self.minTimestamp = minT
 47        self.maxTimestamp = maxT
 48        self.errorReporter = utils.getErrorReporter(errorMode)
 49
 50    def __len__(self):
 51        return len(self._entries)
 52
 53    def __iter__(self):
 54        for entry in self.entries:
 55            yield entry
 56
 57    def __eq__(self, other):
 58        if not isinstance(self, type(other)):
 59            return False
 60
 61        isEqual = True
 62        isEqual &= self.name == other.name
 63        isEqual &= math.isclose(self.minTimestamp, other.minTimestamp)
 64        isEqual &= math.isclose(self.maxTimestamp, other.maxTimestamp)
 65        isEqual &= len(self.entries) == len(other.entries)
 66
 67        # TODO: Intervals and Points now use isclose, so we can simplify this
 68        #       logic (selfEntry == otherEntry); however, this will break
 69        #       things for klattgrids
 70        if isEqual:
 71            for selfEntry, otherEntry in zip(self.entries, other.entries):
 72                for selfSubEntry, otherSubEntry in zip(selfEntry, otherEntry):
 73                    try:
 74                        isEqual &= math.isclose(selfSubEntry, otherSubEntry)
 75                    except TypeError:
 76                        isEqual &= selfSubEntry == otherSubEntry
 77
 78        return isEqual
 79
 80    @property
 81    def entries(self):
 82        return tuple(self._entries)
 83
 84    @property
 85    @abstractmethod
 86    def timestamps(self) -> List[float]:
 87        pass
 88
 89    def appendTier(self, tier: "TextgridTier") -> "TextgridTier":
 90        """Append a tier to the end of this one.
 91
 92        This tier's maxtimestamp will be lengthened by the amount in the passed in tier.
 93        """
 94        if self.tierType != tier.tierType:
 95            raise errors.ArgumentError(
 96                f"Cannot append a tier of type {type(self)} to a tier of type {type(tier)}."
 97            )
 98
 99        maxTime = self.maxTimestamp + tier.maxTimestamp
100
101        # We're increasing the size of the tier, so of course its intervals
102        # may exceed the bounds of the tier's maxTimestamp, triggering
103        # errors/warnings--we can ignore those
104        appendTier = tier.editTimestamps(
105            self.maxTimestamp, constants.ErrorReportingMode.SILENCE
106        )
107
108        entries = self._entries + appendTier._entries
109        entries.sort()
110
111        return self.new(
112            self.name, entries, minTimestamp=self.minTimestamp, maxTimestamp=maxTime
113        )
114
115    def find(
116        self,
117        matchLabel: str,
118        substrMatchFlag: bool = False,
119        usingRE: bool = False,
120    ) -> List[int]:
121        """Returns the index of all intervals that match the given label
122
123        Args:
124            matchLabel: the label to search for
125            substrMatchFlag: if True, match any label containing matchLabel.
126                if False, label must be the same as matchLabel.
127            usingRE: if True, matchLabel is interpreted as a regular expression
128
129        Returns:
130            A list of indicies
131        """
132        returnList = []
133        if usingRE is True:
134            for i, entry in enumerate(self.entries):
135                matchList = re.findall(matchLabel, entry.label, re.I)
136                if matchList != []:
137                    returnList.append(i)
138        else:
139            for i, entry in enumerate(self.entries):
140                if not substrMatchFlag:
141                    if entry.label == matchLabel:
142                        returnList.append(i)
143                else:
144                    if matchLabel in entry.label:
145                        returnList.append(i)
146
147        return returnList
148
149    def new(
150        self: T,
151        name: Optional[str] = None,
152        entries: Optional[list] = None,
153        minTimestamp: Optional[float] = None,
154        maxTimestamp: Optional[float] = None,
155    ) -> T:
156        """Make a new tier derived from the current one"""
157        if name is None:
158            name = self.name
159        if entries is None:
160            entries = copy.deepcopy(self.entries)
161            entries = [
162                self.entryType(*entry)
163                if isinstance(entry, tuple) or isinstance(entry, list)
164                else entry
165                for entry in entries
166            ]
167        if minTimestamp is None:
168            minTimestamp = self.minTimestamp
169        if maxTimestamp is None:
170            maxTimestamp = self.maxTimestamp
171        return type(self)(name, entries, minTimestamp, maxTimestamp)
172
173    def sort(self) -> None:
174        """Sorts the entries in the list of entries"""
175        # A list containing tuples and lists will be sorted with tuples
176        # first and then lists.  To correctly sort, we need to make
177        # sure that all data structures inside the entry list are
178        # of the same data type.  The entry list is sorted whenever
179        # the entry list is modified, so this is probably the best
180        # place to enforce the data type
181        self._entries = [
182            entry if isinstance(entry, self.entryType) else self.entryType(*entry)
183            for entry in self.entries
184        ]
185        self._entries.sort()
186
187    def union(self, tier: "TextgridTier") -> "TextgridTier":
188        """The given tier is set unioned to this tier.
189
190        All entries in the given tier are added to the current tier.
191        Overlapping entries are merged.
192        """
193        retTier = self.new()
194
195        for entry in tier.entries:
196            retTier.insertEntry(
197                entry,
198                collisionMode=constants.IntervalCollision.MERGE,
199                collisionReportingMode=constants.ErrorReportingMode.SILENCE,
200            )
201
202        retTier.sort()
203
204        return retTier
205
206    @abstractmethod
207    def editTimestamps(
208        self,
209        offset: float,
210        reportingMode: Literal["silence", "warning", "error"] = "warning",
211    ) -> "TextgridTier":  # pragma: no cover
212        pass
213
214    @abstractmethod
215    def insertEntry(
216        self,
217        entry,
218        collisionMode: Literal["replace", "merge", "error"] = "error",
219        collisionReportingMode: Literal["silence", "warning"] = "warning",
220    ) -> None:  # pragma: no cover
221        pass
222
223    @abstractmethod
224    def dejitter(
225        self,
226        referenceTier: "TextgridTier",
227        maxDifference: float = 0.001,
228    ) -> "TextgridTier":  # pragma: no cover
229        pass
230
231    @abstractmethod
232    def eraseRegion(
233        self,
234        start: float,
235        end: float,
236        collisionMode: Literal["truncate", "categorical", "error"] = "error",
237        doShrink: bool = True,
238    ) -> "TextgridTier":  # pragma: no cover
239        pass
240
241    @abstractmethod
242    def crop(
243        self,
244        cropStart: float,
245        cropEnd: float,
246        mode: Literal["strict", "lax", "truncated"],
247        rebaseToZero: bool,
248    ) -> "TextgridTier":  # pragma: no cover
249        pass
250
251    @abstractmethod
252    def insertSpace(
253        self,
254        start: float,
255        duration: float,
256        collisionMode: Literal["stretch", "split", "no_change", "error"],
257    ) -> "TextgridTier":  # pragma: no cover
258        pass
259
260    @abstractmethod
261    def deleteEntry(self, entry) -> None:  # pragma: no cover
262        pass
263
264    @abstractmethod
265    def validate(self, reportingMode) -> bool:  # pragma: no cover
266        pass