Table of Contents
1. Basic Setup
RapidProM is an extension of RapidMiner. It is currently based on RapidMiner Unuk, a particular release of RapidMiner 5. RapidProM’s source code is published on https://github.com/rapidprom. This tutorial is written based on the 2.1 repository. In order to extend the source code, one needs to fork this repository. All ProM based code that is (re)used within RapidProM is conveniently stored in the libraries repository. This repository does not need to be forked in order to extend RapidProM.
The root folder of the repository contains three main folders, being Logo, RapidMiner_Unuk, and, RapidProM. All RapidProM code can be find in the RapidProM folder. The RapidMiner_Unuk folder contains the source code of the RapidMiner Unuk Release and is needed to build and test the code developed in the RapidMiner folder. The contents of both the RapidProM and the RapidMiner_Unuk folders are eclipse projects. To be able to extend RapidProM we suggest to import the two projects into an IDE that supports eclipse based project files.
2. Creating an Operator
As indicated, RapidProM is based on RapidMiner Unuk. Extending RapidProM is therefore by definition equivalent to extending RapidMiner. Luckily, the developers of RapidMiner developed their own documentation on how to extend RapidMiner. We kindly refer the gentle reader to this document to get a basic understanding of extending RapidMiner in general.
From this point forward, we assume the gentle reader to have read some parts of the aforementioned document and we assume some degree of familiarity with the concepts of Operators and IOObjects. Note that additionally there is the concept of an IOObjectRenderer, which represents a visualization of an IOObject. We assume that one has forked the repository. Additionally we advise to take a quick look at the source code, or, alternatively, the Javadoc.
Let’s assume you have written some fancy operator CustomOperator1 that translates some input IOObject Input1 into an output IOObject Output1. This could for example be an operator that takes an event log and produces some filtered event log, or, an operator that produces a Petri net based on some input event log etc. After developing the operator, we are interested in testing whether the operator does its job properly. To do this, the following three steps are to be executed:
- Register. We have to make sure that the developed IOObject(s) and Operator(s) are defined in order for RapidMiner to be able to actually know of their existence. Please follow the following step in order to do so:
- Define the IOObject in:
- Define the Operator’s description in:
- Define the Operator in:
- Build. The next step is to build the RapidProM extension. This is done by running the build.xml file as an ant build script. However, make sure that the ivy-2.4.0.jar file is included in the build script’s class path! The ivy jar file is located in the RapidProM eclipse project, in the lib folder.
- Run. Once you endured the hassle of building an ant script, thou are ready to run thou own custom RapidProM extension for the first time, aye! This is done by running RapidMiner from it’s source. This is done by running the conveniently located java class com.rapidminer.gui.RapidMinerGUI, located in the RapidProM Unuk eclipse project.
These three steps form the basis of making an operator and its associated IOObjects executable in RapidMiner. Finally, in case the developed operator needs external jar files there are roughly two solutions to incorporate these:
- Put the jar file in the lib folder (and also in the RapidProM project classpath).
- If the jar file is available via ivy (e.g. via a maven repository) you can add a dependency to the ivy.xml file in the RapidProM eclipse project. Make sure to update the ivysettings.xml file in case the jar file is hosted on a different location.
3. Including ProM Code
In this section we detail on how to include existing ProM code into RapidProM. We first explain how the ProM code can be included into RapidProM, after which we explain how to wrap around plugins.
3.1 Including the Code
Let's assume that you have written a plugin in ProM, called CustomPlugin1. Obviously there is some complicated algorithm behind it and you do not feel to copy the code (shame on you if you would). First and foremost one has to make sure the following precondition is met: Make sure that your plugin has a public access method that takes a PluginContext interface as an input parameter. The previous sentence alternatively means: do not only provide a method that takes an UIPluginContext as an input parameter. If you would, RapidProM is bound to fail miserably and the balance in the force might be disturbed. A public method that does not even need a PluginContext would be even better, though we understand that you might need it to misuse some underlying framework functionality.
So, let us get back to your CustomPlugin1. The first thing to do is to make a jar out of it. As it is a ProM plugin, you probably use the Hudson server. After almost destroying your laptop/computer due to failing downstream builds that are completely unrelated to the code you’ve made, you probably end up with a jar that contains CustomPlugin1. Basically you can now do almost exactly the same as described in Section 2 w.r.t. external jars:
- Unordered List ItemPut the jar file in the lib folder (and also in the RapidProM project classpath).
- First, edit the ivy settings file (DO NOT REPLACE IT) such that you include references to ProM. (See https://svn.win.tue.nl/trac/prom/wiki/Libs, ivysettings.xml). Second, edit the ivy.xml file with a reference, e.g.
<dependency org="prom" name="PackageForCustomPlugin1" rev="latest” transitive="false" />
There is a side remark w.r.t. (2) to be made here. It is important to set transitivity to false, otherwise ivy will start fetching packages that your package PackageForCustomPlugin1 is depending on. This is inconvenient because these packages might already be loaded by RapidProM. However, as RapidProM uses fixed package versioning, this implies that the possibility exists that these packages are loaded twice with a different version (http://tech-read.com/2009/01/13/what-is-jar-hell/). Thus, please check whether all ProM packages that PackageForCustomPlugin1 depends on are included in RapidProM or not (remember, this information can be found in the libraries repository). For each package that is not yet included, again add a
<dependency org="prom" name="OtherPackage" rev="latest” transitive="false" />
line in the ivy.xml code. Clearly for this OtherPackage one again has to check whether all packages that it depends on are included in RapidProM.
3.2. Wrapping Plugins
Assuming that you managed to get all the source code from ProM needed for your own plugin, either by using jars in the lib folder or using ivy, you are now ready to start wrapping operators around the plugins you would like to port. Basically there is not much to it, in general:
- Create an IOObject wrapping around all the objects that your plugin uses (if these do not already exist), e.g. consider org.rapidprom.ioobjects.XLogIOObject
- Create an IOObjectRenderer. Typically this is a direct reference to the visualizer of the corresponding object in ProM.
- Create an Operator wrapping around your plugin. In general RapidMiner supports setting parameters, so different plugin versions can all be integrated in one Operator.
There is one important remark to be made here: If your plugin takes a PluginContext object as an input parameter, one can get this object from the org.rapidprom.external.connectors.prom.ProMPluginContextManager singleton class. Please use the getFutureResultAwareContext(Class<?> classContainingProMPlugin) method. As an argument to the method, provide the class in which you have defined your plugin, i.e., the class that contains the @Plugin and the @PluginVariant annotation.
Further, there are some existing abstract classes of we highly recommend to use as a basis.
- org.rapidprom.ioobjects.abstr.AbstractRapidProMIOObject; An easy to use wrapper for any ProM based object that automatically stores the PluginContext that was used to create this object (if any).
- org.rapidprom.ioobjectrenderers.abstr.AbstractRapidProMIOObjectRenderer; Allows you to only to implement the visualization of the corresponding IOObject.
- org.rapidprom.ioobjectrenderers.abstr.AbstractMultipleVisualizersRenderer; A renderer that allows you to add multiple renderers for a particular IOObject. For example, an event log has different views, also a Petri net can be visualized using both JGraph and Dot.
- org.rapidprom.operators.abstr.AbstractRapidProMDiscoveryOperator; Operator that automatically adds a parameter to select a classifier to used, based on the input event log’s meta data.
- org.rapidprom.operators.abstr.AbstractRapidProMExporterOperator; Operator with some predefined methods to wrap around exporters from ProM.
- org.rapidprom.operators.abstr.AbstractRapidProMExtractorOperator; Operator with some predefined methods for extracting (i.e. using a file as an input port) data.
- org.rapidprom.operators.abstr.AbstractRapidProMImportOperator; Operator with some predefined method for importing (i.e. a file is a parameter of the operator) data.
Finally, if you managed to get all the source code from ProM needed for your own plugin, either by using jars in the lib folder or using ivy, and, you have developed a first version of your plugin you’re ready to start testing. Execute the three steps, Register, Build, Run as explained in Section 2 and your Operator should be available.
There is a tiny, though painful, side remark to make here. Due to the fact that RapidProM uses fixed versioning, chances exist that the code you developed (or the code in the packages you depend on) are based on a newer version of a plugin than the version available in RapidProM. If this is the case, please contact us at rapidprom[at]promtools[dot]org as in such case the libraries of RapidProM need to be updated first.
3.3 Publishing an Operator
If you have tested your operator thoroughly and think it is ready and suitable for adoption in RapidProM, your operator can be included in a new RapidProM release. In such case, contact us via rapidprom[at]promtools[dot]org providing details about your operator (what is it’s purpose, what external libraries where used etc.). Moreover, send us a pull request containing your code (https://help.github.com/articles/fork-a-repo/). After assessing whether the plugin/code is suitable for adoption, we will incorporate your code in the next release of RapidProM.