MonodiKit: Medieval Chant Document Analysis and Processing

MonodiKit is a Python library designed to facilitate the analysis and processing of medieval chant documents. It was specifically tailored to handle data in the monodi+ data format as edited by the Corpus Monodicum project. The library offers a set of classes that provide a wide range of functionalities, including parsing and processing of chant documents, exploring their hierarchical structure, managing metadata, generating musical notation, and extracting relevant information.

Key Features

• Parsing and processing of medieval chant documents.
• Access to the hierarchical structure of chant documents.
• Management of metadata associated with chant documents.
• Export to MEI
• Extraction of relevant information.

Usage

To use MonodiKit, follow these steps:

Install monodikit from pip:

pip install monodikit

Import the MonodiKit library into your Python project:

import monodikit

If you want to use the data published by Corpus monodicum, you have to download it from OSF. Now you can load the data into monodikit with:

corpus = monodikit.Corpus("./data/*")
print(len(corpus.documents))

Examples

Check out Examples.md for more examples.

FAF (Frequently Asked Functions)

Get Overview over Corpus

You can get a Dataframe of the Corpus documents and source metadata:

import pandas as pd
import monodikit
corpus = monodikit.Corpus(dir)
document_meta = pd.DataFrame.from_records(corpus.document_metadata)
source_meta = pd.DataFrame.from_records(corpus.source_metadata)

So you can list all document metadata of genre "Tropus" or you can get all liturgical play (which are groups of documents that are identified by the liturgical_play_id)

# Show metadata of all tropes
print(document_meta.loc[document_meta["genre"] == "Tropus"]) 

# Show IDs of all liturgical plays (for example to build a sub corpora out of one or all of them)
print(document_meta.loc[document_meta["liturgical_play_id"] != None].value_counts())

Search in Corpus

With search_in_window you can search for a sequence of pitches or intervals within a certain window size. If len(sequence) == window size, it is just a complete match. The following code will give you every segment of three pitches that include a E4 and F4 in this order.

results = monodikit.Search.search_in_window(corpus, ["E4", "F4"], 3)

You can do the same with intervals, just provide the information in the "preprocess" argument.

results = monodikit.Search.search_in_window(corpus, [1,1,-1,-1,0,0], 6,  preprocess="intervals")

You can now create a html file with the results:

with open("result.html", "w") as f:
    f.write(monodikit.Search.visualize_html(results))

or view it directly in a jupyter notebook with:

from IPython.display import HTML
HTML(monodikit.Search.visualize_html(results))

Multiple Sequence Alignment with MAFFT

You can also align the found chants (you have to install MAFFT)

mafft_input = monodikit.Search.to_mafft_input(results[0:10], context=2) # Align the first 10 search results
align = monodikit.Synopsis.run_mafft(mafft_input)
html = monodikit.Synopsis.visualize_alignments(align, highlight=[segment["ids"] for result in results for segment in result["segments"]], offset=2) # visualize and highligh notes that were in the search result window.

"""
.. include:: ../Readme.md
.. include:: ../Examples.md
"""
from .models.document import (
    Chant,
    Division,
    Syllable,
    Neume,
    NeumeComponent
)
from .models.corpus import (
    Corpus
)
from .models.genre_specific import (
    ProperTropeComplex,
    Song,
    Sequence,
    PlayPassage,
    Play,
    OrdinaryChant
)
from .analysis.search import (
    Search
)
from .analysis.utility import (
    Utility,
)
from .analysis.synopsis import (
    Synopsis
)

Sub-modules

monodikit.analysis

monodikit.models