Merge pull request #182 from vocalpy/rename-parameters-for-consistency

Rename parameters for consistency
vocalpy · May 18, 2022 · 3efd406 · 3efd406
2 parents cc1a4d0 + 51e6672
commit 3efd406
Show file tree

Hide file tree

Showing 11 changed files with 104 additions and 103 deletions.
diff --git a/src/crowsetta/formats/seq/birdsongrec.py b/src/crowsetta/formats/seq/birdsongrec.py
@@ -36,8 +36,9 @@ class BirdsongRec:
         Extension of files in annotation format: ``'.xml'``.
     sequences: list
         List of ``birdsongrec.Sequence`` instances.
-    xml_path: pathlib.Path
+    annot_path: pathlib.Path
         Path to file from which annotations were loaded.
+        Typically with filename 'Annotation.xml'.
     wav_path: pathlib.Path
         Path to directory containing .wav files annotated by the .xml file.
         If not specified, defaults to directory "Wave", relative to the parent
@@ -82,19 +83,19 @@ class BirdsongRec:
     ext: ClassVar[str] = '.xml'
 
     sequences: List[birdsongrec.Sequence]
-    xml_path: pathlib.Path = attr.field(converter=pathlib.Path)
+    annot_path: pathlib.Path = attr.field(converter=pathlib.Path)
     wav_path: Optional[pathlib.Path] = attr.field(default=None, converter=attr.converters.optional(pathlib.Path))
 
     @classmethod
     def from_file(cls,
-                  xml_path: PathLike,
+                  annot_path: PathLike,
                   wav_path: Optional[PathLike] = None,
                   concat_seqs_into_songs: bool = True) -> 'Self':
         """Load BirdsongRecognition annotations from an .xml file.
 
         Parameters
         ----------
-        xml_path : str, pathlib.Path
+        annot_path : str, pathlib.Path
             Path to .xml file from BirdsongRecognition dataset
             that contains annotations.
         wav_path : str, pathlib.Path
@@ -120,25 +121,25 @@ def from_file(cls,
         --------
         >>> example = crowsetta.data.get('birdsong-recognition-dataset')
         >>> with example.annot_path as annot_path:
-        ...     birdsongrec = crowsetta.formats.seq.BirdsongRec.from_file(xml_path=annot_path)
+        ...     birdsongrec = crowsetta.formats.seq.BirdsongRec.from_file(annot_path=annot_path)
         """
-        xml_path = pathlib.Path(xml_path)
-        crowsetta.validation.validate_ext(xml_path, extension=cls.ext)
-        if not xml_path.exists():
+        annot_path = pathlib.Path(annot_path)
+        crowsetta.validation.validate_ext(annot_path, extension=cls.ext)
+        if not annot_path.exists():
             raise FileNotFoundError(
-                f"xml_path not found: {xml_path}"
+                f"annot_path not found: {annot_path}"
             )
 
         if wav_path is None:
-            wav_path = xml_path.parent.joinpath('Wave')
+            wav_path = annot_path.parent.joinpath('Wave')
         else:
             wav_path = pathlib.Path(wav_path)
 
         # `birdsong-recongition-dataset` has a 'Sequence' class
         # but it is different from a `crowsetta.Sequence`
-        birdsongrec_seqs = birdsongrec.parse_xml(xml_path,
+        birdsongrec_seqs = birdsongrec.parse_xml(annot_path,
                                                  concat_seqs_into_songs=concat_seqs_into_songs)
-        return cls(sequences=birdsongrec_seqs, xml_path=xml_path, wav_path=wav_path)
+        return cls(sequences=birdsongrec_seqs, annot_path=annot_path, wav_path=wav_path)
 
     def to_seq(self,
                round_times: bool = True,
@@ -175,7 +176,7 @@ def to_seq(self,
         --------
         >>> example = crowsetta.data.get('birdsong-recognition-dataset')
         >>> with example.annot_path as annot_path:
-        ...     birdsongrec = crowsetta.formats.seq.BirdsongRec.from_file(xml_path=annot_path)
+        ...     birdsongrec = crowsetta.formats.seq.BirdsongRec.from_file(annot_path=annot_path)
         >>> seqs = birdsongrec.to_seq()
 
         Notes
@@ -277,7 +278,7 @@ def to_annot(self,
         --------
         >>> example = crowsetta.data.get('birdsong-recognition-dataset')
         >>> with example.annot_path as annot_path:
-        ...     birdsongrec = crowsetta.formats.seq.BirdsongRec.from_file(xml_path=annot_path)
+        ...     birdsongrec = crowsetta.formats.seq.BirdsongRec.from_file(annot_path=annot_path)
         >>> annots = birdsongrec.to_annot()
 
         Notes
@@ -308,6 +309,6 @@ def to_annot(self,
         annot_list = []
         for seq, wav_filename in zip(seqs, wav_filenames):
             annot_list.append(
-                crowsetta.Annotation(seq=seq, annot_path=self.xml_path, notated_path=wav_filename)
+                crowsetta.Annotation(seq=seq, annot_path=self.annot_path, notated_path=wav_filename)
             )
         return annot_list
diff --git a/src/crowsetta/formats/seq/generic.py b/src/crowsetta/formats/seq/generic.py
@@ -280,12 +280,12 @@ class that represents annotations from a generic format,
 
     @classmethod
     def from_file(cls,
-                  csv_path: PathLike) -> 'Self':
+                  annot_path: PathLike) -> 'Self':
         """load annotations in 'generic-seq' format from a .csv file
 
         Parameters
         ----------
-        csv_path : str, pathlib.Path
+        annot_path : str, pathlib.Path
             Path to .csv file containing annotations
             saved in the ``'generic-seq'`` format.
 
@@ -295,7 +295,7 @@ def from_file(cls,
         >>> with example.annot_path as annot_path:
         ...     generic = crowsetta.formats.seq.GenericSeq.from_file(annot_path))
         """
-        annots = csv2annot(csv_path=csv_path)
+        annots = csv2annot(csv_path=annot_path)
         return cls(annots=annots)
 
     def to_seq(self) -> List[crowsetta.Sequence]:
@@ -329,15 +329,15 @@ def to_annot(self) -> List[crowsetta.Annotation]:
         return self.annots
 
     def to_file(self,
-                csv_path: PathLike,
+                annot_path: PathLike,
                 abspath: bool = False,
                 basename: bool = False) -> None:
         """writes these annotations to a .csv file
         in ``'generic-seq'`` format.
 
         Parameters
         ----------
-        csv_path : str, pathlib.Path
+        annot_path : str, pathlib.Path
             path including filename of .csv to write to,
             will be created (or overwritten if it exists already)
         abspath : bool
@@ -347,7 +347,7 @@ def to_file(self,
             if True, discard any information about path and just use file name.
             Default is False.
         """
-        annot2csv(csv_path=csv_path,
+        annot2csv(csv_path=annot_path,
                   annot=self.annots,
                   abspath=abspath,
                   basename=basename)
diff --git a/src/crowsetta/formats/seq/notmat.py b/src/crowsetta/formats/seq/notmat.py
@@ -32,11 +32,11 @@ class NotMat:
         Offset times of segments, in seconds.
     labels : numpy.ndarray
         Labels for segments.
-    notmat_path : str, pathlib.Path
+    annot_path : str, pathlib.Path
         Path to .not.mat file from which
         annotations were loaded.
     audio_path : str, pathlib.Path
-        Path to audio file that ``notmat_path`` annotates.
+        Path to audio file that ``annot_path`` annotates.
 
     Notes
     -----
@@ -50,28 +50,28 @@ class NotMat:
     onsets: np.ndarray = attr.field(eq=attr.cmp_using(eq=np.array_equal))
     offsets: np.ndarray = attr.field(eq=attr.cmp_using(eq=np.array_equal))
     labels: np.ndarray = attr.field(eq=attr.cmp_using(eq=np.array_equal))
-    notmat_path: pathlib.Path
+    annot_path: pathlib.Path
     audio_path: pathlib.Path
 
     @classmethod
     def from_file(cls,
-                  notmat_path: PathLike) -> 'Self':
+                  annot_path: PathLike) -> 'Self':
         """load annotations from .not.mat file
 
         Parameters
         ----------
-        notmat_path: str, pathlib.Path
+        annot_path: str, pathlib.Path
             Path to a .not.mat file saved by the evsonganaly GUI.
 
         Examples
         --------
         >>> example = crowsetta.data.get('notmat')
         >>> with example.annot_path as annot_path:
-        ...     notmat = crowsetta.formats.seq.NotMat.from_file(notmat_path=annot_path)
+        ...     notmat = crowsetta.formats.seq.NotMat.from_file(annot_path=annot_path)
         """
-        notmat_path = pathlib.Path(notmat_path)
-        crowsetta.validation.validate_ext(notmat_path, extension=cls.ext)
-        notmat_dict = evfuncs.load_notmat(notmat_path)
+        annot_path = pathlib.Path(annot_path)
+        crowsetta.validation.validate_ext(annot_path, extension=cls.ext)
+        notmat_dict = evfuncs.load_notmat(annot_path)
         # in .not.mat files saved by evsonganaly,
         # onsets and offsets are in units of ms, have to convert to s
         onsets = notmat_dict['onsets'] / 1000
@@ -80,8 +80,8 @@ def from_file(cls,
             list(notmat_dict['labels'])
         )
 
-        audio_path = notmat_path.parent / notmat_path.name.replace('.not.mat', '')
-        return cls(notmat_path=notmat_path,
+        audio_path = annot_path.parent / annot_path.name.replace('.not.mat', '')
+        return cls(annot_path=annot_path,
                    onsets=onsets,
                    offsets=offsets,
                    labels=labels,
@@ -110,7 +110,7 @@ def to_seq(self,
         --------
         >>> example = crowsetta.data.get('notmat')
         >>> with example.annot_path as annot_path:
-        ...     notmat = crowsetta.formats.seq.NotMat.from_file(notmat_path=annot_path)
+        ...     notmat = crowsetta.formats.seq.NotMat.from_file(annot_path=annot_path)
         >>> seq = notmat.to_seq()
 
         Notes
@@ -156,7 +156,7 @@ def to_annot(self,
         --------
         >>> example = crowsetta.data.get('notmat')
         >>> with example.annot_path as annot_path:
-        ...     notmat = crowsetta.formats.seq.NotMat.from_file(notmat_path=annot_path)
+        ...     notmat = crowsetta.formats.seq.NotMat.from_file(annot_path=annot_path)
         >>> annot = notmat.to_annot()
 
         Notes
@@ -169,7 +169,7 @@ def to_annot(self,
         """
         seq = self.to_seq(round_times=round_times, decimals=decimals)
 
-        return crowsetta.Annotation(annot_path=self.notmat_path,
+        return crowsetta.Annotation(annot_path=self.annot_path,
                                     notated_path=self.audio_path,
                                     seq=seq)
 

diff --git a/src/crowsetta/formats/seq/simple.py b/src/crowsetta/formats/seq/simple.py
@@ -18,7 +18,7 @@
 i.e. a single audio or spectrogram file.
 """
 import pathlib
-from typing import ClassVar, List, Mapping, Optional
+from typing import ClassVar, Mapping, Optional
 
 import attr
 import numpy as np

diff --git a/src/crowsetta/formats/seq/textgrid.py b/src/crowsetta/formats/seq/textgrid.py
@@ -36,10 +36,10 @@ class TextGrid:
         Extension of files in annotation format: ``'.TextGrid'``.
     textgrid : textgrid.TextGrid
         object that contains annotations from the a '.TextGrid' file.
-    textgrid_path : str, pathlib.Path
+    annot_path : str, pathlib.Path
         Path to .TextGrid file from which annotations were loaded.
     audio_path : str, pathlib.Path
-        Path to audio file that ``textgrid_path`` annotates.
+        Path to audio file that ``annot_path`` annotates.
 
     Notes
     -----
@@ -59,20 +59,20 @@ class TextGrid:
     ext: ClassVar[str] = '.TextGrid'
 
     textgrid: textgrid.TextGrid
-    textgrid_path: pathlib.Path
+    annot_path: pathlib.Path
     audio_path: Optional[pathlib.Path] = attr.field(default=None, converter=attr.converters.optional(pathlib.Path))
 
     @classmethod
     def from_file(cls,
-                  textgrid_path: PathLike,
+                  annot_path: PathLike,
                   audio_path: Optional[PathLike] = None,
                   ) -> 'Self':
         """load annotations from .TextGrid file,
         like those generated by the Praat application.
 
         Parameters
         ----------
-        textgrid_path: str, pathlib.Path
+        annot_path: str, pathlib.Path
             Path to a .TextGrid file in the format used by Praat.
         audio_path : str. pathlib.Path
             Path to audio file that the ``annot_path`` annotates.
@@ -82,15 +82,15 @@ def from_file(cls,
         --------
         >>> example = crowsetta.data.get('textgrid')
         >>> with example.annot_path as annot_path:
-        ...    textgrid = crowsetta.formats.seq.TextGrid.from_file(textgrid_path=annot_path)
+        ...    textgrid = crowsetta.formats.seq.TextGrid.from_file(annot_path=annot_path)
         """
-        textgrid_path = pathlib.Path(textgrid_path)
-        crowsetta.validation.validate_ext(textgrid_path, extension=cls.ext)
+        annot_path = pathlib.Path(annot_path)
+        crowsetta.validation.validate_ext(annot_path, extension=cls.ext)
 
-        tg = textgrid.TextGrid.fromFile(textgrid_path)
+        tg = textgrid.TextGrid.fromFile(annot_path)
 
         return cls(textgrid=tg,
-                   textgrid_path=textgrid_path,
+                   annot_path=annot_path,
                    audio_path=audio_path)
 
     def to_seq(self,
@@ -125,7 +125,7 @@ def to_seq(self,
         --------
         >>> example = crowsetta.data.get('textgrid')
         >>> with example.annot_path as annot_path:
-        ...    textgrid = crowsetta.formats.seq.TextGrid.from_file(textgrid_path=annot_path)
+        ...    textgrid = crowsetta.formats.seq.TextGrid.from_file(annot_path=annot_path)
         >>> seq = textgrid.to_seq()
 
         Notes
@@ -193,7 +193,7 @@ def to_annot(self,
         --------
         >>> example = crowsetta.data.get('textgrid')
         >>> with example.annot_path as annot_path:
-        ...    textgrid = crowsetta.formats.seq.TextGrid.from_file(textgrid_path=annot_path)
+        ...    textgrid = crowsetta.formats.seq.TextGrid.from_file(annot_path=annot_path)
         >>> annot = textgrid.to_annot()
 
         Notes
@@ -208,6 +208,6 @@ def to_annot(self,
                           round_times=round_times,
                           decimals=decimals)
 
-        return crowsetta.Annotation(annot_path=self.textgrid_path,
+        return crowsetta.Annotation(annot_path=self.annot_path,
                                     notated_path=self.audio_path,
                                     seq=seq)