Link Search Menu Expand Document

FONN - FOlk N-gram aNalysis

  • Targeting the goals of Polifonia WP3, FoNN contains tools to extract feature sequence data, extract musical patterns, and detect similarity within a symbolic music corpus. Although some of FoNN’s functionality is tailored to Western European folk music, the software can be used on any corpus in a compatible symbolic representation format (MIDI, ABC Notation, **kern, MusicXML, or any other format compatible with the music21 Python library).

The repo contains a fully functional work-in-progress version of the software, along with two test music datasets: the Meertens Annotated Corpus (MTC-ANN) of Dutch folk songs and The Session corpus of Irish traditional folk dance tunes. Three demo notebooks are supplied in ./FoNN/demo_notebooks directory. These demos illustrate FoNN’s feature extraction, pattern extraction, and similarity search tools as applied to the MTC-ANN corpus:

  • feature_extraction_demo.ipynb: Reads the symbolic MTC-ANN music corpus from **kern format; extracts feature sequence data and writes to csv at ./FoNN/mtc_ann_corpus/feature_sequence_data
  • pattern_extraction_demo.ipynb: Reads the feature sequence data outputted by the above notebook, extracts unique feature patterns and counts their occurrences per tune across the corpus. Writes output to ./FoNN/mtc_ann_corpus/pattern_corpus.
  • similarity_search_demo.ipynb: Using the data outputted by the notebook above, for a user-selectable query tune, this demo detects similar tunes across the corpus via FoNN’s three novel pattern-based similarity metrics. Writes output to ./FoNN/mtc_ann_corpus/similarity_results

The repo also contains a data extraction and processing pipline to generate inputs for Polifonia Patterns Knowledge Graph (KG). Two Jupyter notebooks which run this pipeline are stored in ./FoNN/pattern_knowledge_graph_pipeline directory:

  • ./FoNN/pattern_knowledge_graph_pipeline/patterns_kg_data_extraction.ipynb runs FoNN’s pattern extraction tools to extract corpus data.
  • ./FoNN/pattern_knowledge_graph_pipeline/patterns_kg_data_processing.ipynb combines pattern data, feature sequence data and descriptors for each tune in the corpus and writes this data to a corpus-level Pickle file matching the Patterns KG input requirements.

NOTE: Deliverable 3.4 of the Polifonia project describes the context and research informing development of these tools. It will be published on Cordis later this year (2023).

FoNN – Polifonia components:

  1. FoNN - FOlk N-gram aNalysis
  2. Ceol Rince na hÉireann (CRÉ) corpus
    • 2.1. For the associated Ceol Rince na hÉireann corpus of 1,195 monophonic Irish traditional dance tunes in ABC and MIDI formats, please see: ./cre_corpus/readme.md.
  3. Root Note Detection

FoNN - Requirements

To ensure FONN runs correctly, please navigate to local repo root directory and run the following in Terminal:

pip install -r requirements.txt

FoNN - preprocessing step for ABC corpora

NOTE: The Session and CRÉ corpora are provided in both ABC Notation and MIDI formats.

  • To ingest a corpus in ABC Notation format, first install the ABC2MIDI external dependency, which can be downloaded directly here. For information on ABC2MIDI, please see the project documentation.

  • If ingesting a corpus in ABC Notation, first convert to MIDI by running the ./FoNN/abc_ingest.py script. This preliminary step uses ABC2MIDI to encode a specific ‘beat stress model’ into the MIDI output, which is used later in the workflow to filter data for rhythmically-accented notes. Such higher-level representation of melody is of particular interest in the study of Irish and related European & North American folk musics.

  • The workflow from here onwards is the same for corpora originating in all formats: if a corpus does not originate in ABC Notation, please skip to section 1.1.

1. FoNN - FOlk N-gram aNalysis: running the tools

1.1. Reading a corpus

  • Running .FoNN/demo_notebooks/feature_extraction_tools_demo.ipynb extracts feature sequence data from an input corpus via FoNN.feature_sequence_extraction_tools.Corpus class.
  • By default this notebook reads the corpus at ./FoNN/mtc_ann_corpus/krn and outputs feature sequence data to ./FoNN/mtc_ann_corpus/feature_sequence_data.
  • Input path and format can be edited as desired, while output will always write to ./FoNN/[corpus name]/feature_sequence_data subdirectory.
  • This notebook extracts 16 feature sequences in what we term note-level, duration-weighted note-level, and accent-level representations, as explained below:
    1. Note-level: for every music score document in the corpus, each note is represented via 16 feature values.
    2. Duration-weighted note-level: for every music score document in the corpus, each 1/8 note temporal increment is represented via 16 feature values.
    3. Accent-level: for every music score document in the corpus, accented on-the-beat notes are represented via 16 feature values while other less metrically significant notes are dropped.
  • Throughout the FoNN toolkit, these levels of data granularity are specified via the following string names:
    1. note-level: ‘note’
    2. duration-weighted note-level: ‘duration_weighted’
    3. accent-level: ‘accent’
  • The 16 musical features extracted for each note are: 
    -- 'midi_note_num': Chromatic pitch represented as MIDI number
-- 'onset': note onset (1/8 notes)
-- 'duration': note (1/8 notes)
-- 'velocity': MIDI velocity
-- 'diatonic_note_num': Diatonic pitch
-- 'beat_strength' -- music21 beatStrength attribute
-- 'chromatic_pitch_class': Pitch normalised to a single octave, represented as an integer between 0-11.
-- 'bar_num': Bar number
-- 'relative_chromatic_pitch': Chromatic pitch relative to the root note or tonal centre of the input sequence.
-- 'relative_diatonic_pitch': Diatonic pitch relative to the root note or tonal centre of the input sequence.
-- 'chromatic_scale_degree': Chromatic pitch class relative to the root note or tonal centre of the input sequence.
-- 'diatonic_scale_degree': Diatonic pitch class relative to the root note or tonal centre of the input sequence.
-- 'chromatic_interval': Change in chromatic pitch between two successive notes in the input sequence
-- 'diatonic_interval': Change in diatonic pitch between two successive notes in the input sequence
-- 'parsons_code': simple melodic contour. Please see Tune.extract_parsons_codes() docstring for detailed explanation.
-- 'parsons_cumsum': cumulative Parsons code values.
  • For more detail on how to customise inclusion/exclusion of features and choice of output data level, please refer to ./FoNN/demo_notebooks/feature_extraction_tools_demo.ipynb.

1.2. Extracting patterns and counting their occurrences:

  • For a user-selected musical feature, /FoNN/demo_notebooks/pattern_extraction_demo.ipynb uses FoNN.pattern_extraction.NgramPatternCorpus class to extract all unique n-gram patterns from the input corpus. The default feature is ‘diatonic_pitch_class’ but other features can be selected by the user from the list above in Section 1.1.
  • Default input data is the MTC-ANN corpus feature sequence data at ./FoNN/mtc_ann_corpus/feature_sequence_data, but pattern extraction can be applied to any other symbolic corpus which has first been processed via FoNN’s feature extraction pipeline as described in section 1.1.
  • A pattern is defined as a subsequence of length between 3 and 12 elements which occurs at least once in the corpus. All patterns following this definition which occur in the corpus are stored in an array. Their occurrences in every tune in the corpus are counted and stored in a sparse matrix. These counts are weighted and converted to TF-IDF values to supress frequent-but-insignificant ‘stop word’ patterns. These outputs are the core input requirements for FoNN’s similarity search tool; they are stored in ./FoNN/[corpus name]/pattern_corpus dir.

1.3. Pattern-based tune similarity

  • The /FoNN/demo_notebooks/similarity_search_demo.ipynb notebook contains sample similarity searches for a user-selected query tune from the MTC-ANN corpus via FoNN.similarity_search.
  • Results are returned which rank other tunes in the corpus by their similarity to the candidate tune. These are obtained via FoNN’s three novel metrics: ‘motif’, ‘incipit and cadence’, and ‘TFIDF’.
    1. ‘motif’: First a representative pattern is extracted from the query tune via maximal tfidf. Similar patterns to this search term pattern are detected via Levenshtein distance, with only one single edit permitted. The number of similar patterns per tune in the corpus is calculated, normalised by tune length, and returned as a tune-similarity metric.
    2. ‘incipit and_cadence’: An extended version of a traditional musicological incipit search. Structurally-important incipit and cadence subsequences are extracted from all tunes in the corpus and compared via pairwise edit distance against the query tune. Users can select from three available edit distance metrics: Levenshtein distance; Hamming distance; and a custom-weighted Hamming distance in which musically-consonant substitutions are penalised less than dissonant substitutions. The edit distance output is taken as a tune-dissimilarity metric.
    3. ‘tfidf’: A classical IR baseline methodology: the Cosine similarity between TFIDF vectors of all tunes in the corpus is taken as a tune similarity metric.
  • All results are displayed in the notebook and automatically written to csv files at ./FoNN/[corpus name]/similarity_results.

1.4. Test music datasets

1.5 Patterns KG data extraction and processing pipeline

  • Step 1: Run ./FoNN/pattern_knowledge_graph_pipeline/patterns_kg_data_extraction.ipynb to extract corpus feature sequence and pattern data.
  • Step 2: Run ./FoNN/pattern_knowledge_graph_pipeline/patterns_kg_data_processing.ipynb to combine feature sequence and pattern data for the entire corpus and write to Pickle file for KG creation via Polifonia Patterns Knowledge Graph (KG) repo.
  • Further information on user-customization of pipeline parameters is provided within the notebooks.

2. Ceol Rince na hÉireann (CRÉ) MIDI corpus [legacy component]

  • A new version of the previously-existing Ceol Rince na hÉireann corpus, containing 1,195 monophonic Irish traditional dance tunes. the corpus in provided in ABC Notation and in MIDI. Please see: ./cre_corpus/readme.md for more information.

  • Highlights:

    • Corpus title: Ceol Rince na hÉireann
    • Source: Black, B 2020, The Bill Black Irish tune archive homepage, viewed 5 January 2021.
    • Contents: 1,195 traditional Irish dance tunes, each of which is represented as a monophonic MIDI file. Also included is roots.csv, a file giving the expert-annotated root note for every file in the corpus as a chromatic integer pitch class.

3. Root Note Detection [legacy component]

Work-in-progress on automatic detection of musical root for each tune in the corpus. Please see: /.root_key_detection/README.md. This component contains a jupyter notebook script that makes use of cre_root_detection.csv, which is a file containing pitch class values assigned to each piece of music in the corpus by the above-mentioned root-detection metrics outputted by setup_corpus.py. From this input data, the script makes use of machine learning methods to classify the root note. The root note detection notebook can be accessed at /.root_note_detection/root_note_detection.ipynb.

Attribution

DOI

If you use the code in this repository, please cite this software as follows:

@software{diamond_fonn_2022,
	address = {Galway, Ireland},
	title = {{FONN} - {FOlk} {N}-gram {aNalysis}},
	shorttitle = {{FONN}},
	url = {https://github.com/polifonia-project/folk_ngram_analysis},
	publisher = {National University of Ireland, Galway},
	author = {Diamond, Danny and Shahid, Abdul and McDermott, James},
	year = {2022},
}

License

This work is licensed under CC BY 4.0, https://creativecommons.org/licenses/by/4.0/