Potnia

Potnia: A Python library for the conversion of transliterated ancient texts to Unicode - Published in JOSS (2025)

https://github.com/ancientnlp/potnia

Keywords from Contributors

Scientific Fields

Repository

Potnia is an open-source Python library designed to convert Romanized transliterations of ancient texts into Unicode representations of their respective native scripts.

README.rst

================================================================
Potnia
================================================================

.. image:: https://raw.githubusercontent.com/AncientNLP/potnia/main/docs/_static/img/PotniaLogo.png

.. start-summary

|pypi badge| |testing badge| |coverage badge| |docs badge| |git3moji badge| |black badge| |JOSS badge|

.. |pypi badge| image:: https://img.shields.io/pypi/v/potnia
    :target: https://pypi.org/project/potnia/

.. |testing badge| image:: https://github.com/AncientNLP/potnia/actions/workflows/testing.yml/badge.svg
    :target: https://github.com/AncientNLP/potnia/actions
    
.. |coverage badge| image:: https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/rbturnbull/e640f26fb59e39e3051de8fbf020de62/raw/coverage.json
    :target: https://ancientnlp.github.io/potnia/coverage/

.. |docs badge| image:: https://github.com/AncientNLP/potnia/actions/workflows/docs.yml/badge.svg
    :target: https://ancientnlp.github.io/potnia
    
.. |black badge| image:: https://img.shields.io/badge/code%20style-black-000000.svg
    :target: https://github.com/psf/black

.. |git3moji badge| image:: https://img.shields.io/badge/git3moji-%E2%9A%A1%EF%B8%8F%F0%9F%90%9B%F0%9F%93%BA%F0%9F%91%AE%F0%9F%94%A4-fffad8.svg
    :target: https://robinpokorny.github.io/git3moji/

.. |JOSS badge| image:: https://joss.theoj.org/papers/7641150c49e996a21fa0f4dc3aadb258/status.svg
    :target: https://joss.theoj.org/papers/7641150c49e996a21fa0f4dc3aadb258





Potnia is an open-source Python library designed to convert Romanized transliterations of ancient texts into Unicode representations of ther respective native scripts.

Currently, the scripts supported by Potnia are:

- Linear A
- Linear B
- Hittite cuneiform
- Arabic

Functionality for Luwian hieroglyphs, Sumero-Akkadian cuneiform, Lydian and Etruscan is in development.

Contributions are welcome! Please see the `CONTRIBUTING.rst `_ file for more information.

.. end-summary


.. start-quickstart

Installation
====================

To install Potnia, run the following command:

.. code-block:: bash

    pip install potnia

To install the latest version from the repository, you can use this command:

.. code-block:: bash

    pip install git+https://github.com/AncientNLP/potnia.git

You can also install Potnia by cloning the repository and installing using poetry. 
This will install all the dependencies required for Potnia from the with the version numbers pinned in the ``poetry.lock`` file. 
Make sure that poetry is installed on your system. If not, see the `instructions `_.
Then follow these steps:

.. code-block:: bash

    git clone https://github.com/AncientNLP/potnia.git
    cd potnia
    poetry install

You can test that Potnia is working by running ``pytest``.

.. note::

    For proper display of ancient script glyphs, please refer to the `Fonts `_  section.

Usage
====================

To convert transliterated Linear B to Linear B Unicode, use the following code:

.. code-block:: python

    >>> from potnia import linear_b
    >>> linear_b("a-ri-to-jo")
    '𐀀𐀪𐀵𐀍'


If you wish to regularize the text to remove additional annotations present in the `LiBER `_ 
and  `DĀMOS `_ transliteration, use the following code:

.. code-block:: python

    >>> linear_b("e-ke-qe ]-o-na-to , ke-ke-me-na⌞ ⌟ko-to-na GRA qs ] vac.", regularize=True)
    '𐀁𐀐𐀤 %𐀃𐀙𐀵 𐀐𐀐𐀕𐀙 𐀒𐀵𐀙 𐂎 %'

Note that uncertain/missing signs or sections of text are presently being replaced with a wildcard '%' character.

To tokenize transliterated Linear B texts without converting it to Unicode, use the following code:

.. code-block:: python

    >>> linear_b.tokenize_transliteration("]wa VIR 1 MUL 2 'ko-wa 1' ko-wo 1")
    [']', 'wa', ' ', 'VIR', ' ', '1', ' ', 'MUL', ' ', '2', ' ', "'", 'ko', 'wa', ' ', '1', "'", ' ', 'ko', 'wo', ' ', '1']

Command Line Interface (CLI)
============================

Potnia also provides a command line interface (CLI).

To convert transliterated Linear B to Unicode, use the following command:

.. code-block:: bash

    potnia linear-b "a-ri-to-jo"

To regularize the text, use the following command:

.. code-block:: bash

    potnia linear-b "e-ke-qe ]-o-na-to , ke-ke-me-na⌞ ⌟ko-to-na GRA qs ] vac." --regularize

To see the full set of commands available in the CLI, use the following command:

.. code-block:: bash

    potnia --help

Graphical User Interface (GUI)
==============================

.. image:: https://raw.githubusercontent.com/AncientNLP/potnia/main/docs/_static/img/potnia-gui.png

Potnia also provides a graphical user interface (GUI). To start it, run:

.. code-block:: bash

    potnia gui

This will show a link in the terminal that you can click on to open the GUI in your browser.

    
.. end-quickstart

Credits
====================

.. start-credits

Potnia is developed by:

- Emily Tour (University of Melbourne)
- `Kabir Manandhar Shrestha `_ (Melbourne Data Analytics Platform, University of Melbourne)
- `Dr Robert Turnbull `_ (Melbourne Data Analytics Platform, University of Melbourne)

To cite Potnia, use this reference:

    Tour, Emily, Kabir Manandhar Shrestha, and Robert Turnbull. 'Potnia: A Python Library for the Conversion of Transliterated Ancient Texts to Unicode.' *Journal of Open Source Software* 10, no. 108 (2025): 7725. `doi:10.21105/joss.07725 `_

You can also use the following BibTeX entries:

.. code-block:: bibtex

    @article{potnia, 
        author       = {Emily Tour and Kabir Manandhar Shrestha and Robert Turnbull},
        title        = {{Potnia: A Python library for the conversion of transliterated ancient texts to Unicode}},
        year         = {2025}, 
        journal      = {Journal of Open Source Software},
        publisher    = {The Open Journal}, 
        volume       = {10}, 
        number       = {108},
        pages        = {7725},
        doi          = {10.21105/joss.07725}, 
        url          = {https://doi.org/10.21105/joss.07725}
    }

    @misc{potnia_release,
        author       = {Emily Tour and Kabir Manandhar Shrestha and Robert Turnbull},
        title        = {{Potnia: A Python library for the conversion of transliterated ancient texts to Unicode}},
        year         = {2025},
        url          = {https://doi.org/10.26188/28721354.v1},
        note         = {Version 0.4.0, Apache License 2.0},
        doi          = {10.26188/28721354.v1}
    }

We acknowledge support from Wytamma Wirth, Brent Davis, Kim Doyle, Man-Hua (Kate) Chu, Anhui (Ellie) Situ, Ekaterina Vylomova, Chris Guest and Stavroula (Stephie) Nikoloudis. This research was supported by The University of Melbourne’s Research Computing Services. Robert Turnbull completed part of this work through the BICROSS project, which has received funding from the European Research Council (ERC) under the European Union’s Horizon Europe research and innovation programme (grant agreement no. 101043730 – BICROSS – ERC-2021-COG).

.. image:: https://raw.githubusercontent.com/AncientNLP/potnia/main/docs/_static/img/erc-logo.jpg
    :alt: ERC logo
    :align: center
    :width: 200px

.. end-credits

GitHub Events

Committers

Last synced: 7 months ago

Issues and Pull Requests

Last synced: 6 months ago

Packages