canapy 0.1.0__py3-none-any.whl

canapy/__init__.py

@@ -0,0 +1,15 @@
+# Author: Axel Arnaud
+# Licence: BSD-3-Clause
+# Copyright: Axel Arnaud
+import logging
+
+import crowsetta
+
+from . import log
+from .corpus import Corpus
+from config import Config
+from .formats.marron1csv import Marron1CSV
+
+crowsetta.register_format(Marron1CSV)
+
+logging.basicConfig(level=logging.INFO)

canapy/annotator/__init__.py

@@ -0,0 +1,63 @@
+# Author: Axel Arnaud
+# Licence: BSD-3-Clause
+# Copyright: Axel Arnaud
+"""
+This module provides annotator classes and a registry for audio classification in Canapy.
+
+Classes
+-------
+Annotator
+    Base class for annotators.
+SynAnnotator
+    An annotator that uses a Syntaxic approach with an Echo State Network (ESN).
+NSynAnnotator
+    An annotator that uses a non-Syntaxic approach with an Echo State Network (ESN).
+Ensemble
+    An ensemble annotator that combines the predictions of other annotators.
+
+Functions
+---------
+get_annotator
+    Retrieves an annotator object by name from the registry.
+get_annotator_names
+    Retrieves a list of available annotator names.
+
+"""
+import logging
+
+from .base import Annotator
+from .synannotator import SynAnnotator
+from .nsynannotator import NSynAnnotator
+from .ensemble import Ensemble
+
+
+logger = logging.getLogger("canapy")
+
+
+class _Registry:
+    def __init__(self):
+        self._registry = {
+            "syn-esn": SynAnnotator,
+            "nsyn-esn": NSynAnnotator,
+            "ensemble": Ensemble,
+        }
+
+    def __getitem__(self, item):
+        return self._registry[item]
+
+    def register_annotator(self, name, cls):
+        if name in self._registry:
+            logger.warning(f"'{name}' is already registered. Skipping.")
+            return
+        self._registry[name] = cls
+
+
+registry = _Registry()
+
+
+def get_annotator(name):
+    return registry[name]
+
+
+def get_annotator_names():
+    return sorted(registry._registry.keys())

canapy/annotator/base.py

@@ -0,0 +1,243 @@
+# Authors: Nathan Trouvain at 29/06/2023 <nathan.trouvain<at>inria.fr>
+#          Vincent Gardies at 10/07/2023 <vincent.gardies<at>inria.fr>
+# Licence: BSD-3-Clause
+# Copyright: Nathan Trouvain
+
+import abc
+import pickle
+import logging
+
+from pathlib import Path
+from config import default_config
+from .commons.compat import _Compat, _CompatModelUnpickler
+
+logger = logging.getLogger("canapy")
+
+
+class Annotator(abc.ABC):
+    """
+    Base abstract class for annotators
+
+    The basic usage of an annotator involves three steps:
+        1. Load your annotator (using the 'from_disk' method or by creating a new one).
+
+        2. Train your annotator (using the 'fit' method).
+
+        3. Make predictions with the annotator (using the 'predict' method).
+
+    """
+
+    _trained: bool = False
+    _vocab: list = list()
+
+    @classmethod
+    def from_disk(
+        cls,
+        path,
+        config=default_config,
+    ):  # spec_directory=None):
+        """
+        Load an annotator object from disk.
+
+        Parameters
+        ----------
+        path : str
+            Path to the file containing the annotator object.
+        config : Config, default=default_config
+            The configuration object for the annotator.
+        spec_directory : str, optional
+            The directory containing the spectrogram files.
+
+        Returns
+        -------
+        Annotator
+            The loaded annotator object.
+
+        Raises
+        ------
+        NotImplementedError
+            If the loaded annotator object is of an unsupported type.
+
+        Note
+        ----
+        Annotators that have been created and saved in the disk with the former version of canapy are also loadable.
+        Make sure to give the configuration of the model if you had made some changes, and a spec_directory.
+
+        Examples
+        --------
+            >>> from canapy.annotator.base import Annotator
+
+            >>> my_annotator = Annotator.from_disk("/path/to/annotator")
+            >>> # The annotator saved in the 'saved_annotator' file is now loaded into 'my_annotator'
+
+            >>> from config import default_config
+            >>> my_old_config = default_config  # Get the config that the model was saved with
+            >>> my_annotator_old = Annotator.from_disk("/path/to/old/model",
+            >>>     config=my_old_config  # If no changes were made to the config, default_config will work
+            >>>     spec_directory="/path/to/spec"
+            >>> )
+            >>> # The annotator saved in the 'syn' file is loaded into my_annotator_old
+
+        """
+
+        from . import get_annotator
+
+        with Path(path).open("rb") as file:
+            try:
+                loaded_annot = pickle.load(file)
+            except ModuleNotFoundError:
+                loaded_annot = _CompatModelUnpickler(file).load()
+
+        # This case concerns Annotators made with this version of Canapy
+        if isinstance(loaded_annot, Annotator):
+            if hasattr(loaded_annot, 'rpy_model') or (hasattr(loaded_annot, '_vocab') and len(loaded_annot._vocab) > 0):   
+                loaded_annot._trained = True         
+            # if spec_directory is not None:
+            #     loaded_annot.spec_directory = spec_directory
+            return loaded_annot
+
+        # This case concerns Annotators made with a previous version of Canapy
+        elif isinstance(loaded_annot, _Compat):
+            # The name of the file is used to determine the type of annotator.
+            # If you need to change the model's name, make sure it ends with its type (syn / nsyn).
+            annotator_type = get_annotator(
+                "nsyn-esn" if len(path) > 3 and path[-4] == "n" else "syn-esn"
+            )
+
+            new_annotator = annotator_type(config)  # spec_directory)
+            new_annotator._trained = True
+            new_annotator.rpy_model = loaded_annot.esn
+            new_annotator._vocab = loaded_annot.vocab
+            return new_annotator
+        else:
+            raise NotImplementedError
+
+    def to_disk(self, path):
+        """
+        Save the annotator object to disk.
+
+        Parameters
+        ----------
+        path : str or Path
+            Path to the file where the annotator object will be saved.
+
+        Example
+        -------
+            >>> from canapy.annotator.synannotator import SynAnnotator
+            >>> from config import default_config
+            >>> my_annotator = SynAnnotator(default_config, "/home/vincent/Documents/data_canary/spec")
+            >>> my_annotator.to_disk("/home/vincent/Documents/data_canary/annotators/my_annotator")
+            >>> # The annotator is now saved in the disk
+
+        """
+        with Path(path).open("wb+") as file:
+            pickle.dump(self, file)
+
+    @property
+    def trained(self):
+        """
+        Property indicating if the annotator is trained.
+
+        Returns
+        -------
+        bool
+            True if the annotator is trained, False otherwise.
+
+        Example
+        -------
+            >>> from canapy.annotator.ensemble import Ensemble
+            >>> from config import default_config
+            >>> my_ensemble_annotator = Ensemble (default_config, None)
+            >>> # For example, we are using an Ensemble annotator
+            >>> print(f"My annotator is trained : {my_ensemble_annotator.trained()}")
+            My annotator is trained : False
+            >>> from canapy.corpus import Corpus
+            >>> corpus = Corpus.from_directory(audio_directory="/path/to/audio", annots_directory="/path/to/annotation")
+            >>> my_ensemble_annotator.fit(corpus)
+            >>> # We create a corpus from some files and then train the annotator on it
+            >>> print(f"My annotator is trained : {my_ensemble_annotator.trained()}")
+            My annotator is trained : True
+
+        """
+        return self._trained
+
+    @property
+    def vocab(self):
+        """
+        Property containing the vocabulary of the annotator.
+
+        Returns
+        -------
+        list
+            The vocabulary of the annotator.
+
+        Note
+        ----
+        The vocabulary of the annotator is determined during the 'fit' method.
+        Trying to access the vocabulary of an annotator before training it is useless
+        """
+        return self._vocab
+
+    def fit(self, corpus):
+        """
+        Fit the annotator to the given corpus.
+
+        Parameters
+        ----------
+        corpus : Corpus
+            The corpus object used for training the annotator.
+
+        Returns
+        -------
+        Annotator
+            The trained annotator itself.
+
+        Note
+        ----
+        Even though this function returns the trained annotator, the annotator itself is trained.
+
+        Example
+        -------
+            >>> from canapy.annotator.nsynannotator import NSynAnnotator
+            >>> from config import default_config
+            >>> my_annotator = SynAnnotator(default_config, "/path/to/spec")
+            >>> # A not-syntaxic annotator is used in this example
+            >>> from canapy.corpus import Corpus
+            >>> corpus = Corpus.from_directory(audio_directory="/path/to/audio", annots_directory="/path/to/annotation")
+            >>> my_annotator_trained = my_annotator.fit(corpus)
+            >>> # The annotator is now trained with the given corpus
+            >>> my_annotator_trained == my_annotator
+            True
+
+        """
+        raise NotImplementedError
+
+    def predict(self, corpus, return_raw=False, redo_transforms=False):
+        """
+        Predict annotations for the given corpus.
+
+        Parameters
+        ----------
+        corpus : Corpus
+            The corpus object for which to predict annotations.
+        return_raw : bool, optional
+            If True, raw annotations are added into the 'data_resources'
+            Raw outputs are necessary to train an 'EnsemleAnnotator' on a corpus
+        redo_transforms : bool, optional
+            If True, redo the transformations on the corpus before predicting.
+
+        Returns
+        -------
+        Corpus
+            The corpus object with predicted annotations.
+
+        Note
+        ----
+        Annotators need to be trained before being able to make predictions
+
+        Examples
+        --------
+        Find examples of use in annotators subclasses
+
+        """
+        raise NotImplementedError

canapy/annotator/commons/__init__.py

@@ -0,0 +1,3 @@
+# Author: Axel Arnaud
+# Licence: BSD-3-Clause
+# Copyright: Axel Arnaud

canapy/annotator/commons/compat.py

@@ -0,0 +1,28 @@
+# Author: Axel Arnaud
+# Licence: BSD-3-Clause
+# Copyright: Axel Arnaud
+import pickle
+from types import SimpleNamespace
+
+
+class _CompatModelUnpickler(pickle._Unpickler):
+    def __init__(self, fp):
+        super().__init__(fp)
+        self._magic_classes = {}
+
+    def find_class(self, module, name):
+        if "canapy" in module.split(".") and module.split(".")[1] in [
+            "dataset",
+            "processor",
+            "sequence",
+            "model",
+            "config",
+        ]:
+            return _Compat
+        else:
+            return super().find_class(module, name)
+
+
+class _Compat(SimpleNamespace):
+    def __setitem__(self, key, value):
+        pass

canapy/annotator/commons/esn.py

@@ -0,0 +1,102 @@
+# Author: Nathan Trouvain at 04/07/2023 <nathan.trouvain<at>inria.fr>
+# Licence: BSD-3-Clause
+# Copyright: Nathan Trouvain
+import numpy as np
+import reservoirpy as rpy
+from reservoirpy.nodes import Reservoir, Ridge
+from reservoirpy import ESN
+from reservoirpy.mat_gen import fast_spectral_initialization
+from canapy.utils.exceptions import NotTrainedError
+from .mfccs import load_mfccs_for_annotation
+
+def maximum_a_posteriori(logits, classes=None):
+    logits = np.atleast_2d(logits)
+    predictions = np.argmax(logits, axis=1)
+    if classes is not None:
+        predictions = np.take(classes, predictions)
+    return predictions
+
+def init_esn_model(model_config, input_dim, audio_features, seed=None, workers=None, dtype=np.float64, **overrides):
+    rpy.set_seed(seed)
+
+    def get_p(key, default_attr, default_val):
+        if key in overrides:
+            return overrides[key]
+        return getattr(model_config, default_attr, default_val)
+
+    sr = get_p("sr", "sr", 0.4)
+    leak = get_p("leak", "leak", 0.1)
+    iss_val = get_p("iss", "iss", 0.0005)
+    ridge = get_p("ridge", "ridge", 1e-8)
+    isd_val = get_p("isd", "isd", 0.02)
+    isd2_val = get_p("isd2", "isd2", 0.002)
+    n_units = get_p("units", "units", 1000)
+
+    # Construction du scaling block par block
+    scalings = []
+    if "mfcc" in audio_features:
+        scalings.append(np.ones((input_dim,)) * iss_val)
+    if "delta" in audio_features:
+        scalings.append(np.ones((input_dim,)) * isd_val)
+    if "delta2" in audio_features:
+        scalings.append(np.ones((input_dim,)) * isd2_val)
+
+    if not scalings:
+        input_scaling = iss_val
+    else:
+        input_scaling = np.concatenate(scalings, axis=0)
+
+    reservoir = Reservoir(
+        n_units,
+        sr=sr,
+        lr=leak,
+        input_scaling=input_scaling,
+        bias=iss_val,
+        W=fast_spectral_initialization,
+        dtype=dtype,
+    )
+
+    readout = Ridge(ridge=ridge)
+    n_workers = workers if workers is not None else getattr(model_config, "workers", -1)
+    
+    return ESN(
+        reservoir=reservoir,
+        readout=readout,
+        workers=n_workers, 
+        backend=getattr(model_config, "backend", "multiprocessing")
+    )
+
+def fit_esn_seq_by_seq(model, X_seqs, Y_seqs):
+    """Memory-efficient ESN fit: interleave reservoir.run and readout.worker
+    one sequence at a time so peak RAM = one state matrix instead of all of them.
+    Mathematically equivalent to model.fit(X_seqs, Y_seqs).
+    """
+    model.fit([np.asarray(X_seqs[0])], [np.asarray(Y_seqs[0])])
+    reservoir = model.reservoir
+    readout   = model.readout
+
+    def _gen():
+        for x_seq, y_seq in zip(X_seqs, Y_seqs):
+            reservoir.reset()
+            states = np.asarray(reservoir.run(x_seq))
+            yield readout.worker(states, y_seq)
+            del states
+
+    readout.master(_gen())
+
+
+def predict_with_esn(annotator, corpus, return_raw=False, redo_transforms=False):
+    if not hasattr(annotator, 'rpy_model'):
+        raise NotTrainedError("Annotator does not contain a trained rpy_model.")
+
+    corpus = annotator.transforms(
+        corpus, purpose="annotation", output_directory=corpus.spec_directory, redo=redo_transforms,
+    )
+    notated_paths, mfccs = load_mfccs_for_annotation(corpus)
+    raw_preds = annotator.rpy_model.run(mfccs)
+
+    if isinstance(raw_preds, np.ndarray) and raw_preds.ndim < 3:
+        raw_preds = [raw_preds]
+
+    cls_preds = [maximum_a_posteriori(y, classes=annotator.vocab) for y in raw_preds]
+    return notated_paths, cls_preds, raw_preds if return_raw else None

canapy/annotator/commons/mfccs.py

@@ -0,0 +1,144 @@
+# Author: Nathan Trouvain at 05/07/2023 <nathan.trouvain<at>inria.fr>
+# Licence: BSD-3-Clause
+# Copyright: Nathan Trouvain
+import logging
+
+import numpy as np
+import pandas as pd
+
+from ...timings import seconds_to_frames, seconds_to_audio
+from ...utils.exceptions import NotTrainableError, MissingData
+
+logger = logging.getLogger("canapy")
+
+
+def load_mfccs_and_repeat_labels(corpus, purpose="training"):
+    if purpose == "training":
+        split = "train"
+
+        if len(corpus.dataset.query(split)) == 0:
+            raise NotTrainableError(
+                "Training data was not provided, or corpus was "
+                "not properly divided between train and test data."
+            )
+
+    elif purpose == "eval":
+        split = "not train"
+
+        if len(corpus.dataset.query(split)) == 0:
+            raise NotTrainableError(
+                "Test data was not provided, or corpus was "
+                "not properly divided between train and test data."
+            )
+    else:
+        raise ValueError("'purpose' should be either 'training' or 'eval'.")
+
+    # load data
+    df = corpus.dataset.query(split).copy()
+
+    if "syn_mfcc" not in corpus.data_resources:
+        raise MissingData(
+            "'syn_mfcc' were never computed or can't be found in Corpus. "
+            "Maybe provide and audio/spec directory to the Corpus ?"
+        )
+
+    mfcc_paths = corpus.data_resources["syn_mfcc"]
+
+    df["seqid"] = df["sequence"].astype(str) + df["annotation"].astype(str)
+
+    sampling_rate = corpus.config.transforms.audio.sampling_rate
+    hop_length = seconds_to_audio(
+        corpus.config.transforms.audio.hop_length, sampling_rate
+    )
+
+    df["onset_spec"] = seconds_to_frames(df["onset_s"], hop_length, sampling_rate)
+    df["offset_spec"] = seconds_to_frames(df["offset_s"], hop_length, sampling_rate)
+
+    n_classes = len(corpus.dataset["label"].unique())
+
+    mfccs = []
+    labels = []
+    sequences = []
+    annotations = []
+    for seqid in df["seqid"].unique():
+        seq_annots = df.query("seqid == @seqid")
+
+        notated_audio = seq_annots["notated_path"].unique()[0]
+        notated_spec = mfcc_paths.query("notated_path == @notated_audio")[
+            "feature_path"
+        ].unique()[0]
+
+        seq_end = seq_annots["offset_spec"].iloc[-1]
+        mfcc = np.load(notated_spec)
+
+        # MFCC may be stored as archive arrays for convenience
+        # (see transforms/commons/audio.py)
+        if hasattr(mfcc, "keys") and "feature" in mfcc:
+            mfcc = mfcc["feature"].squeeze()
+        else:
+            raise KeyError("No key named 'feature' in mfcc archive file.")
+
+        if seq_end > mfcc.shape[1]:
+            logger.warning(
+                f"Found inconsistent sequence length: "
+                f"audio {notated_audio} was converted to "
+                f"{mfcc.shape[1]} timesteps but last annotation is at "
+                f"timestep {seq_end}. Annotation will be trimmed."
+            )
+
+        seq_end = min(seq_end, mfcc.shape[1])
+
+        mfcc = mfcc[:, :seq_end]
+
+        # repeat labels along time axis
+        repeated_labels = np.zeros((seq_end, n_classes))
+        for row in seq_annots.itertuples():
+            onset = row.onset_spec
+            offset = min(row.offset_spec, seq_end)
+            label = row.encoded_label
+
+            repeated_labels[onset:offset] = label
+
+        mfccs.append(mfcc.T)
+        labels.append(repeated_labels)
+        sequences.append(seq_annots["sequence"].unique()[0])
+        annotations.append(seq_annots["annotation"].unique()[0])
+
+    return annotations, sequences, mfccs, labels
+
+
+def load_mfccs_for_annotation(corpus):
+    if "syn_mfcc" not in corpus.data_resources:
+        raise MissingData(
+            "'syn_mfcc' were never computed or can't be found in Corpus. "
+            "Maybe provide and audio/spec directory to the Corpus ?"
+        )
+
+    selected_paths = corpus.dataset.notated_path.unique().tolist()
+    mfcc_paths = corpus.data_resources["syn_mfcc"]
+    mfccs = []
+    notated_paths = []
+    for row in mfcc_paths.itertuples():
+        spec_path = row.feature_path
+
+        if pd.isna(row.notated_path):
+            notated_path = spec_path
+        else:
+            notated_path = row.notated_path
+
+        # We might not want to load all data, but only the subset
+        # actually present in the corpus
+        if len(selected_paths) > 0 and notated_path not in selected_paths:
+           continue
+
+        mfcc = np.load(spec_path)
+
+        # MFCC may be stored as structured arrays for convenience
+        # (see transforms/commons/audio.py)
+        if hasattr(mfcc, "keys") and "feature" in mfcc:
+            mfcc = mfcc["feature"].squeeze()
+
+        mfccs.append(mfcc.T)
+        notated_paths.append(notated_path)
+
+    return notated_paths, mfccs