Latest revision as of 11:25, 4 March 2012

Introduction

This page lists the various files that may comprise a surrogate model. Each surrogate model must have a unique keyword (unique in the sense that in any given Rave installation, each keyword must be unique). For this reason it is suggested that if you code your own surrogate model and intend to distribute it to others, you give it a keyword that is specific enough to almost guarantee uniqueness. You may find it useful to code your surrogate models as specialized versions of the ones that are distributed with Rave, by making copies of their folder and all its files, renaming them to have a new keyword, and making whatever changes are necessary. (Keep in mind that any modifications you make to the existing Rave files can only be distributed under the GPLv2 license.)

The files described below are named for a surrogate model whose keyword is KEYWORD. All files related to this object must be placed in a folder named KEYWORD that is placed in the modeling directory (rave\modeling\). Optionally, you can put a number in the folder name before KEYWORD; these numbers are used to change the alphabetical order of the folders so that the surrogate models types are listed in the desired order in Rave. Any time KEYWORD appears in a file name you must replace it with the unique keyword for the object you are coding. Otherwise, the filenames must be exactly as they appear below or Rave will not recognize them. Note that some file names do not include the keyword---Rave recognizes these by their location within the KEYWORD directory.

File List

modelinfo.txt

This is a two-line plain text file. The first line must contain the name of the model as you want it to appear in the menu on the Create New Model gui. The second line (can be very long, ok if this wraps) contains a longer description of the model. (NOTE: the second line is currently unused, but in the future this text will appear somewhere.)

modelsettingsKEYWORD.m

This is a script, not a function. Each line should be of the form:

settings.<settingname>=<defaultvalue>;

Use this file to define all the settings that are needed to create your model and set their default values. This script is run as soon as the model type is selected from the menu, before creating its user-interface controls.

Some settings are common to all models and are created automatically by Rave. You should not include these settings in this file: (note, whereas the settings in this file are processed as soon as the user selects the model from the menu, the settings listed below are not processed until the model is added to the queue.

• settings.dataset= %data set index.
• settings.datasetpath= %path to this data set's initial file.
• settings.inputs= %column indices of variables that are independent variables to this model.
• settings.output= %column indices of variables to fit models to. (set in loop below);
• settings.fitrows= %indices of rows to fit model to
• settings.validaterows= %indices of rows to validate model against
• settings.testrows= %indices of rows to test model against
• settings.fitcolumn= %index of the column being used to fit data
• settings.status= %a string indicating current model fit status (initial string is: 'Waiting...')

Other settings are not created until the model is added to the queue or created. These will be explained separately in the description of the files below.

makemodeluicontrolsKEYWORD.m

addtoqueueKEYWORD.m

• settings.notes= %a short descriptive string about the model (see addtoqueueKEYWORD.m below)
• settings.longname= %the name of this model type, as it appears in the menu

ravemakemodelKEYWORD.m

• settings.userdata= %curently unused, but you could use this to store anything you like
• settings.modelstring= %the text of a function that calculates this model (see ravemakemodelKEYWORD.m below)
• settings.name= %an optional user-specified name for this model

• settings.actualvalues= %the actual values of the output variable that this model is based on
• settings.predictedvalues= %the corresponding values as calculated by this model

Lastly, there are some more settings that Rave will calculate for you, you don't need to include these in any of the files you create:

• settings.modeledcolumn=[]; %a list of columns in the data set that are based on this model.
• settings.r2= % correlation coefficient
• settings.rmse= %root mean square error
• settings.meanerror= %mean error
• settings.sigmaerror= %standard deviation of error