Unsupervised PCFG for jazz harmony

This repository accompanies our submission titled "The Potential of Unsupervised Induction of Harmonic Syntax for Jazz".

We reuse code from the following repositories, we thank their authors.

• https://github.com/fosfrancesco/musicparser
• https://github.com/sustcsonglin/TN-PCFG
• https://github.com/nikitakit/self-attentive-parser
• https://github.com/DCMLab/JazzHarmonyTreebank

Our code is primarily found in musicparser/constituency/. Code in musicparser/dependency/ is based on Foscarin et al.'s musicparser repo (with changes). Code in pcfg/ is from Yang et al.'s TN-PCFG repo, again with some adaptations and additions.

Install

Developed with python 3.12.

git clone XXX
cd unsupervised-harmony-pcfg
pip install torch==2.2.1 torchvision==0.17.1 torchaudio==2.2.1 --index-url https://download.pytorch.org/whl/cu121
pip install -r requirements.txt
cd ../ && git clone https://github.com/robaerd/jams
cd jams && git checkout imp-install-fix && pip install -e . && cd ../
cd harmony-pcfg/data && mkdir choco && cd choco 
wget https://github.com/smashub/choco/releases/download/v1.0.0/v1.0.0.zip
unzip v1.0.0.zip
cd ../../

Run

Runs are started with the launch.py script, and use config files in config/ for model settings. Also see the argparse arguments in the launch script.

The best checkpoints in terms of validation F1 overlap with JHT of these runs are saved in trained_checkpoints/.

N-PCFG with comp2flat embeddings trained on JHT (annotated and unsupervised part):

export WANDB_ENTITY='<choose>'
CUDA_VISIBLE_DEVICES=0 python launch.py --wandb_log --model_conf config/npcfg_nt30_t60_comp2flat.yaml --train_data jht --wandb_group "N-PCFG jht comp2flat 128" --seeds 0 42 84 --embedding_type flat --unsupervised --join_repeats --tree_type complete

N-PCFG with comp2flat embeddings trained on JHT (annotated and unsupervised part) and jazz subsets of ChoCo. The checkpoint of the best model with this set-up (seed=84) is available in trained_checkpoints/N-PCFG_jht_irealpro_choco_seed-84.ckpt.

CUDA_VISIBLE_DEVICES=0 python launch.py --wandb_log --unsupervised --wandb_group 'N-PCFG both jazz' --train_data both --seeds 0 42 84 --model_conf config/npcfg_nt30_t60_comp2flat.yaml --join_repeats --tree_type complete --embedding_type flat --max_choco_len 100 --val_check_interval 275 --choco_corpora jaah jazz-corpus real-book --filter_turnaround_choco --filter_turnaround_jht --choco_preprocess

N-PCFG with comp2flat embeddings trained on JHT (annotated and unsupervised part), with rule-based progression loss on marginals:

CUDA_VISIBLE_DEVICES=0 python launch.py --wandb_log --unsupervised --wandb_group "N-PCFG jht rules-marginal" --train_data jht --seeds 0 42 84 --model_conf config/npcfg_nt30_t60_5ths_marg5.yaml --join_repeats --tree_type complete --embedding_type flat

N-PCFG with comp2flat embeddings trained on JHT (annotated and unsupervised part) and jazz subsets of ChoCo, with rule-based progression loss on marginals:

CUDA_VISIBLE_DEVICES=0 python launch.py --wandb_log --unsupervised --wandb_group "N-PCFG both jazz rules-marginal" --train_data both --seeds 0 42 84 --model_conf config/npcfg_nt30_t60_5ths_marg.yaml --join_repeats --tree_type complete --embedding_type flat --max_choco_len 100 --val_check_interval 275 --choco_corpora jaah jazz-corpus real-book --patience 400 --filter_turnaround_choco --filter_turnaround_jht

Results

Predicted and annotated trees (for the 30 JHT songs in our evaluation set) are saved for the runs mentioned above in trees/, in .json format and plotted as TeX qtree's on .pdf's.

After having trained models and logged data to wandb, the script plots.py can be used to generate all plots in the article. For the nonterminal plots (figure 6, 7), first run a full evaluation with the wanted checkpoint.

CUDA_VISIBLE_DEVICES=0 python launch.py --wandb_log --unsupervised --wandb_group "N-PCFG both jazz eval" --model_conf config/npcfg_nt30_t60_comp2flat.yaml --join_repeats --tree_type complete --embedding_type flat --nonterminal_metrics --seeds 84 --ckpt_path 'pretrained_checkpoints/N-PCFG_jht_irealpro_choco_seed-84.ckpt' --max_epochs 0

Script print_grammar.py can be run to print the learned grammar rules. No data in wandb is needed, just set the checkpoint path to a trained model you want to print the grammar rules for (such as in trained_checkpoints/).

The full grammar (with all rules and probabilities) induced by the best model trained without progression loss on the JHT and the jazz subsets of ChoCo is available in data/N-PCFG_jht_irealpro_choco_seed-84_grammar.json.

License

This work is made available under a Creative Commons Attribution Non-Commercial Share-Alike 4.0 (CC BY-NC-SA 4.0) license.