ebi-pm 0.3.12

Ebi: a stochastic process mining utility

Ebi - a process mining tool

Ebi is a process mining software suite, maintained by the BPM group of RWTH Aachen University, Germany. It contains several algorithms and techniques that perform analyses on event logs and process models. Ebi can be used as a command-line utility, from a browser and in ProM. Furthermore, Ebi can be called from Rust, Python, Java and Javascript.

Ebi provides process mining and stochastic process mining algorithms, and supports exact arithmetic for most of these algorithms.

More information on its use can be found in its PDF manual.

Use Ebi from a browser

Most commands of Ebi can be used directly from the browser on the commands page.

This will run fully on your computer, is limited to 4GB of RAM, and does not upload files.

Use Ebi as a command line utility

1. Download Ebi CLI for Windows or for Linux.
2. In Linux, give the file execution permissions.
3. Open a command prompt and run the executable. Installation is not necessary, and Ebi does not require internet access.
4. For an overview of the commands, refer to the commands page or the PDF manual.

Ebi runs on Mac OS X and many other platforms by self-compilation; please see below.

A good way to get started is to try ebi info followed by a file name, which will parse the file and print some information about it.

Use Ebi in ProM

Ebi is also available in the ProM framework on Windows and Linux. In the ProM Package Manager, install Ebi. Then, several Ebi commands can be used like any other ProM plug-in. As Ebi is extremely flexible in its inputs and outputs, please ensure you choose the correct input and output plug-in (there are many).

The PDF manual indicates which commands are available in ProM.

Call Ebi from Python

Ebi can be used as a Python package, which integrates with PM4Py.

1. Install the Ebi-pm package using pip:

    pip install ebi-pm
   

2. Then, one can use Ebi as follows:

    import pm4py
    import ebi
    # Load a log using PM4Py
    log = pm4py.read_xes("myLog.xes", return_legacy_log_object=True)
    # Load a model as a string
    with open('mymodel.slpn', 'r') as file:
        model = file.read()
    # Call the Ebi function
    result = ebi.conformance_earth_movers_sample(
        log,
        model,
        1000
    )
    print(result)
   

The names of the Ebi functions can be found on the commands page or in the PDF manual.

Some PM4Py objects, such as event logs, are read directly by Ebi, but most are passed as strings. If Ebi returns an exact fraction, it is returned as an array consisting of 1) a floating-point approximation, 2) the full numerator, and 3) the full denominator.

Call Ebi from Rust

Ebi can be used as a Rust crate, available from crates.io.

1. Add the following to the Cargo.toml file:

    [dependencies]
    ebi = "*"
   

2. Then, one can use Ebi as follows:

    use ebi::ebi_objects::FiniteStochasticLanguage;
    use ebi::{
        ebi_traits::ebi_trait_finite_stochastic_language::EbiTraitFiniteStochasticLanguage,
        techniques::earth_movers_stochastic_conformance::EarthMoversStochasticConformance,
    };
    use ebi_objects::ebi_arithmetic::{Fraction, One};
    use std::fs;
    // Read the first file and box it
    let fin1 = fs::read_to_string("testfiles/empty_trace.slang").unwrap();
    let slang1 = fin1.parse::<FiniteStochasticLanguage>().unwrap();
    let mut object1: Box<dyn EbiTraitFiniteStochasticLanguage> = Box::new(slang1);
    // Read the second file and box it
    let fin2 = fs::read_to_string("testfiles/empty_trace.slang").unwrap();
    let slang2 = fin2.parse::<FiniteStochasticLanguage>().unwrap();
    let mut object2: Box<dyn EbiTraitFiniteStochasticLanguage> = Box::new(slang2);
    // Compute EMSC
    let emsc = object1
        .earth_movers_stochastic_conformance(object2.as_mut())
        .unwrap();
    assert_eq!(emsc, Fraction::one());
   

Call Ebi from Java

To use Ebi from Java:

1. Download the Ebi library for Windows or Linux and put it in a folder that is accessible to the Path of your program.

2. Add the following static declarations:

   static native String call_ebi_internal(String command_name, String output_format, String[] inputs);
   static {
       try {
           System.loadLibrary("ebi");
           System.out.println("Ebi library loaded");
       } catch (Exception e) {
           e.printStackTrace();
       }
   }
   

3. Then, Ebi can be called through the native function, for instance:

   String log = Files.readString("log.xes", StandardCharsets.UTF_8);
   String result = call_ebi_internal("Ebi analyse completeness", ".frac", new String[] {log});
   

The commands page indicates the commands that can be called from Java.

Call Ebi from Javascript

Ebi is available as an NPM library.

Getting started with development

Ebi is hosted on Github. To get started with development, or to compile for Mac OS X:

1. Install Rustup
2. Log out and in again
3. Install Visual Studio Code
4. In Visual Studio Code, install the extension rust-analyzer
5. With a browser, go to the project on Github, choose "Clone", "Visual Studio Code (SSH)", and clone it in Visual Studio Code.
6. To run Ebi, use the terminal of Visual Studio Code to give the command "cargo run --" instead of "ebi". Everything else is equivalent to the commands mentioned in the manual.
7. To compile Ebi, give the command "cargo build --release". The binary is then placed in the project folder, in the "build/release" sub-folder.

Information on the architecture of Ebi, including its sub-crates, can be found in the PDF manual.

We welcome pull requests on Github. Before opening a pull request, please ensure that the test batch file src/tests/test.sh finishes without errors (on Windows, rename it to .bat and remove the first three lines). This file may take up to an hour to run, depending on your machine.

License

Ebi has a dual MIT and GPL license.