STEM Loggers

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

   

3. This will load the New Logger wizard

   

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

   

   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

   

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

   

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

   

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

   

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...