dmengine
========
|PyPI version| |License| |Supported Python| |Wheel|
|Build| |Codecov|
DM-engine is a Python implementation of **Distributed Morphology** (DM_).
Distributed Morphology is a framework from theoretical linguistics that is used
to describe the morphology (word structure) of natural languages. This package
provides an engine that calculates the word forms that are generated by a given
DM analysis.
Analyses are entered as plain-text files in the human-friendly YAML_ format.
Minimally, they consist of a **title**, an inventory of **feature values**, a
list of insertable **vocabulary items** (VIs), and a list of **inputs** to be
processed (see the example below). The ``dmengine`` command-line tool calculates
the results and generates a detailed transcript of all calculations for later
inspection. The resulting YAML file can be converted into a LaTeX-based report
that can directly be compiled into a PDF file.
Links
-----
- GitHub: https://github.com/xflr6/dmengine
- PyPI: https://pypi.org/project/dmengine/
- Issue Tracker: https://github.com/xflr6/dmengine/issues
- Download: https://pypi.org/project/dmengine/#files
Installation
------------
This package runs under Python 3.7+, use pip_ to install:
.. code:: bash
$ pip install dmengine
This will also install the PyYAML_ and oset_ packages from PyPI as required
dependencies.
Converting the results to a **PDF report** also requires a **LaTeX
distribution** (`TeX Live`_ and MikTeX_ should work). Make sure its executables
are on your systems' path.
Usage
-----
Create a **plain text file** that defines your analysis:
.. code:: yaml
# example.yaml - simple demonstration of the analysis definition syntax
title: English verbal agreement
features:
- value: V
category: pos
- value: Nom
category: case
- value: +1
category: person
- value: +2
category: person
- value: +3
category: person
- value: -pl
category: number
- value: +pl
category: number
vis:
- exponent: sleep
features: [ V ]
- exponent: -s
features: [ Nom, +3, -pl ]
- exponent: -Ø
features: [ Nom ]
paradigms:
- name: Intransitive paradigm
headers: [ [1, 2, 3], [sg, pl] ]
inputs:
- [ [V], [Nom, +1, -pl] ]
- [ [V], [Nom, +1, +pl] ]
- [ [V], [Nom, +2, -pl] ]
- [ [V], [Nom, +2, +pl] ]
- [ [V], [Nom, +3, -pl] ]
- [ [V], [Nom, +3, +pl] ]
Save your analysis definition to a file ending with ``.yaml`` (e.g.
``example.yaml``).
Open a shell (command line window) and navigate to the directory of your
definition file.
Calculate the results of the analyis with the ``dmengine`` command creating a
PDF report:
.. code:: bash
$ dmengine example.yaml --pdf
This will create three files:
- ``example-results.yaml`` |--| plain-text file with the results in YAML format
- ``example-results.tex`` |--| LaTeX source for the result report
- ``example-results.pdf`` |--| PDF output of the report compiled with ``pdflatex``
Results
-------
Go to the **outputs section** of the report. It provides a **paradigm table**
of the calculated results:
.. image:: https://raw.github.com/xflr6/dmengine/master/docs/example-outputs.png
The **log section** of the report contains detailed information about each
individual input and the **derivation of the output**.
.. image:: https://raw.github.com/xflr6/dmengine/master/docs/example-log.png
Invocation options
------------------
Check the **usage** of the ``dmengine`` command:
.. code:: bash
$ dmengine --help
usage: dmengine [-h] [--version] [--report] [--pdf] [--view]
filename [directory]
Calculates a given Distributed Morphology (DM) analysis
positional arguments:
filename dm analysis .yaml definition file
directory analysis results output directory
optional arguments:
-h, --help show this help message and exit
--version show program's version number and exit
--report create a LaTeX report from the results
--pdf render the report to PDF (implies --report)
--view open the report in viewer app (implies --pdf)
Rules
-----
Analyses can use the following types of **rules** that manipulate the input
*before* insertion:
- ``impoverishment`` |--| feature deletion
- ``obliteration`` |--| head removal
- ``fission`` |--| head feature extraction
- ``fusion`` |--| head merging
- ``copy`` |--| head duplication
- ``add`` |--| features addition
- ``metathesis`` |--| head position swapping
The following types of **readjustment rules** are supported (manipulating the
output *after* insertion):
- ``delete`` |--| exponent removal
- ``copy`` |--| exponent duplication
- ``metathesis`` |--| exponent position swapping
- ``transform`` |--| regular expression search & replace
Contexts
--------
The insertion of vocabulary items and the application of pre-insertion rules can
be restricted to the following context types:
- ``this_head`` |--| the processed head must have the features
- ``left_head`` |--| the left-adjacent head must have the features
- ``right_head`` |--| the right-adjacent head must have the features
- ``any_head`` |--| any input head must have the features
- ``anywhere`` |--| features must be matched somewhere in the input
TODO
----
- check expected spell-out for each input
- delete_matching: yes/no
- delete_other: all, given, none
- set_delete: global, slot, vi
See also
--------
Raphael Finkel provides `web-based engines`_ for calculating Paradigm Function
Morphology and Network Morphology analyses.
License
-------
``dmengine`` is distributed under the `MIT license`_.
.. _DM: https://www.ling.upenn.edu/~rnoyer/dm/
.. _YAML: https://en.wikipedia.org/wiki/YAML
.. _pip: https://pip.readthedocs.io
.. _PyYAML: https://pypi.org/project/PyYAML/
.. _oset: https://pypi.org/project/oset/
.. _TeX Live: https://www.tug.org/texlive/
.. _MikTeX: https://miktex.org
.. _web-based engines: https://www.cs.uky.edu/~raphael/linguistics/claw.html
.. _MIT license: https://opensource.org/licenses/MIT
.. |--| unicode:: U+2013
.. |PyPI version| image:: https://img.shields.io/pypi/v/dmengine.svg
:target: https://pypi.org/project/dmengine/
:alt: Latest PyPI Version
.. |License| image:: https://img.shields.io/pypi/l/dmengine.svg
:target: https://github.com/xflr6/dmengine/blob/master/LICENSE.txt
:alt: License
.. |Supported Python| image:: https://img.shields.io/pypi/pyversions/dmengine.svg
:target: https://pypi.org/project/dmengine/
:alt: Supported Python Versions
.. |Wheel| image:: https://img.shields.io/pypi/wheel/graphviz.svg
:target: https://pypi.org/project/dmengine/#files
:alt: Wheel format
.. |Build| image:: https://github.com/xflr6/csv23/actions/workflows/build.yaml/badge.svg?branch=master
:target: https://github.com/xflr6/csv23/actions/workflows/build.yaml?query=branch%3Amaster
:alt: Build
.. |Codecov| image:: https://codecov.io/gh/xflr6/dmengine/branch/master/graph/badge.svg
:target: https://codecov.io/gh/xflr6/dmengine
:alt: Codecov
Raw data
{
"_id": null,
"home_page": "https://github.com/xflr6/dmengine",
"name": "dmengine",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "DM Halle Marantz impoverishment fission linguistics",
"author": "Sebastian Bank",
"author_email": "sebastian.bank@uni-leipzig.de",
"download_url": "https://files.pythonhosted.org/packages/20/d8/2f7762a1e96b5d364ef773b985570dfac4aa4acdf6201b8ba4b334c13f08/dmengine-0.3.1.zip",
"platform": "any",
"description": "dmengine\n========\n\n|PyPI version| |License| |Supported Python| |Wheel|\n\n|Build| |Codecov|\n\nDM-engine is a Python implementation of **Distributed Morphology** (DM_).\n\nDistributed Morphology is a framework from theoretical linguistics that is used\nto describe the morphology (word structure) of natural languages. This package\nprovides an engine that calculates the word forms that are generated by a given\nDM analysis.\n\nAnalyses are entered as plain-text files in the human-friendly YAML_ format.\nMinimally, they consist of a **title**, an inventory of **feature values**, a\nlist of insertable **vocabulary items** (VIs), and a list of **inputs** to be\nprocessed (see the example below). The ``dmengine`` command-line tool calculates\nthe results and generates a detailed transcript of all calculations for later\ninspection. The resulting YAML file can be converted into a LaTeX-based report\nthat can directly be compiled into a PDF file.\n\n\nLinks\n-----\n\n- GitHub: https://github.com/xflr6/dmengine\n- PyPI: https://pypi.org/project/dmengine/\n- Issue Tracker: https://github.com/xflr6/dmengine/issues\n- Download: https://pypi.org/project/dmengine/#files\n\n\nInstallation\n------------\n\nThis package runs under Python 3.7+, use pip_ to install:\n\n.. code:: bash\n\n $ pip install dmengine\n\nThis will also install the PyYAML_ and oset_ packages from PyPI as required\ndependencies.\n\nConverting the results to a **PDF report** also requires a **LaTeX\ndistribution** (`TeX Live`_ and MikTeX_ should work). Make sure its executables\nare on your systems' path.\n\n\nUsage\n-----\n\nCreate a **plain text file** that defines your analysis:\n\n.. code:: yaml\n\n # example.yaml - simple demonstration of the analysis definition syntax\n title: English verbal agreement\n features:\n - value: V\n category: pos\n - value: Nom\n category: case\n - value: +1\n category: person\n - value: +2\n category: person\n - value: +3\n category: person\n - value: -pl\n category: number\n - value: +pl\n category: number\n vis:\n - exponent: sleep\n features: [ V ]\n - exponent: -s\n features: [ Nom, +3, -pl ]\n - exponent: -\u00d8\n features: [ Nom ]\n paradigms:\n - name: Intransitive paradigm\n headers: [ [1, 2, 3], [sg, pl] ]\n inputs:\n - [ [V], [Nom, +1, -pl] ]\n - [ [V], [Nom, +1, +pl] ]\n - [ [V], [Nom, +2, -pl] ]\n - [ [V], [Nom, +2, +pl] ]\n - [ [V], [Nom, +3, -pl] ]\n - [ [V], [Nom, +3, +pl] ]\n\nSave your analysis definition to a file ending with ``.yaml`` (e.g.\n``example.yaml``).\n\nOpen a shell (command line window) and navigate to the directory of your\ndefinition file.\n\nCalculate the results of the analyis with the ``dmengine`` command creating a\nPDF report:\n\n.. code:: bash\n\n $ dmengine example.yaml --pdf\n\nThis will create three files:\n\n- ``example-results.yaml`` |--| plain-text file with the results in YAML format\n- ``example-results.tex`` |--| LaTeX source for the result report\n- ``example-results.pdf`` |--| PDF output of the report compiled with ``pdflatex``\n\n\nResults\n-------\n\nGo to the **outputs section** of the report. It provides a **paradigm table**\nof the calculated results:\n\n.. image:: https://raw.github.com/xflr6/dmengine/master/docs/example-outputs.png\n\nThe **log section** of the report contains detailed information about each\nindividual input and the **derivation of the output**.\n\n.. image:: https://raw.github.com/xflr6/dmengine/master/docs/example-log.png\n\n\nInvocation options\n------------------\n\nCheck the **usage** of the ``dmengine`` command:\n\n.. code:: bash\n\n $ dmengine --help\n \n usage: dmengine [-h] [--version] [--report] [--pdf] [--view]\n filename [directory]\n \n Calculates a given Distributed Morphology (DM) analysis\n \n positional arguments:\n filename dm analysis .yaml definition file\n directory analysis results output directory\n \n optional arguments:\n -h, --help show this help message and exit\n --version show program's version number and exit\n --report create a LaTeX report from the results\n --pdf render the report to PDF (implies --report)\n --view open the report in viewer app (implies --pdf)\n\n\nRules\n-----\n\nAnalyses can use the following types of **rules** that manipulate the input\n*before* insertion:\n\n- ``impoverishment`` |--| feature deletion\n- ``obliteration`` |--| head removal\n- ``fission`` |--| head feature extraction\n- ``fusion`` |--| head merging\n- ``copy`` |--| head duplication\n- ``add`` |--| features addition\n- ``metathesis`` |--| head position swapping\n\n\nThe following types of **readjustment rules** are supported (manipulating the\noutput *after* insertion):\n\n- ``delete`` |--| exponent removal\n- ``copy`` |--| exponent duplication\n- ``metathesis`` |--| exponent position swapping\n- ``transform`` |--| regular expression search & replace\n\n\nContexts\n--------\n\nThe insertion of vocabulary items and the application of pre-insertion rules can\nbe restricted to the following context types:\n\n- ``this_head`` |--| the processed head must have the features\n- ``left_head`` |--| the left-adjacent head must have the features\n- ``right_head`` |--| the right-adjacent head must have the features\n- ``any_head`` |--| any input head must have the features\n- ``anywhere`` |--| features must be matched somewhere in the input\n\n\nTODO\n----\n\n- check expected spell-out for each input\n- delete_matching: yes/no\n- delete_other: all, given, none\n- set_delete: global, slot, vi\n\n\nSee also\n--------\n\nRaphael Finkel provides `web-based engines`_ for calculating Paradigm Function\nMorphology and Network Morphology analyses.\n\n\nLicense\n-------\n\n``dmengine`` is distributed under the `MIT license`_.\n\n\n.. _DM: https://www.ling.upenn.edu/~rnoyer/dm/\n\n.. _YAML: https://en.wikipedia.org/wiki/YAML\n.. _pip: https://pip.readthedocs.io\n.. _PyYAML: https://pypi.org/project/PyYAML/\n.. _oset: https://pypi.org/project/oset/\n.. _TeX Live: https://www.tug.org/texlive/\n.. _MikTeX: https://miktex.org\n\n.. _web-based engines: https://www.cs.uky.edu/~raphael/linguistics/claw.html\n\n.. _MIT license: https://opensource.org/licenses/MIT\n\n\n.. |--| unicode:: U+2013\n\n\n.. |PyPI version| image:: https://img.shields.io/pypi/v/dmengine.svg\n :target: https://pypi.org/project/dmengine/\n :alt: Latest PyPI Version\n.. |License| image:: https://img.shields.io/pypi/l/dmengine.svg\n :target: https://github.com/xflr6/dmengine/blob/master/LICENSE.txt\n :alt: License\n.. |Supported Python| image:: https://img.shields.io/pypi/pyversions/dmengine.svg\n :target: https://pypi.org/project/dmengine/\n :alt: Supported Python Versions\n.. |Wheel| image:: https://img.shields.io/pypi/wheel/graphviz.svg\n :target: https://pypi.org/project/dmengine/#files\n :alt: Wheel format\n\n.. |Build| image:: https://github.com/xflr6/csv23/actions/workflows/build.yaml/badge.svg?branch=master\n :target: https://github.com/xflr6/csv23/actions/workflows/build.yaml?query=branch%3Amaster\n :alt: Build\n.. |Codecov| image:: https://codecov.io/gh/xflr6/dmengine/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/xflr6/dmengine\n :alt: Codecov\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Distributed Morphology calculator",
"version": "0.3.1",
"project_urls": {
"CI": "https://github.com/xflr6/dmengine/actions",
"Homepage": "https://github.com/xflr6/dmengine",
"Issue Tracker": "https://github.com/xflr6/dmengine/issues"
},
"split_keywords": [
"dm",
"halle",
"marantz",
"impoverishment",
"fission",
"linguistics"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ef4897c81b79d77d2b3f7d144dbb889183083c763dddc5b91a37b50445d49e3f",
"md5": "a0f60c1e44f91309219f81c7b4bbf95c",
"sha256": "1dff4a9b1b723af801654d44cd059237e28a5488fcf9225e44ef97a9774885ee"
},
"downloads": -1,
"filename": "dmengine-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a0f60c1e44f91309219f81c7b4bbf95c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 36433,
"upload_time": "2022-06-12T10:37:09",
"upload_time_iso_8601": "2022-06-12T10:37:09.117530Z",
"url": "https://files.pythonhosted.org/packages/ef/48/97c81b79d77d2b3f7d144dbb889183083c763dddc5b91a37b50445d49e3f/dmengine-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "20d82f7762a1e96b5d364ef773b985570dfac4aa4acdf6201b8ba4b334c13f08",
"md5": "43262c7be93683529ae9f6b5f35697ee",
"sha256": "535a56cd51cf31b7ea5b6051898d438b33d0916429475f788dc42da111082ce5"
},
"downloads": -1,
"filename": "dmengine-0.3.1.zip",
"has_sig": false,
"md5_digest": "43262c7be93683529ae9f6b5f35697ee",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 78309,
"upload_time": "2022-06-12T10:37:10",
"upload_time_iso_8601": "2022-06-12T10:37:10.925219Z",
"url": "https://files.pythonhosted.org/packages/20/d8/2f7762a1e96b5d364ef773b985570dfac4aa4acdf6201b8ba4b334c13f08/dmengine-0.3.1.zip",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-06-12 10:37:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "xflr6",
"github_project": "dmengine",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "dmengine"
}
JSON
