Skip to content
Version of OMNISIA pattern discovery software used to produce results published at MML 2019
HTML Java LilyPond Common Lisp MATLAB TeX
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
Points
maths
midi
notes
pitch
.gitattributes
.gitignore
LICENSE
README.md
omnisia.jar

README.md

OMNISIA version 201907232256

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

You can’t perform that action at this time.