G2p improvements (v2.0.0b11) (MontrealCorpusTools#383)

Performance improvements
Aditya514 · Jan 3, 2022 · 63473f9 · 63473f9
1 parent d8bddd4
commit 63473f9
Show file tree

Hide file tree

Showing 90 changed files with 7,950 additions and 5,857 deletions.
diff --git a/.gitignore b/.gitignore
@@ -85,3 +85,5 @@ montreal_forced_aligner/_version.py
 <<<<<<< main
 
 docs/source/reference/multiprocessing/generated/
+
+*.lprof
diff --git a/README.md b/README.md
@@ -10,4 +10,55 @@ The Montreal Forced Aligner is a command line utility for performing forced alig
 
 Please see the documentation http://montreal-forced-aligner.readthedocs.io for installation and usage.
 
-If you run into any issues, please check the [mailing list](https://groups.google.com/forum/#!forum/mfa-users) for fixes/workarounds or to post a new issue.
+If you run into any issues, please check the [mailing list](https://groups.google.com/forum/#!forum/mfa-users) for fixes/workarounds or to post a [new issue](https://github.com/MontrealCorpusTools/Montreal-Forced-Aligner/issues).
+
+## Installation
+
+You can install MFA either entirely through [conda](https://docs.conda.io/en/latest/) or a mix of conda for Kaldi and Pynini dependencies and Python packaging for MFA itself
+
+### Conda installation
+
+MFA is hosted on [conda-forge](https://conda-forge.org/) and can be installed via:
+
+```
+conda install -c conda-forge montreal-forced-aligner
+```
+
+in your environment of choice.
+
+### Source installation
+
+If you'd like to install a local version of MFA or want to use the development set up, the easiest way is first create the dev environment from the yaml in the repo root directory:
+
+```
+conda create -n mfa-dev -f environment.yml  # or environment_win.yml on Windows
+```
+
+Alternatively, the dependencies can be installed via:
+
+```
+conda install -c conda-forge python=3.8 kaldi sox librosa biopython praatio tqdm requests colorama pyyaml  # and pynini if on Linux or Mac
+```
+
+MFA can be installed in develop mode via:
+
+```
+pip install -e .[dev]
+```
+
+You should be able to see appropriate output from `mfa version`
+
+#### Development
+
+The test suite is run via `tox -e py38-win` or `tox -e py38-unix` depending on the OS, and the docs are generated via `tox -e docs`
+
+
+## Quick links
+
+* [Getting started docs](https://montreal-forced-aligner.readthedocs.io/en/latest/getting_started.html)
+* [User Guide](https://montreal-forced-aligner.readthedocs.io/en/latest/user_guide/index.html)
+* [API Reference](https://montreal-forced-aligner.readthedocs.io/en/latest/reference/index.html)
+* [Release notes](https://montreal-forced-aligner.readthedocs.io/en/latest/changelog/index.html)
+* [MFA Models](https://github.com/MontrealCorpusTools/mfa-models)
+* [Eleanor Chodroff's MFA tutorial](https://www.eleanorchodroff.com/tutorial/montreal-forced-aligner-v2.html)
+* [@mmcauliffe's forced alignment blog posts](https://memcauliffe.com/tag/forced-alignment.html)
diff --git a/docs/source/_static/interrogate_badge.svg b/docs/source/_static/interrogate_badge.svg
diff --git a/docs/source/changelog/changelog_2.0.rst b/docs/source/changelog/changelog_2.0.rst
@@ -10,6 +10,20 @@
 Beta releases
 =============
 
+2.0.0b11
+--------
+
+- Re-optimized corpus loading following the switch to a more class-based API.
+- Optimized validation, particularly when acoustics are being ignored
+- Added better progress bars for corpus loading, acoustic modeling, G2P training, transcription and alignment
+- Changed the default behavior of G2P generation to use a threshold system rather than returning a single top pronunciation.  The threshold defaults to 0.99, but can be specified through ``--g2p_threshold``.  Specifying number of pronunciations will override this behavior (use ``--num_pronunciation 1`` for the old behavior).
+- Changed the behavior of G2P evaluation to check whether the generated hypothesis is in the golden pronunciation set, so languages with pronunciation variation will be less penalized in evaluation
+- Added :class:`~montreal_forced_aligner.data.Word` and :class:`~montreal_forced_aligner.data.Pronunciation` data classes
+- Refactored and simplified TextGrid export process
+- Removed the ``multilingual_ipa`` mode in favor of a more general approach to better modeling phones
+- Added functionality to evaluate alignments against golden alignment set
+- Added the ability to compare alignments to a reference aligned, such as human annotated data. The evaluation will compute overlap score (sum of difference in aligned phone boundaries versus the reference phone boundaries) and overall phone error rate for each utterance.
+
 2.0.0b10
 --------
 
@@ -122,7 +136,7 @@ Beta release!
 
 - Add support for aligning mp3 files
 - Fix for log error in 0 probability entries in probabilistic lexicons
-- Add support for multilingual IPA mode (see :ref:`multilingual_ipa` for more details)
+- Add support for multilingual IPA mode
 - Add support for specifying per-speaker pronunciation dictionaries (see :ref:`speaker_dictionaries` for more details)
 - Fixed cases where TextGrid parsing errors were misattributed to sound file issues, and these should be properly detected
   by the validator now

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -23,6 +23,7 @@
 
 sys.path.insert(0, os.path.abspath("../../"))
 import montreal_forced_aligner  # noqa
+from montreal_forced_aligner.utils import get_mfa_version  # noqa
 
 # -- General configuration ------------------------------------------------
 
@@ -53,7 +54,10 @@
     # "sphinx_autodoc_typehints",
 ]
 panels_add_bootstrap_css = False
-intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "Bio": ("https://biopython.org/docs/latest/api/", None),
+}
 
 extlinks = {
     "mfa_pr": ("https://github.com/MontrealCorpusTools/Montreal-Forced-Aligner/pull/%s", "PR #%s"),
@@ -135,7 +139,6 @@
     "MultispeakerDictionary": "montreal_forced_aligner.dictionary.MultispeakerDictionary",
     "Trainer": "montreal_forced_aligner.abc.Trainer",
     "Aligner": "montreal_forced_aligner.abc.Aligner",
-    "DictionaryData": "montreal_forced_aligner.dictionary.DictionaryData",
     "Utterance": "montreal_forced_aligner.corpus.classes.Utterance",
     "File": "montreal_forced_aligner.corpus.classes.File",
     "FeatureConfig": "montreal_forced_aligner.config.FeatureConfig",
@@ -187,9 +190,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = ".".join(montreal_forced_aligner.utils.get_mfa_version().split(".", maxsplit=2)[:2])
+version = ".".join(get_mfa_version().split(".", maxsplit=2)[:2])
 # The full version, including alpha/beta/rc tags.
-release = montreal_forced_aligner.utils.get_mfa_version()
+release = get_mfa_version()
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst
@@ -1,8 +1,6 @@
 
 .. _`Conda forge`: https://conda-forge.org/
 
-.. _getting_started_ref:
-
 ***************
 Getting started
 ***************
@@ -45,7 +43,7 @@ Installation
 
     +++
 
-    .. link-button:: installation_ref
+    .. link-button:: installation
             :type: ref
             :text: To the installation guide
             :classes: btn-block btn-primary btn-navigation stretched-link

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -18,7 +18,7 @@ Montreal Forced Aligner documentation
 
     +++
 
-    .. link-button:: getting_started_ref
+    .. link-button:: getting_started
             :type: ref
             :text: Install MFA
             :classes: btn-block btn-primary btn-navigation stretched-link

diff --git a/docs/source/installation.rst b/docs/source/installation.rst
@@ -1,6 +1,4 @@
 
-.. _installation_ref:
-
 ************
 Installation
 ************

diff --git a/docs/source/reference/acoustic_modeling/helper.rst b/docs/source/reference/acoustic_modeling/helper.rst
@@ -21,7 +21,6 @@ Multiprocessing workers and functions
 .. autosummary::
    :toctree: generated/
 
-   acc_stats_func
    compute_alignment_improvement_func
    compare_alignments
 
@@ -31,7 +30,7 @@ Multiprocessing workers and functions
 .. autosummary::
    :toctree: generated/
 
-   mono_align_equal_func
+   MonoAlignEqualFunction
 
 
 .. currentmodule:: montreal_forced_aligner.acoustic_modeling.triphone
@@ -40,24 +39,24 @@ Multiprocessing workers and functions
    :toctree: generated/
 
    tree_stats_func
-   convert_alignments_func
+   ConvertAlignmentsFunction
 
 
 .. currentmodule:: montreal_forced_aligner.acoustic_modeling.lda
 
 .. autosummary::
    :toctree: generated/
 
-   lda_acc_stats_func
-   calc_lda_mllt_func
+   LdaAccStatsFunction
+   CalcLdaMlltFunction
 
 
 .. currentmodule:: montreal_forced_aligner.acoustic_modeling.sat
 
 .. autosummary::
    :toctree: generated/
 
-   acc_stats_two_feats_func
+   AccStatsTwoFeatsFunction
 
 Multiprocessing argument classes
 --------------------------------
@@ -67,7 +66,6 @@ Multiprocessing argument classes
 .. autosummary::
    :toctree: generated/
 
-   AccStatsArguments
    AlignmentImprovementArguments
 
 

diff --git a/docs/source/reference/alignment/helper.rst b/docs/source/reference/alignment/helper.rst
@@ -15,60 +15,34 @@ Mixins
 Multiprocessing workers and functions
 -------------------------------------
 
-.. currentmodule:: montreal_forced_aligner.alignment.adapting
-
-.. autosummary::
-   :toctree: generated/
-
-   map_acc_stats_func
-
 .. currentmodule:: montreal_forced_aligner.alignment.multiprocessing
 
 .. autosummary::
    :toctree: generated/
 
-   align_func
-   compile_train_graphs_func
+   AlignFunction
+   CompileTrainGraphsFunction
    compile_information_func
-   ali_to_ctm_func
+   AliToCtmFunction
+   AccStatsFunction
+   WordCtmProcessWorker
    PhoneCtmProcessWorker
-   CleanupWordCtmProcessWorker
-   NoCleanupWordCtmProcessWorker
-   CombineProcessWorker
-   ExportPreparationProcessWorker
    ExportTextGridProcessWorker
 
 
 Multiprocessing argument classes
 --------------------------------
 
-.. currentmodule:: montreal_forced_aligner.alignment.adapting
-
-.. autosummary::
-   :toctree: generated/
-
-   MapAccStatsArguments
-
 .. currentmodule:: montreal_forced_aligner.alignment.multiprocessing
 
 .. autosummary::
    :toctree: generated/
 
    AlignArguments
-   compile_train_graphs_func
+   AccStatsArguments
    CompileTrainGraphsArguments
-   compile_information_func
    CompileInformationArguments
-   ali_to_ctm_func
    AliToCtmArguments
-   PhoneCtmProcessWorker
    PhoneCtmArguments
-   CleanupWordCtmProcessWorker
-   CleanupWordCtmArguments
-   NoCleanupWordCtmProcessWorker
-   NoCleanupWordCtmArguments
-   CombineProcessWorker
-   CombineCtmArguments
-   ExportPreparationProcessWorker
-   ExportTextGridProcessWorker
+   WordCtmArguments
    ExportTextGridArguments
diff --git a/docs/source/reference/corpus/index.rst b/docs/source/reference/corpus/index.rst
@@ -96,14 +96,13 @@ Features
    :toctree: generated/
 
    FeatureConfigMixin
-   mfcc_func
+   MfccFunction
    MfccArguments
-   calc_fmllr_func
+   CalcFmllrFunction
    CalcFmllrArguments
    IvectorConfigMixin
    VadConfigMixin
-   compute_vad_func
-   VadArguments
+   ComputeVadFunction
    VadArguments
 
 Ivector
@@ -114,5 +113,5 @@ Ivector
 .. autosummary::
    :toctree: generated/
 
-   extract_ivectors_func
+   ExtractIvectorsFunction
    ExtractIvectorsArguments
diff --git a/docs/source/reference/dictionary/helper.rst b/docs/source/reference/dictionary/helper.rst
@@ -21,8 +21,9 @@ Mixins
    :toctree: generated/
 
    DictionaryMixin
+   TemporaryDictionaryMixin
 
-.. currentmodule:: montreal_forced_aligner.dictionary.base
+.. currentmodule:: montreal_forced_aligner.dictionary.pronunciation
 
 .. autosummary::
    :toctree: generated/
@@ -39,19 +40,20 @@ Mixins
 Helper
 ------
 
-.. currentmodule:: montreal_forced_aligner.dictionary
+.. currentmodule:: montreal_forced_aligner.dictionary.mixins
 
 .. autosummary::
    :toctree: generated/
 
-   DictionaryData -- Data class generated by PronunciationDictionary to parse to and from Kaldi-internal strings
+   SanitizeFunction
+   SplitWordsFunction
 
-.. currentmodule:: montreal_forced_aligner.dictionary.mixins
+.. currentmodule:: montreal_forced_aligner.dictionary.multispeaker
 
 .. autosummary::
    :toctree: generated/
 
-   SanitizeFunction
+   MultispeakerSanitizationFunction
 
 Pronunciation probability functionality
 =======================================

diff --git a/docs/source/reference/helper/abc.rst b/docs/source/reference/helper/abc.rst
@@ -3,7 +3,9 @@
     .. autosummary::
        :toctree: generated/
 
+       KaldiFunction
        MfaModel -- Base model type for MFA
+       MfaCorpusClass
        MfaWorker -- Base worker class for MFA
        TopLevelMfaWorker -- MFA workers that have acoustic models
        TrainerMixin -- Trainer type interface

diff --git a/docs/source/reference/helper/data.rst b/docs/source/reference/helper/data.rst
@@ -3,4 +3,12 @@
     .. autosummary::
        :toctree: generated/
 
+       TextFileType
+       SoundFileType
+       SoundFileInformation
+       PhoneSetType
+       Word
+       Pronunciation
+       UtteranceData
+       FileData
        CtmInterval -- Data class for representing intervals in Kaldi's CTM files