IDyOM Project

h1. Low-level functions in Resampling and Viewpoint selection

These are some low-level functions in the <code>resampling</code> package, which are called by the <code>idyom:idyom</code> function. You shouldn't need to use them unless you are developing the code.

h2. <code>resampling:idyom-resample</code>

<code>idyom:idyom</code> uses <code>resampling:idyom-resample</code> to compute the note-by-note IC values, and can be used to obtain these a list.  The function takes a subset of the top-level arguments (see above):

* Required: dataset-id, target-viewpoints, source-viewpoints (no viewpoint selection)

* Model: models, ltmo, stmo

* Training: pretraining-ids, k, resampling-indices

h2. <code>resampling:output-information-content</code>

Takes the output of <code>resampling:idyom-resample</code> and returns the average information content. It takes the following arguments:

* predictions: the output of <code>resampling:idyom-resample</code>

* detail: an integer which determines how the information content is averaged (these are returned as multiple values): 

** 1: averaged over the entire dataset 

** 2: and also averaged over each composition 

** 3: and also for each event in each composition

h2. <code>resampling:format-information-content</code>

<code>resampling:format-information-content</code> takes the output of <code>resampling:idyom-resample</code> and writes it to file. It takes the following arguments:

* predictions: the output of <code>resampling:idyom-resample</code>

* file: a string denoting a file

* dataset-id: an integer reflecting the dataset-id

* detail: an integer which determines how the information content is averaged (these are returned as multiple values): 

** 1: averaged over the entire dataset 

** 2: and also averaged over each composition 

** 3: and also for each event in each composition

h2. Viewpoint Selection 

The top-level <code>idyom:idyom</code> function supports viewpoint selection (see above), i.e. searching a space of viewpoints.  This uses two functions: <code>run-hill-climber</code> and <code>run-best-first</code>, which take 4 arguments:

* a list of viewpoints: the algorithm searches through the space of combinations of these viewpoints

* a start state (usually nil, the empty viewpoint system)

* an evaluation function returning a numeric performance metric: e.g., the mean information content of the dataset returned by <code>dataset-prediction</code>

* a symbol describing which way to optimise the metric: <code>:desc</code> mean lower values are better <code>:asc</code> mean greater values are better

Here is an example:

<pre>

CL-USER> (viewpoint-selection:run-hill-climber 

          '(:cpitch :cpintfref :cpint :contour)

          nil

          #'(lambda (viewpoints)

              (utils:round-to-nearest-decimal-place 

               (resampling:output-information-content 

                (resampling:dataset-prediction 0 '(cpitch) viewpoints :k 10 :models :both+) 

                1)

               2))

          :desc)

 =============================================================================

   System                                                Score

 -----------------------------------------------------------------------------

   NIL                                                   NIL

   (CPITCH)                                              2.52

   (CPINT CPITCH)                                        2.43

   (CPINTFREF CPINT CPITCH)                              2.38

 =============================================================================

#S(VIEWPOINT-SELECTION::RECORD :STATE (:CPINTFREF :CPINT :CPITCH) :WEIGHT 2.38)

</pre>

Since this can be quite a time consuming process, there are also functions for caching the results.

<pre>

(initialise-vs-cache)

(load-vs-cache filename package)

(store-vs-cache filename package)

</pre>