A GAMS MIRO app is quite useful if there is data to be visualized, e.g. in the form of tables, diagrams or other charts. This applies to output data as well as input data.
Input data that is to be visualized in MIRO can be imported either from existing scenarios in the database or via a local file (currently, this can be a MIROSCEN file, a GDX container, an Excel spreadsheet, or CSV files). A MIROSCEN file is a special file format used by MIRO to export and import a complete MIRO scenario. In contrast to other supported file formats like GDX, Excel or CSV, a MIROSCEN file includes metadata such as tags, views, attachments etc.
To import such data, click on the Load data button in the navigation bar. The following dialog pops up:
You can decide whether you want to import an existing scenario from the database or load a file from your local computer.
Scenarios that you have previously named and saved in the MIRO database will be displayed in Database.
When you start a GAMS MIRO app for the first time, GAMS automatically extracts the data from your model and loads this data into the
database. This happens every time you rebuild your MIRO app i.e. every time you launch it in the
development mode via GAMS Studio
or the command line. A special scenario with the name default is created for this purpose and overridden every time you
rebuild your app!
Every time you start a MIRO app in development mode (via GAMS Studio or the command line), the data relevant to MIRO is extracted from your model and stored in the MIRO database as a special scenario named default.
To import a file from your local machine, either in the form of a MIROSCEN file, a GDX container, an Excel spreadsheet or a CSV file, select the menu item Local and click on browse. Navigate to the directory where your file resides and select it.
Confirm the data import with a click on import. If you started with an empty sheet, a new, unnamed scenario is now shown in the interface. To save it, click on Save as and give it a name.
When importing CSV data, delimiters other than the comma are also supported. The currently supported delimiters are: , tab ; | :.
Excel spreadsheet - import rules
Instead of importing all the datasets for your model, you can also select the symbols to import manually. To do so, click on Manually choose datasets and choose those symbols to be imported from the uploaded spreadsheet. This will cause MIRO to ignore other datasets.
Besides the local and the database import there is a third option: Hypercube. This tab allows you to import scenarios that have been generated and saved in the Hypercube Mode.
Such a scenario that is generated in Hypercube Mode corresponds to a scenario from the Base Mode, except that the former additionally contains a trace file.
Since those scenarios are identified by their hash value (read more about this here) and not by a user-defined name like in Base Mode, you need to import them differently.
Please refer to the chapter about scenario selection in Hypercube Mode to learn how to retrieve the hash value of a Hypercube scenario.
Import multiple scenarios on startup
In addition to the options mentioned above, which can be accessed directly from MIRO, (multiple) scenarios can also be imported automatically when starting an application. To do this, the scenarios to be imported (MIROSCEN, GDX, CSV or Excel files) must be put in the folder data_<modelname> (located in the model directory). With the next start of MIRO, those scenarios are imported automatically. Note that in development mode MIRO skips the import of files that have not changed since the last start.
In addition to scenario data, views can also be imported together with the scenario data. Simply place the JSON file with the view data here as well. The file has to be named <scenarioName>_views.json. For example if you want to provide data in the form of a GDX file and views for a scenario with the name my_scenario, you have to place both my_scenario.gdx and my_scenario_views.json into the data_<modelname> directory.
The tables that were empty before are now populated. In the upper part of the main window, you can navigate between different tabs to switch through the different GAMS symbols that you have specified in your model.
We can now change the input data. You may want to edit individual cells, sort by a different column or add/remove entire records (rows in the table). In our transport demo you have the option to edit the capacities, the demand, the distance matrix and several scalar values:
With the help of sliders and a dropdown menu we can now adjust the freight costs and the model type to be used. If we are satisfied with the settings we can start the GAMS run.
Solve the model
A click on the Solve model button starts the model run. In the background GAMS is called and the model transport.gms is started. The values set by us in MIRO now serve as input data for the model.
During the calculations, MIRO automatically switches to the section GAMS interaction. There you can see the current GAMS log and lst files. If you specified a custom log this is also shown here.
Note: Since the models of the demo applications are solved very quickly, this step is sometimes hardly visible. The menu entry GAMS interaction can also be viewed at any time after a model run.
As long as the calculations are running in GAMS, the Stop button on the left can be clicked.
A first click on this button sends an interrupt request to the running job in order to perform a graceful stop and collect an incumbent result back from the execution if the solver supports this feature.
A second click sends a request to stop the running job immediately.
After the run, the view changes again to the Output section.
In the Output section the results are visualized.
As with the input data, a distinction is made between GAMS parameters and scalar values. The GAMS parameters are each visualized in a separate tab and the scalars are summarized in a table.
If you have configured a graphical representation of your data, you can also see it here. In the model Transport a plot for the transport schedule is configured in the form of a map, see figure below.
With a click on the button in the upper right corner you can switch between a plot and the tabular representation of the data.
The Costs tab shows the objective function value of the model calculation in a tile. Like before, you can switch between graphical and tabular representation with a click on the button.
Download temporary files:
If this option is enabled, all temporarily created files of the model run (like solution reports or the lst and log files) can be downloaded either separately or as a ZIP archive with a click on the button.
Finding and loading scenarios
To help you find and load exactly the scenarios you are interested in, MIRO has a powerful Batch Load module that graphically assists you create and execute complex database queries.
Filters can be applied to scenario metadata such as the creation time, scenario name, or optional tags you have assigned to a scenario. You can also filter by any input and output scalars defined in your model as well as any Double-dash parameters and GAMS options. You can combine any of these filters with the logical operators AND and OR:
You can search for empty entries (NA) by leaving the field empty if it is a numeric field, or by using the exists and doesn't exist operators for character fields!
Once you have found the scenarios you were looking for, you can do one of the following:
- Delete scenarios:
Remove the selected scenarios.
- Download data:
Download scenario data for external analysis.
Run one of your customized batch analysis scripts (only visible if you have custom analysis scripts set up).
- Load into sandbox:
Load the selected scenario into the sandbox (only visible if you have selected exactly one scenario).
Interactive scenario comparison: Compare different scenarios directly in split, tab or pivot view. Best suited for a small number of scenarios to be compared (maximum allowed number of scenarios: 10).
The scenario comparison mode is useful if you want to compare the input and/or output data of different model runs.
Scenarios from the database as well as the currently loaded sandbox scenario can be used for comparison.
There are three different types of comparison available, split view, tab view and pivot view mode.
Unlike the split view and tab view, which take your chart configuration into account, here all records are displayed as pivot tables. Also note that the pivot comparison mode always compares the sandbox scenario with other scenarios. The sandbox scenario is therefore also called base scenario in this context.
The data of the sandbox scenario and all selected scenarios are merged into a single table with an additional domain: Scenario. You can add/remove scenarios at any time by clicking the button in the upper left corner. To close the scenarios currently loaded in the pivot mode, click the button in the upper right corner. If you have made changes to your sandbox scenario and want to update the data in the pivot view, click the button.
Views can also be used in pivot view mode. They are attached to the sandbox/base scenario. Thus, the scenario you currently have in your sandbox determines what views will be available to you in the pivot view scenario comparison. To save a new view, you only need to save your sandbox scenario once the new view has been added.
Views from the pivot comparison mode can be managed (imported/exported/deleted) just like normal views via the Views dialog in the Scenario → Edit Metadata menu. You can learn more about views here.
If you have opened scenarios in the split or tab view mode and switch to the pivot view, the scenarios from these modes are pre-selected in the load dialog so that you can easily continue using them.
If two scenarios are to be compared, the split-screen view is particularly suitable. Here the data of two scenarios can be compared side by side.
You can choose between:
- Load scenario:
Load saved scenario data from the database.
- Load sandbox:
Load the sandbox scenario which is opened in the Input / Output section.
If you have opened scenarios in the pivot or tab view mode and switch to the split view, the scenarios from these modes are shown in a "Local" tab.
Scenarios can also be loaded into tabs (as you know it from e.g. your internet browser). This allows to compare more than two scenarios including their graphics.
If you have opened scenarios in the split or pivot view mode and switch to the tab view, the scenarios from these modes are pre-selected in the load dialog so that you can easily continue using them.
The synchronize tabs option makes comparing scenarios more convenient. It can be used in both the split view and the tab view.
As soon as this option is activated via the synchronize tabs button in the navigation bar, the switch to another dataset of a scenario is also performed for all other open scenarios.
This means that if you change the dataset to be displayed in one scenario (e.g. switch from 'Price' to 'absolute error' in the image above), the view also changes for all the other scenario(s) loaded in the comparison mode.
For many operations in MIRO there are shortcuts. Especially when comparing scenarios it can be helpful to switch through the different tabs with shortcuts. To learn more about shortcuts, check out our cheat sheets!