LINEAGE Viewer Tutorial
by Kenneth Eaton
This tutorial is designed to walk the user through the features of the LINEAGE viewer for the Peg Solitaire contest submission data set (available online at http://www.mathworks.com/matlabcentral/fileexchange/23509). Instead of focusing on the contest metrics, the LINEAGE viewer helps visualize the evolution of the code throughout the contest, displaying the ancestry of the submissions and allowing the user to view and compare the submission code.
The LINEAGE viewer is opened by calling the function "lineage.m" with a single input argument: a relative or absolute file path string for the Peg Solitaire contest data .mat file. If no inputs are specified, LINEAGE will attempt to load a file by the name of 'contest_data.mat' from the current directory.
After a brief loading period, the following interface should be visible:
The two panels on the left are where submission data will be displayed (discussed further down). The axes on the bottom right display the ancestry of submissions versus time, as derived from the "parent" data included in the Peg Solitaire contest data file.
The three phases of the contest (darkness, twilight, and daylight) are indicated by the dark gray, light gray, and white regions of the plot (respectively). The daylight phase is further divided into 24-hour blocks (from noon to noon) as indicated by the vertical black dotted lines.
Each submission is plotted as a circular point and is connected by solid lines to both its "parent" submission that is was based on and any "children" submissions that were based on it. All the submissions that share a given parent are considered "siblings". A "family" of submissions is denoted by each unique color, which indicates all the submissions that derive from a unique "origin" (a submission which has no parent). Submissions with no parents or children (origins that dead-end) are plotted as single black points.
The points with black squares around them denote submissions that improved upon performance within their family. This means that these submissions had better scores than all of their siblings as well as any ancestral submissions (and their siblings) located above them in the familial hierarchy.
The point with a black star around it represents the best scoring of all submissions.
When the mouse cursor is placed over the Ancestry plot, the cursor will change from an arrow to the following symbol:
While within the axes region, the mouse can be used to explore the Ancestry plot in the following ways:
Zooming: To zoom in on the plot, click and hold the middle mouse button. The cursor will change to the following symbol:
While holding the middle mouse button down, upward movements of the mouse will zoom in on the center of the plot and downward movements will zoom out. There are limits placed on how far in or out the plot can be zoomed. Note: zooming may be sluggish due to the number of points on the plot.
Panning: To pan back and forth on the plot, click and hold the left mouse button. The cursor will change to the following symbol:
While holding the left mouse button down, the plot will be dragged in the direction of the mouse movement. The plot is limited in how far it will pan such that part of the plot is always underneath the center of the Ancestry plot window. Note: panning may be sluggish due to the number of points on the plot.
Reset view: A double-click of any mouse button will return the plot to the default view that it has upon loading.
Preview: If the cursor is moved near enough to a submission's point, a preview of the data for that submission will be displayed in the area above the Ancestry plot. This preview will show the title, author, submission time, and score. Note that you may have to zoom in a certain amount first before preview data begins to show up.
Selection: When the cursor is close enough to a submission to show a preview, the right mouse button can be clicked to load that submission data and code into one of the panels on the left of the LINEAGE interface. When a submission is selected, an arrow will be displayed next to the submission's point with a number next to it: "1" for the submission displayed on the top and "2" for the submission displayed on the bottom.
On each submission panel on the left of the LINEAGE interface there is a button that reads either "Replace" (green button) or "Keep" (red button). The submission with a button that says "Replace" will be the one replaced when the next submission is selected from the Ancestry plot. Pressing either button will cause the two buttons to toggle, switching the panel that will be replaced.
The submission data that is normally displayed in the preview is displayed at the top of each submission panel. In addition, the code of each submission is displayed in the listbox of each submission panel. The line numbers are displayed, and the lines of code that are different between the two selected submissions are highlighted. The code can be scrolled through, but cannot be selected or modified. A sample LINEAGE interface with two submissions selected is displayed below: