patkit 0.22.0__tar.gz → 0.22.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patkit
-Version: 0.22.0
+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
@@ -691,41 +691,34 @@ Classifier: Development Status :: 3 - Alpha
 Classifier: Programming Language :: Python
 Requires-Python: >=3.10.13
 Requires-Dist: bioread>=3.0.1
-Requires-Dist: build>=1.2.2.post1
 Requires-Dist: click-default-group>=1.2.4
 Requires-Dist: click>=8.1.8
-Requires-Dist: deepdiff>=8.6.2
 Requires-Dist: dipy>=1.10.0
 Requires-Dist: fonttools>=4.55.3
-Requires-Dist: icecream>=2.1.3
 Requires-Dist: jinja2>=3.1.5
-Requires-Dist: licenseheaders>=0.8.8
 Requires-Dist: matplotlib>=3.10.0
 Requires-Dist: more-itertools>=10.5.0
 Requires-Dist: mpl-point-clicker>=0.4.1
 Requires-Dist: nestedtext>=3.7
 Requires-Dist: numpy>=2.2.1
-Requires-Dist: pdoc>=15.0.1
 Requires-Dist: pillow>=12.2.0
 Requires-Dist: praat-textgrids>=1.4.0
 Requires-Dist: pydantic>=2.10.4
 Requires-Dist: pydicom>=3.0.2
-Requires-Dist: pylint>=3.3.3
 Requires-Dist: pyqt6>=6.10.0
 Requires-Dist: pyreadline3>=3.5.4; platform_system == 'Windows'
 Requires-Dist: qbstyles>=0.1.4
 Requires-Dist: scipy>=1.15.0
 Requires-Dist: seaborn>=0.13.2
-Requires-Dist: setuptools>=75.7.0
 Requires-Dist: sk-video>=1.1.10
 Requires-Dist: sounddevice>=0.5.5
 Requires-Dist: strictyaml>=1.7.3
-Requires-Dist: virtualenv>=20.28.1
 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.20.1.png)
+![PATKIT GUI](https://giuthas.github.io/patkit/PATKIT_UI_0.22.0.png)
 
 PATKIT provides tools for phonetic analysis of speech data. It includes a GUI
 for manual assessment/analysis/annotation (see picture above), command line
@@ -756,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:
@@ -776,13 +766,27 @@ Try this in case trying to run patkit complains about a missing `xcb` plugin.
 
 ## Current version and development plans
 
-See [Changelog](https://giuthas.github.io/patkit/Changelog), for what's new in the current version
-and what's coming up.
+See [Changelog](https://giuthas.github.io/patkit/Changelog), for what's new in
+the current version and what's coming up.
 
 
 ## What's included
 
-TODO 0.22.1: give a quick description of included data and goodies here.
+There is some test and demo data that is temporarily hosted in the GitHub repo.
+Download the contents of
+`https://github.com/giuthas/patkit/tree/main/recorded_data/` and
+`https://github.com/giuthas/patkit/tree/main/scenarios/`. Easiest way to do
+this is by copy-pasting the URLs to [this
+page](https://download-directory.github.io/) to get a zip file with the
+contents of the directory.
+
+Place the unzipped directories in the same directory and after installing
+patkit try running 
+```
+patkit scenarios/minimal
+```
+and experiment from there.
+
 TODO 1.0: Move the data elsewhere to be optionally loaded.
 
 ## Contributing

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

@@ -1,6 +1,7 @@
+[![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.20.1.png)
+![PATKIT GUI](https://giuthas.github.io/patkit/PATKIT_UI_0.22.0.png)
 
 PATKIT provides tools for phonetic analysis of speech data. It includes a GUI
 for manual assessment/analysis/annotation (see picture above), command line
@@ -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:
@@ -51,13 +49,27 @@ Try this in case trying to run patkit complains about a missing `xcb` plugin.
 
 ## Current version and development plans
 
-See [Changelog](https://giuthas.github.io/patkit/Changelog), for what's new in the current version
-and what's coming up.
+See [Changelog](https://giuthas.github.io/patkit/Changelog), for what's new in
+the current version and what's coming up.
 
 
 ## What's included
 
-TODO 0.22.1: give a quick description of included data and goodies here.
+There is some test and demo data that is temporarily hosted in the GitHub repo.
+Download the contents of
+`https://github.com/giuthas/patkit/tree/main/recorded_data/` and
+`https://github.com/giuthas/patkit/tree/main/scenarios/`. Easiest way to do
+this is by copy-pasting the URLs to [this
+page](https://download-directory.github.io/) to get a zip file with the
+contents of the directory.
+
+Place the unzipped directories in the same directory and after installing
+patkit try running 
+```
+patkit scenarios/minimal
+```
+and experiment from there.
+
 TODO 1.0: Move the data elsewhere to be optionally loaded.
 
 ## Contributing

{patkit-0.22.0 → patkit-0.22.2}/patkit/__init__.py

@@ -56,7 +56,7 @@ from .cli import run_cli
 from .initialise import add_derived_data, initialise_patkit
 from .qt_annotator import run_annotator
 
-# __all__ = ['add_derived_data', 'initialise_patkit']
+__all__ = ['add_derived_data', 'initialise_patkit', 'run_cli', 'run_annotator']
 
 # Load logging config from json file.
 LOG_CONFIG = "patkit_logging_configuration.json"

{patkit-0.22.0 → patkit-0.22.2}/patkit/cli_commands.py

@@ -37,13 +37,57 @@ from pathlib import Path
 
 import click
 
+from patkit.constants import OpenPathType
 from patkit.initialise import initialise_config, initialise_patkit
+from patkit.path_resolution import get_manifest_scenarios, resolve_open_path
 from patkit.qt_annotator import run_annotator
 from patkit.interpreter import run_interpreter
 from patkit.simulation import run_simulations
 from patkit.simulation.simulate import setup_contours_comparisons_soundpairs
 
 
+def resolve_scenario_path(path: Path) -> Path:
+    """
+    CLI-specific path resolution that prompts the user via the terminal.
+
+    Parameters
+    ----------
+    path : Path
+        The original target path provided by the user.
+
+    Returns
+    -------
+    Path
+        The chosen scenario path, or the original path if none apply.
+    """
+    scenarios = get_manifest_scenarios(path=path)
+
+    if not scenarios:
+        return path
+
+    if len(scenarios) == 1:
+        click.echo(
+            f"Automatically opening the single scenario from "
+            f"manifest: {scenarios[0]}"
+        )
+        return scenarios[0]
+
+    click.echo("\nMultiple scenarios found in the manifest file:")
+    for idx, s_path in enumerate(scenarios, 1):
+        click.echo(f"  [{idx}] {s_path}")
+
+    choice = click.prompt(
+        "\nPlease select which scenario you want to open",
+        type=click.IntRange(1, len(scenarios)),
+        default=1
+    )
+
+    chosen_path = scenarios[choice - 1]
+    click.echo(f"Opening selected scenario: {chosen_path}\n")
+
+    return chosen_path
+
+
 @click.command(name="open")
 @click.argument(
     "path",
@@ -60,6 +104,28 @@ def open_in_annotator(
     \b
     PATH to the data - maybe be a file or a directory.
     """
+    path_type, path = resolve_open_path(path)
+    match path_type:
+        case OpenPathType.MANIFEST:
+            path = resolve_scenario_path(path=path)
+        case OpenPathType.SCENARIO:
+            pass
+        case OpenPathType.DIRECTORY:
+            raise NotImplementedError(
+                "Opening a directory of data without "
+                "config is not implemented yet."
+            )
+        case OpenPathType.SINGLE_DATA:
+            raise NotImplementedError(
+                "Opening a single data file without "
+                "config is not implemented yet."
+            )
+        case _:
+            raise NotImplementedError(
+                f"Unimplemented type of load path "
+                f"{path_type}."
+            )
+
     config, logger = initialise_config(
         path=path, require_gui=True, require_data=True)
     session = initialise_patkit(config=config, logger=logger)
@@ -81,6 +147,28 @@ def interact(
     \b
     PATH to the data - maybe be a file or a directory.
     """
+    path_type, path = resolve_open_path(path)
+    match path_type:
+        case OpenPathType.MANIFEST:
+            path = resolve_scenario_path(path=path)
+        case OpenPathType.SCENARIO:
+            pass
+        case OpenPathType.DIRECTORY:
+            raise NotImplementedError(
+                "Opening a directory of data without "
+                "config is not implemented yet."
+            )
+        case OpenPathType.SINGLE_DATA:
+            raise NotImplementedError(
+                "Opening a single data file without "
+                "config is not implemented yet."
+            )
+        case _:
+            raise NotImplementedError(
+                f"Unimplemented type of load path "
+                f"{path_type}."
+            )
+
     config, logger = initialise_config(path=path, require_data=True)
     session = initialise_patkit(config=config, logger=logger)
     run_interpreter(session=session, configuration=config)
@@ -101,6 +189,7 @@ def publish(path: Path):
 
     NOT IMPLEMENTED YET.
     """
+    path = resolve_scenario_path(path=path)
     config, logger = initialise_config(path=path, require_publish=True)
     session = initialise_patkit(config=config, logger=logger)
     print(

{patkit-0.22.0 → 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.0 → patkit-0.22.2}/patkit/constants.py

@@ -39,7 +39,6 @@ values and avoids typos and makes an IDE help in writing code.
 Frozen dataclasses are used for constants that only ever need to be accessed
 and never are stored. In effect, they function as look-up tables.
 """
-from dataclasses import dataclass
 from enum import Enum
 from importlib.metadata import version
 
@@ -50,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'
 
@@ -169,8 +169,7 @@ class IntervalCategory(Enum):
     LAST_LABELED = 'last labeled'
 
 
-@dataclass(frozen=True)
-class PatkitConfigFile:
+class PatkitConfigFile(str, Enum):
     """
     Human written yaml files to control importing data.
 
@@ -194,6 +193,7 @@ class PatkitConfigFile:
     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"
@@ -203,9 +203,29 @@ class PatkitConfigFile:
     SESSION = 'session-config.yaml'
     SPLINE = 'spline-config.yaml'
 
+    def __str__(self) -> str:
+        """
+        Ensure f-strings and print() output the string value.
+        """
+        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
+
 
-@dataclass(frozen=True)
-class PatkitSuffix:
+class PatkitSuffix(str, Enum):
     """
     Suffixes for files saved by patkit.
 
@@ -217,12 +237,18 @@ class PatkitSuffix:
     DATA = ".npz"
     META = ".meta"
 
+    def __str__(self) -> str:
+        """
+        Ensure f-strings and print() output the string value.
+        """
+        return self.value
+
 
 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"
@@ -232,8 +258,7 @@ class SavedObjectTypes(Enum):
     TRIAL = "Trial"
 
 
-@dataclass(frozen=True)
-class SourceSuffix:
+class SourceSuffix(str, Enum):
     """
     Suffixes for files imported by patkit.
 
@@ -257,6 +282,22 @@ class SourceSuffix:
     TEXTGRID = ".TextGrid"
     WAV = ".wav"
 
+    def __str__(self) -> str:
+        """
+        Ensure f-strings and print() output the string value.
+        """
+        return self.value
+
+
+class OpenPathType(Enum):
+    """
+    Path types resolved when running patkit subcommands (open, interact...).
+    """
+    MANIFEST = "manifest"
+    SCENARIO = "scenario"
+    SINGLE_DATA = "single_data"
+    DIRECTORY = "directory"
+
 
 # def patkit_suffix(
 #         patkit_type: Union[Recording, Session, Modality]) -> str:
@@ -430,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.0 → 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.0 → patkit-0.22.2}/patkit/data_structures/base_classes.py

@@ -52,10 +52,10 @@ class AbstractDataObject(abc.ABC):
     Abstract base class for patkit data objects.
 
     Almost no class should directly inherit from this class. Exceptions are
-    AbstractDataContainer and AbstractData. The latter is the abstract baseclass for
-    Modality and Statistic and the former for all data base classes: Recording,
-    Session, DataSet and any others that contain either DataContainers and/or
-    AbstractDataContainers.
+    AbstractDataContainer and AbstractData. The latter is the abstract
+    baseclass for Modality and Statistic and the former for all data base
+    classes: Recording, Session, DataSet and any others that contain either
+    DataContainers and/or AbstractDataContainers.
     """
 
     def __init__(self,
@@ -116,7 +116,7 @@ class AbstractDataObject(abc.ABC):
     @property
     def file_info(self) -> FileInformation:
         """
-        The paths and filenames of this AbstractDataObject as a FileInformation object.
+        The paths and filenames of this AbstractDataObject.
 
         NOTE: Regularly you should not need to access this directly. Instead,
         use the `[recorded|patkit]_path`, `[recorded|patkit]_data_file`, and
@@ -182,7 +182,7 @@ class AbstractDataObject(abc.ABC):
         Path to the recorded meta data file of this AbstractDataObject.
 
         This file will exist only for some recorded data. For example, wav
-        files do not have a corresponding recorded meta data file. 
+        files do not have a corresponding recorded meta data file.
 
         This file may also cover more than one recorded data file - usually a
         whole Session if not just a single recorded data file.
@@ -230,7 +230,7 @@ class AbstractDataObject(abc.ABC):
         """
         if not self._file_info.recorded_path:
             return None
-        if not self.container is None:
+        if self.container is not None:
             return self.container.recorded_path / self._file_info.recorded_path
         return self._file_info.recorded_path
 
@@ -367,11 +367,11 @@ class AbstractDataObject(abc.ABC):
         Get meta data as a dict.
 
         This is a helper method for saving as nested text. Allows for rewriting
-        any fields that need a simpler representation. 
+        any fields that need a simpler representation.
 
         Subclasses should override this method if any of their fields require
         special handling such as derived Enums needing to be converted to plain
-        text etc. 
+        text etc.
 
         Returns
         -------
@@ -383,9 +383,9 @@ class AbstractDataObject(abc.ABC):
 
 class AbstractDataContainer(AbstractDataObject):
     """
-    Abstract baseclass for Recording, Session, and DataSet. 
+    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.
     """
 
@@ -409,9 +409,9 @@ class AbstractDataContainer(AbstractDataObject):
         """
         Name of this instance.
 
-        AbstractDataContainers get their names mainly from the file system. DataSets
-        are named after the root directory name, Sessions for the session
-        directories and Trials for the trial file names. 
+        AbstractDataContainers get their names mainly from the file system.
+        DataSets are named after the root directory name, Sessions for the
+        session directories and Trials for the trial file names.
 
         Returns
         -------
@@ -456,7 +456,7 @@ class AbstractDataContainer(AbstractDataObject):
 
 class AbstractData(AbstractDataObject):
     """
-    Abstract baseclass for Modality and Statistic. 
+    Abstract baseclass for Modality and Statistic.
 
     This class collects behaviors shared by the classes that contain data:
     Modalities contain time varying data and Statistics contain time
@@ -519,7 +519,7 @@ class AbstractData(AbstractDataObject):
 
 class Statistic(AbstractData):
     """
-    Abstract baseclass for statistics generated from members of a container. 
+    Abstract baseclass for statistics generated from members of a container.
 
     Specifically Statistics are time independent data while Modalities are
     time-dependent data.
@@ -539,16 +539,17 @@ class Statistic(AbstractData):
             parsed_data: np.ndarray | None = None,
     ) -> None:
         """
-        Build a Statistic.       
+        Build a Statistic.
 
         Parameters
         ----------
         metadata : PatkitBaseModel
             Parameters used in calculating this Statistic.
         container : AbstractDataContainer
-            The container of this Statistic. Usually this will be the object whose
-            contents this Statistic was calculated on. By default, None, to
-            facilitate mass generation and setting the container after wards.
+            The container of this Statistic. Usually this will be the object
+            whose contents this Statistic was calculated on. By default, None,
+            to facilitate mass generation and setting the container after
+            wards.
         file_info : FileInformation
             The patkit load path and names for this Statistic. Recorded path
             and names should usually be empty. Defaults to None, when the