IDyOMpy

This project proposes a Python implementation for the IDyOM model made by Marcus Pearce.

IDyOMpy is a variable-order Markov chain model capable of predicting the next note of a priming melody after being trained on a corpus of music. It is used in the field of music cognition in order to quantify for each note in a given melody its amount of surprise. This information has been demonstred very powerful to explain emotional experience and physiological reaction of music listening.

This information correspond to the information content (negative log likelihood) of each notes as well as the entropy of the probability distribution at each point in time. These values can be computed by training and evaluating the model on different data set or by cross-evaluation on the same data. You can pass a dataset as a fodler containing midi files, not other formats are supported. Other exclusive features are available in this implementation, such as computing a trace of the generalization error over training and extracting the moments of silence when a note was strongly expected. All the technical details of the implementation as well as the comparison with the LISP implementation are available in the companion paper (to be published).

You can find a precise documentation on this website. If you use the program for your research, please cite the companion paper.

Installation

Using pip

To be implemented

Using Git

git clone https://github.com/GuiMarion/IDyOMpy.git
cd IDyOMpy
python3 -m pip install -r requirements.txt

Usage

Usage: usage App.py [options]

Options:
  -h, --help            show this help message and exit
  -t TRAIN_FOLDER, --train=TRAIN_FOLDER
                        Train the model with the passed folder.
  -s TRIAL_FOLDER, --surprise=TRIAL_FOLDER
                        Compute surprise over the passed folder. We use -t
                        argument to train, if none are privided, we use the
                        passed folder to cross-train.
  -c CROSS_EVAL, --cross_eval=CROSS_EVAL
                        Compute suprise by pieces over the passed dataset
                        using k-fold cross-eval (see k_fold option).
  -e EVOLUTION_FOLDER, --evolution=EVOLUTION_FOLDER
                        Train and evaluate over training on the passed folder
                        (cross-val).
  -n TRIAL_FOLDER_SILENT, --silentNotes=TRIAL_FOLDER_SILENT
                        Compute silent notes probabilities over the passed
                        folder. We use -t argument to train.
  -l, --long_term       Only use long term model (False by default).
  -b, --short_term      Only use short term model (False by default).
  -k K_FOLD, --k_fold=K_FOLD
                        Specify the k-fold for all cross-eval, you can use -1
                        for leave-one-out (default 5).
  -v VIEWPOINTS, --viewPoints=VIEWPOINTS
                        Viewpoints to use (pitch, length or both), both by
                        default.
  -p NB_PIECES, --nb_pieces=NB_PIECES
                        Number of pieces to evaluate on during evolution
                        training (20 by default).
  -d THRESHOLD_MISSING_NOTES, --threshold_missing_notes=THRESHOLD_MISSING_NOTES
                        Define the threshold for choosing the missing notes
                        (0.3 by default).
  -r, --time_representation
                        Enable time representation instead of note
                        representation (deactivated by default).
  -m MAX_ORDER, --max_order=MAX_ORDER
                        Maximal order to use (default 20).
  -q QUANTIZATION, --quantization=QUANTIZATION
                        Rythmic quantization to use (default 24).
  -u FOLDER_DUPLICATES, --check_dataset=FOLDER_DUPLICATES
                        Check wether the passed folder contains duplicates.
  -a, --test            Launch unittests.

Examples

Train/Eval with default options

python3 App.py -t dataset/trainFolder -s dataset/testFolder

Cross-validation with default options

python3 App.py -c dataset/yourFolder

Choosing you k-fold (-1 is for leave-one-out)

python3 App.py -c dataset/yourFolder -k -1

Using only the long-term model

python3 App.py -c dataset/yourFolder -k -1 -l

Using only the short-term model

python3 App.py -c dataset/yourFolder -k -1 -b

Using time representation

python3 App.py -c dataset/yourFolder -k -1 -r

Change the maximal order

python3 App.py -c dataset/yourFolder -k -1 -m 10

Evolution training (record the evolution of the training)

python3 App.py -e dataset/yourFolder