Documentation

Once COLIBRI Studio is installed, the COLIBRI perspective organizes all the provided tools. Commonly, the first action consists of creating a new CBR Project by means of the New CBR Project Wizards. Then, the tools in the perspective can be used to modify the configuration and generate the source code of your application. There are three wizards accessible through the New menu:

• Option 1: Select File >> New.
  
  or
• Option 2: Select the new icon.
  

Wizard New CBR Project Wizard

This wizard let's you create an empty CBR Project or choose which elements of you want to configure with the wizard.

At least you have to perform two steps: (1) create a new project and configure extra required libraries (if any) through the Eclipse standard wizard, and (2) choose the package and name of the java class that will implement your CBR system and select an in-memory organization of your case base:

Optionally, you can define the case structure, configure the similarity measures and define the persistence of your cases:

Once finished, the package explorer will show the generated project. A java file with an empty skeleton of a CBR application will be automatically created and opened in an editor. Its content is the typical instantiation of the CBRApplication interface of the jCOLIBRI framework (you may need to read the jCOLIBRI tutorial to understand that code). Here you can program directly or use the System Editor tool to generate the source code of your application by retrieving and adapting a template.

Wizard New k-NN CBR Project

This wizard generates a complete k Nearest Neighbours system. Users must configure the case structure, similarity and persistence and the wizard generates a fully functional system. The configuration is performed by means of the dialogs used in the previous wizard.

Wizard New CBR System from template

This wizard creates a new CBR Project and lets users select a template from the catalog that will be adapted to generate the CBR system. Once the project is configured, the wizard asks for the type (family) of CBR system to generate. Next, a recommender proposes templates that are associated to a real implementation and a screenshot. This way users can test the behaviour of the CBR system once implemented (in a testbed domain). By clicking on the Try it! you can try the behaviour of the selected template.

When the template has been selected, the wizard lets users decide the level of adaptation to be performed:

• Open the configured template. This option opens the template configured with the methods that implement the behavior shown in the previous step. This way, adaptation consists on changing desired methods and adjust the parameters.
• Open the original template. It opens the template without any kind of configuration. The tasks conforming the template are displayed and the user is in charge of assigning and configuring a method for each one.

After this last step, the wizard is closed and the System Editor tool will open the selected template.

System Editor

The System Editor tool allows to adapt a retrieved template by selecting the components that solve each task. The Standard CBR Application tab shows the global structure of a CBR system in jCOLIBRI. Actually, it represents the methods of the StandardCBRApplication interface. On the left side, three panels represent the variables that connect the inputs and outputs of each component. Inputs are drawn on the left side of component and outputs on the right side.

These variables can be defined as:

• Input. Represents an input of the CBR system. The generated source code will include a setter method for each input variable. They are used to configure the CBR system.
• Local Variable. Are local and private variables of the CBR system. The cannot be accessed externally.
• Output. Represents an output of the CBR system. The generated source code will include a getter method for each output variable. They are used to return the result of the reasoning process.

The preCycle, cycle and postCycle tabs contain the subtemplate associated to every stage of a CBR system in jCOLIBRI. Users must configure every subtemplate by chosing a suitable component for every task. Once the template is complete the tool can generate automatically the source code of the CBR system. The panel on the right side of the window describes the meaning of every element that can appear in a template. The System Editor checks the templates to ensure they are correctlly configured. Errors and warnings found will be displayed in the Problems panel.

Variables are defined with a name and a java type. They can be created automatically from the template, right-clicking on an unassigned variable.

Every input or output must be assigned to an existing variable. Unassigned parameters will cause an error entry the Problems View located in the bottom side of the window.
Existing variables can be assigned to inputs or outputs by clicking on the parameter. A list of compatible variables will be shown. The compatibility is checked according to the java classes hierarchy. Moreover, the getter methods of every variable are also displayed.

The component used to solve each task can be changed by double-clicking on the task. A dialog will show the components able to solve the task. It displays the description and structure of the component. Note that these components are automatically obtained by analysing the annotations in jCOLIBRI or the CBR Project.

The buttons bar includes the following actions:

• Open a template with the recommendation wizard.
• Open an template located in the project as a system. This template has to be generated with the Template Editor tool.
• Open an existing system from the project.
• Save the system. Systems are saved in the project in a folder called "templates".
• Generate the source code. This is the most important action. It generates the source code of the application according to the configured system.
• Generate a screenshot of the template.

Template Editor

This tool should be only used by expert users that want to define a new template. These templates can be later configured with the system editor.
Templates can be created, loaded and stored in the project. When creating a template, some metadata is required, like the author, description or family of the system (generic, textual, recommender, etc).

The upper buttons bar contains the different elements that can be inserted into a template. By default, standard tasks can be chosen, although new tasks can be defined with the last button.

Case Designer

The Case Designer tool is used to define the structure of the cases. In jCOLIBRI cases contain a Description, Solution, Result and Justification components. Each component is composed of several attributes, that can be also simple or compound. Each component or compound attribute corresponds to a Java Bean that contains the defined simple attributes with their corresponding getter and setter methods. Therefore a simple attribute is defined by its name and its java type. One simple attribute of each component must be defined as an ID. These ID attributes are used by the persistence connector to represent primary keys.

The button bar allows to create a new case structure, load and save it from/to an xml file, and generate the corresponding java beans.

Case Base Selector

Configures the in-memory organization of the case-base. Once the case base organization is selected, the tool can generate the source code that configures it.

Plain Text connector

Configures the Plain Text Connector by selecting a text file containing the cases. Each line defines a case and attributes are separated by a specific character. The tool allows to select the file, define the separator and map every column with an attribute of the case (defined in the Case Designer tool).

The tool allows to save the connector to an xml file and generate the source code that configures it in the application.

Similarity

Defines the similarity configuration of the CBR system. Note that some applications won't use this feature if they do not execute the Nearest-Neighbour algorithm.
Compound attributes are configured with a global similarity function, whereas simple attributes use local similarity functions. These functions are automatically obtained from the jCOLIBRI library. Read the jCOLIBRI tutorial for more information about similarity measures.