Ecosampler is a utility for Ecopath with Ecosim (EwE) that records alternate balanced Ecopath parameter sets (referred to as ‘samples’) produced by the EwE Monte Carlo routines. Ecosampler can then run these samples through the EwE core modules Ecopath, Ecosim and Ecospace, and any active plug-in. Any saved model output can then be used to assess the impact of Ecopath input parameter uncertainty onto predictions of any EwE module.

Obtaining the Plug-in

Ecosampler is distributed as part of EwE version 6.6+. For any issues, contact the EwE development team at ewedevteam@gmail.com.

Interface

The Ecosampler interface is launched by choosing Navigator > Tools > Ecosampler. The Ecosampler interface offers the following elements (Figure 1):

1. A toolbar that offers options to turn sample recording on and off, and to import samples stored elsewhere.
2. A overview with the list of recorded samples, and for each sample a sequential number, whether a sample is currently loaded in the EwE user interface, and the data and computer system the sample was recorded on.
3. A sample management section where samples can be loaded, unloaded, and deleted.
4. A batch run section to run a number of samples through EwE and any loaded module and active plug-ins..

Recording Samples

Ecosampler records samples from the Monte Carlo routine that ships with the EwE desktop software.  Toggle the Record button (Figure 2) to enable and disable record mode.

To record samples, do the following:

1. Turn recording on in Ecosampler by clicking the inactive Record button until its icon turns red, indicating that record mode is active. A black record option indicates that Ecosampler recording is off.
2. Run the Monte Carlo routine built into EwE.

While recording, Ecosampler listens to the execution of Monte Carlo, and intercepts and stores any alternate mass-balanced parameter found by Monte Carla as a “sample” in the currently loaded model database. The samples immediately appear in the samples list, showing the current date and the name of the computer EwE is executed on.

To stop recording samples, do the following:

1. Turn recording off by clicking the active “Record” button until its icon turns black, indicating that record mode is inactive.

Managing Samples

A stored sample can be loaded in the EwE interface to assess its validity.

To load a sample, do the following:

1. Select a sample in the samples list
2. Press Load.

The sample list will indicate which sample is loaded, and when a loaded sample is selected, the load button text will read Unload.

To unload a sample and restore the original Ecopath parameter values, do the following:

1. Select the loaded sample
2. Press Unload.

A stored sample can be deleted if it produces unrealistic or outlying behaviour.

To delete a sample, do the following:

1. 1. Select the sample to delete
   2. Press Delete.

Importing Samples

Recording a large number of samples may take considerable time, especially when Monte Carlo is configured to perturb the diet composition matrix and when the chances to randomly find alternate mass-balanced models are slim. In this case, it makes sense to record samples for the same model simultaneously on multiple computers. Once all recording is complete, the Import Samples functionality can then be used to bring all generated samples – generated by the Ecosampler runs in different copies of the EwE model – back into one model.

To import models from another model do the following:

1. Click Import.
2. Select From another model.
3. Browse to the model.
4. Press OK.

The sample list will be updated with samples found in the selected model.

Expiring Samples

Samples are alternate mass-balanced configurations for one specific set of values of an Ecopath model. If any Ecopath input parameter is changed by the user and this change is saved, all stored samples in principle become invalid. In this case, Ecosampler will prompt the user whether stored samples should be deleted.

Running Samples

The second aim of Ecosampler is to run samples though various components of EwE and collect output.

To run Ecosampler samples through EwE, do the following:

1. Load the desired Ecosim and Ecospace scenarios are correctly loaded.
2. Activate desired plug-ins.
3. Enable data auto-saving (Menu > Tools > Options > File Management) for every component that you wish to gather output data for.
4. Enter the number of samples to run in the Batch run panel.
5. Press Run.

When a batch run is started, Ecosampler will execute the current model configuration as a baseline sample, and will store this in a subfolder Sample_baseline under the default core output path. If Ecopath does not balance, the user is notified, and the batch run is aborted.

If Ecopath did balance, then Ecosampler checks if Ecosim, Ecospace and Ecotracer are loaded. Ecosampler will start processing the list of samples, starting at the first stored sample up to the end of the list or until the number of requested samples has been processed. It will run each sample in turn.

When running a sample, EcoSampler performs the following steps:

• Append the current core output path with a subfolder Sample_[sample number] for the loaded sample. This reroutes all auto-saving component output to a unique folder per sample;
• Load the sampled parameter set into Ecopath;
• Run Ecopath, and if Ecopath balances for the loaded sample, run Ecosim (if loaded) and Ecospace (if loaded) with Ecotracer enabled (if loaded). Any connected component that is configured to auto-save its output will now do so.

Using the Ecosampler Output

The output of Ecosampler is an organized series of folders – a baseline output folder and a unique folder per executed sample – under the current EwE output directory, with regular file-based output for the components that were activated. Each sample folder contains the various output files written by EwE components set to automatically write their output to file when Ecosampler was executed.

Troubleshooting

Ecosampler writes its activities to the Ecopath log file, which can be viewed by choosing Main Menu > About > View Log File.

Further Development

A series of future changes can be foreseen:

• Prompt user when deleting a sample because delete cannot be undone;
• Hide System column when there are no samples from another computer;
• Implement a system to rate samples, where the rating may be used for randomly selected samples during batch runs;
• Automatically rate or score samples when they are generated?
• Build to logic to import samples generated by the Cefas MSE plug-in.

References

Steenbeek, J., Corrales, X., Platts, M., and Coll, M. 2018. EcoSampler: automating the ability to assess input parameter sensitivity on Ecopath with Ecosim aquatic food web model results. SoftwareX. https://doi.org/10.1016/j.softx.2018.06.004.