dmengine 0.4.1
Distributed Morphology calculator
Requires Python: >=3.10
Keywords: DM, Halle, Marantz, impoverishment, fission, linguistics

dmengine
========

|PyPI version| |License| |Supported Python| |Downloads|

|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.10+, 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
.. |Downloads| image:: https://img.shields.io/pypi/dm/dmengine.svg
    :target: https://pypistats.org/packages/dmengine
    :alt: Monthly downloads

.. |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