Widgets

Slider

Configuration

Sliders are useful in situations where the user has to select a numeric value from a range.

Example:

Slider configuration

Available Options

The following options are available for a slider widget:

Enter the element name as it should be displayed in a tab

With this option the tab name of the symbol is defined, see screenshot below. The default value of the element name is the explanatory text of the symbol.

Note:

If all scalar widgets are displayed in the same tab (see aggregate widgets in the general options), then the name specified here is not displayed at all.

Element name
Choose a label

If a label has been specified, it will be displayed above the slider. In the example below the label select the maximum number of stocks is used. A label is optional.

Element label
Minimum / maximum / default value

Minimum / maximum value: Both a minimum and a maximum value are required for a slider. These define the range from which the user can select values.
Default value: A default value is the initial value of the slider i.e. the slider value set when starting the application. This is optional. If the value does not fall between the minimum and maximum values, a warning is issued. If this value is not specified, the minimum value is used as the default value. As soon as data is loaded which contains a value for the slider symbol, the slider is set to that value.

All three parameters can be set either statically or dynamically. If the range of the slider is independent of the data loaded, it is a good idea to configure it as a static slider. This means, for example, that the lower and upper limits of a slider are always 1 and 10. Scenario data does not change these.

Static values



Dynamic limits:
Sometimes it makes sense to adapt the limits to the data. An example for this can be found in the demo model pickstock. Here, two sliders are used. With one of the sliders, the user can select the maximum number of stocks, with the other one the number of training days.

Configuration of a slider (3)

In both sliders the maximum value - the upper limit - results from the input data of the parameter Price.

Configuration of a slider (4)

The maximum value for the maximum number of stocks is 30, since the data set Price that is currently loaded contains 30 stocks. If the user deletes e.g. all values of the stock AAPL from the data, the maximum value of the slider changes to 29. The same is true for the second slider: the number of training days. Here the maximum value of 252 results from the number of available dates in price.
In the Configuration Mode we can easily define such dynamic limits. For the first slider the configuration looks as follows:

Configuration of a slider (4)

The Static value? box is unchecked for the maximum value. Since the maximum slider value should result from the data of the symbol price, the corresponding header stock symbol in which the stocks are contained is selected (see table above). The operator is set to count since we want to count all stock symbols in our data to set the maximum value.

For the calculation of such limits from the data, the following operators are available:

Configuration of a slider (5)

More on Dependencies among widgets can be found here.

Step size

The step size specifies the interval between each selectable value on the slider. The value must be greater than 0 and must not exceed the total range of the slider.

Step size
Minimum step size

The minimum step size defines the minimum interval that can be used for scenario creation in Hypercube Mode for a range slider.

Sliderrange with step size of 5 and minimum step size of 1

In Hypercube Mode, when a slider range is used, scenarios are generated depending on the specified step size. Example: We configure a single slider with a lower bound of 70, an upper bound of 100 and a step size of 5. In the Hypercube Mode this single slider becomes a slider range with the same limits and the same step size. In the image below the selected limits of 75 to 90 and a step size of 5 result in 4 different variants (75, 80, 85, 90), i.e. 4 scenarios to be calculated.

Sliderrange with step size of 5

The minimum step size sets the minimum value the user can specify as step size in Hypercube Mode. The value may be lower than the regular step size. For example, if the slider above is configured with a regular step size of 5, the limits of the slider can be set in increments of 5. However, the step size for scenario generation on the right side can differ, e.g. be set in smaller intervals. If set to 1, this would result in 16 scenarios (75, 76, 77, ..., 89, 90).

Sliderrange with step size of 5 and minimum step size of 1
Note:

The minimum step size is only relevant in Hypercube Mode.

Show tick marks?

Tick marks are displayed below the sliders and help to visually divide the entire slider width.

Slider without tick marks:

Slider without tick marks

Slider with tick marks:

Slider with tick marks
Should element be expanded automatically in Hypercube Mode?

As explained in detail in the corresponding chapter, widgets will be expanded in the Hypercube Mode. With the option available here, the automatic extension of a widget can be switched off. The picture below shows extended widgets.

Expand in Hypercube Mode

JSON example

Slider with dynamic upper bound.


{
  "inputWidgets": {
    "maxstock": {
      "label": "Select the maximum number of stocks",
      "min": 1,
      "default": 3,
      "step": 1,
      "max": "card(price$symbol)",
      "alias": "maximum number of stocks to select",
      "widgetType": "slider"
    }
  }
}
                                    

Range slider

Configuration

A range slider returns two numeric values. For this reason, such a slider is not suitable for GAMS scales, but only for GAMS command line parameters, i.e. double-dash parameters.

Example:

In the Configuration Mode we define a double-dash parameter --range with the bounds 1 and 100. The lower default value shall be 42 and the upper default value 75:

Slider range configuration

In the GAMS model we can access the selected range with %RANGE_LO% for the lower value and %RANGE_UP% for the upper value.

More on widgets with ranges can be found here.

Range sliders in Hypercube Mode

A range slider in Base Mode becomes a range slider in Hypercube Mode with an additional checkbox:

Sliderrange in Hypercube Mode

With this checkbox you can determine if the selected range of the slider should result in a single scenario (All combinations? unchecked) or if all possible combinations within this range should be used (All combinations? checked). In the example above - All combinations? is checked - the selected step size determines which scenarios are generated for the Hypercube job. With a step size of 5 this would result in 10 different symbol ranges / scenarios:

  • 75 - 90
  • 80 - 90
  • 85 - 90
  • 90 - 90
  • 75 - 85
  • 80 - 85
  • 85 - 85
  • 75 - 80
  • 80 - 80
  • 75 - 75

An unchecked All combinations? would result in a single scenario. In this scenario, the symbol would have a range from 75 to 90.

Available Options

The available options of a range slider are identical to those of a normal slider. The only difference is that instead of a single default value, two of these values need to be specified.

JSON example

Note: In order for MIRO to recognize whether the symbol is a double dash parameter or a GAMS option, they are prefixed with either _gmspar_ for double dash parameters or _gmsopt_ for GAMS options.


{
  "inputWidgets": {
    "_gmspar_range": {
      "widgetType": "slider",
      "alias": "Range",
      "min": 1,
      "max": 100,
      "default": 42,
      "step": 1,
      "ticks": false,
      "noHcube": false,
      "label": "Select a range"
    }
  }
}
                                    

Checkbox

Configuration

A checkbox returns 0 or 1 and is therefore suitable for use in binary decisions.

Example:

Configuration of a GAMS Scalar binaryDecision as a checkbox:


$onExternalInput
Scalar binaryDecision 'binary decision' / 0 /;
$offExternalInput
                                    
Checkbox configuration

Available Options

The following options are available for a checkbox widget:

Enter the element name as it should be displayed in a tab

With this option the tab name of the symbol is defined. For an example see the same option for a slider. The default value of the element name is the explanatory text of the symbol.

Choose a label

If a label has been specified, it will be displayed above the checkbox. For an example see the same option for a slider.

Default value

The default value specifies the initial state of the checkbox (checked or unchecked).

Should element be expanded automatically in Hypercube Mode?

As explained in detail in the corresponding chapter, widgets will be expanded in the Hypercube Mode. In Hypercube Mode a checkbox becomes a multi dropdwon menu with the entries yes and no. With the option available here, the automatic expansion of a widget can be switched off.

JSON example


{
  "inputWidgets": {
    "_gmsopt_keep": {
      "widgetType": "checkbox",
      "alias": "Keep",
      "label": "Keep process directory?",
      "value": 1,
      "noHcube": true,
      "class": "checkbox-material"
    }
  }
}
                                    

Dropdown menu

Configuration

Besides normal GAMS scalars, a dropdown menu can also be used for singleton sets. Unlike scalars, singleton sets can have a label and an element text instead of a numeric value. What is specified as choices when configuring the dropdown menu is communicated as the element label between MIRO and GAMS. The alias assigned to the dropdown choice defines the element text in the model. Read more about Singleton Sets in MIRO here.

Example:

Dropdown menu for a Singleton Set with model types as choices:

Dropdown menu configuration

The model type for which the dropdown menu is configured, is a GAMS Singleton Set (symbol name: typeSelect). The configuration of a GAMS option has been avoided because the information about such a command-line parameter is lost when a scenario is exported as a GDX file or used in Hypercube Mode. By using a singleton set instead, this information is saved:


Set t      'Available model types' / lp, mip, minlp /;

$onExternalInput
Singleton Set typeSelect(t) 'model type' / lp /;
$offExternalInput

[...]
 
$eval.Set type typeSelect.TL;

solve transport%type% using %type% minimizing z;
                                    

The value of the singleton set which comes from MIRO is stored in the compile-time variable type by using the Dollar Control Option eval.Set. This can then be used (in compile time) to run the desired model.

Tip:

If you configure a dropdown menu and you want a choice to be nothing, use the symbol "_" as a choice. MIRO treats an underscore internally as if nothing is set.

Tip:

Similar to the dynamic limits of a slider, the selectable options of a dropdown menu can be filled dynamically, depending on the loaded data.

Available options

The following options are available for a checkbox widget:

With this option the tab name of the symbol is defined. For an example see the same option for a slider. The default value of the element name is the explanatory text of the symbol.

If a label has been specified, it will be displayed above the dropdown menu. For an example see the same option for a slider.

As with a slider, the values/elements of a dropdown menu can be filled either statically or dynamically. Static choices remain unchanged, regardless of the loaded data. In contrast to this the selectable elements of a dropdown menu with dynamic choices are filled depending on the loaded data.


Static choices:

For a static dropdown menu the following options are available:

  • Choices to select from:
    Here, a list of values to select from in the resulting dropdown menu is specified.
  • Aliases for choices:
    If aliases are given, then an alias — rather than the choice — is displayed to the user. Aliases are optional. The choice-alias mapping follows the order in which the elements are specified. If aliases are given, the number of aliases must match the number of choices.
  • Default value:
    The default value specifies the initial selection of the dropdown menu. This option is only available for static dropdown menus.

Example: Configuration of a dropdown menu with static choices:

Static dropdown menu configration

The user then gets the following dropdown menu:

Static dropdown menu

Dynamic choices:

In the following example a dropdown menu with dynamic choices is configured in the model Pickstock for a Singleton Set:


$onExternalInput
Singleton Set stock 'stock' / AAPL /;
$offExternalInput
                                    

The dropdown menu should always contain all stocks that are included in the existing data. Note that this example is not part of the Pickstock demo model.

The following options are available when using dynamic choices.

  • Select symbol and header to depend upon:
    If the selection options of a dropdown menu are to be filled dynamically, the set from whose elements the choices are to be derived must be specified. For this purpose, those symbols are available which are used as input symbols in MIRO (i.e. those symbols which were tagged with $onExternalInput / $offExternalInput in the GAMS model). In this example the symbol Price is used, which contains all stocks:
    Symbol price
    Symbol selection
    Tip:

    Instead of a single symbol, all input symbols whose domain the selected set is part of can be used to fill the drop-down menu with data. To do this, simply remove the selected symbol. An All is shown then:

    All symbols

    Next, we specify the column of the symbol Price where the data for the drop-down menu should come from. Since we are interested in the individual stocks, we select the column stock symbol.

    Symbol header selection
    Note:

    Only unique elements of a column are extracted. If an element is contained more than once in the selected column, duplicate entries are removed.

    Note:

    Only those headers / columns that contain set elements of the selected symbol can be specified. Value columns cannot be used to fill the dropdown choices.

    These two options are sufficient to dynamically fill the choices of the dropdown menu.

  • Should the symbol table(s) be filtered depending on the selection in the dropdown menu?:
    This option is optional.
    Table filtering
    When active, it has the following effects: The user selects a stock in the dropdown menu (e.g. AAPL).
    Filter selection
    This has the consequence that all tables containing stock symbols are filtered according to this selection. Only those rows with AAPL are displayed:
    Filtered table
    Tip:

    The filter is used exclusively for visual support. A table filtered in this way is always transferred to the GAMS model as a whole, i.e. unfiltered, regardless of what is currently displayed in the interface.

Tip:

This option is intended for the use of singleton sets to define compile-time variables in the GAMS model. Using singleton sets instead of command line parameters has the advantage that their information is not lost at any time, e.g. during GDX export. Read more about this topic here.

Singleton sets can have an element label and an element text. If the set is configured as a dropdown menu, both components will be communicated with GAMS by default.

If this option is activated, the choice of the dropdown menu will become the element text of the set, whereas the label will be set to the empty string. This allows for the communication of strings between MIRO and GAMS while preserving the UEL order.

Migrating a singleton set into a compile time variable can be done using the $eval.set method. Since the variable should be filled by the element text, the attribute TE has to be used: $eval.Set VARNAME SETID.TE.

Note that aliases for the dropdown menu choices must be configured to use this option!

As explained in detail in the corresponding chapter, widgets will be expanded in the Hypercube Mode. In Hypercube Mode a dropdown menu becomes a multi dropdwon menu. With the option available here, the automatic expansion of a widget can be switched off.

JSON example

Static dropdown menu:

{
  "inputWidgets": {
    "type": {
      "widgetType": "dropdown",
      "alias": "model type",
      "choices": ["lp", "mip", "minlp"],
      "aliases": ["LP", "MIP", "MINLP"],
      "selected": "lp",
      "noHcube": false,
      "clearValue": false,
      "multiple": false,
      "label": "Select the model type"
    }
  }
}
                                    

Multidropdown menu

Configuration

Note:

A multi-dropdown menu can only be used for one-dimensional, dynamic sets.

Example: Model Pickstock. We define a new dynamic set subdate(date). In MIRO we want to fill the elements of subset via a multi-dropdown menu.

Set       date                 'date'
          symbol               'stock symbol';
          
$onExternalInput
Parameter price(date<,symbol<) 'Price';
$offExternalInput

[...];

$onExternalInput
set       subdate(date)        'subset of dates' /2016-01-04/;
$offExternalInput

In the Configuration Mode we can configure a multi-dropdown menu for symbol subdate:

Multi-dropdown menu configuration
Note:

The only difference between configuring a single and a multi-dropdown menu is the checkbox Should multiple items be selectable?.

Note that we do not use static choices for the dropdown menu but fill the choices with all dates of the symbol price. Furthermore, we activate the option that the table of symbol price shall be filtered based on the user's selection in the dropdown menu of subdate. This means that if the user selects one or more dates in the dropdown menu, only the entries containing these dates are visible in the Price table. More information on dependencies among widgets can be found in the options of a dynamic dropdown menu and here.

In the MIRO application the result of this configuration looks like this:

Multi-dropdown menu in MIRO

Available options

The available options of a multidropdown menu are identical to those of a single dropdown menu. The only exception is that the option to communicate the value as element text with GAMS cannot be set for a multi-dropdown menu.

JSON example


{
  "inputWidgets": {
    "subdate": {
      "widgetType": "dropdown",
      "alias": "subset of dates",
      "selected": "",
      "noHcube": false,
      "multiple": true,
      "label": "Select dates",
      "choices": "$price$date$"
    }
  }
}
                                    

Date selector

Configuration

Returns a date string in the format yyyy-mm-dd.

Example:

Date selector for Singleton Set singleDate:


$onExternalInput
Singleton Set singleDate 'single date' / 2016-01-01 /;
$offExternalInput
                                    
Date selector configuration

Available options

The following options are available for a date selector widget:

Enter the element name as it should be displayed in a tab

With this option the tab name of the symbol is defined. For an example see the same option for a slider. The default value of the element name is the explanatory text of the symbol.

Choose a label

If a label has been specified, it will be displayed above the date selector. For an example see the same option for a slider.

Default / earliest / latest date

When configuring a date selector, the earliest and the latest date that can be selected by the user can be specified. Dates outside this range cannot be selected. In addition, a specific date can be set as the default date. The dates for the earliest and the latest selectable date are optional. If required, they can be set statically by specifying a fixed date. The default date is not optional. Here either a static date string can be specified or the option Use current date can be activated. The current date is then always selected as the default.

Choose how you want the date to be formatted

This option specifies the format of the date to display in the browser. The defaults is yyyy-mm-dd. This setting does not affect the actual format of the string the widget returns.

What date range should be displayed per default?

Specifies the start screen of the date overview. The start screens Month, Year and Decade are available.

Month:

Month view

Year:

Year view

Decade:

Decade view

If you click on a year, the monthly overview opens. From there, you can click on a month to go to the detailed day view.

What day shall be the start of the week?

This option determines the day of the week with which each line of the date overview should begin.

Start on Sunday:

Start on Sunday

Start on Monday:

Start on Monday
Select weekdays that you want to disable

Individual weekdays can be deactivated in the date overview, so that the corresponding days are not selectable by the user.

Should datepicker be closed immediately when a date is selected?

If active, the date overview of the widget will be closed as soon as a date is clicked. Otherwise, the widget remains open and closes only when you click outside the datepicker.

Should element be expanded automatically in Hypercube Mode?

As explained in detail in the corresponding chapter, widgets will be expanded in the Hypercube Mode. A date selector in Base Mode will become a date range selector in Hypercube Mode. With the option available here, the automatic extension of a widget can be switched off.

Expand in Hypercube Mode

JSON example


{
  "inputWidgets": {
    "singledate": {
      "widgetType": "date",
      "alias": "single date",
      "format": "yyyy-mm-dd",
      "startview": "month",
      "weekstart": 0,
      "autoclose": true,
      "noHcube": false,
      "label": "Select a date",
      "value": "2016-01-01",
      "min": "2016-01-01",
      "max": "2017-01-01"
    }
  }
}
                                    

Daterange selector

Configuration

Returns two dates. For more on widget ranges, see here.

Example:

Date range selector for double-dash parameter date:

Date range configuration

Available options

The available options of a date range selector are almost identical to those of a date selector. The following options are available in addition to a date selector:

Default dates

Since the widget is used for date ranges the date range selector needs two default dates instead of one. The configuration of these does not differ from that of the standard date selector.

Date range separator
Select the separator between start and end date selector

With this option you can determine what should be displayed between the two date selectors (default: "to").

Example with two different separators:

Date range separator

JSON example


{
  "inputWidgets": {
    "_gmspar_date": {
      "widgetType": "daterange",
      "alias": "date range",
      "format": "yyyy-mm-dd",
      "startview": "month",
      "weekstart": 0,
      "separator": " to ",
      "autoclose": true,
      "noHcube": false,
      "label": "Select a time range",
      "start": "2020-01-01"
    }
  }
}
                                    

Text input

Configuration

Returns the entered text.

Example:

Text input for double-dash parameter comment:

Text input configuration

Available options

The following options are available for a text input widget:

Enter the element name as it should be displayed in a tab

With this option the tab name of the symbol is defined. For an example see the same option for a slider. The default value of the element name is the explanatory text of the symbol.

Choose a label

If a label has been specified, it will be displayed above the text input. For an example see the same option for a slider.

Choose the default value

The default value is the initial value of the text input i.e. the text set when starting the application. This is optional.

Choose a placeholder

A placeholder is a text that is displayed in the text box as long as no input has been made by the user. This is primarily for orientation purposes. A placeholder is optional.

Communicate as element text with GAMS?

Tip:

This option is intended for the use of singleton sets to define compile-time variables in the GAMS model. Using singleton sets instead of command line parameters has the advantage that their information is not lost at any time, e.g. during GDX export. Read more about this topic here.

Singleton sets can have an element label and an element text. When configured as a text input, both components can be communicated with GAMS by using a double pipe ('||') as separator:

Element name

If this option is activated, the entire content of the text input widget is communicated as the element text of the singleton set to GAMS. The element label in turn is communicated as an empty string. Migrating a singleton set into a compile time variable in GAMS can then be done using the $eval.set method. Since the variable should be filled by the element text, the attribute TE has to be used: $eval.Set VARNAME SETID.TE.

Text input and Singleton Sets:

If a text input is used for a Singleton Set and you want to communicate both its label and its element text via GAMS MIRO, you must use a double pipe ('||') as separator:

Element name

Find more information here.

JSON example


{
  "inputWidgets": {
    "_gmspar_comment": {
      "widgetType": "textinput",
      "alias": "Comment",
      "value": "",
      "placeholder": "e.g. \"experimental run\"",
      "label": "Insert a comment"
    }
  }
}
                                    

Numeric input

Configuration

Returns a number.

Example:

Numeric input configuration

Available options

The following options are available for a numeric input widget:

Enter the element name as it should be displayed in a tab

With this option the tab name of the symbol is defined. For an example see the same option for a slider. The default value of the element name is the explanatory text of the symbol.

Choose a label

If a label has been specified, it will be displayed above the numeric input. For an example see the same option for a slider.

Default value

A default value is the initial value of the numeric input i.e. the value set when starting the application. This is optional.

Minimum value

Specifies the minimum valid value for the widget. This is optional.

Maximum value

Specifies the maximum valid value for the widget. This is optional.

Number of decimal places

Defines the default number of decimal places to show on the formatted value, and keep for the precision

Decimal separator to use

Defines the decimal separator character to be used. Default: "." (dot).

Thousand grouping separator to use

Defines the thousand grouping separator character to be used. Default: "," (comma).

Currency symbol

Places a symbol in front of the entered value, e.g. a dollar sign. This option is used exclusively for visual support. Only the number is returned as value. This is optional.

JSON example


{
  "inputWidgets": {
    "maxstock": {
      "widgetType": "numericinput",
      "alias": "maximum number of stocks to select",
      "value": 4,
      "min": 0,
      "max": 30,
      "sign": null,
      "label": "Select the maximum number of stocks"
    }
  }
}