Coding distributions for use in Rave

To create a new distribution, make a new folder under rave\distributions\ whose name is the KEYWORD that identifies your distribution. See below for the limitations on how you must code this distribution, in particular the requirement to use the inverse-transform sampling method.

Inside this folder, you must place the following files:

• distributioninfo.txt - A two-line text file. The first line contains a (short) name for this distribution. The second line contains a slightly longer description of the distribution.

• distributionsettingsKEYWORD.m - a SCRIPT that creates a scalar structure named "settings" whose fields are the settings/parameters that define this distribution. Rave will display both the field names and values to the user, so make the fieldnames meaningful. Some fieldnames are reserved for use by Rave and must not appear in this script. These are: "type", "name", "serialnumber"

• distributionupdatesettingsKEYWORD.m - a function that takes in a settings structure provided by the user and returns a new settings structure that is guaranteed to be valid, or returns an empty array to indicate a total failure (in which case Rave will revert to the last valid settings structure it had). For now there is no standard way to handle errors in this function, so you can report them to the user as warnings or with dialog boxes (for things that the user REALLY needs to know). Try to avoid making this function cause actual errors that will stop matlab execution. Note: Rave adds some additional fields to the settings structure, so this function should only modify the input settings structure, not create a new one from scratch. This ensures that any fields added by Rave are unchanged by this function.
  • Example 1, for a normal distribution the value settings.sigma must be non-negative. So if the input settings structure has settings.sigma = -1, this function prints a warning to the command window and returns an empty array... this causes rave to revert to the last valid settings structure that existed for this variable.
  • Example 2, for a triangular distribution, the values settings.a, .b, .c must be monotonically increasing. If the user inputs these out of order, this function simply reorders them so that they are monotonically increasing. This function then returns the new settings array, which Rave uses. It also prints a warning to the command window.

• distributionsampleKEYWORD.m - an inverse-cdf function that returns x given y such that y=P(x). Must have the signature: x=distributionsamplenormal(settings,y). Where n is a scalar number of points to sample, settings is the settings structure, and yis a vector of length n numbers between 0 and 1. In practice, Rave will construct the y vector depending on the user's desired sampling method (e.g. random or quasi-monte carlo).

• distributionpdfKEYWORD.m - a function that returns y given x such that y=p(x). Must have the signature: y = distributionKEYWORD(x,settings), where x is a vector of arbitrary length. The output y is a same-size vector whose values are y = p(x).

• distributionfitdataKEYWORD.m(optional) - A function that creates this distribution from a vector of data. Must have the signature: settings=distributionfitdataKEYWORD(data,settings). The input settings structure will be the default settings (in case this function does not recalculate all of the settings). If this function does not exist then Rave won't let users create your distribution automatically from data.