Skip to main content

Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

STEM Loggers

STEM TOP BAR.gif

STEM Wiki

About STEM Loggers

This article is about logging in STEM 1.3.0 and newer. For older versions of STEM, see this article.


<insert some boilerplate welcome text>

Available Loggers

Logger Compartment Logger Headless* Description   
CSV Logger Yes Yes Logs simulation data to a flat file using a configurable delimeter (such as a comma).  Useful for recording raw results of a STEM simulation for analysis. Settings
Map View Logger No No A simple logger for visually recording STEM simulations.  Captures the current view of the STEM Map and writes it to an image file. Settings
Equirectangular Map Logger Yes Yes Highly configurable image drawers for capturing STEM simulations visually using various map projections.  Creates high resolution images using specific settings independent of the current STEM Map View.  Useful for creating production-quality STEM images for print and film animations. Settings
Mercator Map Logger
Orthographic Map Logger
Azimuthal Equidistant Map Logger

* Headless loggers can be used when STEM is running in headless mode.

Please Note: IF/WHEN running headless mode, there is a defect when logging compartments generated by the 
model builder.  For the workaround please see the page Server Side Logger Workaround

Compartment Loggers

A new feature of STEM Loggers is to ability to select specific disease/population model compartments to record. Limiting the logged compartments helps prevent large amounts of potentially irrelevant data being logged, reducing storage costs and increasing performance in disease models that have a large number of compartment (such as Dengue).

A compartment in STEM is made up of three components:

  • The Diesease or Population Model
  • The population identifier
  • The disease property or compartment

More information about compartment modeling in STEM.

You need to create at least one disease or population decorator in your STEM workspace before creating a logger that logs compartments.

Simulation Logging in STEM

Please Observe 1: For now, please always accept the Default log directory location (do not specify a log directory name). 
We are having issues with users not finding the log folder. 
The default location will put logs in time-stamped folders inside the RecordedSimulations folder. 
Please Observe 2: We also ask that users never use the 'space' character in folder or project names. 
This creates issues on some operating systems.

Create a Logger

Creating a STEM Logger is similar to creating STEM Models, Scenarios, Decorators, etc. The New Logger wizard guides you through the steps.

  1. Before you begin, launch STEM, switch to the Design perspective and make sure:
    • You have at least one STEM Project in your workspace
    • If creating a compartment logger, you've created the disease or population model/decorator for your scenario
  2. Launch the New Logger wizard by clicking the "Create a new logger" button
    STEMLoggers CreateButton.png
  3. This will load the New Logger wizard
    STEMLoggers NewLoggerWizard.png
  4. In the New Logger Wizard, select a Project from the dropdown menu and enter a Name
    Tip: The new logger's configuration will be stored in <PROJECT>/Loggers/<NAME>.logger.
  5. Select a Logger Type from the dropdown menu
    Options include:
    • CSV File Logger
    • Map View Logger
    • Several projected map loggers, including:
      • Equirectangular Map Logger
      • Mercator Map Logger
      • Orthographic Map Logger
      • Azimuthal Equidistant Map Logger
  6. Configure the logger by entering logger type-specific settings
    Note: See the section below for help configuring each logger type
  7. To choose Compartments to Log, click the Select Compartments button
    Note Some loggers do not log compartments. Skip this step if you don't see a Select Compartments button
    STEMLoggers SelectCompartments.png
    In the Compartments to Log dialog
    1. In the Project dropdown, Select the project that contains the Disease or Population Model (Decorator)
    2. In the Decorator dropdown, select a Disease or Population Model. This will populate the Available Properties menu
    3. In the Available Properties, select the compartments you wish to log and click Add. This places them in the Select properties list.
      Repeat these steps until you have selected all the compartments you wish to log
    4. When finished selecting compartments, click OK
  8. When you're finished, click Next or Finished if you do not need to change the logger Dublin Core metadata
  9. Your new Logger should automatically open in an Editor window
    In the Project Explorer, The Logger should also be listed under the Project's Loggers
    STEMLoggers Editor.png

Add the Logger to a Scenario

Once the Logger is created, you're ready to move on and add it to a Scenario.

  1. In STEM, Create a new Scenario or Open an existing Scenario
  2. Navigate to the Logger you wish to add by expanding its parent Project and then Loggers sub-tree in the Project Explorer
  3. Select the Logger you wish to add and drag it to the Scenario in the Scenario Editor
    Tip: Scenarios can have multiple loggers. Repeat this step for each Logger you want to add to the Scenario
    STEMLoggers Scenario.png
  4. When finished editing, save the Scenario

Simulation Logging

The STEM Logger Manager will automatically attach loggers to a Simulation from a Scenario containing one or more Loggers. By default, Loggers are enabled automatically when a simulation starts (this is configurable in your Logger's properties).

To disable or enable a logger once a simulation start, follow these steps

  1. Open the Active Loggers view
    • Select the Window menu then click Other
    • In the Show View dialog, select Active Loggers and click OK
    STEMLoggers ActiveLoggers.png
  2. In the Active Loggers view, expand the running simulation
  3. Right click on the Logger you wish to control
    • If the Logger is enabled, select Disable Logger to disable
    • If the Logger is disabled, select Enable Logger to enable
    STEMLoggers ActiveLoggersDisableLogger.png

Logger Configurations

STEM Loggers are configurable on a per-logger basis and contain various settings for each logger type.

General Settings

Setting Type Description
Enabled Boolean Whether the logger is enabled when a simulation starts. Default is "Yes"
Use Default Log Directory Boolean Whether to use the Default Logger Directory (Project/RecordedSimulations folder). Default is "Yes".
Log Directory String/Path Required if Use Default Log Directory is no . Useful if you want to log to an external device.
Run Every n Steps Integer Triggers the logger only every n simulation cycles/steps. A value of 1 runs every step. 2 would run on steps 0, 2, 4, etc. Default is 1.
Compartments to Log List The list of decorator compartments to log. See here for more details.


Delimited File / CSV Logger

Setting Type Description
File Delimeter String The character(s) to use to separate entries in the log. Default is a single comma ',' for CSV.
Log Run Parameters Boolean Whether to write a file containing the parameters used to initialize the simulation. Default is "Yes".
Log Writer Buffer Size Integer The number of bytes to write before flushing the log file buffer. Increased this number for better performance. Default is 1024 bytes.


Projected Image Loggers

Setting Type Description
Image Width Integer The image width in pixels of the image created by the logger. Default is 1000 pixels.
Image Height Integer The image height in pixels of the image created by the logger. Default is 500 pixels.
Force Aspect Ratio Boolean Whether the image's proportions should match those of the objects being written. If yes, the width or height of the image may be changed proportionally to prevent skewing. Default is "Yes".
Fit Canvas to Polygons Boolean Whether the canvas's bounds should be fit to the objects drawn or the projection. If Yes, then the canvas boundary is the bounding box of the objects being drawn. If No, then the canvas boundary is bounding box of the projection (useful for "whole Earth" views, such as creating a Google Maps overlay). Default is "Yes".
Origin Latitude* Number Required only for origin-dependent map projections. The latitude of the principal Y axis of the projection. Default is 0.0.
Origin Longitude* Number Required only for origin-dependent map projections. The latitude of the principal X axis of the projection. Default is 0.0.
Use Logarithmic Scaling Boolean Whether to scale compartment values logarithmically when determining polygon color. Default is "Yes".
Gain Number Multiplier to apply to compartment values when determining polygon color. Default is 1.0.
Use Transparent Background Boolean Whether to make the background transparent or not. If no, the image background is determined by the color provider. Default is "No".
Border Transparency Number Alpha transparency applied to borders. Value in percent from 0 to 100. Default is 25%
Color Provider Class The STEM Color Provider to when determining the polygon fill color.

Map Writer Logger

Setting Type Description
Automatically Open
Map View
Boolean Whether the logger should try to automatically open the STEM Map View. If the STEM Map View is not open, the logger will write a blank image. Default is "Yes".

STEM Logging API

Coming soon...

Back to the top