- 1 About STEM Loggers
- 2 Simulation Logging in STEM
- 3 Logger Configurations
- 4 STEM Logging API
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>
|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.
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
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.
- 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
- Launch the New Logger wizard by clicking the "Create a new logger" button
- This will load the New Logger wizard
- 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.
- 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
- Configure the logger by entering logger type-specific settings
- Note: See the section below for help configuring each logger type
- 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
- In the Project dropdown, Select the project that contains the Disease or Population Model (Decorator)
- In the Decorator dropdown, select a Disease or Population Model. This will populate the Available Properties menu
- 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
- When finished selecting compartments, click OK
- When you're finished, click Next or Finished if you do not need to change the logger Dublin Core metadata
- Your new Logger should automatically open in an Editor window
Add the Logger to a Scenario
Once the Logger is created, you're ready to move on and add it to a Scenario.
- In STEM, Create a new Scenario or Open an existing Scenario
- Navigate to the Logger you wish to add by expanding its parent Project and then Loggers sub-tree in the Project Explorer
- Select the Logger you wish to add and drag it to the Scenario in the Scenario Editor
- When finished editing, save the Scenario
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
- Open the Active Loggers view
- Select the Window menu then click Other
- In the Show View dialog, select Active Loggers and click OK
- In the Active Loggers view, expand the running simulation
- 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
STEM Loggers are configurable on a per-logger basis and contain various settings for each logger type.
|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
|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
|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
|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