You are viewing the RapidMiner Developers documentation for version 2024.0 - Check here for latest version

Adding Operator Parameters

Ports handle the data that flows through your operator. You can, however, also define parameters that influence the behavior of the operator.

Parameters are presented in the Parameters panel of Altair AI Studio, where users can alter the parameters' values. There are several types of parameters available for defining real or integer numbers, strings, and collections of strings in combo boxes (either editable or not). Also available are special types for selecting a column or several columns. For the most complex parameter type, you might even define a GUI component as a configuration wizard.

Back to the operator class to add parameters. In fact, you just have to override one method:

@Override
public List<ParameterType> getParameterTypes(){
    return super.getParameterTypes();
}

Notice that you have to return a list of ParameterTypes. It's good practice to call the super method to retrieve the parameters defined in extending operators or abstract classes that provide basic functionality. Otherwise, the functionality provided by the super class might fail because you haven't defined the needed parameters.

For now, add a parameter defining which text should be logged to the console when the operator is executed. It looks like this:

@Override
public List<ParameterType> getParameterTypes(){
    List<ParameterType> types = super.getParameterTypes();

    types.add(new ParameterTypeString(
        PARAMETER_TEXT,
        "This parameter defines which text is logged to 
        the console when this operator is executed.",
        "This is a default text",
        false));
    return types;
}

First, retrieve the list of ParameterTypes of the super class and then add your own parameter. In this example, the parameter is of type string and named with the public constant PARAMETER_TEXT. The string that follows should describe the functionality of the parameter type; it is shown in the info tool tip of the parameter. The next string is the default value of the parameter, followed by the last parameter, which determines if the parameter is expert or not. In this example, the parameter is not an expert parameter.

Before looking at the result, you must add the constant to the class. Simply define a public constant:

public static final String PARAMETER_TEXT = "log text";

The Parameters panel now looks like this:

../img/parameter-view.png

You could use the class ParameterTypeInt for integer values or ParameterTypeDouble for double values, but there are also ParameterTypes for files, dates, category selection and much more. Check out which ParameterType constructors are available!

Expert parameters

Parameters can be either normal or expert. Expert parameters aren't shown until the user switches to expert mode. Therefore, it is good practice to define parameters as expert if their effect is only understandable by those with deeper knowledge of the underlying algorithm. All expert parameters must have default values so that the user is not required to define a parameter he cannot understand. To enable this, simply define in the constructor calls of your ParameterTypes whether a parameter is an expert parameter or not.

Using parameters

After defining the parameter, use it to individualize the message that your operator writes to the Log panel. First, retrieve the value the user entered and store it in a local variable:

String text = getParameterAsString(PARAMETER_TEXT);

Then, use the local variable to change the output of the operator. There are several getParameterAsXXX() methods that you can call to get the value in the correct type.

Parameter dependencies

Defining parameter dependencies provides the user with further guidance. For example, some parameters may only be used if other parameters are set. Using these dependencies indicates to the user which parameter will have an effect preventing time spent with irrelevant parameters. If, for example, you are familiar with the large amount of parameters that kernel-based methods like the SVM offer, you probably understand why this is important.

You can add a Boolean parameter determining whether the operator should log custom text. In this case, if checked, the user sees the parameter field for the text. To introduce another parameter with its constant:

public static final String PARAMETER_USE_CUSTOM_TEXT = "use custom text"

Now, build a parameter condition like in the following code:

@Override
public List<ParameterType> getParameterTypes(){
    List<ParameterType> types = super.getParameterTypes();

    types.add(new ParameterTypeBoolean(
        PARAMETER_USE_CUSTOM_TEXT,
        "If checked, a custom text is printed to the log view.",
        false,
        false));

    ParameterType type = new ParameterTypeString(
        PARAMETER_TEXT,
        "This parameter defines which text is logged to 
        the console when this operator is executed.",
        "This is a default text",
        false);

    type.registerDependencyCondition(
        new BooleanParameterCondition(
            this, PARAMETER_USE_CUSTOM_TEXT, true, true));

    types.add(type);

    return types;
}

For registering the condition, you had to remember the type in a local variable, which is then added to the list separately. Here you added a BooleanParameterCondition, which needs to reference a ParameterHandler. For operators, this is the operator itself. The second argument is the name of the references parameter. The two Boolean values indicate 1) if the parameter becomes mandatory if the condition is satisfied and 2) the value the referenced parameter must have in order to fulfil the condition.

The resulting parameter panel now looks like this, depending on the parameter settings:

../img/parameter-condition.png

The next step is to document the behavior of your operator to provide help.

Categories

Versions

Adding Operator Parameters

Expert parameters

Using parameters

Parameter dependencies