The handles structure

Introduction

The "handles structure", (usually referred to simply as "handles") is one of the main data structures used by Rave. It is a variable named "handles", which appears in just about every Rave function.

Ok, so what does handles actually contain? While it would be easy to store EVERYTHING in handles, it would quickly become gigantic and difficult to use. One of the guiding principles you should follow when using rave is only store information in handles if there is no other place you can put it. At first this might sound confusing, since we already established that handles is the only variable your functions can access. But there are a few workarounds to let you store data elsewhere. First off, suppose you have a red line, and you have a function that needs to know what color the line is. You could store this in handles, but don’t. It is already “stored” in the line itself. You function should ask the line what color it is (using something like get(linehandle,’color’)). Additionally, EVERY graphical object has two properties that can be used to store additional data. The first is the “tag” which MUST be a single string. Usually this is used to “name” the object with a unique identifier that can be used later by findobj to retrieve that object’s handle (which can in turn be used with get to retrieve other properties of the object). The tag can also sometimes be useful for storing other text data that doesn’t act as a name. The second (more useful for the purpose of storing data) property is called “userdata”. It can be used to store ANYTHING.

In particular, each graph you create has its own data structure, always named “udata” (short for userdata) that is stored in the userdata property of one object that composes the graph (this is described in much more detail below). The important thing to note here is that you have two main options for storing information: if the information you need to store is particular to one graph, you should store that information in the graph’s udata. If the information is “high-level” enough to be shared by several graphs, store it in handles.

Side note, optimizers have their own data structure named “settings” described later.

But PLEASE think very hard if there is any way to avoid making a new field under the main handles structure. I think it is in everyone’s best interest if we keep the list of handles fields to just those listed below. Anything stored directly under handles should be VERY high level and useful to most if not all graphs. If you have information that needs to be stored temporarily, for example while an optimizer is running, store it under handles.temp.

Again, PLEASE try not to add new fields to handles, as this will break your users older saved .rve files, and NEVER modify the behavior of the existing fields, as this will certainly break many other features.

The list below summarizes the most commonly used fields in handles (eventually I’ll expand to include all of them). The index {d} represents the number of a data set, and the index {a} represents the number of an analysis. If a field is referenced with {d}{a} then its contents differ for each data set AND for each analysis. If a field is referenced with just {d} then it differs between each dataset, but is the same for each analysis.

Fields related to data sets and variables

• handles.datasetnames – the names of all data sets.
• handles.datasetnames{d} is a string containing the name of the d-th data set. The first data set that is loaded has d=1, the second data set loaded has d=2, etc.
• handles.analysisname – the names of all analyses.
• handles.analysisnames{a} – the name of the a’th analysis.
• handles.alldata – all of the data is contained in here.
• handles.alldata{d} – an m*n matrix containing all data of the d’th data set. This data set has n variables and m data points for each variable.
• handles.alldata{d}(:,c) – is a m*1 vector containing all data values for the c’th variable in the d’th data set.
• handles.allnames – the names of the variables
• handles.allnames{d}{c} – a string containing the name of the c’th variable in the d’th data set.
• handles.targetvalues – the “ideal” values of the variables. –inf indiciates desire to minimize a variable, inf indicates desire to maximize a variable
• handles.targetvalues{d}(c) = the target value of the c-th variable in the d-th data set.
• handles.preferences – the weight each variable has when calculating certain types of objective functions
• handles.preferences{d}(c)= the weight of the c-th variable in the d-th data set.

• handles.isfunction – a logical vector indicating whether variables are calculated by a user-supplied function. If “false” then the variable is “independent”.
• handles.isfunction{d}(c)= true if the c-th variable of d-th dataset is calculated by a user-supplied function. Otherwise false.
• handles.funnames – names of user-supplied functions
• handles.funnames{d}{c}= the name of the function that calculates the c-th variable of the d-th dataset. Or an empty string if c-th variable is independent.
• handles.funvars – input variables on which calculated variables depend
• handles.funvars{d}{c} – vector of the variables that are inputs to the function that calculates the c-th variable. IMPORTANT: this list can only contain values from 1 to c. In other words, only feedforward function dependencies are allowed.
• handles.nargout{d}{c}=
• handles.datatype{d}{c}=

Fields related to analyses

• handles.discretevalue – the list of “feasible” values that discrete variables in a data set can take
• handles.discretevalues{d}{a}{c}= a vector of allowable values for the c-th variable in the d-th dataset in the a-th analysis.
• handles.xdials – the “current value” of each variable
• handles.xdials{d}{a}(c)=
• handles.minlimit{d}{a}(c)=
• handles.maxlimit{d}{a}(c)=
• handles.isselected{d}{a}(r)=
• handles.rowcolors{d}{a}(r)=
• handles.isvisible{d}{a}(r)=

Fields related to constraints

• handles.constrainthandles{d}{x}=
• handles.constrainttext{d}{x}=
• handles.constrainttype{d}{x}=
• handles.constraintvalues{d}{x}=
• handles.constraintadders{d}{x}=
• handles.constraintscalers{d}{x}=
• handles.constraintvars{d}{x}=
• handles.constraintcolors{d}{x}=

Fields related to graphs

• handles.activeindex=
• handles.allblockers =
• handles.allgraphs(ai)=
• handles.fakeax(ai)=
• handles.fakerax(ai)=
• handles.currentgraph=
• handles.activegraph=
• handles.activetype=
• handles.activetab=
• handles.activesubgraph=
• handles.subax=
• handles.subfakeax=
• handles.subfakerax=
• handles.statsax=
• handles.grabbers
• handles.graphnames=

Fields related to the main data table

• handles.tablemode = A logical scalar, = 0 if user is in graph mode, = 1 if user is in table mode. The “table/graph” button in the upper left of the screen sets this value and displays the table or graphs.
• handles.maintable.undos{z}= Is a structure containing information about the z-th undoable action. Undoing this action moves it to the redos field.
• handles.maintable.redos{z}= Is a structure containing information about the z-th redoable action. Redoing this action moves it to the undos field.
• hHandles.maintable.x{d}= Is an index vector of which variables to display in the maintable for the d-th data set. (Similar to udata.view.x for graphs).
• hHandles.maintable.colwidths{d}= Is a vector of column widths (in pixels) for all variables in the d-th data set.
• handles.maintable.wasdragged= logical scalar that =1 when a column is being dragged or has just finished being dragged and =0 otherwise.
• handles.maintable.colorrows= logical scalar indicating whether or not to color the row headers to match data colors.
• handles.mainable.shadehidden= logical scalar indicating whether or not to color hidden data rows differently.
• handles.maintable.allowedits= not used yet
• handles.maintable.allowselection= not used yet
• handles.maintable.d= the index of the data set currently being displayed in the data table (Similar to udata.view.d for graphs)
• handles.maintable.a= the index of the analysis set currently being displayed in the data table (Similar to udata.view.a for graphs)
• handles.maintable.ignoreupdates= logical scalar. When = 1, ravemaintablechangedcallback is not called when the table is changed. This is value is primarily used within ravemaintablechangedcallback to prevent it from calling itself recursively. (Note: ravemaintablechangedcallback is the function that stores undo events and re-evaluates functions when the user edits the table)

Fields related to passing information between the graph view and the table view

• handles.datasetupdatespending{d}= A cell array of strings indicating changes that have been made to the d-th data set. It may contain the strings: ‘data’, ‘isvalid’. The functions ravedisplayworkspace and ravedisplaymaintable check these strings and redraw graphs or call ravecreatemaintablemodel as needed.
• handles.analysisupdatespending{a}= A cell array of strings indicating changes that have been made to the a-th analysis. It may contain the strings:
• handles.tablemodelupdatespending{d}=

Fields related to plugins

• handles.graphinfo.<graphname>= A structure containing information
• handles.optimizerinfo.<optimizername>=

Fields related to rave interface

• handles.wspanel – The handle of the uipanel that forms the workspace. All graphs and other objects in the workspace are children of this.
• handles.mainaxes – The handle of the axes that shows the background of the workspace. The gridlines are children of this.
• handles.infobar – The handle of the information bar at the top of the screen. Change what it says using set(handles.infobar,’string’,’what you want it to say’). Clear it using set(handles.infobar,’string’,’’).
• handles.prefs – The preference structure. This is an exact copy of the raveprefs variable that you can access using “load raveprefs”.
• handles.colors – The color preferences structure. This is an exact copy of raveprefs.colors.
• handles.explorer – The axes that form the “navigator” at the top left of the screen.
• handles.expblockers – The handles of the rectangles that represent each graph in the navigator.
• handles.fig – The handle of the rave window itself. I often use this as the input to guidata, because you’re guaranteed it is always a valid handle.
• handles.tabobjects – A vector of handles for EVERYTHING that is currently displayed in the tabs, so that the function delete(handles.tabobjects) will clear the tabs. The last line of any “tab” function (e.g. formattabline.m) should ALWAYS be handles.tabobjects=[the handles of everything you created in the tabs];