patkit 0.22.1__tar.gz → 0.22.2__tar.gz

{patkit-0.22.1 → patkit-0.22.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patkit
-Version: 0.22.1
+Version: 0.22.2
 Summary: Phonetic Analysis ToolKit: Tools for processing phonetic data
 Project-URL: bug_tracker, https://github.com/giuthas/patkit/issues
 Project-URL: changelog, https://github.com/giuthas/patkit/blob/main/docs/Release_notes.markdown
@@ -715,6 +715,7 @@ Requires-Dist: sounddevice>=0.5.5
 Requires-Dist: strictyaml>=1.7.3
 Description-Content-Type: text/markdown
 
+[![test](https://github.com/giuthas/patkit/actions/workflows/test.yaml/badge.svg)](https://github.com/giuthas/patkit/actions/workflows/test.yaml)
 # PATKIT - Phonetic Analysis ToolKIT 
 
 ![PATKIT GUI](https://giuthas.github.io/patkit/PATKIT_UI_0.22.0.png)
@@ -748,10 +749,7 @@ thesis](https://eresearch.qmu.ac.uk/handle/20.500.12289/10163).
   - See [uv](https://docs.astral.sh/uv/#getting-started) for more details.
 - On the commandline run `uv tool install patkit`
 - Run `patkit --help` for instructions.
-- If you want to run the example data, get the `recorded_data` and `scenarios` folders from
-  [github](https://github.com/giuthas/patkit).
-  - Run `patkit scenarios/minimal` in the folder where you downloaded the data
-    and experiment from there.
+- If you want to run the example data, see 'What's included' below for instructions.
 
 - If on Linux of the debian variety (ubuntu, popos, others), you may also need 
 to run the following:
@@ -785,8 +783,9 @@ contents of the directory.
 Place the unzipped directories in the same directory and after installing
 patkit try running 
 ```
-patkit scenarios minimal
+patkit scenarios/minimal
 ```
+and experiment from there.
 
 TODO 1.0: Move the data elsewhere to be optionally loaded.
 

{patkit-0.22.1 → patkit-0.22.2}/README.md

@@ -1,3 +1,4 @@
+[![test](https://github.com/giuthas/patkit/actions/workflows/test.yaml/badge.svg)](https://github.com/giuthas/patkit/actions/workflows/test.yaml)
 # PATKIT - Phonetic Analysis ToolKIT 
 
 ![PATKIT GUI](https://giuthas.github.io/patkit/PATKIT_UI_0.22.0.png)
@@ -31,10 +32,7 @@ thesis](https://eresearch.qmu.ac.uk/handle/20.500.12289/10163).
   - See [uv](https://docs.astral.sh/uv/#getting-started) for more details.
 - On the commandline run `uv tool install patkit`
 - Run `patkit --help` for instructions.
-- If you want to run the example data, get the `recorded_data` and `scenarios` folders from
-  [github](https://github.com/giuthas/patkit).
-  - Run `patkit scenarios/minimal` in the folder where you downloaded the data
-    and experiment from there.
+- If you want to run the example data, see 'What's included' below for instructions.
 
 - If on Linux of the debian variety (ubuntu, popos, others), you may also need 
 to run the following:
@@ -68,8 +66,9 @@ contents of the directory.
 Place the unzipped directories in the same directory and after installing
 patkit try running 
 ```
-patkit scenarios minimal
+patkit scenarios/minimal
 ```
+and experiment from there.
 
 TODO 1.0: Move the data elsewhere to be optionally loaded.
 

{patkit-0.22.1 → patkit-0.22.2}/patkit/configuration/configuration.py

@@ -85,7 +85,7 @@ class ConfigPaths:
 
 class Configuration:
     """
-    Main configuration class of patkit.    
+    Main configuration class of patkit.
     """
 
     # TODO: implement save functionality.
@@ -95,7 +95,7 @@ class Configuration:
             configuration_paths: ConfigPaths
     ) -> None:
         """
-        Init the main configuration object. 
+        Init the main configuration object.
 
         Run only once. Updates should be done with methods of the class.
 
@@ -113,7 +113,8 @@ class Configuration:
             self._data_yaml = load_data_params(
                 self._config_paths.data_config)
             self._data_config = DataConfig(**self._data_yaml.data)
-            recorded = self._config_paths.path/self._data_config.recorded_data_path
+            recorded = \
+                self._config_paths.path/self._data_config.recorded_data_path
             self._data_config.recorded_data_path = recorded.resolve()
         else:
             self._data_config = None

{patkit-0.22.1 → patkit-0.22.2}/patkit/constants.py

@@ -49,6 +49,7 @@ from patkit.external_class_extensions import (
 # TODO 1.0: Decouple program and file format versions at version 1.0.
 PATKIT_VERSION = version('patkit')
 PATKIT_FILE_VERSION = PATKIT_VERSION
+EXERCISE_FILE_VERSION = PATKIT_VERSION
 
 DEFAULT_ENCODING = 'utf-8'
 
@@ -192,6 +193,7 @@ class PatkitConfigFile(str, Enum):
     SESSION: how PATKIT should read a session based on recorded data
     SPLINE: spline formatting
     """
+    ANSWER = "patkit-answer.yaml"
     EXERCISE = "patkit-exercise.yaml"
     DATA = "patkit-data.yaml"
     GUI = "patkit-gui.yaml"
@@ -208,6 +210,21 @@ class PatkitConfigFile(str, Enum):
         return self.value
 
 
+class PatkitDirectory(str, Enum):
+    """
+    Standard directory names used in PATKIT.
+    """
+    ANSWERS = "answers"
+    EXAMPLE = "example"
+    EXERCISE = "exercise"
+
+    def __str__(self) -> str:
+        """
+        Ensure f-strings and print() output the string value.
+        """
+        return self.value
+
+
 class PatkitSuffix(str, Enum):
     """
     Suffixes for files saved by patkit.
@@ -231,7 +248,7 @@ class SavedObjectTypes(Enum):
     """
     Represent type of a saved patkit object in .meta.
     """
-    # TODO 1.0: Check if this is actually in use.
+    EXERCISE = "Exercise"
     DATASET = "Dataset"
     MODALITY = "Modality"
     RECORDING = "Recording"
@@ -454,3 +471,49 @@ class ExerciseMode(ListablePrintableEnum, metaclass=ValueComparedEnumMeta):
     """
     ANSWER = "Answer"
     EXAMPLE = "Example"
+
+
+class ExerciseScrambler(
+    ListablePrintableEnum, metaclass=ValueComparedEnumMeta
+):
+    """
+    Ways of scrambling boundaries for an Exercise.
+    """
+    EQUIDISTANT = "Equidistant"
+
+
+class DefaultCanvasColors(str, Enum):
+    """
+    Default background colors for the Matplotlib figure canvas.
+
+    These represent the hardcoded default theme colors for different
+    annotator and exercise modes until config overrides are implemented.
+    """
+    ANNOTATOR_LIGHT = "white"
+    ANNOTATOR_DARK = "black"
+
+    EXAMPLE_LIGHT = "#e7eaff"
+    EXAMPLE_DARK = "#000212"
+
+    ANSWER_LIGHT = "#e6ffe9"
+    ANSWER_DARK = "#001202"
+
+    def __str__(self) -> str:
+        """
+        Ensure f-strings and print() output the string value.
+        """
+        return self.value
+
+
+class DefaultCursorColors(str, Enum):
+    """
+    Default colors for GUI cursor and selection elements.
+    """
+    SELECTION = "deepskyblue"
+    PLAYBACK = "red"
+
+    def __str__(self) -> str:
+        """
+        Ensure f-strings and print() output the string value.
+        """
+        return self.value

{patkit-0.22.1 → patkit-0.22.2}/patkit/data_structures/__init__.py

@@ -43,7 +43,7 @@ from .data_structures import (
     Exercise, Answer, Manifest, Modality, Recording, Session
 )
 from .metadata_classes import (
-    FileInformation,
+    AnswerMetadata, ExerciseMetadata, FileInformation,
     ModalityData, ModalityMetaData, PointAnnotations,
     RecordingMetaData, StatisticMetaData
 )

{patkit-0.22.1 → patkit-0.22.2}/patkit/data_structures/base_classes.py

@@ -385,7 +385,7 @@ class AbstractDataContainer(AbstractDataObject):
     """
     Abstract baseclass for Recording, Session, and DataSet.
 
-    This class collects behaviors that are shared by the data base classes i.e.
+    This class collects behaviors that are shared by the database classes i.e.
     classes which collect DataContainers and/or AbstractDataContainers.
     """
 

{patkit-0.22.1 → patkit-0.22.2}/patkit/data_structures/data_structures.py

@@ -32,20 +32,6 @@
 """PATKIT's main datastructures."""
 
 from __future__ import annotations
-from .metadata_classes import (
-    FileInformation, ModalityData, ModalityMetaData, PointAnnotations,
-    RecordingMetaData
-)
-from .base_classes import AbstractDataContainer, AbstractData, Statistic
-from patkit.patgrid import PatGrid
-from patkit.utility_functions import stem_path
-from patkit.errors import (
-    DimensionMismatchError, MissingDataError, OverwriteError
-)
-from patkit.constants import AnnotationType, SourceSuffix
-from patkit.configuration import SessionConfig
-import textgrids
-import numpy as np
 
 import abc
 import logging
@@ -54,11 +40,30 @@ from copy import deepcopy
 from pathlib import Path
 from textwrap import indent
 
+import textgrids
+import numpy as np
+
+from patkit.configuration import SessionConfig
+from patkit.constants import (
+    AnnotationType, PatkitDirectory, SourceSuffix
+)
+from patkit.errors import (
+    DimensionMismatchError, MissingDataError, OverwriteError
+)
+from patkit.patgrid import PatGrid
+from patkit.utility_functions import stem_path
+
+from .metadata_classes import (
+    AnswerMetadata, ExerciseMetadata, FileInformation,
+    ModalityData, ModalityMetaData, PointAnnotations,
+    RecordingMetaData
+)
+from .base_classes import AbstractDataContainer, AbstractData, Statistic
 
 _logger = logging.getLogger('patkit.data_structures')
 
 
-class Answer(UserList):
+class Answer(AbstractDataContainer, UserList):
     """
     Answer is an answer to an Exercise and consists of PatGrids.
 
@@ -69,23 +74,42 @@ class Answer(UserList):
         self,
         container: Exercise,
         scenario: Session,
-        scramble: bool,
-        name: str = "",
-        author: str = "",
+        metadata: AnswerMetadata,
+        name: str,
         cursor: int = 0,
+        file_info: FileInformation | None = None,
     ):
-        super().__init__()
+        """
+        Initialize an Answer object containing PatGrids for an Exercise.
+
+        Parameters
+        ----------
+        container : Exercise
+            The Exercise this Answer belongs to.
+        scenario : Session
+            The Session containing the recordings.
+        name : str
+            The name of the answer.
+        cursor : int
+            The cursor index pointing to the active recording.
+        file_info : FileInformation | None
+            The FileInformation metadata for the answer.
+        """
+        if file_info is None:
+            file_info = FileInformation()
+
+        super().__init__(name=name, metadata=metadata,
+                         container=container, file_info=file_info)
         self.container = container
         self.scenario = scenario
-        self.name = name
-        self.author = author
         self.cursor = cursor
 
         for recording in self.scenario:
             patgrid = deepcopy(recording.patgrid)
             self.append(patgrid)
 
-        if scramble:
+        # TODO: this will probably break loading edited answers
+        if self.metadata.scramble:
             for patgrid in self:
                 for tier in patgrid:
                     patgrid[tier].scramble()
@@ -100,6 +124,20 @@ class Answer(UserList):
             representation += indent(text=patgrid_string, prefix="\t")
         return representation
 
+    @property
+    def patkit_data_path(self) -> Path:
+        """Dynamically compute the path to the answer directory."""
+        # Route example answers directly to the example directory
+        if (
+            self.container.example is not None and
+            self is self.container.example
+        ):
+            return self.container.patkit_path / PatkitDirectory.EXAMPLE
+
+        return (
+            self.container.patkit_path / PatkitDirectory.ANSWERS / self.name
+        )
+
     def current(self) -> PatGrid:
         """
         The PatGrid at the current index.
@@ -151,7 +189,7 @@ class Answer(UserList):
         return self.cursor
 
 
-class Exercise(UserDict):
+class Exercise(AbstractDataContainer, UserDict):
     """
     Exercise is list of Answers relating to a Scenario (Session).
 
@@ -162,24 +200,46 @@ class Exercise(UserDict):
     def __init__(
         self,
         scenario: Session,
+        name: str,
+        metadata: ExerciseMetadata,
         answers: list[Answer] | None = None,
         example: dict[str, Answer] | None = None,
         index: int = 0,
+        file_info: FileInformation | None = None,
     ):
-        super().__init__()
+        """
+        Initialize an Exercise.
+
+        Parameters
+        ----------
+        scenario : Session
+            The Session containing the recordings for this exercise.
+        answers : list[Answer] | None
+            A list of Answer objects to populate the exercise.
+        example : dict[str, Answer] | None
+            The example scrambled Answer to present to the user.
+        index : int
+            The cursor index.
+        """
+        super().__init__(name=name, metadata=metadata, file_info=file_info)
         if example is None:
             _logger.debug("Creating an example answer")
+            metadata = AnswerMetadata(
+                scramble=False,
+            )
             self.example = Answer(
                 container=self,
                 scenario=scenario,
-                scramble=False,
+                metadata=metadata,
+                name=PatkitDirectory.EXAMPLE,
             )
         else:
             self.example = example
         self.scenario = scenario
 
         if answers is not None:
-            self.update(answers)
+            for answer in answers:
+                self[answer.name] = answer
 
         self.cursor = index
 
@@ -202,6 +262,14 @@ class Exercise(UserDict):
     def current_answer(self) -> Answer:
         return self[list(self.keys())[self.cursor]]
 
+    @property
+    def patkit_path(self) -> Path | None:
+        return self.file_info.patkit_path
+
+    @patkit_path.setter
+    def patkit_path(self, path: Path) -> None:
+        self.file_info.patkit_path = path
+
     def new_blank_answer(
         self,
         cursor: int = 0,
@@ -218,7 +286,7 @@ class Exercise(UserDict):
         name : str | None
             Name of the new Answer, by default None. If None is passed the new
             name will be autogenerated and have the form
-            `f"Answer {len(self)+1}"`.
+            `f"Answer_{len(self)+1}"`.
         author : str
             Name of the new Answer's author, by default an empty string.
         """
@@ -226,15 +294,19 @@ class Exercise(UserDict):
 
         # TODO 1.0: Is this the best place to name answers?
         if name is None:
-            name = f"Answer {len(self)+1}"
+            name = f"Answer_{len(self)+1}"
 
+        metadata = AnswerMetadata(
+            scramble=True,
+            author=author
+        )
         blank = Answer(
             container=self,
             scenario=self.scenario,
-            scramble=True,
+            name=name,
+            metadata=metadata,
             cursor=cursor,
         )
-        name = f"Answer {len(self)+1}"
         self[name] = blank
 
 
@@ -336,11 +408,15 @@ class Session(AbstractDataContainer, UserList):
             config: SessionConfig,
             file_info: FileInformation,
             recordings: list[Recording] | None = None,
-            statistics: dict[str, Statistic] | None = None
+            statistics: dict[str, Statistic] | None = None,
+            exercise: Exercise | None = None,
     ) -> None:
         super().__init__(
-            container=None, name=name, metadata=config,
-            file_info=file_info, statistics=statistics)
+            container=None,
+            name=name,
+            metadata=config,
+            file_info=file_info,
+            statistics=statistics)
 
         if recordings is not None:
             for recording in recordings:
@@ -349,6 +425,7 @@ class Session(AbstractDataContainer, UserList):
             self.extend(recordings)
 
         self.config = config
+        self.exercise = exercise
 
     def __repr__(self) -> str:
         representation = "Session:\n"

{patkit-0.22.1 → patkit-0.22.2}/patkit/data_structures/metadata_classes.py

@@ -42,7 +42,7 @@ from pydantic import PositiveInt
 from patkit.configuration import (
     PointAnnotationParams
 )
-from patkit.constants import AnnotationType
+from patkit.constants import AnnotationType, ExerciseScrambler
 from patkit.external_class_extensions import PatkitBaseModel
 from patkit.utility_functions import (
     is_sequence_form, stem_path
@@ -116,6 +116,54 @@ class FileInformation:
         return stem_path(basepath)
 
 
+class AnswerMetadata(PatkitBaseModel):
+    """
+    Metadata of an Exercise Answer.
+
+    Parameters
+    ----------
+    scramble : bool
+        Whether to scramble the PatGrids upon creation.
+    author : str
+        The author/user of the answer.
+    time_created : str | None
+        ISO formatted timestamp of when this answer was created.
+    time_last_edited : str | None
+        ISO formatted timestamp of when this answer was last edited.
+    """
+    scramble: bool
+    author: str = ""
+    time_created: str | None = None
+    time_last_edited: str | None = None
+
+    def model_post_init(self, __context):
+        now = datetime.now().isoformat()
+        if self.time_created is None:
+            self.time_created = now
+        if self.time_last_edited is not None:
+            self.time_last_edited = now
+
+
+class ExerciseMetadata(PatkitBaseModel):
+    """
+    Metadata for an Exercise.
+
+    Parameters
+    ----------
+    time_created : str | None
+        ISO formatted timestamp of when this exercise was created.
+    scrambling_method : str
+        The method used to scramble the exercise TextGrids.
+    """
+    time_created: str | None = None
+    scrambling_method: ExerciseScrambler = ExerciseScrambler.EQUIDISTANT
+
+    def model_post_init(self, __context):
+        now = datetime.now().isoformat()
+        if self.time_created is None:
+            self.time_created = now
+
+
 @dataclass
 class ModalityData:
     """

{patkit-0.22.1 → patkit-0.22.2}/patkit/gui/__init__.py

@@ -32,9 +32,12 @@
 """GUI elements."""
 
 from .annotator_window import UiMainWindow
+from .audio_player import AudioPlayer
 from .boundary_animation import BoundaryAnimator
+from .exercise_dialogs import NewAnswerDialog, NewExerciseDialog
 from .image_save_dialog import ImageSaveDialog
 from .list_save_dialog import ListSaveDialog
 from .list_selection_dialog import ListSelectionDialog
 from .player_controls import PlayerControls
+from .plot_controller import PlotController
 from .replace_dialog import ReplaceDialog