Usage

Usage

You can run MINERful as a stand-alone software by invoking the command shell scripts or directly running the JAR with your Java installation. If you are a developer, you can include the JAR in your Java project and use use the MINERful APIs.

MINERful as a stand-alone application (with .sh files)

The easiest way to launch MINERful is to make use of the .sh files.

• To launch the miner: run-MINERful.sh
• To reduce the number of constraints in a process specification: run-MINERfulSimplifier.sh
• To create synthetic logs: run-MINERfulEventLogMaker.sh
• To run tests (as we did for the evaluation sections of our papers): test-launchers/*.sh

Each of those launchers can be invoked with the -h parameter. An explanation of all possible parameters that can be passed is written there (beware, they are quite an amount so take your time). Depending on the case, some parameters are specified in the .sh files, whereas others are left free. In case, feel free to modify the constants declared at the beginning of the script, so as to customise them.

The scripts that end with the -unstable.sh suffix do not launch MINERful via its JAR, but directly using bytecode files. In this way, we can immediately try the modified source code without overwriting the JAR version.

Usage examples of MINERful as a stand-alone application (with .sh files)

• Mine an XES log file located in /home/user/file.xes:

  run-MINERful.sh -iLF '/home/user/file.xes' 
  

• Display the help screen:

  run-MINERful.sh -h
  

Mine an XES log file located in /home/user/file.xes and export the discovered specification in an XML file located in /home/user/model-condec.xml, formatted as Declare/ConDec. Set an event based support threshold of 0.95, an event based confidence level threshold of 0.25, and an event based coverage threshold of 0.125, a trace based support threshold of 0.95, a trace based confidence level threshold of 0.25, and a trace based coverage threshold of 0.125 (if you have no idea what these parameters are about, check this paper out):

  run-MINERful.sh -iLF '/home/user/file.xes' - -oConDec '/home/user/model-condec.xml'  -s 0.05 -c 0.95 -g 0.05 -sT 0.125 -cT 0.95 -gT 0.125

• Mine an XES log file located in /home/user/file.xes, with comprehensive debug lines

  run-MINERful.sh -d all -iLF '/home/user/file.xes' 
  

• Mine an XES log file located in /home/user/file.xes, with comprehensive debug lines. Let results be exported in a CSV file located in /home/user/output.csv:

  run-MINERful.sh -d all -iLF '/home/user/file.xes' -oCSV '/home/user/output.csv'
  

• Mine an XES log file located in /home/user/file.xes, with comprehensive debug lines. Set an event based support threshold of 0.05, an event based confidence level threshold of 0.95, and an event based coverage threshold of 0.05, a trace based support threshold of 0.125, a trace based confidence level threshold of 0.95, and a trace based coverage threshold of 0.125 (if you have no idea what these parameters are about, check this paper out). Let results be exported in a CSV file located in /home/user/output.csv:

  run-MINERful.sh -d all -iLF '/home/user/file.xes' -oCSV '/home/user/output.csv' -s 0.05 -c 0.95 -g 0.05 -sT 0.125 -cT 0.95 -gT 0.125
  

Usage examples of MINERful as a stand-alone application (running the JAR)

This is a little bit trickier, but necessary, in case you have a Microsoft Windows system. From your prompt, type:

  java -cp ".\lib\*;MINERful.jar" minerful.<LAUNCHER_CLASS> -h

where LAUNCHER_CLASS can be MinerFulMinerStarter to run the miner, MinerFulTracesMakerStarter to launch the builder of synthetic logs, MinerFulSimplificationStarter to use the simplification engine, and so on (kudos to Ralph A. for testing the commands on Windows).

The -h parameter appended at the end of the prompt shows and explains the parameters you can pass. They are exactly the same as the Linux/MacOS version.

MINERful APIs

For advanced users: You can use MINERful as a Java package and integrate it with your software! Check out the minerful.examples.api source code to see some examples. In particular:

• discovery.MinerFulObserverInvokerOnXesFile demonstrates how to invoke the MINERful miner as an API, and subsequently observe the changes that are applied to the process specification in a publish/subscribe fashion. Lastly, the specification is saved as a Declare Map file.
• discovery.MinerFulCallerOnStringFile demonstrates how to call MINERful to discover a process specification out of strings saved on a file.
• io.FromDeclareMapToJSONandCSV demonstrates how to call MINERful to load a process specification stored as a Declare map XML file, and then store it converted into MINERful CSV, and JSON formats.
• logmaking.FromCharactersProcessSpecificationToLog demonstrates how to generate XES logs starting from the definitions of new constraints. It can be interesting also because it shows how to create a process specification on the fly.
• logmaking.FromStringsProcessSpecificationToLog demonstrates how to generate XES logs starting from the definitions of constraints exerted on activities identified by single characters (more or less the same as above).