view SMC2015latex/section/framework.tex @ 71:9a60ca4ae0fb

updating models and latex files.  added
results.csv

\section{Framework}
\label{sec:framework}

\begin{figure}[t]
\centering
\includegraphics[width=0.9\columnwidth]{images/framework.pdf}
\caption{Module hierarchy in the SynPy toolkit: the top-level module provides a simple interface for the user to test different syncopation models. Musical constructs such as bars, velocity and note sequences, notes and time-signatures are defined in the `music objects' module; support for common procedures such as sequence concatenation and subdivision is provided in `basic functions'. Models and file reading components can be chosen as required by the user.\label{fig:framework}}
\end{figure}

The architecture of the toolkit is shown in Figure~\ref{fig:framework}. Syncopation values can be calculated for each bar in a given source of rhythm data along with selected statistics over all bars; the user specifies which model to use and supplies any special parameters that are required. Sources of rhythm data can be a bar object or a list of bars (detailed below in Section~\ref{sec:musicobjects}) or, alternatively, the name of a file containing music data. Where a model is unable to calculate a value for a given rhythm pattern, a `None' value is recorded for that bar and the indices of unmeasured bars reported in the output.  If no user parameters are specified, the default parameters specified in the literature for each model are used. Output can optionally be saved directly to XML or JSON files. An example of usage in the Python interpreter is shown in Figure~\ref{ta:example}.

\begin{figure}
\footnotesize{
\begin{minted}[frame=single,framesep=10pt]{python}
>>>from synpy import *
>>>import synpy.PRS as model
>>>calculate_syncopation(model, "clave.rhy", 
   outfile="clave.xml")
{'bars_with_valid_output': [0, 1],
 'mean_syncopation_per_bar': 8.625,
 'model_name': 'PRS',
 'number_of_bars': 2,
 'number_of_bars_not_measured': 0,
 'source': 'clave.rhy',
 'summed_syncopation': 17.25,
 'syncopation_by_bar': [8.625, 8.625]}
\end{minted}
}
\caption{To use the toolkit, the top level \code{synpy} module is imported along with a model (in this example Pressing \cite{Pressing97}). Calling \code{calculate\_syncopation()} then gives the syncopation results as shown, writing output to an XML file. Output file names and extra parameters for a model are added as optional arguments as required by the user. 
\label{ta:example} }
\end{figure}

\subsection{Music objects}
\label{sec:musicobjects}
The `music objects' module provides classes to represent the musical constructs described in Section~\ref{sec:background}.  A \code{Bar} object holds the rhythm information for a single bar of music along with its associated time-signature and optional tempo and TPQ values (see Section~\ref{sec:background:rhythm:timespan}). \code{Bar} objects may be initialised with either a note sequence or velocity sequence and can be chained together in the form of a doubly-linked \code{BarList} allowing syncopation models to access next and previous bars where appropriate (several models \cite{LHL84,Keith91,Pressing97,Gomez05} require knowledge of the contents of previous and/or next bars in order to calculate the syncopation of the current bar). The note sequence and velocity sequence classes are direct implementations of the sequences described in Section~\ref{sec:background:rhythm:note}.    Common low-level procedures such as sequence concatenation and subdivision are provided in `basic functions'.

\subsection{File Input}
\label{sec:fileinput}
Two file reader modules are currently provided: one for for reading plain text rhythm annotation (\code{.rhy}) files and one for reading standard MIDI files (\code{.mid}). These modules open their respective file types and return a \code{BarList} object ready for processing.  

\begin{figure}
\footnotesize{
\begin{minted}[frame=single,framesep=10pt]{python}
T{4/4} # time-signature
TPQ{4} # ticks per quarternote
# Bar 1
Y{(0,3,2),(3,1,1),(6,2,2),(10,2,1),(12,4,1)}
# Bar 2
V{1,0,0,0.5,0,0,1,0,0,0,0.5,0,0.5,0,0,0}
\end{minted}
}
\caption{Example rhythm annotation file \code{clave.rhy} containing two bars of the Son Clave rhythm as discussed Section~\ref{sec:background}. The first bar is expressed as a note sequence with resolution of four ticks per quarter-note; the second is the same rhythm expressed as a velocity sequence.}
\label{ta:clave} 
\end{figure}
Our \code{.rhy} annotation format is a light text syntax for describing rhythm patterns directly in terms of note and velocity sequences (see Figure~\ref{ta:clave}). The full syntax specification is given in Backus Naur Form on the toolkit repository \cite{Song14URL}.

The MIDI file reader can open type 0 and type 1 standard MIDI files and select a given track to read rhythm from.  Notes with zero delta time between them (i.e. chords) are treated as the same event for the purposes of creating note sequences from the MIDI stream. Time-signature and tempo events encoded in the MIDI stream are assumed to correctly describe those parameters of the recorded music so it is recommended that the user uses correctly annotated and quantised MIDI files.

\begin{figure*}[t]
\centering
\includegraphics[width=0.85\textwidth]{images/allmodels.pdf}
\caption{Syncopation predictions of the seven models in the toolkit for the syncopation dataset from~\cite{Song15thesis}. The range of prediction values across all rhythm patterns is given for each model. Within each rhythm category, the rhythm patterns are arranged by tatum-rate (i.e. quarter-note rate then eighth-note rate) then in alphabetical order (the data set naming convention uses letters a-l to represent short rhythm components that make up longer patterns). Gaps in model output occur where a particular model is unable to process the specific rhythm category i.e. LHL, PRS, TMC, SG cannot process polyrhythms and KTH can only measure rhythms in duple meters.}
\label{fig:modelpredictions}
\end{figure*}

\subsection{Plugin architecture}
The system architecture has been designed to allow new models to be added easily.   Models have a common interface, exposing a single function that will return the syncopation value for a bar of music.  Optional parameters may be supplied as a Python dictionary if the user wishes to specify settings different from the those given in the literature for a specific model.







% \section{MIDI Input}\label{sec:midi}

% \cite{Taylor89MusicTheory}

% \section{Text Input}\label{sec:textinput}

% \begin{table*}
% \small{
% \begin{minted}[frame=single,framesep=10pt]{console}
% <piece>             ::=  [<comment-lines>] <timesig> <line> | <piece> <line>

% <comment-lines>     ::= <comment> "\n" | <comment-lines> <comment> "\n"

% <line>              ::= [<barlist>] [<comment>] "\n"

% <comment>           ::= "#" <comment-text>

% <barlist>           ::= <time-info> | [<time-info>] <bar> | <barlist> <bar>

% <time-info>         ::= [<timesig>] [<ticks-per-quarter>] [<tempo>] 

% <tempo>             ::= "QPM{" <digits> "}"

% <ticks-per-quarter> ::= "TPQ{" <digits> "}"

% <timesig>           ::= "T{" <digit> "/" <digit> "}"

% <bar>               ::= "V{" <velocity-sequence> "}" | "Y{" <note-sequence> "}"

% <note-sequence>     ::= <note> | <note-sequence> "," <note>

% <note>              ::= "(" <digits> "," <digits> "," <digits> ")"

% <velocity-sequence> ::= <decimal> | <velocity-sequence> "," <decimal>

% <decimal>           ::= "0" | "1" | "0." <digits>

% <digits>            ::= <digit> | <digits> <digit>

% <digit>             ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
% \end{minted}
% }
% \caption{Syntax of rhythm text format Backus-Naur Form}
% \label{ta:BNF} 
% \end{table*}