This repository contains the code used to produce the results published in the following paper:
Meredith, D. (2019). RecurSIA-RRT: Recursive translatable point-set pattern discovery with removal of redundant translators. 12th International Workshop on Machine Learning and Music. Würzburg, Germany.
A pre-print of the conference paper is also available on arXiv at the following location:
https://arxiv.org/abs/1906.12286
The main entry-point file for the OMNISIA program is at
/Points/src/com/chromamorph/points022/OMNISIA.java
Import the entire repo into a new workspace in a recent version of Eclipse, then navigate to the OMNISIA main file and click on the run button. This should output some help text to the console and it should start by printing the message, "ERROR: No input file provided".
Now select the menu option, Run -> Run Configurations. This should bring up the Run Configurations dialogue box. Find the "Arguments" tab and click on it. In the "Program arguments" text box, enter the following:
-i data/WTCI-FUGUES-FOR-JNMR-2014/bwv846b-done.opnd -d -draw
Then press the "Apply" button, then press the "Run" button. Eclipse may give you a message box saying that there errors in the workspace. If it does, just press the "Proceed" button in this dialogue box. OMNISIA should then start analysing the first fugue from Bach's "Forty-Eight", BWV 846 and some text should be printed to the console while it is performing the analysis. After a few seconds, the analysis should be complete. It is possible that the program does not terminate (this is a bug due to the use of the Processing library for producing graphical output). If the program stops outputting progress messages to the console and it has printed a line that starts "Output image file: ", then you can safely press the red square button above the console window and terminate the program.
OMNISIA should have created some output files in a folder whose path should be something like the following:
data/WTCI-FUGUES-FOR-JNMR-2014/bwv846b-done-opnd-2019-07-23-23-16-04-148
except that the suffix of the path will give a datestamp for the time that you started the analysis. Look inside this folder, and you will find a number of files, including the following:
- bwv846b-done.log This is a log file providing a record of the parameter values used for this run of OMNISIA. It provides all information required for replicating the run.
- bwv846b-done.png This is a png image file giving a graphic visualization of the pattern analysis generated by the program.
- bwv846b-done.pts This is a simple text file providing the actual point set analysed by the program. Since the -d switch was used, OMNISIA analysed a morphetic pitch representation of the input data, in which the dataset consists of a set of 2-dimensional points, <onset, morphetic_pitch>, where onset is in tatums.
- bwv846b-done.switches provides the command line switches used to generate the data to enable replicability.
- bwv846b-done-diat.cos This is the actual encoding generated by OMNISIA for the input file. The default basic algorithms used is COSIATEC. The encoding is a list of translational equivalence classes (TECs), in which each TEC has the form T(P(p(x1,y1),p(x2,y2),...),V(v(x_a,y_a),v(x_b,y_b),...)) where each p(xi,yi) is a 2-dimensional point and each v(x_p,y_p) is a translation vector. After the list of TECs itself in this file, there are number of lines, each of which contains a key--value pair, giving other information about the encoding such as the compression factor ("compressionRatio"), number of TECs ("numberOfTECs") and so on.
- bwv846b-done-diat.log This file provides a condensed transcript of the console output generated during the analysis process.
For a complete list of the switches available, run OMNISIA with no command line arguments. It is recommended that you export a jar file from the OMNISIA.java file. This can most easily be done by right-clicking on the OMNISIA.java file in the Eclipse "Package Explorer" window (typically) on the left hand side of the workspace desktop. This brings up a dialogue in which you should select Java, then "Runnable JAR file", then press the Next button. You then have to select a "Launch configuration". If you've followed the instructions above, then you can select "OMNISIA-Points" from the dropdown list. Then select a location for your JAR file in the "Export destination" box (I suggest a date-stamped file in the root of "omnisia-master" directory). Then press the Finish button. You may get some warnings as Eclipse is generating the JAR file. Just press OK and complete the process. This should give you a runnable JAR file.
You can then open a command line interface, navigate to the folder containing the JAR file you just created and run the following command:
java -jar omnisia.jar
You should get output that resembles the following:
ERROR: No input file provided.
# OMNISIA HELP
Switches
-a Basic algorithm to use. Possible values are:
SIA, SIATEC, COSIATEC, SIATECCompress, Forth, RecurSIA.
Default is COSIATEC.
-i Path to input file (REQUIRED).
-o Path to output directory. Default is same
directory as input file.
-d If present, then use morphetic (diatonic)
pitch instead of chromatic pitch. If morphetic
pitch is not available in the input data (e.g.,
MIDI format), then input data is pitch-spelt using
the PS13s1 algorithm.
-h Help. If present, then this help screen to be printed.
This happens if the program is called with no arguments
or if it is unable to determine the values of all
necessary parameters from the arguments provided.
-m If present, generates output in MIREX format.
-ct If present, uses Collins' compactness trawler,
as used in his SIACT and SIARCT-CFP algorithms.
-cta The variable which Collins et al call 'a'. It is the minimum
compactness permitted in the trawled patterns.
-ctb The variable which Collins et al call 'b'. It is the minimum
size of the patterns trawled by the compactness trawler.
-rsd If present, limits SIA to r superdiagonals, as used in Collins'
SIAR algorithm. Number of superdiagonals determined by the -rswitch.
-r Number of superdiagonals to analyse if limited with -rsd switch.
Default value is 1.
-rrt If present, redundant translators are removed.
-minc Threshold value for minimum TEC compactness (default is 0.0).
-min Minimum allowed pattern size. Default is 0.
-max Maximum allowed pattern size. Default is 0, which means that
patterns of all sizes are allowed.
-merge If present, TECs are merged.
-minm Minimum match size if TECs are merged. Default value is 5.
-spins Number of iterations if TECs are merged. Default value is 10.
-no10 If present, channel 10 (drum channel) is removed if input
is in MIDI format.
-draw If present, generates an image file containing a visualization
of the analysis.
-crlow Minimum compression ratio in Forth's algorithm. Default is 0.2.
-crhi Maximum compression ratio in Forth's algorithm. Default is 1.0.
-comlow Minimum compactness threshold in Forth's algorithm. Default is 0.2
-comhi Maximum compactness threshold in Forth's algorithm. Default is 1,0
-cmin c_min threshold in Forth's algorithm. Default is 15
-sigmin sigma_min threshold in Forth's algorithm. Default is 0.5.
-bbcomp If present, use bounding-box compactness in Forth's algorithm
instead of within-voice segment compactness.
-nodate If present, then does not append date to output directory names.
-bbmode If present, then uses BB mode when generating output in MIREX format.
-segmode If present, then uses Segment mode when generating output in MIREX format.
-out If present, overrides -o and prints a single output
encoding to the given path.
-top If present, limits output to top N patterns.
-recalg If RecurSIA is main algorithm used, then value of this switch
determines which basic algorithm is used on each pattern. Possible values are COSIATEC,
SIATECCompress or Forth.
-sortpat When using COSIATEC, getBestTEC sorts TECs
with preference given to TECs with larger patterns.
# Parameter values
Basic algorithm: (-a): COSIATEC
Input file (-i): null
Output directory (-o): null
Morphetic (diatonic) pitch (-d): false
MIREX (-m): false
Compactness trawler (-ct): false
Minimum compactness of trawled patterns (-cta): 0.67
Minimum size of trawled patterns (-ctb): 3
For r superdiagonals (-rsd): false
r (-r): 1
Remove redundant translators (-rrt): false
Minimum TEC compactness (-minc): 0.0
Minimum pattern size (-min): 0
Maximum pattern size (-max): Unlimited
Merge TECS (-merge): false
Minimum match size if TECs are merged (-minm): 5
Number of iterations if TECs are merged (-spins): 10
Remove channel 10 (drum channel) in MIDI (-no10): false
Help requested (-h): false
Draw analysis (-draw): false
Minimum compression ratio in Forth's algorithm (-crlow): 0.2
Maximum compression ratio in Forth's algorithm (-crhi): 1.0
Minimum compactness threshold in Forth's algorithm (-comlow): 0.2
Maximum compactness threshold in Forth's algorithm (-comhi): 1.0
c_min threshold in Forth's algorithm (-cmin): 15
sigma_min threshold in Forth's algorithm (-sigmin): 0.5
Using bounding-box compactness in Forth's algorithm (-bbcomp): false
Appending date to output directories (-nodate) (N.B.: if true, then NO DATE APPENDED): false
Using BB mode in MIREX output (-bbmode): false
Using Segment mode in MIREX output (-segmode): false
Output file (-out): null
Top N Patterns (-top): 0
Basic algorithm used by RecurSIA (-recalg): COSIATEC
Sort TECs by decreasing pattern size (-sortpat): false
For more information on how to use the switches, see the following presentation:
http://www.titanmusic.com/software/omnisia/OMNISIA.pptx
The RecurSIA algorithm is implemented in the following Java source file:
/Points/src/com/chromamorph/points022/RecurSIAEncoding.java
The RRT algorithm is implemented in the removeRedundantTranslators() method that starts in line 284 in the TEC class definition:
/Points/src/com/chromamorph/points022/TEC.java
The removeRedundantTranslators() method of the Encoding class runs the TEC removeRedundantTranslators() method on each TEC that it contains, see line 820 in the file
/Points/src/com/chromamorph/points022/Encoding.java
David Meredith
24 July 2019
Brenderup, Fyn, Denmark