=====Creating an aquatic food web - Tutorial=====

====Purpose====

The purpose of this tutorial is to get you acquainted with the MERLIN-Expo software. The situation is entirely fictitious, the data is fabricated. 

====Introduction====

By using the [[library#aquatic food|aquatic food models]] you can design a full aquatic food web for a lake or river in the area you are studying. ((Note that when this tutorial is written, the phytoplankton and zoo plankton models have not yet been added to the library.)) 

In this example we will create try to re-create a food web for the river Glein (on the mouth of which King Arthur had his [[http://www.britannia.com/history/arthur/kabattles.html|first battle]]). During the battle there were severe cases of lead poisoning, and we will see if the fish diet of the soldiers was the cause. Three species of fish lived there: Eel, Perch and Minnow, and two species of invertebrates: Shrimp and Clams. 

The tutorial consists of three parts. In this first part we will start small, with just a model for invertebrates. In [[creating an aquatic food web part 2|part 2]] we will add fish and a river. In [[creating an aquatic food web part 3|part 3]] we will add a human intake model as well as a model for man. 

We will begin by [[#Step 1: Creating the project|creating]] a fresh project for use to work with. After, we will [[#Step 2: Adding a model for invertebrates|add]] a [[sub-system]] for the invertebrates. Next we [[#Step 3: Selecting contaminants and species|select]] the contaminant we are interested in (lead) and add the organisms (invertebrates). After, we will look at some important [[#Step 4: Adding time series input data|input data sets]] and [[#Step 5: Entering parameter values|parameters]]. Finally we will [[#Step 6: Running a simulation|run a simulation]] and [[#Step 7: Plotting results|check out the simulation results]].

====Step 1: Creating the project====

In the [[Info screen]], click the {{:new24.png?nolink}} **New** button. In the window that appears, choose the blank (empty) template. This will give us a clean canvas onto which we will paint our river and its inhabitants. 

====Step 2: Adding a model for invertebrates====

We will now add a [[sub-system|sub-system box]] for invertebrates. It is often (always) a good idea to start small and to build rather than adding all the sub-systems at once. 

Go to the {{:matrixview24.png?nolink}}[[Model screen]]. Right-click the empty area and choose **Get from library...**. A window appears with all the available [[sub-system|sub-systems]] in the [[library|model library]]. 

{{ ::food-web-example-library.png?nolink |}}

Locate and select the **Invertebrate** model. Click **Ok**. A single box should now appear in your [[model_screen#graph]]. If you want to peek inside, click the **+** symbol. 

====Step 3: Selecting contaminants and species====

Click the {{:context24.png?nolink}} **Context** tab. {{ ::food-web-example-context.png?direct&200|}}

In the section named **Contaminants**, find **Lead** in the list and select it. It should now move from the 'available' to the 'selected' list. 

In the **Food** section, there is a button named **Add**. Next to it is a drop-down list with available food types. The invertebrates [[sub-system]] offer just one food item type: invertebrate. 

Click the **Add** button two times. Two items should now appear in the table below (Invertebrates and Invertebrates_2). Click in the **Name** cell of each to rename them to //Shrimp// and //Clam//. 



====Step 4: Adding time series input data====

{{ ::food-web-example-timeseries.png?direct&200|}} There are only two important things to know about time series in MERLIN-Expo 
  - They start at day 0 ((Time series start at day 0 because the simulation time is set to start at day 0. You can change the simulation start time in the [[simulation screen]])). 
  - The time unit is always days [d<sup>-1</sup>]. 

The invertebrates model require two (potentially) time dependent sets of data: concentration of the contaminant in water and the water temperature. We will let these be constant for now:

Click the {{:timeseries24.png?nolink}} **Time series** tab. In the list both of the data items should be listed. Make sure that //Concentration of the chemical in dissolved river water// is selected. In the table, enter the value

^Time^Value [mg m<sup>-3</sup>]^
|0.0|1.0|

Next click //Water temperature//. Leave the value 15.0 as it is. 

====Step 5: Entering parameter values====

{{ ::food-web-example-parameters.png?direct&200|}} Proceed to the {{:parameters24.png?nolink}} [[Parameters screen]]. You might notice that it is very similar to the [[time series screen]]. The [[parameter|parameters]] are listed on the left hand side. When you select a parameter, the area to the right will display information and a table in which you can change the parameter data. 

The table will (by default) show you the value, PDF and unit. The [[PDF]] is only relevant for [[probabilistic simulation|probability studies]] and will be ignored in this exercise. 

There are many parameters to find values for, and to keep you from getting bored we will only change a few of the parameters from their default values.

//Invertibrate age at maturity// 
^Invertebrates^Value^
|Shrimp|2200|
|Clam|1700|

//Invertebrate diet preference for food items// - How much one species' diet consists of another species (cannibalism is also allowed).

^Invertebrates^Shrimp^Clam^
|Shrimp|0|0.3|
|Clam|0|0|

//Invertebrate length at maturity// 

^Invertebrates^Value^
|Shrimp|6|
|Clam|4|

====Step 6: Running a simulation====

{{ ::food-web-example-run-simulation.png?direct&200|}} Move on to the next tab, {{:runall24.png?nolink|}} **Simulation**. The [[simulation screen]] is were you make the final settings before performing a calculation. You specify the start and end time and what type of simulation you want to run. The {{:simulationsettings24.png?nolink|}} **Simulation Settings** button allow you to select which data you want from the simulation and to play around with the [[solver]] settings. 

Change the **End time** to 700 days, and then click the {{:runall24.png?nolink}} **Run** button to start the simulation. The **Information** area should now fill up with messages from the simulation engine. 

====Step 7: Plotting results====

The reward of your labour is now within reach. Click the {{:chartview24.png?nolink}} **Chart** tab to access the [[charts screen]]. The {{:chartview24.png?nolink|}} chart screen and its close cousin, the {{:createtimetable24.png?nolink|}} [[tables screen]], will list all the [[simulation output|outputs]] of the simulation. Simulation results are overwritten each time you run a new simulation, but if you want to keep results - eg. to compare results from two different simulations - you can create [[archive|archives]] of simulation data. 

Expand the node with today's date, then expand the Invertebrates node. 

Inside, click the //Concentration of the chemical in invertebrates (...)// label. This output will have different values for different species of invertebrates. If you had chosen to model more than one [[contaminant]], it would also have different values for different contaminants. When you select the output, two lists should appear under it. One which lets you select species, one to select contaminants. 

{{ ::food-web-example-plot.png?direct&200|}} In the first list, select both //Shrimp// and //Clam//. A plot should now be displayed on the right hand side. 

Below the graph are tools that can help modify the plot. Select a legend on the **Right**, and also check the **Shapes** box. The chart should resemble the picture on the right.

====Step 8: Saving your project====

Return to the **Information** tab. Click the {{:saveas24.png?nolink }} **Save as...** button. Choose a name and folder for the project file and click **Save**. 

If you want to compare your results with ours, you can download the solution file {{::food_web_part_1.eco|here}}.

Are you ready to continue to [[creating an aquatic food web part 2|part 2]]?