cyclone Documentation
cyclone is our multi-perspective clone evolution inspection tool. Currently, cyclone offers five different views which you can use to inspect clone data contained in an rcf file. The views are:
General Features
The features described in this section are not limited to a single view but apply to one or more views.
Menu File
Open. Allows you to select an rcf file from which clone data is loaded and displayed in cyclone's views.
Save. Saves any changes to the clone data to the rcf file. Currently, the only thing that can be changed are the annotations of the different entities.
Save As. Same as Save, but allows you to choose a different file name before saving.
Clear Console. Clears the console in the lower part of cyclone's GUI.
Recent Files. The list contains up to four recent rcf files which you can reopen by choosing the corresponding entry in the menu.
Quit. Exits cyclone.
Menu Layout
This menu is specific to the Evolution View and explained in the corresponding section.
Menu Diff
This menu is specific to the Source View and explained in the corresponding section.
Menu Filter
This menu allows you to filter the clone data by removing clones with certain properties. When a particular filter is selected, all views are updated accordingly. Filters are additive—that is, a filter always operates on the data that is currently displayed and not the total data.
Static. This filter removes all clone genealogies that are static—that is, that never changed during their lifetime. A clone genealogy is considered static when none of its clone classes is marked as changed and there are no fragments appearing or disappearing during its lifetime. This filter can be used to reduce the clone data to the interesting clones that changed at least once during their history.
Excessive. Removes all clone genealogies that either existed in the very first or in the very last version of the system. In other words, a genealogy is excessive when it reaches beyond the boundaries of the analysis. The filter can be used to reduce the clone data to the genealogies that are completely contained in the analysis period—that is, they are created and disappear within the versions analyzed.
By Path. Filters clones according to the paths of the files that contain the cloned fragments. The filter prompts you for an arbitrary string and removes all clone genealogies whose files' paths do not contain that string—in other words, that are unrelated to that string. If the string is contained in the path of at least one file containing a fragment of the genealogy, the genealogy is kept. You can use the check box Invert to invert this behavior—that is, all genealogies related to the string are removed.
Invert. Inverts the clone data that are currently displayed. Everything that has been removed by filter becomes visible, whereas the currently visible data are removed (become invisible).
Reset. Resets all filter. Everything becomes visible again. The clone data which is displayed corresponds to the total number of data contained in the rcf file.
Menu Help
About. Displays information about cyclone itself.
Evolution View
This view provides an interactive visualization of clone genealogies. You can use this view to analyze how clones evolved and how they changed during the evolution of the system. The clones of each version are organized in a row. The index of the respective version is given at the very left of the screen. Each circle represents the occurrence of a cloned fragment (a continuous source code section) in the corresponding version. Fragments that are clones of each other are grouped in a rectangle—the clone class. The lines illustrate the ancestry of cloned fragments—that is, when two fragments are connected by a line, both are occurrences of the same fragment in different versions.
- cyclone's evolution view.
Clone Types. The similarity between cloned fragments (the type of the clone class) is indicated by the color of the rectangle that represents the corresponding class. A black rectangle tells that the clone class is of type 1, a dark gray rectangle indicates that the clone class is of type 2, and a light gray rectangle tells that the clone class if of type 3.
Changes. Changes to clones are visualized by coloring the corresponding clones class. If the rectangle of a clones class is colored with light gray, the fragments of that clone class have changed consistently from the version where the clone class is colored to the next version. If the rectangle is colored with dark gray, the fragments of the clone class have change inconsistently—that is, the fragments of the clone class have not been changed in the same way—from that version to the next.
Layout. When the mouse pointer is located above a clone class, hover information is displayed that provides details about the fragments that are contained in that clone class. You can use drag & drop to move clone classes to an arbitrary position. You can use the menu Layout to control the general layout.
- Layout → Compressed: Clone classes of each version are shown with a fixed amount of space in-between them. The advantage is that the overall canvas size is smaller compared to the other option. However, extensive deletions or additions of clones may result in many over overlying ancestry lines.
- Layout → Vertical: Clone classes of each genealogy are aligned vertically. The graph looks much more organized but may contain large blank areas.
- Layout → Reset: Resets the layout when clone classes have been manually moved.
Selection. For easy tracking of clones you can select individual fragments, clone classes, and their traces.
- Left Mouse Button: Selects a particular fragment or clone class. The fragment or clone class will also be selected in the other views. A selected fragment and clone class will be shown in red color. The intensity of the color maintains the information about change consistency.
- Middle Mouse Button: The respective fragment or clone class and all its predecessors and successors will be highlighted and shown in red color.
- Right Mouse Button: Deselect any selected fragments or clone classes.
Key Interaction. In addition to the interaction via the mouse, you can use certain keys to control the evolution view.
- +/-: Zooms the graph.
- Ctrl+F: Prompts you for an ID and consequently searches the fragment with the given ID. If the fragment is found, it will be selected and centered in the view.
- Ctrl+C: Prompts you for an ID and consequently searches the clone class with the given ID. If the clone class is found, it will be selected and centered in the view.
Source View
This view allows to compare the source code of two cloned fragments—and the files that contain them. The following elements are part of this view:
- A toolbar at the top which you can use to control which fragments are displayed. You can use the buttons to set the mode which is used and to easily navigate fragments and clone classes.
- A textfield to annotate the clone class that is currently displayed. When the rcf file is saved, the annotation will be permanently stored.
- A table listing the fragments of the current clones class. The arrows in the left-most column indicate in which source panel the respective fragment is shown.
-
The box contains the unique ID of the clone class. The color describes the
similarity between the clone class' fragments.
- Red indicates that the fragments are identical disregarding comments and white space (type-1 clone).
- Orange indicates that the fragments are identical with respect to the type of tokens. However, there are differences in the actual values of identifiers and literals (type-2 clone).
- Yellow indicates that the fragments have similar token sequences but some tokens are contained in only one of the fragments (type-3 clone).
- Two source panels that display the actual source code. In-between both panels is another small panel that establishes the connection between the left and right source code panel if applicable.
- cyclone's view for comparing source code.
The source view indicates the boundaries of cloned fragments using color. The source code that belongs to the current fragment is shown in normal color with syntax highlighting applied to it. The source code that is not part of the fragment and comments is shown in light gray. Under certain circumstances (see modes) there is no corresponding fragment to be displayed in one of the views in case of which the complete source code is shown in normal color with syntax highlighting applied to it.
The source view also highlights the differences between the source code shown in the left and in the right panel. This can be done either in terms of tokens or in terms of lines. You can select the type of differences you are interested in via the menu Diff. Any differences are shown with colored background.
cyclone allows you to scroll both source panels individually. This way, you can select the part of the source code that is of interest to you for in both panels. When you've lost the cloned fragments that are currently displayed, you can realign them.
 |
Realign the fragments that are currently displayed in the source panels. |
Modes
cyclone offers three different modes which determine which fragments are shown in the source panels of this view.
 |
Displays a fragment's occurrence in the previous version in the left panel and the fragment's occurrence in the current version in the right panel. This mode can be used to inspect how a fragment has changed from the previous version. |
 |
Displays two fragments of the current clone class. The first fragment of the clone class is always displayed in the left panel. The right panel shows one of the clone class' other fragments. |
 |
Displays a fragment's occurrence in the current version in the left panel and the fragment's occurrence in the next version in the right panel. This mode can be used to inspect how a fragment has changed to the next version. |
Navigation
Navigating clone classes is not limited to a single version, when the last (or first) clone class is reached, using the navigation facilities will eventually continue with a clone class of the next (or previous) version—if such a version exists.
 
|
Displays the previous (or next) clone class. |
|
Displays the previous (or next) clone class that is marked as inconsistently changed. |
|
Displays the previous (or next) clone class that is marked as consistently changed. |
|
Displays the previous (or next) clone class that is marked as either consistently or inconsistently changed. |
  |
Displays the previous (or next) fragment. In single-version mode
(), these buttons determine which fragment
is shown in the right source panel whereas the left source panel always
shows the first fragment of the current clone class. When not in
single-version mode, these buttons affect both source panels.
|
 |
Displays a random clone class of the current version. |
Treemap View
The treemap view presents a decomposition of the system with each rectangle being a single file or directory. The area of the rectangle is determined by the number of lines of code that are contained in the file or the files within a directory respectively. The intesity of the color indicates the clone coverage of that entity—that is, the number of lines of code that are covered by a t least one clone divided by the total number of lines of code.
- cyclone's treemap view.
Version. The treemap always represents only a single version of the system. You can select the version using the drop-down menu in the top left corner.
Path. Next to the menu is a text field that shows the path of the entity the mouse is currently pointing at.
Depth. You can use the spin button to determine the depth of the decomposition. Depth 1 refers to a single rectangle representing the whole systems. Depth 2 refers to a decomposition according to the first-level directories of the system and so forth. When the maximum depth is selected, every rectangle represents a single source file of the system.
Root. You can right-click an arbitrary entity of the treemap and set it as the root of the map—that is, that entity will fill the complete map. This can be used to zoom in on entities to inspect the details. You can reset the root using the corresponding button in the toolbar.
Boundaries. The remaining two check boxes allow you to control whether the boundaries of files and directories are shown or not. Boundaries of files are shown in gray whereas boundaries of directories are shown in black. This helps to distinguish neighboring entities having the same color.
Links
The treemap allows you to select individual entities using the left mouse button. By default entities are shown in red. When an entity is selected, its color changes to blue. Note that this indicates only that the entity is selected, the color's intensity determines the clone coverage of the respective entity.
In addition to the selected entity, all other entities that share clones with the selected entity are shown using green color. Furthermore, the entities are linked with lines indicating that those entities share clones. Sharing clones is defined as there exists at least one clone class that contains at least one fragment located within the selected entity and at least one fragment located within the linked entity. The number next to the links refers to the number of clone classes to which this condition applies.
You can deselect an entity using the middle mouse button.
List View
The list view contains a list representation of versions (the left table), clone classes (the upper right table), and fragments (the lower right table). Each row in the tables provides an editable field Annotation that allows you to annotate the corresponding entity. In general, the list view is good for sorting entities according to a particular property. When an entity is selected in this view, it becomes automatically selected in the other view.
So, for example, you can sort clone classes according to the lenght of their fragments, select the longest clone class and then switch to the source view to inspect that particular clone class.
- cyclone's list view.
Versions. The view shows all versions that have been loaded from the rcf file. For each version, the view shows the total number of clone classes, the number of clone classes for each type of similarity, and the number of fragments.
Clone Classes. The corresponding table lists all clone classes that are contained in the version that is currently selected. For each clone class, the table shows its ID, type of similarity, length measured in tokens, and the number of fragments.
Fragments. The lower right table lists the fragments that are contained in the currently selected clone class. Fragments are given together with their ID and the file they are located in.
Plot View
This view contains a variety of graphs which visualize different characteristics of clone evolution. You can determine which graph is shown using the drop-down menu in the toolbar. You can use the check boxes to control whether the key, horizontal, and vertical lines are shown. The view also provide a plain export of the data that are currently displayed using the corresponding button in the toolbar.
Individual data points that are plotted can be selected. When selected, the precise coordinates are displayed next to the corresponding data point.
- cyclone's plot view.
cyclone currently offers the following plots to be displayed:
- Quantities: Displays the quantitative evolution of different clone-related metrics. The x-axis refers to the versions of the system, whereas the y-axis denotes the corresponding quantity of the respective metric.
- Lifetime: This plot shows how many clone genealogies life for a given number of versions. The x-axis denotes the number of versions—the lifetime. The y-axis shows the number of genealogy whose lifetime equals the corresponding x-value.
- Change Frequency: Shows how many genealogies changed a given number of times. The x-axis denotes the number of changes whereas the y-axis denotes the number of genealogies that changed exactly this often.