Skip to main content

Tools and algorithms for phonology-aware Early Chinese NLP.

Project description


ci docs codecov pyup pypi pyversions


this software is tested on the latest versions of macOS, windows, and ubuntu. you will need a supported version of python (above), along with pip.

$ pip install dphon

if you're on windows and are seeing incorrectly formatted output in your terminal, have a look at this stackoverflow answer.



the main function of dphon is to look for instances of text reuse in a corpus of old chinese texts. instead of relying purely on graphemes, it does this by performing grapheme-to-phoneme conversion, and determining possible reuse based on whether passages are likely to have sounded similar (or rhymed) when spoken aloud.

you will need to have files stored locally as utf-8 encoded plain-text (.txt) or json-lines (.jsonl) format. for the former, one file is assumed to represent one document. for the latter, one file can contain any number of lines, each of which is a document, with required keys id (a unique identifier) and text (text content) and any number of optional keys. you can obtain a representative corpus of old chinese sourced from the kanseki repository via direct-phonology/ect-krp.

a simple invocation of dphon might look like:

$ dphon text_a.txt text_b.txt

which would look for phonetically similar passages between text_a and text_b. the output will be a list of sequences and their phonemic transcriptions, with an identifier based on the file's name and an indicator of where in the text the sequence occurs:

1.  text_a (2208–2216):
    *ləʔ ɢʷraj kʰˤajʔ ɢʷraj kˤaʔs ɢʷraj tə ɢʷraj tə                                                                                                           
2.  text_b (3340–3348):
    不可弗爲以爲可 故爲之爲之繇其道物                                                                                                                        
    *ləʔ ɢʷraj kʰˤajʔ kˤaʔs ɢʷraj tə ɢʷraj tə pit 

the numbers next to the identifiers are token indices, and may vary depending on how the text is tokenized – dphon currently uses character-based tokenization. whitespace will be removed, and the output will be aligned to make it easier to spot differences between the two sequences. by default, insertions are highlighted in green, and mismatches (differences between the two sequences) are highlighted in red. additional (non-matching) context added to either side of match sequences is displayed using a dimmed color.

matches are sorted by the ratio of their phomenic similarity to their graphic similarity – in other words, matches between texts that sound highly similar but were written very differently will be at the top of the list.

by default, dphon only returns matches that display at least one instance of graphic variation – a case where two different graphemes are used in the same place to represent the same sound. these cases are highlighted in blue. if you're interested in all instances of reuse, regardless of graphic variation, you can use the --all flag:

$ dphon --all text_a.txt text_b.txt

you can view the full list of command options with:

$ dphon --help

this tool is under active development, and results may vary. to find the version you are running:

$ dphon --version

advanced usage

by default, dphon uses your system's $PAGER to display output, since the results can be quite long. on MacOS and Linux, this will likely be less, which supports additional options like searching through the output once it's displayed. for more information, see the man page:

$ man less

dphon can colorize output for nicer display in the terminal if your pager supports it. to enable this behavior on MacOS and Linux, set LESS=R:

$ export LESS=R

if you want to save the results of the run to a file, you can use redirection. this is useful when writing structured formats like .csv and .jsonl. you can also write html to preserve colors:

$ dphon -o html files/*.txt > results.html

alternatively, you can pipe the output of dphon to another utility like sed for filtering the results further. for example, you could strip out the ideographic space   from results to remove the alignments:

$ dphon files/*.txt | sed 's/ //g'


matching sequences are determined by a "dictionary" file that represents a particular reconstruction of old chinese phonology. these data structures perform grapheme-to-phoneme conversion, yielding the associated sound for each character:

"埃": "qˤə"
"哀": "ʔˤəj"
"藹": "qˤats"

for characters with multiple readings, dphon currently chooses the first available reading for comparison. more work is planned for version 3.0 to address this shortcoming.

in version 1.0, dphon's default reconstruction was based on Schuessler 20071, but used a single "dummy" character to represent all the lexemes in a rhyming group. the dictionary was compiled by John O'Leary (@valgrinderror) and Gian Duri Rominger (@GDRom). since version 2.0, dphon uses a dictionary based on the Baxter-Sagart 2014 reconstruction2, with additional work by Rominger.

the matching algorithm is based on Paul Vierthaler's chinesetextreuse project3, with some modifications. it uses a BLAST-like strategy to identify initial match candidates, and then extend them via phonetic edit distance comparison. finally, the results are aligned using a version of the Smith-Waterman algorithm that operates on phonemes, powered by the lingpy library4.

development setup

python >=3.6 is required.

first, clone the repository:

$ git clone
$ cd dphon

then, to create and activate a virtual environment (recommended):

$ python -m venv venv
$ source venv/bin/activate

install dependencies:

$ pip install -r dev-requirements.txt

finally, install the package itself in development mode:

$ pip install -e .

now your changes will be automatically picked up when you run dphon.

pull requests should be made against the develop branch.

code documentation

code documentation is available on github pages and is automatically generated with pdoc3 on pushes to main.

to build documentation locally:

$ pdoc --html --output-dir docs dphon


unit tests are written with unittest. you can run them with:

$ python -m unittest


make sure the version number in dphon/ is correct!

if there are any built files in dist/ from older releases, remove them before you start this process:

$ rm dist/*

to build a source archive and distribution for a release:

$ python sdist bdist_wheel

to publish the release on test PyPI (useful for making sure everything worked):

$ twine upload --repository-url dist/*

if everything is OK, publish the package to PyPI:

$ twine upload dist/*

1 Schuessler, Axel (2007), _ABC Etymological Dictionary of Old Chinese_, Honolulu: University of Hawaii Press, ISBN 978-0-8248-2975-9.

2 Baxter, William H.; Sagart, Laurent (2014), Old Chinese: A New Reconstruction, Oxford University Press, ISBN 978-0-19-994537-5.

3 Vierthaler, Paul, and Mees Gelein. “A BLAST-Based, Language-Agnostic Text Reuse Algorithm with a MARKUS Implementation and Sequence Alignment Optimized for Large Chinese Corpora,” April 26, 2019.

4 List, Johann-Mattis; Greenhill, Simon; Tresoldi, Tiago; and Forkel, Robert (2019): LingPy. A Python library for historical linguistics. Version 2.6.5. URL:, DOI: With contributions by Christoph Rzymski, Gereon Kaiping, Steven Moran, Peter Bouda, Johannes Dellert, Taraka Rama, Frank Nagel. Jena: Max Planck Institute for the Science of Human History.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for dphon, version 2.0.0
Filename, size File type Python version Upload date Hashes
Filename, size dphon-2.0.0-py3-none-any.whl (179.4 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size dphon-2.0.0.tar.gz (162.6 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page