Tutorial

The following tutorial provides a simple step by step guide to using DyMSiM with an example dataset. It assumes a relatively low level of knowledge and should be accessible to most users. Should you require additional assistance regarding the features of STELLA, please refer to the help section in STELLA.

Background on Dataset

The scenario provided for this tutorial focuses on the eastern portion of the Dominican Republic. Daily precipitation and temperature data were downloaded from the National Climatic Data Center (http://www7.ncdc.noaa.gov/CDO/cdo)* and hours of daylight data was obtained from the US Naval Oceanography portal (http://www.usno.navy.mil). While the data selected were chosen to be representative of the conditions, they have been adjusted slightly for demonstration in this tutorial, and therefore should not be used for any other purposes. The original data can be downloaded from the sources noted above.

    • To open the model for this tutorial select File > Open > DyMSiM.STM

    • The model below should open on your screen:

    • View > Zoom Out will display the entire model on a single screen

A review of the STELLA help documentation will explain the different structures and components contained within the model (stocks, flows, connectors, converters, etc). However, you will note in DyMSiM that several of the components have been color coded. Graphical functions have been colored orange. These require the importation of daily climate data time series via a linkage with excel spreadsheet. The features coded green designate those specified by the user.

Importing time series data

Start off by importing the time series data into DyMSiM. To do so select: Edit > Import Data. The following box will appear:

    • Under Import Type select Persistent and Dynamic. This will link the excel sheet to DyMSiM and automatically update the data in the model whenever changes are made in Excel

    • Under Import Data Source use Browse to select the excel file that accompanies this tutorial DyMSiM_tutorial_data.xls

    • Under Data Orientation select the first option displaying the data in column format, then click OK.

    • The data will begin importing, and a dialogue box will appear when the import is complete. Note that this may take several minutes due to the large volume of data being imported.

DyMSiM_tutorial_data.xlsx

Check each of the orange-colored graphical functions (Real, Temperature, Precipitation and Hours Daylight) to ensure that the data imported correctly by double clicking on it. Below is an example of what you should see when you open the Temperature graphical function:

All 725 data points from the Excel file should be displayed inside the graphical function. Ensure that the Data Points box and the upper bound of the x-axis both have the number 725 listed. If not, manually enter 725 into these boxes. Perform the same visual check for the other 3 graphical functions.

The climate variables have now been successfully imported into the model. The next step is specifying the environmental parameters of the location.

Start out by specifying the area of the location in the model. Double click on Area and enter ‘40468564’. The size of the site specified for this example is 40468564 cm2 (which is equivalent to 1 acre).

Next, you will need to specify the percentage of each of the 3 landcover classes cover in the total area: impermeable landcover, permeable landcover, and permanent water.

Open the Percent Permeable converter by double clicking on it and enter .92

Next, open the Percent Permanent converter and enter .03 and in the Percent Container converter and enter .05.

What is being specified here is a location that is largely dominated by permeable surface cover, with a small amount of permanent water present and impermeable surfaces (such as containers) that collect water.

Now it is necessary to specify the additional environmental parameters. We will assume that there is no existing water on the ground before the start of the simulation, and therefore leave the Water Ground value at 0. However, because the eastern tip of the Dominican Republic is predominated by karst topography, we can assume a fairly high permeability rate. Therefore, open the Permeability Rate container and enter 80.

Irrigation in the Dominican Republic may play an important role in supporting vector breeding during the drier period of the year. Therefore, let’s assume a small portion of the area we are studying is used for irrigation purposes. We can include the impacts of irrigation timings during the year by specifying the timeframe in DyMSiM.

The driest period occurs during February through April, so we will use the timing-based irrigation scheme in DyMSiM. Set the IR Index to 1.

Now we need to enter the Julian dates of this period so DyMSiM knows when to begin including irrigation effects and when not to. Open the Julian Start converter and enter 30 (the Julian date for Feb 1). Then open the Julian Stop converter and enter 120 (the Julian date for April 30).

Next we need to specify how conducive the environment is to mosquito and larvae development. We will assume the location provides ideal conditions, and therefore in the Food or ecological rating converter, enter 1 (note that this value should be decreased to reflect instances of less than ideal conditions).

We have now specified all the basic parameters necessary to model the Cx. quinquefasciatus population in our location. Before beginning the simulation, we should set up a table and graph to display the results.

To insert a graph: click on the graph pad icon (green symbol to the left), and then click on any of the open space in the model to deposit it. A blank graph will appear. The Y-axis should be labeled with the days in the time series (725), but we need to specify the X-axis. For now, we will specify the X-axis to display only the simulated mosquito population. To do so, double click along the X-axis.

Under Allowable, scroll down and click on Mosquitoes. Use the button to select your choice. Check that the X-axis is set to display days from 1-725, and the the blank graph, with both the Y and X axis numbered. You can close the graph for now.

Insert the Table in the same way by selecting the Table icon and depositing it on the graph pad. In the table that opens, double click on the column next to Days and select Mosquitoes in the same way you did for the graph. Once you have done that, you can close the graph.

Now we are ready to run DyMSiM. From the main tool bar, select Run > Run Specs. In the dialogue box, ensure that the simulation is set to run from 1-725, the Unit of Time selected is Days (as this is a daily model), and that the DT selected is 1 (This tells the model to produce a count for every 1 unit of time selected- in this case for every day), leave the rest of the defaults as they are and select OK.

To run the model, select Run > Run. You will see the model begin to run- this may take several minutes. When the model has finished, double click on your Graph and Table to see the time series and data table of the daily modeled mosquito population.

Your graph should look like this:

If you run the model again with the same settings, but turn off the irrigation feature (IR Index =0), you will get the graph below. Although the general trend of the populations are similar, you can see how including irrigation during the typically hotter and drier season can help support the mosquito populations.

If you open your table, you should see a generated mosquito count for each day of the simulation. By choosing Edit > Export Data and selecting an existing Excel file, this data can be exported and linked in the same was as the imported data.

Offsetting the temperature

The above scenario was done using existing temperature data. However, let’s assume we want to model the mosquito count under different temperature scenarios. We’ll start by increasing the temperature by 2oC. To do this, open the Difference converter and enter 2, and then run the model the same way as before. The chart below compares the original model run against a 2°C increase in temperature, with the data exported to and graphed in Excel. Aside from the change in temperature, all other inputs were held constant between the model runs. Notice how the mosquito population changes throughout the year as a result of increasing the temperature 2 degrees. To decrease the temperature, simply enter (-X) as the value to negatively offset.

As noted above, the converters in green are those that must be specified by the user. You can experiment with those by changing their values or turning them off.

Finally, if available, you can use the Real graphical function to compare your results to or validate against actual mosquito counts. The Real data was imported with the rest of the time series data. To view how the actual mosquito trend compares to the simulated one, open the Graph Pad, double-click on the X-axis, and select Real. You can also add other variables to the graph, such as your temperature or precipitation values to see how these model mosquito populations overlay with your imported climate data.

The graph above shows the simulated mosquito populations, as well as daily temperature and precipitation values as one way to visually display the data in STELLA. This provides a quick way for examining how the mosquito population is responding to the input climate variables.Here you can notice how the mosquito population tends to decrease during the extreme temperatures, and also increases after significant precipitation events. Additional examples can be found on the "Application Examples" page.

This tutorial should have provided you with the basic steps on properly entering data into DyMSiM, as well as highlighted some of the different tools available within the model and a basic background for working with DyMSiM within STELLA. For additional information on how these variables work within the model refer to the user’s manual portion of this document. For help with STELLA software, please refer to the documentation and help features provided by ISEE systems

*Note on NCDC Data: Adjustments were made to fill missing values in the NCDC data, and should therefore be used only for the purposes of this tutorial. The original data can be obtained directly from NCDC through their online data directory at http://www.ncdc.noaa.gov/oa/climate/climatedata.html#daily. Finally, the data and products may have conditions placed on their international or commercial use. They can be used within the U.S. or for non-commercial international activities without restriction. The non-U.S. data cannot be redistributed for commercial purposes.