Purpose

This chapter provides guidelines for configuring, and running external time series of maps in Ecospace, the spatial‐temporal module of the Ecopath with Ecosim (EwE) food web modelling approach.

Availability

The spatial temporal data framework is under continous development, and currently is only available under an EwE professional license, both to support the ongoing development and because setup of the framework is a requiring undertaking often requiring support. We do, however, seek to lower the learning curve through this chapter.

For more information about licensing, please see https://ecopath.org/go-pro/

Using the Spatial Temporal Framework

The spatial temporal framework is a plug‐in to the Ecopath with Ecosim food web modelling approach ^{[1] [2] [3]}, built with the sole purpose to dynamically insert (time varying) spatial data that is external to the EwE model into Ecospace map layers ^[4].

The framework integrates with the EwE6 user interface in several locations as shown in Figure 1.

Defining Connections

A ‘connection’ is the link between an Ecospace map layer and a repository of maps (or time series of maps) that are not stored within the EwE model. Connections are defined by the EwE user, and can be shared across computer systems.

Connections are managed from the central Define external spatial temporal connections screen (Figure 2), which is accessible from several locations throughout Ecospace. Here, one can create and delete connections of different types, manage in which file the connections are stored on the local machine, export connections and their data for reuse or sharing with others, and control whether the framework is allowed to dedicate background processing time to index the spatial and temporal overlap of external data with the current Ecospace scenario.

Existing connections are briefly summarized. The Used column states if the connection is actually applied to one or more Ecospace layers. The Status column uses icons to explain whether the connection has errors (Red X), has only partial spatial overlap with the modelled area (Orange !), or entirely covers the modelled area (Green checkmark). The warning icon  is also used to notify that data compatibility has not been assessed yet, which can be done by enabling indexing or by running Ecospace, in case each used connection is automatically validated.

To define a new connection:

• Go to Menu > Ecospace > Define external data connections…
• Select the type of connection to create. Presently, four file‐based connection types are supported,
  (1) a time series of ASCII files that must be prepared to match the spatial extent and cell size of a dedicated Ecospace scenario;
  (2) a time series of spatial files that will be made fit for inclusion in Ecospace by the DotSpatial / GDAL GIS engine encapsulated in the spatial temporal data framework;
  (3) a file with X,Y,Z,T time series values provided in CSV file format, where (X,Y) coordinates can either indicate (column, row) or (longitude, latitude); and
  (4) a single spatial file.
• Press Create…. A new connection is defined, and the Configure external data connection view opens up (Figure 3) to allow its content to be modified.

The configuration process of file‐based connections is straightforward:

• Enter a name that identifies its content, keeping in mind that you may have a large number of connections to sift through. To illustrate, the Mediterranean modelling exercise used for illustration in this chapter featured 150 different connections per scenario.
• Enter a description to state data source, spatial and temporal resolution, data pedigree, and other details, considering one may have many connections to manage.
• Optionally, select the Ecospace variable the connection is limited to. This does NOT assign the connection; it only limits where this connection is available in the EwE user interface.
• Press Browse to select which files belong to the connection browse to the folder where the files reside, and select and insert the desired files. The files list will populate in response. Note that each file represents a map in time. times can be entered by hand, or can be set automatically, either by entering a start date (year/month) and monthly interval, or by reading the time step from a fixed position in the file names. Seasonal data rotates the first year of data until the indicated end date.

• Press OK    

Assigning External Data to Ecospace

To make external connections operational in Ecospace, do the following:

• Go to Navigator > Ecospace > Input > External data… The External data view opens up (Figure 4), and displays all Ecospace map layers that can receive external data. The toolbar offers options to limit the number of layers on display, with filters by layer type, and only viewing layers with active connections. The external data interface also shows a time line that reflects the temporal overlap of external data with the Ecospace scenario.

Every map layer has up to six slots for assigning connections. To assign external data to a layer,

• Click the first available slot in the layer that you wish to drive with external data.

This opens up the interface Assign connections (Figure 5),

• Select a connection from the list of available connections
• Click the use button (Green arrow pointing right) to assign the connection. A configuration panel opens with additional options. Available options depend on the type of connection that was selected, and the type of Ecospace layer the connection is applied to. Some Ecospace layers may require data to be scaled, for instance, and for those layers you will need to provide a scalar. The configuration panel also summaries compatibility of assigned external data with the current Ecospace scenario.
• Click Configure to review or change the configuration of the connection (as explained above).
• Select an Integration method if applicable – these are geospatial macros that convert data to the desired Ecospace layer needs.
• Enter a scaling method if applicable
• Enter a scaling factor, which can be left at default 1 if data in the Ecospace scenario is the same as the first month of external data.
• Calculate the scaling factor to scale the first year of external data scales to an Ecopath base value (this is highly recommended when driving the Relative PP layer, for instance).
• Press Close to make the external data connection stick, and save the model.

Running Ecospace with External Data

When Ecospace is executed as normal, the EwE status panel will show a notification every time external data is accessed, and also whether integration into the intended Ecospace layer was successful. These notifications are also written to an extensive log file, which is saved in the directory where the EwE model is located. This file can be helpful for troubleshooting external data connection issues.

If Ecospace has encountered any issue with external data during a run, it will notify the user that issues were encountered. As the Ecospace run missed some needed external data it should not be trusted, and the status panel and/or spatial log file will provide clues as to why needed spatial data was not found.

Configuration Files

All spatial temporal data connection definitions are stored in configuration files. At any given moment, EwE operates on only one configuration file that defines available external data connections. This central storage allows external connections to be reused between Ecospace modelling exercises, and provides a means to organize how much data is visible to a specific modelling exercise.

Configuration files are managed in Menu > Tools > Options > External data… Here, one can create or delete configuration files (in .xml format), add an existing configuration file to EwE, and set the active configuration file.

Once a connection is applied to an Ecospace layer, the definition of the connection is stored within Ecospace, while the data remains outside the model.

It is advisable to use separate configuration files for different models, as the number of external spatial temporal data connections can become overwhelming.

Sharing External Data

The export external spatial data interface, which can be launched from all locations in the EwE user interface where external data connections are managed, creates new configuration files from selected external data connection definitions, and optionally their data. All exported data is placed in a user selected folder.

To share external data connected to your model with another computer or colleague,

• Open the export external spatial data view, for instance through Menu > Tools > Options > External data > Export
• Enter a descriptive file name (such as “External data Med 0.01667dd”)
• Select Choose to browse to the a location where the exported data can be placed
• Select which connections to export. The “Used” button selects all connections assigned in Ecospace; the “All”button selects all available connections as defined the current configuration file.
• Check “Export local data as well”
• Click Export. Please be patient, this may take a while.

Once the export process is complete, share the data as follows,

• Copy the entire exported folder with your model to make it available or place the exported folder on a shared network drive.

To incorporate shared data into EwE,

• Go to Tools > Options > External data
• Click Add
• Browse to the shared configuration file
• Press Open and the configuration file will be added to EwE
• Press Set Current to make this the active configuration file
• Load Ecospace.

When an Ecospace scenario is loaded, the spatial temporal data framework automatically resolves conflicts in external data connections against the current configuration file.